sonos-control（索诺斯控制）

Sonos Control

Overview

This skill provides comprehensive control over Sonos speaker systems through MCP tools. Use it to search for and play music, manage playback queues and playlists, control volume, and switch between speakers. The skill handles both simple requests ("play some Neil Young") and complex multi-step workflows ("create a mix of 5 tracks from these artists").

Core Principle: Multi-Step Workflows

Most music requests require multiple tool calls in sequence. Execute workflows automatically without asking permission at each step - just complete the workflow and confirm the result.

Critical Rule: Search results are ephemeral. After using search_for_track or search_for_album, immediately select and add desired tracks/albums to the queue before executing another search, as each new search clears previous results.

Available MCP Tools

Speaker Management

• sonos:get_master_speaker - Get current active speaker name
• sonos:set_master_speaker - Switch to a different speaker (e.g., "Bedroom", "Kitchen")

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