Bose-SoundTouch/examples/introspect/cli-demo.md

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

$ soundtouch-cli --host 192.0.2.100 source introspect --source SPOTIFY

Expected Output:

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

$ soundtouch-cli --host 192.0.2.100 source introspect --source SPOTIFY --account my_spotify_user

Expected Output:

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

$ soundtouch-cli --host 192.0.2.100 source introspect-spotify

Expected Output:

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

$ soundtouch-cli --host 192.0.2.100 source introspect-spotify

Expected Output (when Spotify is not set up):

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

$ soundtouch-cli --host 192.0.2.100 source introspect-all

Expected Output:

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

$ soundtouch-cli --host 192.0.2.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

$ soundtouch-cli source introspect --source SPOTIFY

Output:

host is required. Use --host flag or set SOUNDTOUCH_HOST environment variable

Invalid Service

$ soundtouch-cli --host 192.0.2.100 source introspect --source INVALID_SERVICE

Expected Output:

⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ SoundTouch CLI v1.0.0
🔗 Connecting to SoundTouch device at 192.0.2.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

# Check what services are available
$ soundtouch-cli --host 192.0.2.100 source availability

# Then introspect specific services
$ soundtouch-cli --host 192.0.2.100 source introspect --source SPOTIFY

2. Activate Service After Introspect

# Check service status
$ soundtouch-cli --host 192.0.2.100 source introspect-spotify

# If inactive, activate it
$ soundtouch-cli --host 192.0.2.100 source select --source SPOTIFY

3. Compare Sources and Introspect Data

# Compare configured sources vs available services
$ soundtouch-cli --host 192.0.2.100 source compare

# Get detailed introspect data for specific services
$ soundtouch-cli --host 192.0.2.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:

export SOUNDTOUCH_HOST=192.0.2.100
soundtouch-cli source introspect-spotify

Use Cases

1. Service Setup Verification

Check if streaming services are properly configured and authenticated:

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:

# 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:

# 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:

# 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:

   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:

   # Future feature
   soundtouch-cli --host $DEVICE source introspect-spotify --format json
   

3. Batch operations: Use shell scripting to check multiple devices:

   for device in 192.0.2.100 192.0.2.101; do
     echo "=== Device $device ==="
     soundtouch-cli --host $device source introspect-spotify
   done
   

4. Environment setup: Set up your environment for easier usage:

   export SOUNDTOUCH_HOST=192.0.2.100
   alias st='soundtouch-cli'
   st source introspect-spotify