Sonos

App · 20 actions

Control playback, volume, favorites and playlists on your Sonos speakers.

Actions

ActionWhat it does
Get group volumegetVolume.
Get playback metadatagetMetadataStatus.
Get playback statusgetPlaybackStatus.
Get player volumegetVolume.
List favoritesgetFavorites.
List groups and playersgetGroups.
List householdsgetHouseholds.
List playlistsgetPlaylists.
Load favoriteloadFavorite.
Load playlistloadPlaylist.
Pausepause.
Playplay.
Seek in trackseek.
Set group mutesetMute.
Set group volumesetVolume.
Set play modessetPlayModes.
Set player mutesetMute.
Set player volumesetVolume.
Skip to next trackskipToNextTrack.
Skip to previous trackskipToPreviousTrack.

Get group volume

getVolume.

Inputs

Householdhousehold_idtextRequired
Household ID.
Groupgroup_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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_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

Householdhousehold_idtextRequired
Household ID.
Playerplayer_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

Householdhousehold_idtextRequired
Target householdId

Outputs

dataobject
No description available
Example output
{
  "data": {
    "items": [],
    "version": "example"
  }
}

List groups and players

getGroups.

Inputs

Include device infoinclude_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.
Householdhousehold_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 onlyconnected_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

Householdhousehold_idtextRequired
Target householdId

Outputs

dataobject
No description available
Example output
{
  "data": {
    "playlists": [],
    "version": "example"
  }
}

Load favorite

loadFavorite.

Inputs

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
Favoritefavorite_idtextRequired
The identifier of the favorite. You can find this in the favoriteList object in the getFavorites response.
Operationoperationtext
No description availableOne of: REPLACE, APPEND, INSERT, INSERT_NEXT (Insert next), PLAY_NOW (Play now).
Play on completionplay_on_completiontrue/false
(Optional) If true, the player automatically starts playback. If false or not provided, the player remains in the PLAYBACK_IDLE state.
Repeatrepeattrue/false
Repeat.
Repeat onerepeat_onetrue/false
Repeat one.
Shuffleshuffletrue/false
Shuffle.
Crossfadecrossfadetrue/false
Crossfade.

Outputs

dataobject
This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
  "data": {}
}

Load playlist

loadPlaylist.

Inputs

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
Playlistplaylist_idtextRequired
The identifier of the playlist. You can find this in the playlistsList object in the getPlaylists response.
Operationoperationtext
No description availableOne of: REPLACE, APPEND, INSERT, INSERT_NEXT (Insert next), PLAY_NOW (Play now).
Play on completionplay_on_completiontrue/false
(Optional) If true, the player automatically starts playback. If false or not provided, the player remains in the PLAYBACK_IDLE state.
Repeatrepeattrue/false
Repeat.
Repeat onerepeat_onetrue/false
Repeat one.
Shuffleshuffletrue/false
Shuffle.
Crossfadecrossfadetrue/false
Crossfade.

Outputs

dataobject
This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
  "data": {}
}

Pause

pause.

Inputs

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId

Outputs

dataobject
This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
  "data": {}
}

Play

play.

Inputs

Householdhousehold_idtextRequired
Household ID.
Groupgroup_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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
Item IDitem_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 millisposition_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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
Mutedmutedtrue/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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
VolumevolumenumberRequired
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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId
Repeatrepeattrue/false
Repeat.
Repeat onerepeat_onetrue/false
Repeat one.
Shuffleshuffletrue/false
Shuffle.
Crossfadecrossfadetrue/false
Crossfade.

Outputs

dataobject
Sonos response data.
Example output
{
  "data": {}
}

Set player mute

setMute.

Inputs

Householdhousehold_idtextRequired
Household ID.
Playerplayer_idtextRequired
Target playerId
Mutedmutedtrue/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

Householdhousehold_idtextRequired
Household ID.
Playerplayer_idtextRequired
Target playerId
Volumevolumenumber
(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.
Mutedmutedtrue/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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_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

Householdhousehold_idtextRequired
Household ID.
Groupgroup_idtextRequired
Target groupId

Outputs

dataobject
This object represents an empty (default) success. The platform returns an empty object ({}).
Example output
{
  "data": {}
}

On this page