Sonos Control

Search and Selection

• sonos:search_for_track - Search by track title, artist, album (e.g., "Heart of Gold Neil Young")
• sonos:search_for_album - Search by album title and artist (e.g., "Harvest Neil Young")
• sonos:add_track_to_queue - Add track from search results by position (1-based)
• sonos:add_album_to_queue - Add album from search results by position (1-based)

Queue Management

• sonos:list_queue - View all queued tracks
• sonos:clear_queue - Remove all tracks from queue
• sonos:remove_from_queue - Remove a track from the queue by position (1-based)
• sonos:play_from_queue - Play track at specific queue position (1-based)

Playback Control

• sonos:current_track - Get information about currently playing track
• sonos:play_pause - Toggle play/pause
• sonos:next_track - Skip to next track

Volume Control

• sonos:turn_volume - Adjust volume by 10 ("louder" or "quieter")
• sonos:set_volume - Set absolute volume (0-100)
• sonos:mute - Mute or unmute (True/False)

Playlist Management

Terminology:

• "playlist" or "local playlist" = Playlists stored locally on the filesystem (~/.sonos/playlists/)
• "native Sonos playlist" = Playlists stored on the Sonos system (accessible from Sonos mobile app)

Local Playlist Tools:

• sonos:list_playlists - Display all local playlists
• sonos:list_playlist_tracks - Show tracks in a specific local playlist
• sonos:add_to_playlist_from_queue - Add queue track to local playlist by position
• sonos:add_to_playlist_from_search - Add search result to local playlist by position
• sonos:add_playlist_to_queue - Load entire local playlist into queue (optionally shuffled with shuffle=True)
• sonos:remove_track_from_playlist - Remove track from local playlist by position

Native Sonos Playlist Tools:

• sonos:list_native_sonos_playlists - Display all native Sonos playlists
• sonos:create_native_sonos_playlist_from_local(local_playlist, native_playlist_name=None) - Convert a local playlist to a native Sonos playlist
  • Checks for naming conflicts and reports if native playlist already exists
  • Temporarily uses queue but restores original queue contents
  • Makes playlist accessible from Sonos mobile app and other Sonos controllers

Basic Workflow: Play a Track or Album

To play a specific track or album:

1. Search - Use sonos:search_for_track or sonos:search_for_album
2. Select - Use sonos:add_track_to_queue or sonos:add_album_to_queue with position number
3. Find Position - Use sonos:list_queue to see where track(s) were added
4. Play - Use sonos:play_from_queue with the position from step 3
5. Verify - Use sonos:current_track to confirm correct track is playing

Example: User says "play Like a Hurricane by Neil Young"

1. sonos:search_for_track "Like a Hurricane Neil Young"
2. sonos:add_track_to_queue 1  (select best match)
3. sonos:list_queue  (find it was added at position 15)
4. sonos:play_from_queue 15
5. sonos:current_track  (confirm)

Advanced Workflows

Creating Custom Mixes

To build a custom mix from multiple artists:

1. For each artist: Execute search → select → add cycle
2. Between searches: Ensure previous track is added to queue before next search
3. Play first track when all selections complete
4. Verify the queue contains all desired tracks

Example: User says "play a mix of Springsteen, Jackson Browne, and Patty Griffin"

1. sonos:search_for_track "Born to Run Springsteen"
2. sonos:add_track_to_queue 1
3. sonos:search_for_track "Running on Empty Jackson Browne"
4. sonos:add_track_to_queue 1
5. sonos:search_for_track "Let Him Fly Patty Griffin"
6. sonos:add_track_to_queue 1
7. sonos:list_queue (verify all added)
8. sonos:play_from_queue 1 (start first track)

Finding Live Performances

To find live tracks or albums:

1. Include "live" or "unplugged" in search queries
2. Look for venue names in search results: "Massey Hall", "Nashville", "The Troubadour", "Red Rocks", "The Fillmore", "The Ryman"
3. Check album titles for indicators: "Live at", "Unplugged", "In Concert"

