Play music on Sonos from a routine

Play music on Sonos from a routine lets a developer add a music step in the routine editor, choose a speaker in the current home, pick music from the modes that speaker supports, and optionally set volume. Selection is read-only: nothing plays while the user is choosing, and the chosen music starts only when the routine executes.

What the editor shows

The web console and mobile routine editors both expose Play music on Sonos. They present the same saved action, so a routine created in either client behaves the same at execution time. The speaker is selected first, and changing the home or speaker clears the previous selection. The source options are drawn from the speaker’s reported sourceModes, so only supported modes appear.

The phone uses a row of speaker cards, not a dropdown, and a row of three source chips for the available modes: library, search, and on the speaker. Results appear as cards with artwork when available; if an item has no art, it uses a note glyph. Volume is optional and defaults to leaving the speaker where it is. If volume is off, the action carries no volume key.

Music sources

Spotify library

This mode lists Liked Songs, playlists, and followed artists from the connected Spotify integration. More music loads later pages. A followed artist plays as its top tracks. This mode requires a connected Spotify integration.

Search Spotify

This mode searches songs, playlists, albums, or artists through the connected account. Search runs on submission, not on every keystroke. The results show title, artwork when available, and artist or owner when available. The routine stores the selected URI, not the search text, so the query is not repeated when the routine runs.

Sonos favourites / radio

This mode lists the selected speaker’s last reported favourites. This is the path for existing radio stations. Catalog search does not create radio stations. At execution time, the Sonos connector validates the selected favourite against a fresh list.

Account and speaker rules

Spotify library and search require a connected Spotify integration. Playback uses the Spotify account already connected in the Sonos app. An item visible to a different Spotify account may not be playable by that Sonos account.

The speaker must be assigned to a room in the selected home. The selected speaker determines the available modes, and missing capabilities fail closed. A local speaker supports all three modes. A cloud speaker offers only Sonos favourites and playlists, including radio or Spotify content already saved in Sonos. The cloud API cannot play a bare Spotify URI from ALYT search.

Changing the account, speaker, source, or submitted search clears the previous selection. Changing the home also clears it. A speaker whose stored transport disagrees with the home is omitted from the available list.

Routine action contract

The routine create and update routes accept this action in the do list:

{
  "kind": "music",
  "speakerId": "11111111-1111-4111-8111-111111111111",
  "uri": "spotify:playlist:37i9dQZF1DX4WYpdgoIcn6",
  "name": "Selected playlist",
  "volume": 18
}

The uri must be a supported local Spotify URI or FV: favourite, or a cloud sonos:favorite:<id> / sonos:playlist:<id> that belongs to the selected Sonos household. The name is display metadata only and grants no access. volume is optional, must be an integer from 0 to 100, and omission leaves the current volume unchanged.

Execution and limits

The server checks the speaker’s tenant, property, enabled state, and Sonos integration both on save and immediately before playback. Moving a speaker cannot move a routine’s authority with it. Music is an execution barrier: earlier device changes complete first, volume is applied before the source, and later steps follow playback’s response.

Music is never deduplicated against a remembered source, and it is not retried after an ambiguous timeout. A playing read-back is required for a successful music step. If playback fails, the failure is recorded and later routine steps continue. Run history includes the music and speaker names.

Music actions execute on the platform and are excluded from hub-only execution because the hub firmware has no music action. This does not add offline Spotify playback. Local functions can keep working during a cloud outage, but cloud-dependent connectors require the provider and network.

API access

GET /properties/{propertyId}/routines/music?tenantId=... requires view permission on the property. It returns enabled, connected Sonos speakers placed in that home, each speaker’s sourceModes and favourite choices, and the household’s connected Spotify accounts. Credentials are excluded.

GET /integrations/{integrationId}/search?tenantId=...&q=...&type=track requires view access to the integration’s household. The type is track, playlist, album, or artist. It returns the existing music list envelope with up to ten results and a nextCursor. The cursor is bound to the query and type, and the maximum offset is 1000. Expired sessions are refreshed and stored before the result is returned; revoked access and rate limits produce an error.

The routine editors use the same underlying behaviour as the API contract, so a saved selection remains stable until the user changes the account, speaker, source, search, or home.