playbackStatus

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.

Parameters

See the Control documentation for descriptions of parameters in the header. See the table below for descriptions of parameters in the body.
playMode

Parameter	Type	Value
`availablePlaybackActions`	object	The set of allowed transport actions as defined by the playback policies calculated by the player.
`itemId`	string	The item identifier of the current track, if the audio source is a cloud queue.
`isDucking`	Boolean	A snapshot of the player volume ducking state. When the player is ducked, it lowers the volume of one stream so that another can play over it at a louder volume. A value of true means that the player is currently ducked. A value of false means that the player is not ducked. This attribute does not generate new playbackStatus events.
`playbackState`	string	The playback state. See the list below.
`playModes`	playMode	The set of currently effective play modes for the context.
`positionMillis`	number	The offset position within the current track in milliseconds.
`previousItemId`	string	The ID of the item prior to a playback state change. This indicates what was playing when an action triggered the playbackStatus event.
`previousPositionMillis`	string	The last position in the previous item.
`queueVersion`	string	The last cloud queue change state identifier cached by the player. This could have been from: - the last GET /itemWindow or GET /version response - a loadCloudQueue or skipToItem response This is omitted when the value is unknown, for example, if the server did not respond to a query.

Playback states

Value	Definition
`PLAYBACK_STATE_BUFFERING`	The group is buffering audio. This is a transitional state before the audio starts playing.
`PLAYBACK_STATE_IDLE`	Playback is not playing or paused, such as when the queue is empty or a source cannot be paused (such as streaming radio).
`PLAYBACK_STATE_PAUSED`	Playback is paused while playing content that can be paused and resumed.
`PLAYBACK_STATE_PLAYING`	The group is playing audio.

Available playback actions

The player reports available playback actions in the playbackAction object. The player calculates the available playback actions using playback policies set for the content as well as the content type. The player sends Boolean values for the following actions:

canSkip — if true, the user can skip the content. If false, the user cannot.
canSkipBack — if true, the user can skip to the previous item. If false, the user cannot.
canSeek — if true, the user can seek within the content. If false, the user cannot.
canPause — if true, the user can pause the content and resume it later. If false, the user cannot.
canStop — if true, the user can stop the content. If false, the user cannot.
canRepeat — if true, the user can repeat the content. If false, the user cannot.
canRepeatOne — if true, the user can repeat the same content over and over again. If false, the user cannot.
canCrossfade — if true, the user can crossfade previous and successive items with the current content if with the crossfade setting. If false, the user cannot.
canShuffle — if true, the user can shuffle the content. If false, the user cannot.

Some of the playback actions correlate to playback polices. But some are related to content type. For example, users cannot skip content on live radio stations. Content partners cannot customize canStop or canPause, so they are not listed on the playback policies page.

Example

{
  "playbackState": "PLAYBACK_STATE_PLAYING",
  "positionMillis": 1,
  "itemId": "abc",
  "queueVersion": "asdf3cbjal235jazz",
  "previousItemId": "xyz",
  "previousPositionMillis": 45700,
  "playModes": {
    "repeat": false,
    "repeatOne": false,
    "crossfade": true,
    "shuffle": false
  },
  "availablePlaybackActions": {
    "canSkip": false,
    "canSkipBack": false,
    "canSeek": false,
    "canRepeat": true,
    "canRepeatOne": true,
    "canCrossfade": true,
    "canShuffle": true
  }
}