mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-24 14:47:23 +00:00
Tobias Gesellchen
7ec4ee67af
🔥 NEW ENDPOINTS IMPLEMENTED: 📊 /introspect endpoint: - Get detailed music service state and capabilities data - Support for SPOTIFY, PANDORA, TUNEIN, AMAZON, DEEZER services - Service state tracking (Active, Inactive, InactiveUnselected) - Playback capabilities (skip, seek, resume, data collection) - Authentication token status and user account information - Subscription type and content history metadata 📚 /recents endpoint: - Retrieve recently played content history - Support for all music sources (Spotify, Local, TuneIn, Pandora, etc.) - Rich filtering by source type and content type - Content classification (tracks, stations, playlists, albums) - Presetable item identification and artwork metadata - Timestamp tracking with UTC time support ⚡ CLIENT API: - client.Introspect(source, sourceAccount) method - client.IntrospectSpotify(sourceAccount) convenience method - client.GetRecents() method with comprehensive filtering - Complete error handling and validation - Rich helper methods for content analysis 🖥️ CLI COMMANDS: - soundtouch-cli source introspect --source <SERVICE> - soundtouch-cli source introspect-spotify - soundtouch-cli source introspect-all (bulk introspect) - soundtouch-cli recents list [--detailed] [--limit N] - soundtouch-cli recents filter --source <SRC> --type <TYPE> - soundtouch-cli recents latest (most recent item) - soundtouch-cli recents stats (detailed analytics) 📦 MODELS & FEATURES: - IntrospectRequest/Response with service-specific handling - RecentsResponse with RecentsResponseItem for individual items - Rich filtering: GetSpotifyItems(), GetTracks(), GetPresetableItems() - Content type detection: IsTrack(), IsStation(), IsPlaylist() - Source classification: IsStreamingContent(), IsLocalContent() - Full XML marshalling/unmarshalling with proper attribute handling 🧪 COMPREHENSIVE TESTING: - Unit tests for models with XML parsing validation - Integration tests for real device communication - CLI command tests with mock server responses - Error condition testing and edge case handling - Performance tests and timeout validation 📖 DOCUMENTATION & EXAMPLES: - Updated API endpoints overview marking endpoints as implemented - Comprehensive CLI reference with usage examples - Removed endpoints from unimplemented list - Updated wiki implementation plan status - Complete example applications with README guides - Real-world usage patterns and best practices ✨ KEY FEATURES: - Service health monitoring and diagnostics - Recently played content discovery and analysis - Preset candidate identification - Content statistics and usage analytics - Time-based filtering and relative timestamps - Rich emoji-based CLI output formatting - Cross-service compatibility and error handling This implements two critical missing endpoints from the SoundTouch API, providing essential functionality for music service management and recently played content analysis with full programmatic and CLI access.
394 lines
11 KiB
Markdown
394 lines
11 KiB
Markdown
# Introspect CLI Commands Demo
|
|
|
|
This document demonstrates the usage and output of the new introspect CLI commands added to the soundtouch-cli tool.
|
|
|
|
## Available Commands
|
|
|
|
The introspect functionality is available through three commands in the `source` command group:
|
|
|
|
1. `source introspect` - Get introspect data for any supported service
|
|
2. `source introspect-spotify` - Convenience command specifically for Spotify
|
|
3. `source introspect-all` - Get introspect data for all available services
|
|
|
|
## Command Examples and Expected Output
|
|
|
|
### 1. Basic Spotify Introspect
|
|
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect --source SPOTIFY
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
Getting introspect data for SPOTIFY
|
|
|
|
=== SPOTIFY Service Introspect Data ===
|
|
State: InactiveUnselected
|
|
User: SpotifyConnectUserName
|
|
Currently Playing: ❌ No
|
|
Current Content:
|
|
Shuffle Mode: OFF
|
|
Subscription Type:
|
|
|
|
=== Service State ===
|
|
❌ Service is INACTIVE (Never been used)
|
|
⏸️ Not currently playing
|
|
➡️ Shuffle mode is OFF
|
|
|
|
=== Service Capabilities ===
|
|
❌ ⏮️ Skip Previous
|
|
❌ 🎯 Seek within tracks
|
|
✅ ▶️ Resume playback
|
|
✅ 📊 Data collection: ENABLED
|
|
|
|
=== Spotify Content History ===
|
|
Max History Size: 10 items
|
|
|
|
=== Technical Details ===
|
|
Token Last Changed: 2023-12-14 10:48:15 MST
|
|
Token Timestamp: 1702566495 seconds since Unix epoch
|
|
Token Microseconds: 427884
|
|
Play Status State: 2
|
|
Received Playback Request: ❌ No
|
|
```
|
|
|
|
### 2. Spotify Introspect with Account
|
|
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect --source SPOTIFY --account my_spotify_user
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
Getting introspect data for SPOTIFY
|
|
Source Account: my_spotify_user
|
|
|
|
=== SPOTIFY Service Introspect Data ===
|
|
State: Active
|
|
User: my_spotify_user
|
|
Currently Playing: ✅ Yes
|
|
Current Content: spotify://track/4iV5W9uYEdYUVa79Axb7Rh
|
|
Shuffle Mode: ON
|
|
Subscription Type: Premium
|
|
|
|
=== Service State ===
|
|
✅ Service is ACTIVE
|
|
🎵 Currently playing content
|
|
🔀 Shuffle mode is ON
|
|
|
|
=== Service Capabilities ===
|
|
✅ ⏮️ Skip Previous
|
|
✅ 🎯 Seek within tracks
|
|
✅ ▶️ Resume playback
|
|
🚫 Data collection: DISABLED
|
|
|
|
=== Spotify Content History ===
|
|
Max History Size: 15 items
|
|
|
|
=== Technical Details ===
|
|
Token Last Changed: 2023-12-14 15:30:22 MST
|
|
Token Timestamp: 1702583422 seconds since Unix epoch
|
|
Token Microseconds: 123456
|
|
Play Status State: 1
|
|
Received Playback Request: ✅ Yes
|
|
```
|
|
|
|
### 3. Spotify Convenience Command
|
|
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect-spotify
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
Getting Spotify introspect data
|
|
|
|
=== Spotify Service Introspect Data ===
|
|
State: Active
|
|
User: premium_user
|
|
Currently Playing: ✅ Yes
|
|
Current Content: spotify://playlist/37i9dQZF1DXcBWIGoYBM5M
|
|
Shuffle Mode: ON
|
|
Subscription Type: Premium
|
|
|
|
=== Spotify Service State ===
|
|
✅ Service is ACTIVE
|
|
🎵 Currently playing content
|
|
🔀 Shuffle mode is ON
|
|
|
|
=== Spotify Service Capabilities ===
|
|
✅ ⏮️ Skip Previous
|
|
✅ 🎯 Seek within tracks
|
|
✅ ▶️ Resume playback
|
|
🚫 Data collection: DISABLED
|
|
|
|
💡 Spotify Setup Recommendations:
|
|
(None - service is properly configured and active)
|
|
|
|
=== Spotify Content History ===
|
|
Max History Size: 20 items
|
|
|
|
=== Technical Details ===
|
|
Token Last Changed: 2023-12-14 16:45:10 MST
|
|
Token Timestamp: 1702587910 seconds since Unix epoch
|
|
Token Microseconds: 789012
|
|
Play Status State: 1
|
|
Received Playback Request: ✅ Yes
|
|
```
|
|
|
|
### 4. Inactive Service Example
|
|
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect-spotify
|
|
```
|
|
|
|
**Expected Output (when Spotify is not set up):**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
Getting Spotify introspect data
|
|
|
|
=== Spotify Service Introspect Data ===
|
|
State: InactiveUnselected
|
|
User:
|
|
Currently Playing: ❌ No
|
|
Current Content:
|
|
Shuffle Mode: OFF
|
|
Subscription Type:
|
|
|
|
=== Spotify Service State ===
|
|
❌ Service is INACTIVE (Never been used)
|
|
⏸️ Not currently playing
|
|
➡️ Shuffle mode is OFF
|
|
|
|
=== Spotify Service Capabilities ===
|
|
❌ ⏮️ Skip Previous
|
|
❌ 🎯 Seek within tracks
|
|
✅ ▶️ Resume playback
|
|
✅ 📊 Data collection: ENABLED
|
|
|
|
💡 Spotify Setup Recommendations:
|
|
• Sign in to your Spotify account on the device
|
|
• Use 'soundtouch-cli source select --source SPOTIFY' to activate Spotify
|
|
• Ensure you have Spotify Premium for full functionality
|
|
```
|
|
|
|
### 5. All Services Introspect
|
|
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect-all
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
Getting introspect data for all services
|
|
|
|
🔍 Getting introspect data for SPOTIFY...
|
|
✅ SPOTIFY: Successfully retrieved introspect data
|
|
State: Active (User: spotify_user)
|
|
Playing: ✅ Yes | Content: spotify://track/4iV5W9uYEdYUVa79Axb7Rh
|
|
Capabilities: Skip, Seek, Resume
|
|
|
|
──────────────────────────────────────────────────
|
|
🔍 Getting introspect data for PANDORA...
|
|
❌ PANDORA: Service not available on this device
|
|
|
|
──────────────────────────────────────────────────
|
|
🔍 Getting introspect data for TUNEIN...
|
|
✅ TUNEIN: Successfully retrieved introspect data
|
|
State: Inactive
|
|
Playing: ❌ No
|
|
Capabilities: Resume
|
|
|
|
──────────────────────────────────────────────────
|
|
🔍 Getting introspect data for AMAZON...
|
|
❌ AMAZON: Failed to get introspect data - service not configured
|
|
|
|
──────────────────────────────────────────────────
|
|
🔍 Getting introspect data for DEEZER...
|
|
❌ DEEZER: Service not available on this device
|
|
|
|
══════════════════════════════════════════════════
|
|
📊 Introspect Summary:
|
|
✅ Successful: 2 services
|
|
❌ Failed: 3 services
|
|
📡 Total checked: 5 services
|
|
|
|
✅ Successfully retrieved introspect data for 2 services
|
|
```
|
|
|
|
### 6. Error Handling Examples
|
|
|
|
#### Missing Source Parameter
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
NAME:
|
|
soundtouch-cli source introspect - Get introspect data for a music service
|
|
|
|
USAGE:
|
|
soundtouch-cli source introspect [command options]
|
|
|
|
OPTIONS:
|
|
--account value, -a value Source account name (optional)
|
|
--source value, -s value Music service source (SPOTIFY, PANDORA, TUNEIN, etc.)
|
|
--help, -h show help
|
|
|
|
Required flag "source" not set
|
|
```
|
|
|
|
#### Missing Host Parameter
|
|
```bash
|
|
$ soundtouch-cli source introspect --source SPOTIFY
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
host is required. Use --host flag or set SOUNDTOUCH_HOST environment variable
|
|
```
|
|
|
|
#### Invalid Service
|
|
```bash
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect --source INVALID_SERVICE
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
|
|
🔗 Connecting to SoundTouch device at 192.168.1.100:8090
|
|
|
|
⚠️ Service INVALID_SERVICE may not be available, but continuing with introspect request...
|
|
|
|
Getting introspect data for INVALID_SERVICE
|
|
|
|
❌ Error: failed to get introspect data: HTTP 404: endpoint not found or service not supported
|
|
```
|
|
|
|
## Integration with Other Commands
|
|
|
|
The introspect commands work well with other CLI commands:
|
|
|
|
### 1. Check Availability First
|
|
```bash
|
|
# Check what services are available
|
|
$ soundtouch-cli --host 192.168.1.100 source availability
|
|
|
|
# Then introspect specific services
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect --source SPOTIFY
|
|
```
|
|
|
|
### 2. Activate Service After Introspect
|
|
```bash
|
|
# Check service status
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect-spotify
|
|
|
|
# If inactive, activate it
|
|
$ soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
|
|
```
|
|
|
|
### 3. Compare Sources and Introspect Data
|
|
```bash
|
|
# Compare configured sources vs available services
|
|
$ soundtouch-cli --host 192.168.1.100 source compare
|
|
|
|
# Get detailed introspect data for specific services
|
|
$ soundtouch-cli --host 192.168.1.100 source introspect-all
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
The introspect commands respect the same environment variables as other CLI commands:
|
|
|
|
- `SOUNDTOUCH_HOST` - Default device IP address
|
|
- `SOUNDTOUCH_SKIP_AVAILABILITY_CHECK` - Skip service availability validation
|
|
- `SOUNDTOUCH_TIMEOUT` - Request timeout duration
|
|
|
|
**Example:**
|
|
```bash
|
|
export SOUNDTOUCH_HOST=192.168.1.100
|
|
soundtouch-cli source introspect-spotify
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### 1. Service Setup Verification
|
|
Check if streaming services are properly configured and authenticated:
|
|
```bash
|
|
soundtouch-cli --host $DEVICE source introspect-spotify
|
|
soundtouch-cli --host $DEVICE source introspect --source PANDORA
|
|
```
|
|
|
|
### 2. Troubleshooting Playback Issues
|
|
Understand why certain playback controls aren't working:
|
|
```bash
|
|
# Check if seek is supported
|
|
soundtouch-cli --host $DEVICE source introspect --source SPOTIFY | grep -i seek
|
|
|
|
# Check current playback state
|
|
soundtouch-cli --host $DEVICE source introspect-spotify | grep -i playing
|
|
```
|
|
|
|
### 3. Service Health Monitoring
|
|
Monitor the health and status of streaming services:
|
|
```bash
|
|
# Quick health check for all services
|
|
soundtouch-cli --host $DEVICE source introspect-all
|
|
|
|
# Detailed status for critical service
|
|
soundtouch-cli --host $DEVICE source introspect-spotify
|
|
```
|
|
|
|
### 4. Account Management
|
|
Verify which accounts are associated with services:
|
|
```bash
|
|
# Check current Spotify account
|
|
soundtouch-cli --host $DEVICE source introspect-spotify | grep -i user
|
|
|
|
# Check with specific account parameter
|
|
soundtouch-cli --host $DEVICE source introspect --source SPOTIFY --account specific_user
|
|
```
|
|
|
|
## Tips
|
|
|
|
1. **Use with grep**: Pipe output to `grep` to filter specific information:
|
|
```bash
|
|
soundtouch-cli --host $DEVICE source introspect-spotify | grep -E "(State|User|Playing)"
|
|
```
|
|
|
|
2. **JSON output**: While not currently implemented, future versions may support JSON output for scripting:
|
|
```bash
|
|
# Future feature
|
|
soundtouch-cli --host $DEVICE source introspect-spotify --format json
|
|
```
|
|
|
|
3. **Batch operations**: Use shell scripting to check multiple devices:
|
|
```bash
|
|
for device in 192.168.1.100 192.168.1.101; do
|
|
echo "=== Device $device ==="
|
|
soundtouch-cli --host $device source introspect-spotify
|
|
done
|
|
```
|
|
|
|
4. **Environment setup**: Set up your environment for easier usage:
|
|
```bash
|
|
export SOUNDTOUCH_HOST=192.168.1.100
|
|
alias st='soundtouch-cli'
|
|
st source introspect-spotify
|
|
```
|