Sonos
App · 20 actions
Control playback, volume, favorites and playlists on your Sonos speakers.
Actions
| Action | What it does |
|---|---|
| Get group volume | getVolume. |
| Get playback metadata | getMetadataStatus. |
| Get playback status | getPlaybackStatus. |
| Get player volume | getVolume. |
| List favorites | getFavorites. |
| List groups and players | getGroups. |
| List households | getHouseholds. |
| List playlists | getPlaylists. |
| Load favorite | loadFavorite. |
| Load playlist | loadPlaylist. |
| Pause | pause. |
| Play | play. |
| Seek in track | seek. |
| Set group mute | setMute. |
| Set group volume | setVolume. |
| Set play modes | setPlayModes. |
| Set player mute | setMute. |
| Set player volume | setVolume. |
| Skip to next track | skipToNextTrack. |
| Skip to previous track | skipToPreviousTrack. |
Get group volume
getVolume.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- The groupVolume event in the groupVolume namespace indicates changes to group volume, the group mute state and whether the group volume is fixed or can be changed. When your app subscribes to the groupVolume namespace and receives this event, it can update its user interface to reflect the latest group volume and group mute state. For example, if a user configures a CONNECT to have a fixed line-out volume, your app will receive a groupVolume event with the fixed parameter value of true. Your app should then disable its volume slider so users know that volume adjustments are not permitted. Your app can expect to receive one or multiple groupVolume events associated with a single setVolume command. This is because the individual player volume changes become effective at different times, and groupVolume events may or may not be generated for each of the individual player volume changes. Your app is guaranteed to receive a final groupVolume event when all individual player volume changes are stable. See setVolume for more information on how group volume works. The group mute state is independent of the group volume value, so your app can have a separate mute button and update its state based on the muted parameter in the groupVolume event. The group coordinator also calculates the group mute state by taking into account all the individual player mute states. If all of the players in a group are muted, the muted state for the group is true. If at least one player in a group is not muted then the muted state for the group is false. See setMute for more information on the group mute state.
Example output
{
"data": {
"fixed": false,
"muted": false,
"volume": 1
}
}Get playback metadata
getMetadataStatus.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- The metadataStatus event in the playbackMetadata namespace indicates changes to the metadata for the currently playing track and the next track, if available.
Example output
{
"data": {
"container": {
"book": {
"author": {
"id": {},
"name": "example",
"tags": []
},
"chapterCount": 1,
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"name": "example",
"narrator": {
"id": {},
"name": "example",
"tags": []
}
},
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"imageUrl": "example",
"name": "example",
"podcast": {
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"name": "example",
"producer": {
"id": {},
"name": "example",
"tags": []
}
},
"service": {
"id": "example",
"imageUrl": "example",
"name": "example"
},
"tags": [],
"type": "example"
},
"currentItem": {
"deleted": false,
"id": "example",
"policies": {
"canCrossfade": false,
"canRepeat": false,
"canRepeatOne": false,
"canResume": false,
"canSeek": false,
"canShuffle": false,
"canSkip": false,
"canSkipBack": false,
"canSkipToItem": false,
"canSkipToPrevious": false,
"isVisible": false,
"limitedSkips": false,
"notifyUserIntent": false,
"pauseAtEndOfQueue": false,
"pauseOnDuck": false,
"pauseTtlSec": 1,
"playTtlSec": 1,
"refreshAuthWhilePaused": false,
"showNNextTracks": 1,
"showNPreviousTracks": 1,
"skipsRemaining": 1
},
"track": {
"album": {
"artist": {},
"id": {},
"name": "example",
"tags": []
},
"artist": {
"id": {},
"name": "example",
"tags": []
},
"author": {
"id": {},
"name": "example",
"tags": []
},
"book": {
"author": {},
"chapterCount": 1,
"id": {},
"name": "example",
"narrator": {}
},
"chapterNumber": 1,
"contentType": "example",
"durationMillis": 1,
"episodeNumber": 1,
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"imageUrl": "example",
"mediaUrl": "example",
"name": "example",
"narrator": {
"id": {},
"name": "example",
"tags": []
},
"podcast": {
"id": {},
"name": "example",
"producer": {}
},
"producer": {
"id": {},
"name": "example",
"tags": []
},
"quality": {
"bitDepth": 1,
"codec": "example",
"immersive": false,
"lossless": false,
"sampleRate": 1
},
"releaseDate": "example",
"replayGain": 1.0,
"service": {
"id": "example",
"imageUrl": "example",
"name": "example"
},
"tags": [],
"trackNumber": 1,
"type": "example"
}
},
"currentShow": {
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"imageUrl": "example",
"name": "example",
"tags": []
},
"nextItem": {
"deleted": false,
"id": "example",
"policies": {
"canCrossfade": false,
"canRepeat": false,
"canRepeatOne": false,
"canResume": false,
"canSeek": false,
"canShuffle": false,
"canSkip": false,
"canSkipBack": false,
"canSkipToItem": false,
"canSkipToPrevious": false,
"isVisible": false,
"limitedSkips": false,
"notifyUserIntent": false,
"pauseAtEndOfQueue": false,
"pauseOnDuck": false,
"pauseTtlSec": 1,
"playTtlSec": 1,
"refreshAuthWhilePaused": false,
"showNNextTracks": 1,
"showNPreviousTracks": 1,
"skipsRemaining": 1
},
"track": {
"album": {
"artist": {},
"id": {},
"name": "example",
"tags": []
},
"artist": {
"id": {},
"name": "example",
"tags": []
},
"author": {
"id": {},
"name": "example",
"tags": []
},
"book": {
"author": {},
"chapterCount": 1,
"id": {},
"name": "example",
"narrator": {}
},
"chapterNumber": 1,
"contentType": "example",
"durationMillis": 1,
"episodeNumber": 1,
"id": {
"accountId": "example",
"objectId": "example",
"serviceId": "example"
},
"imageUrl": "example",
"mediaUrl": "example",
"name": "example",
"narrator": {
"id": {},
"name": "example",
"tags": []
},
"podcast": {
"id": {},
"name": "example",
"producer": {}
},
"producer": {
"id": {},
"name": "example",
"tags": []
},
"quality": {
"bitDepth": 1,
"codec": "example",
"immersive": false,
"lossless": false,
"sampleRate": 1
},
"releaseDate": "example",
"replayGain": 1.0,
"service": {
"id": "example",
"imageUrl": "example",
"name": "example"
},
"tags": [],
"trackNumber": 1,
"type": "example"
}
},
"playbackSession": {
"accountId": "example",
"clientId": "example",
"isSuspended": false
},
"streamInfo": "example"
}
}Get playback status
getPlaybackStatus.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- The playbackStatus type in the playback namespace indicates changes to the group playback state, such as idle, buffering, paused, or playing, and the current playback position in the track. If the audio source is a cloud queue, this event also provides information about the cloud queue source, like the queueVersion and the current item’s itemId. It also can provide playback policies and modes. This object type can be a response to a command or an asynchronous event sent to apps subscribed to the playback namespace. The initial state of a group after startup is PLAYBACK_STATE_IDLE. When a user starts playing audio on a group, it transitions to PLAYBACK_STATE_BUFFERING and PLAYBACK_STATE_PLAYING, or it may skip the buffering state and go straight to playing. Depending on the audio source, pausing playback may cause the group to go to either PLAYBACK_STATE_PAUSED or PLAYBACK_STATE_IDLE. For example, streaming audio sources, such as Internet radio stations, will be in PLAYBACK_STATE_IDLE when paused. A group can also transition to PLAYBACK_STATE_IDLE after a playback error occurs. Your app will only be notified of changes to the current track position that result from any user action to seek to a new track position, a new track starting or the last track ending, or a playback error. If a track is playing normally on a group, your app will not receive playbackStatus events while the track position progresses without errors. If your app has a progress bar, you should update it with a local timer when playing normally. You will receive the item ID and offset position for the current item as well as for the previous item. For example, when a user skips from one track to another, you’ll receive the previousItemId and previousPositionMillis for the previous track, as well as the itemId and positionMillis for the currently playing track. If the user pauses the currently playing track, the previous track and position will be the same as the currently playing track and position. If the user seeks within the same track, the previous track will be the same as the currently playing track, but the position will be different.
Example output
{
"data": {
"availablePlaybackActions": {
"canCrossfade": false,
"canPause": false,
"canPlay": false,
"canRepeat": false,
"canRepeatOne": false,
"canSeek": false,
"canShuffle": false,
"canSkip": false,
"canSkipBack": false,
"canSkipToPrevious": false,
"canStop": false
},
"isDucking": false,
"itemId": "example",
"playModes": {
"crossfade": false,
"repeat": false,
"repeatOne": false,
"shuffle": false
},
"playbackState": "PLAYBACK_STATE_IDLE",
"positionMillis": 1,
"previousItemId": "example",
"previousPositionMillis": 1,
"queueVersion": "example"
}
}Get player volume
getVolume.
Inputs
- Household
household_idtextRequired - Household ID.
- Player
player_idtextRequired - Target playerId
Outputs
dataobject- The playerVolume event in the playerVolume namespace indicates changes to the volume for a player, the mute state for the player and whether the player volume is fixed or can be changed. When your app subscribes to the playerVolume namespace and receives this event, it can update its user interface to reflect the latest player volume and player mute state. For example, if a user configures a CONNECT to have a fixed line-out volume, your app will receive a playerVolume event with the fixed parameter value of true. Your app should then disable its volume slider so users know that volume adjustments are not permitted.
Example output
{
"data": {
"fixed": false,
"muted": false,
"volume": 1
}
}List favorites
getFavorites.
Inputs
- Household
household_idtextRequired - Target householdId
Outputs
dataobject- No description available
Example output
{
"data": {
"items": [],
"version": "example"
}
}List groups and players
getGroups.
Inputs
- Include device info
include_device_infotrue/false - This used to control whether the groups response contained the deviceInfo object. As of version 1.38.0, this parameter is deprecated and ignored. The groups response always includes the deviceInfo object.
- Household
household_idtextRequired - Target householdId
Outputs
dataobject- The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object.
Example output
{
"data": {
"groups": [],
"partial": false,
"players": []
}
}List households
getHouseholds.
Inputs
- Connected only
connected_onlytrue/false - Lookup all the households, connected or disconnected, when set to false.
Outputs
dataobject- This object contains a list of households.
Example output
{
"data": {
"households": []
}
}List playlists
getPlaylists.
Inputs
- Household
household_idtextRequired - Target householdId
Outputs
dataobject- No description available
Example output
{
"data": {
"playlists": [],
"version": "example"
}
}Load favorite
loadFavorite.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Favorite
favorite_idtextRequired - The identifier of the favorite. You can find this in the favoriteList object in the getFavorites response.
- Operation
operationtext - No description availableOne of:
REPLACE,APPEND,INSERT,INSERT_NEXT(Insert next),PLAY_NOW(Play now). - Play on completion
play_on_completiontrue/false - (Optional) If true, the player automatically starts playback. If false or not provided, the player remains in the PLAYBACK_IDLE state.
- Repeat
repeattrue/false - Repeat.
- Repeat one
repeat_onetrue/false - Repeat one.
- Shuffle
shuffletrue/false - Shuffle.
- Crossfade
crossfadetrue/false - Crossfade.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Load playlist
loadPlaylist.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Playlist
playlist_idtextRequired - The identifier of the playlist. You can find this in the playlistsList object in the getPlaylists response.
- Operation
operationtext - No description availableOne of:
REPLACE,APPEND,INSERT,INSERT_NEXT(Insert next),PLAY_NOW(Play now). - Play on completion
play_on_completiontrue/false - (Optional) If true, the player automatically starts playback. If false or not provided, the player remains in the PLAYBACK_IDLE state.
- Repeat
repeattrue/false - Repeat.
- Repeat one
repeat_onetrue/false - Repeat one.
- Shuffle
shuffletrue/false - Shuffle.
- Crossfade
crossfadetrue/false - Crossfade.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Pause
pause.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Play
play.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Seek in track
seek.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Item ID
item_idtext - (Optional) The identifier for the item. If included and it does not match the currently playing item, the command fails. This ensures that playback does not jump back to a track if a user starts to scrub just as the player begins to play the next item or due to latency.
- Position millis
position_millisnumberRequired - Position within track in milliseconds. If this value exceeds the current track duration time, Sonos moves to the end of the current track, which results in a skip to the next track.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Set group mute
setMute.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Muted
mutedtrue/falseRequired - The desired mute state of the group: true for muted and false for not muted.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Set group volume
setVolume.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Volume
volumenumberRequired - The new group volume as an integer between 0 and 100, inclusive. Values above this range will be rejected. Any negative value will be interpreted as setting the group volume level to 0.From 0 to 100.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Set play modes
setPlayModes.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
- Repeat
repeattrue/false - Repeat.
- Repeat one
repeat_onetrue/false - Repeat one.
- Shuffle
shuffletrue/false - Shuffle.
- Crossfade
crossfadetrue/false - Crossfade.
Outputs
dataobject- Sonos response data.
Example output
{
"data": {}
}Set player mute
setMute.
Inputs
- Household
household_idtextRequired - Household ID.
- Player
player_idtextRequired - Target playerId
- Muted
mutedtrue/falseRequired - true to mute the player or false to unmute the player.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Set player volume
setVolume.
Inputs
- Household
household_idtextRequired - Household ID.
- Player
player_idtextRequired - Target playerId
- Volume
volumenumber - (Optional) Between 0 and 100. Values above this range will be rejected. Any negative value will be interpreted as setting the volume level to 0.From 0 to 100.
- Muted
mutedtrue/false - (Optional) True to mute the player or false to unmute the player. If not specified, the existing mute state is maintained.
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Skip to next track
skipToNextTrack.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}Skip to previous track
skipToPreviousTrack.
Inputs
- Household
household_idtextRequired - Household ID.
- Group
group_idtextRequired - Target groupId
Outputs
dataobject- This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
"data": {}
}