Sonos

Control Sonos speakers through the sonos_tool command. Provides 21 discrete tools for music search, queue management, playback control, and playlists.

Quick Start

bash

# List the queue
sonos_tool list_queue

# Set volume
sonos_tool set_volume 50

# Play/pause
sonos_tool play_pause

Watching the TUI

For music searches, this skill uses a TUI (Terminal User Interface) running in tmux.

Auto-launch viewer window

Before performing a search, launch a kitty window so the user can watch (only if not already attached):

bash

# Check if any client is already attached to the sonos session
if ! tmux list-clients -t sonos 2>/dev/null | grep -q .; then
    DISPLAY=:0 kitty --title "Sonos TUI" tmux attach -t sonos &
fi

Manual attach

To manually watch searches in real-time:

bash

tmux attach -t sonos

Press Ctrl-b d to detach without stopping the TUI.

Music Search Workflow

Searches use the TUI running in tmux. This allows you to see results and verify selections.

Step 1: Ensure TUI is running

bash

sonos_tool tui_status

If not running, start it:

bash

sonos_tool tui_start

Step 2: Send search query to TUI

bash

# For albums, prefix with "album:"
tmux send-keys -t %0 "album: Artist Name Album Title" Enter

# For tracks (no prefix needed)
tmux send-keys -t %0 "Artist Name Song Title" Enter

Step 3: Wait for results

bash

sonos_tool tui_wait_for_prompt select

Step 4: View results

bash

tmux capture-pane -t %0 -p | tail -20

Step 5: Select from results

bash

# Select item 1
tmux send-keys -t %0 "1" Enter

# Or select multiple: "1 3 5"
# Or skip selection: "0"

Step 6: Wait for completion

bash

sonos_tool tui_wait_for_prompt search

Step 7: Start playback

bash

sonos_tool play_from_queue 1

Available Tools

Speaker Management

Command	Description
`sonos_tool get_master_speaker`	Get current speaker name
`sonos_tool set_master_speaker "Name"`	Change active speaker

Queue Management

Command	Description
`sonos_tool list_queue`	Show all queued tracks
`sonos_tool clear_queue`	Clear all tracks
`sonos_tool add_track_to_queue <pos>`	Add track from search results
`sonos_tool add_album_to_queue <pos>`	Add album from search results
`sonos_tool remove_from_queue <pos>`	Remove track by position
`sonos_tool play_from_queue <pos>`	Play track by position

Playback Control

Command	Description
`sonos_tool current_track`	Show what's playing
`sonos_tool play_pause`	Toggle play/pause
`sonos_tool next_track`	Skip to next track

Volume Control

Command	Description
`sonos_tool turn_volume louder`	Volume up by 10
`sonos_tool turn_volume quieter`	Volume down by 10
`sonos_tool set_volume <0-100>`	Set absolute volume
`sonos_tool mute true`	Mute speakers
`sonos_tool mute false`	Unmute speakers

Playlist Management

Command	Description
`sonos_tool list_playlists`	List local playlists
`sonos_tool list_playlist_tracks <name>`	Show tracks in playlist
`sonos_tool add_playlist_to_queue <name> [shuffle]`	Load playlist to queue
`sonos_tool add_to_playlist_from_queue <name> <pos>`	Save queue track to playlist
`sonos_tool add_to_playlist_from_search <name> <pos>`	Save search result to playlist
`sonos_tool remove_track_from_playlist <name> <pos>`	Remove from playlist

Native Sonos Playlists

Command	Description
`sonos_tool list_native_sonos_playlists`	List Sonos system playlists
`sonos_tool create_native_sonos_playlist_from_local <name> [new_name]`	Convert local to native

TUI Lifecycle

Command	Description
`sonos_tool tui_status`	Check if TUI is running
`sonos_tool tui_start`	Start TUI in tmux
`sonos_tool tui_stop`	Stop the TUI
`sonos_tool tui_wait_for_prompt <search\|select>`	Wait for TUI state

Common Workflows

Play an Album

bash

# 1. Clear queue (optional)
sonos_tool clear_queue

# 2. Start TUI if needed
sonos_tool tui_start

# 3. Search
tmux send-keys -t %0 "album: Aimee Mann Mental Illness" Enter

# 4. Wait and view results
sonos_tool tui_wait_for_prompt select
tmux capture-pane -t %0 -p | tail -15

# 5. Select album (position 1)
tmux send-keys -t %0 "1" Enter
sonos_tool tui_wait_for_prompt search

# 6. Play
sonos_tool play_from_queue 1

Load and Shuffle a Playlist

bash

sonos_tool clear_queue
sonos_tool add_playlist_to_queue favorites true
sonos_tool play_from_queue 1

Quick Playback Control

bash

sonos_tool play_pause      # Toggle play/pause
sonos_tool next_track      # Skip
sonos_tool set_volume 40   # Set volume

Important Notes

•
Queue positions are 1-indexed - Position 1 is the first track
•
Adding tracks doesn't auto-play - Always call play_from_queue after adding
•
Tracks are added to the END - Use list_queue to find the new position
•
TUI runs in tmux session "sonos" - Attach with tmux attach -t sonos to watch
•
Search results are cached - Multiple adds from same search work correctly

Troubleshooting

TUI not responding

bash

sonos_tool tui_stop
sonos_tool tui_start

Speaker connection issues

bash

sonos_tool get_master_speaker
sonos_tool set_master_speaker "SpeakerName"

Can't find tmux pane

The TUI uses pane %0 in the "sonos" session. Verify with:

bash

tmux list-panes -t sonos -F "#{pane_id}"