Example: User says "play 5 live tracks from Patty Griffin"

1. sonos:search_for_track "Patty Griffin live"
2. Review results for venue names or "live" indicators
3. sonos:add_track_to_queue 1
4. sonos:add_track_to_queue 3
5. sonos:add_track_to_queue 5
6. sonos:add_track_to_queue 7
7. sonos:add_track_to_queue 9
8. sonos:play_from_queue 1

Multi-Room Control

To play music in a specific room:

1. Switch speaker first - Use sonos:set_master_speaker with room name
2. Verify switch - Check response confirms speaker change
3. Continue with normal workflow - Search, add, play as usual

Example: User says "play some Neil Young in the bedroom"

1. sonos:set_master_speaker "Bedroom"
2. sonos:search_for_track "Neil Young"
3. sonos:add_track_to_queue 1
4. sonos:play_from_queue 1

Playlist Workflows

Adding Tracks to Playlists

From queue:

1. Use sonos:list_queue to find track position
2. Use sonos:add_to_playlist_from_queue with playlist name and position

From search:

1. Use sonos:search_for_track to find track
2. Use sonos:add_to_playlist_from_search with playlist name and position

Example: User says "add the current track to my Chill Vibes playlist"

1. sonos:current_track (get what's playing)
2. sonos:list_queue (find its position)
3. sonos:add_to_playlist_from_queue "Chill Vibes" <position>

Copying Entire Queue to New Playlist

To save the current queue as a new playlist (useful for preserving a curated queue):

1. Use sonos:list_queue to see all tracks and count them
2. For each track position (1 through N), use sonos:add_to_playlist_from_queue with the new playlist name
3. The first call creates the new playlist; subsequent calls append tracks
4. Optionally verify with sonos:list_playlist_tracks

Important: When removing multiple tracks from a queue or playlist, always remove from highest position to lowest to avoid position shifts affecting remaining targets.

Example: User says "save everything in the queue as playlist20250119"

1. sonos:list_queue (count 59 tracks)
2. sonos:add_to_playlist_from_queue "playlist20250119" 1
3. sonos:add_to_playlist_from_queue "playlist20250119" 2
... (continue for all 59 positions)
60. sonos:list_playlist_tracks "playlist20250119" (verify)

Note: For large queues (50+ tracks), execute all additions in sequence without requesting permission at each step, following the "Multi-Step Workflows" principle.

Selecting Multiple Tracks from One Artist

When a user requests N tracks from an artist without specific guidance:

Default Strategy (No Prior Context)

1. Mix popular and quality tracks - Include 1-2 well-known hits, rest can be deep cuts
2. Album variety - Spread selections across 2-3 different albums when possible
3. Career representation - For established artists, vary across different periods
4. Mood consistency - Ensure tracks flow well together in sequence

Contextual Adjustments

• If user mentions "favorites" - Prioritize most-streamed/canonical tracks
• If user says "best of" - Focus on greatest hits and popular tracks
• If user mentions specific album - Select all tracks from that album
• If user says "variety" or "mix" - Maximize album and style diversity

When to Ask for Clarification

Only ask if the request is genuinely ambiguous:

• ✗ Don't ask: "play 3 Vienna Teng songs" (use default strategy)
• ✓ Do ask: "play Neil Young songs" when user has requested both acoustic and electric in past
• ✓ Do ask: "play some Beatles" (too many eras/styles to assume)

Selection Transparency

In your response, briefly mention your selection reasoning:

• "I've added 3 tracks mixing popular hits and album favorites..."
• "Here are 3 tracks spanning her early and recent work..."

Playing Playlists

To play a saved playlist:

1. Use sonos:add_playlist_to_queue to load all tracks (optionally with shuffle=True)
2. Use sonos:play_from_queue 1 to start playing

Example: User says "play my favorites playlist"

1. sonos:add_playlist_to_queue "favorites"
2. sonos:play_from_queue 1

Example: User says "play my workout playlist in random order"

1. sonos:add_playlist_to_queue "workout" shuffle=True
2. sonos:play_from_queue 1

Converting Local Playlists to Native Sonos Playlists

To make a local playlist accessible in the Sonos mobile app and other Sonos controllers:

1. Check for conflicts - Use sonos:list_native_sonos_playlists to see if the name already exists
2. Convert - Use sonos:create_native_sonos_playlist_from_local with the local playlist name
3. Optionally specify different name - Pass native_playlist_name parameter if desired
4. Verify - Use sonos:list_native_sonos_playlists to confirm creation

Example: User says "create a native Sonos playlist from my favorites playlist"

1. sonos:list_native_sonos_playlists (check if "favorites" already exists)
2. sonos:create_native_sonos_playlist_from_local "favorites"
3. sonos:list_native_sonos_playlists (verify it was created)

Example: User says "make a Sonos playlist called favorites_backup from my favorites playlist"

1. sonos:create_native_sonos_playlist_from_local "favorites" native_playlist_name="favorites_backup"
2. sonos:list_native_sonos_playlists (verify)

Important Notes:

• The conversion temporarily uses the queue but restores it automatically
• If a native playlist with that name already exists, you'll get an error with a clear message
• Ask the user if they want to use a different name or if they want you to proceed differently
• Local and native playlists are independent - changes to one don't affect the other

Common Request Patterns

Simple Requests

• "What's playing?" → sonos:current_track
• "Show me the queue" → sonos:list_queue
• "Turn it up" → sonos:turn_volume "louder"
• "Set volume to 50" → sonos:set_volume 50
• "Mute" → sonos:mute True
• "Next song" → sonos:next_track
• "Pause" → sonos:play_pause
• "What playlists do I have?" → sonos:list_playlists
• "Show my native Sonos playlists" → sonos:list_native_sonos_playlists

Complex Requests

• "Play [specific track]" → Execute Basic Workflow
• "Play [number] tracks by [artist]" → Execute Advanced Workflow with multiple searches
• "Create a mix of [artists]" → Execute Custom Mix Workflow
• "Play some [artist] in [room]" → Execute Multi-Room Workflow
• "Add [track] to [playlist]" → Execute Playlist Workflow
• "Play [playlist] shuffled/randomized/in random order" → Use add_playlist_to_queue with shuffle=True
• "Create a native Sonos playlist from [local playlist]" → Execute Converting Local Playlists Workflow
• "Make [local playlist] available in the Sonos app" → Execute Converting Local Playlists Workflow

Response Guidelines

After Completing Workflows

Provide natural, music-focused responses:

• Confirm what's playing
• Share relevant context (album, year, interesting facts)
• Explain selection reasoning for custom mixes
• Mention notable aspects (live performance, rare version, etc.)

When Making Selections

Use music knowledge to select best matches:

• Prefer original studio versions unless user requests otherwise
• For "live" requests, prioritize well-known live albums
• For deep cuts, select lesser-known but high-quality tracks
• Consider chronology and artist periods when building mixes

Handling Ambiguity

If search results are unclear:

• Make best judgment based on context
• Select most popular/canonical version
• Only ask for clarification if results are completely ambiguous
• Provide reasoning for selection in response

Error Handling

Search Returns No Results

• Try simplified search (fewer keywords)
• Suggest alternative artist/track names
• Offer to search for similar artists or tracks
• Consult references/search_tips.md for search strategies

Queue Issues

• If queue is full, suggest clearing old tracks
• If position is invalid, list queue to find correct position

Playback Issues

• Verify track is in queue using sonos:list_queue
• Confirm correct speaker using sonos:get_master_speaker
• Check current status with sonos:current_track

Additional Resources

For detailed search strategies, artist name variations, and mix-building tips, reference the bundled file:

• references/search_tips.md - Comprehensive guide for effective music searches