Start

Quickstart

GitHub Edit page

Quickstart

This walks through the moves you'll use every day. Replace Kitchen / Living Room with your actual room names.

#1. Discover speakers

sonos discover

You should see one row per visible Sonos zone, with name, model, and IP. JSON works too:

sonos discover --format json

The first run also caches speaker names so --name <Tab> autocompletes.

#Optional: Set Local Defaults

If you usually target one room, make commands shorter:

sonos config set defaultRoom "Kitchen"
sonos config set defaultTimeout 15s

defaultTimeout changes the fallback used by discovery and speaker calls when --timeout is omitted. The built-in default is 15s.

#2. Check what's playing

sonos status --name "Kitchen"
sonos now --name "Kitchen"           # alias
sonos status --name "Kitchen" --format json

status reports on the group coordinator — even if you ask a satellite, you get the truthful playback state.

#3. Control playback

sonos play  --name "Kitchen"
sonos pause --name "Kitchen"
sonos next  --name "Kitchen"
sonos prev  --name "Kitchen"
sonos volume set --name "Kitchen" 25
sonos mute toggle --name "Kitchen"

If Spotify is already linked in the Sonos app, you don't need any Spotify Web API setup:

sonos open --name "Kitchen" "https://open.spotify.com/track/6NmXV4o6bmp704aPGyTVVG"
sonos open --name "Kitchen" spotify:album:0nrRP2bk19rLc0orkWPQk2
sonos enqueue --name "Kitchen" spotify:playlist:37i9dQZF1DXcBWIGoYBM5M --next

#5. Play a URL or playlist

For YouTube, YouTube Music playlists, podcast links, radio streams, and odd formats, use the local proxy path. It resolves common media pages with yt-dlp, pipes yt-dlp sources into ffmpeg, transcodes to MP3, sends the resolved title/provider to Sonos metadata, and exits when playback ends or goes idle:

sonos play-url --name "Kitchen" "https://www.youtube.com/watch?v=-n_rdQIVahw"
sonos play-url --name "Kitchen" "https://music.youtube.com/playlist?list=PL..."
sonos play-url --name "Kitchen" --playlist-limit 10 "https://music.youtube.com/playlist?list=PL..."
sonos play-url --name "Kitchen" "https://example.com/podcast/episode.mp3"

Unambiguous YouTube / YouTube Music playlist pages (?list=… with no ?v=…) enqueue every track automatically. Use --playlist for ambiguous watch+playlist URLs, or --no-playlist when you only want the current video.

#6. Group rooms

sonos group status
sonos group join   --name "Kitchen" --to "Living Room"
sonos group party  --to "Living Room"
sonos group volume set --name "Living Room" 18
sonos group unjoin --name "Kitchen"
sonos group dissolve --name "Living Room"

#7. Save and apply scenes

A scene captures grouping plus per-room volume/mute. Save what's good now, restore it later.

sonos scene save evening
sonos scene list
sonos scene apply evening

#8. Watch live events

sonos watch --name "Kitchen"

Subscribes to AVTransport + RenderingControl and prints state changes as they arrive (Ctrl+C to stop).

#9. Search via Sonos (no Spotify credentials)

sonos smapi services
sonos smapi search --service "Spotify" --category tracks "miles davis kind of blue"
sonos play spotify --name "Kitchen" --category albums "kind of blue"

If a service needs a one-time link first:

sonos auth smapi begin    --service "Spotify"
sonos auth smapi complete --service "Spotify" --wait 2m

#Where to go next