AudioPlayer 1.5
The AudioPlayer interface of the Alexa Voice Service (AVS) and exposes directives and events for capturing and interacting with audio stream.
When you ask Alexa to play music, the AudioPlayer interface monitors the resulting audio stream to make sure it plays back correctly. This includes understanding when an audio stream starts, stops, pauses, or fails.
For example, if you ask "Alexa, play my favorite 90s playlist on Amazon Music", a Play
directive starts the playlist. As it progresses, AudioPlayer reports any changes to the audio stream, allowing your device to respond appropriately. Changes might include notifying your device when the track is nearly finished, or when playback starts and stops.
This page provides reference details for AudioPlayer events and directives.
- For conceptual information about AudioPlayer events and directives, see the AudioPlayer overview.
- For information about mapping playback controls to buttons see the PlaybackController interface.
Version changes
- Support for a skill or content owner to tag an audio stream as suitable for on-device audio analysis
- CHANGED
Play
directive: addedanalyzers
list.
- CHANGED
- Support for passing HTTP header information in an audio stream, enabling DRM and other authenticated resources
- CHANGED
Play
directive: addedhttpHeaders
object toaudioItem.stream
object.
- CHANGED
- Support for instructing a device to end playback of an audio stream ahead of the stream's full length
- CHANGED
Play
directive: addedendOffsetInMilliseconds
field toaudioItem.stream
object.
- CHANGED
Capability assertion
A device can implement Alexa.SoftwareComponentReporter 1.0 on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery. However, Alexa continues to support existing integrations using the Capabilities API.
Sample object
{ "type": "AlexaInterface", "interface": "AudioPlayer", "version": "1.4", "configurations": { "fingerprint": { "package": "{{STRING}}", "buildType": "{{STRING}}", "versionNumber": "{{STRING}}" } } }
fingerprint
Parameter | Description | Type |
---|---|---|
package |
Unique identifier for the audio player software loaded on the device. Must follow a reverse-DNS naming scheme. For example, |
string |
buildType |
The audio player build type. |
string |
versionNumber |
Identifies the version of the audio player loaded on your device. Must be a positive, signed 32-bit long value, represented as a string. |
string |
Context
Context is a container that communicates the state of your clients components to AVS. Context should reflect your components right before an event fired.
To learn more about reporting Context, see Context Overview.
Example message
{ "header": { "namespace": "AudioPlayer", "name": "PlaybackState" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playerActivity": "{{STRING}}", "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } }
Player activity
Parameter | Description |
---|---|
IDLE |
Nothing playing and there are no enqueued items. AudioPlayer is only in an IDLE state when a product is initially powered on or rebooted and before acting on a |
PLAYING |
Stream is playing. AudioPlayer must transition from an IDLE state to PLAYING when your client initiates playback of an audio stream. AudioPlayer must remain in the playing-state when:
|
PAUSED |
Stream paused. AudioPlayer must transition to the PAUSED state when audio on the Content channel is paused to accommodate a higher priority input/output such as user or Alexa speech. Playback must resume when the prioritized activity completes. For more details on prioritizing audio input/outputs, see Interaction Model. |
BUFFER_UNDERRUN |
AudioPlayer must transition to the BUFFER_UNDERRUN state when the client is fed data slower than it's read. AudioPlayer must remain in this state until the buffer is full enough to resume playback, at which point it must return to the PLAYING state. |
FINISHED |
Stream finished playing. When a stream is finished playing, AudioPlayer must transition to the FINISHED state. This is true for every stream in your playback queue. Even if there are streams queued to play, your client is required to send a |
STOPPED |
Stream interrupted. There are four instances when AudioPlayer must transition to the STOPPED state:
|
Directives
Play
When your device first powers on, it waits in an idle state until it receives a Play
directive from AVS. Play
is the first step necessary to start audio playback – think of it as the beginning of the audio transaction.
Play
is a multipart message made up of two formats, a JSON directive and one audio stream. You typically receive this directive in one the following scenarios:
- When an audio stream starts after first powering-on:
Play
transitions your device from theIDLE
state toPLAYING
state. - When an audio stream restarts after it stops:
Play
transitions your device from theSTOPPED
state to thePLAYING
state. - When an audio stream receives a change request:
Play
sends with aplayBehavior
ofREPLACE_ALL
and the current audio stream gets replaced. One example of this includes if a user asks to change the song when it's playing.
expectedPreviousToken
in the stream added to the queue. If the tokens don't match, you must ignore the stream. If expectedPreviousToken
isn't returned, add the stream the playback queueExample message
JSON
{ "header": { "namespace": "AudioPlayer", "name": "Play", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "playBehavior": "{{STRING}}", "playRequestor": { "type": "{{STRING}}", "id": "{{STRING}}" }, "analyzers": { "interface": "{{STRING}}", "enabled": "{{STRING}}" }, "audioItem": { "audioItemId": "{{STRING}}", "stream": { "url": "{{STRING}}", "streamFormat": "AUDIO_MPEG", "offsetInMilliseconds": {{LONG}}, "endOffsetInMilliseconds": {{LONG}}, "expiryTime": "{{STRING}}", "caption": { "content": "{{STRING}}", "type": "{{STRING}}" }, "httpHeaders": { "key": [ { "name": "{{STRING}}", "value": "{{STRING}}" } ], "manifest": [ { "name:": "{{STRING}}", "value:": "{{STRING}}" } ], "audioSegment": [ { "name:": "{{STRING}}", "value:": "{{STRING}}" } ], "all": [ { "name:": "{{STRING}}", "value:": "{{STRING}}" } ] } }, "progressReport": { "progressReportDelayInMilliseconds": {{LONG}}, "progressReportIntervalInMilliseconds": {{LONG}} }, "token": "{{STRING}}", "expectedPreviousToken": "{{STRING}}", "interruptedBehavior": "{{STRING}}" } } }
Binary Audio Attachment
Not all Play
directives contain a binary audio attachment. If a directive includes an audio attachment, the url
value returns with a cid
prefix.
The following headers precede the binary audio attachment.
Content-Type: application/octet-stream Content-ID: {{Audio Item CID}} {{BINARY AUDIO ATTACHMENT}}
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
dialogRequestId |
A unique ID used to correlate directives sent in response to a specific |
string |
Payload parameters
Play
, and must not break if key/value pairs in the JSON are missing.Parameter | Description | Type |
---|---|---|
playBehavior |
Determines how a device handles queueing and playback of a stream. |
string |
playRequestor |
Gives the device additional metadata about what experience triggered the audio playback. |
string |
playRequestor.type |
If the audio playback wasn't triggered by a user's voice request or companion app GUI interaction, this field describes the initiating experience. |
string |
playRequestor.id |
If |
string |
analyzers |
An optional list of configuration elements that allows on-device audio analyzers to process provided audio content. |
object |
analyzers.items.interface |
The name of a capability interface under the |
string |
analyzers.items.enabled |
Enable or disable the audio analyzer specified in the interface field. |
string |
audioItem |
Contains key/value pairs for audioItems. |
object |
audioItem.audioItemId |
Identifies the audioItem. |
string |
audioItem.stream |
Contains key/value pairs for streams. |
object |
audioItem.stream.streamFormat |
The |
string |
audioItem.stream.offsetInMilliseconds |
A timestamp in milliseconds indicating where in the stream the client must start playback. For example, when |
long |
audioItem.stream.endOffsetInMilliseconds |
A timestamp in milliseconds indicating where in the stream the client must stop playback, if provided. If |
long |
audioItem.stream.expiryTime |
The date and time in ISO 8601 format for when the stream becomes invalid. |
string |
audioItem.stream.progressReport |
Contains key/value pairs for progress reports. |
object |
audioItem.stream.progressReport.progressReportDelayInMilliseconds |
Specifies in milliseconds when to send the |
long |
audioItem.stream.progressReport.progressReportIntervalInMilliseconds |
Specifies in milliseconds when to emit a |
long |
audioItem.stream.caption |
Generates captions for the attached audio content. |
object |
audioItem.stream.caption.type |
The caption format. |
object |
audioItem.stream.caption.content |
The time-encoded caption text for the attached audio content. |
string |
audioItem.stream.httpHeaders |
Instructs a device to send specific HTTP headers when fetching the audio stream of a |
object |
audioItem.stream.httpHeaders.key |
List of headers used when fetching encryption keys. Maximum of 20 name:value pairs. |
list |
audioItem.stream.httpHeaders.key.name |
Encryption |
string |
audioItem.stream.httpHeaders.key.value |
Encryption |
string |
audioItem.stream.httpHeaders.manifest |
List of headers used when fetching manifests and variants of a playlist. Maximum of 20 name:value pairs. |
list |
audioItem.stream.httpHeaders.manifest.name |
|
string |
audioItem.stream.httpHeaders.manifest.value |
|
string |
audioItem.stream.httpHeaders.audioSegment |
List of headers used when fetching audio chunks described in the |
list |
audioItem.stream.httpHeaders.audioSegment.name |
|
string |
audioItem.stream.httpHeaders.audioSegment.value |
|
string |
audioItem.stream.httpHeaders.all |
A catch-all list of headers names that get passed into all URL requests. Maximum of 20 name:value pairs. |
list |
audioItem.stream.httpHeaders.all.name |
|
string |
audioItem.stream.httpHeaders.all.value |
|
string |
audioItem.stream.token |
An opaque token that represents the current stream. |
string |
audioItem.stream.expectedPreviousToken |
An opaque token that represents the expected previous stream. |
string |
audioItem.stream.interruptedBehavior |
Specify how your device responds when playback gets interrupted. |
string |
Support for passing HTTP header in an audio stream
When parsing playlists, Alexa uses several categories of derived URLs. These URLs are for obtaining encryption keys, for manifests, and for audio segments. These categories form the groups for the HTTP headers that can be added to the play directive.
The httpHeaders
is a JSON object that nests the headers in "key"
,"manifest"
, "audioSegment"
and "all"
categories. When present in a play directive, it determines headers to be added to URL requests when processing the play directive.
Example httpHeaders object
"httpHeaders": { "key": [ { "name": "Authorization", "value": "ejtsN6..." }, ... ], "manifest": [ { "name": "Authorization", "value": "ejtsN6..." }, ... ], "audioSegment": [ { "name": "Authorization", "value": "ejtsN6..." }, ... ], "all": [ { "name": "Authorization", "value": "ejtsN6..." }, ... ], }
Stop
AVS sends a Stop
directive to your client to stop playback of an audio stream. You might receive a Stop
directive as the result of a voice request, a physical button press or GUI affordance.
Example message
{% raw %}{ "directive": { "header": { "namespace": "AudioPlayer", "name": "Stop", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
dialogRequestId |
A unique ID used to correlate directives sent in response to a specific |
string |
UpdateProgressReportInterval
AVS sends this directive to you to update the frequency in which you receive ProgressReportIntervalElapsed
events.
- Shorter
ProgressReportIntervalInMilliseconds
values indicates that your playback is observed. This requires frequent updates to AVS to keep different assets up-to-date. For example "Now Playing" screens. - Longer values of
ProgressReportIntervalInMilliseconds
indicates that your playback is no longer observed.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "UpdateProgressReportInterval", "messageId": "{{STRING}}", "dialogRequestId" "{{STRING}}" }, "payload": { "progressReportIntervalInMilliseconds": {{LONG}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
progressReportIntervalInMilliseconds |
Starting offset for the duration of playback being reported. |
long |
ClearQueue
AVS sends the ClearQueue
directive to your client to clear the playback queue.
The ClearQueue
directive has two behaviors:
CLEAR_ENQUEUED
: Clears the queue and continues to plays the stream.CLEAR_ALL
: clears the entire playback queue and stops the playing stream. A player should transition to an IDLE state after it handles aCLEAR_ALL
directive and sends aPlaybackQueueCleared
event.
Example message
{ "directive": { "header": { "namespace": "AudioPlayer", "name": "ClearQueue", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "clearBehavior": "{{STRING}}" } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
dialogRequestId |
A unique ID used to correlate directives sent in response to a specific |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
clearBehavior |
A string value used to determine clear queue behavior. |
string |
Events
PlaybackStopped
Send this event to AVS when your client receives one of the following directives and stops playback of an audio stream:
- A
Stop
directive. - A
Play
directive with aplayBehavior
ofREPLACE_ALL
. - A
ClearQueue
directive with aclearBehavior
ofCLEAR_ALL
.
PlaybackFinished
.Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackStopped", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} }, "playbackReports": [ { "startOffsetInMilliseconds": {{LONG}}, "endOffsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } }, ... ] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
playbackReports |
A batch of objects representing metadata about playback after the last |
list |
playbackReports[i].startOffsetInMilliseconds |
Starting offset for the duration of playback being reported. |
long |
playbackReports[i].endOffsetInMilliseconds |
Ending offset for the duration of playback being reported. |
long |
playbackReports[i].playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackReports[i].playbackAttributes.codec |
Encoding of the stream. |
string |
playbackReports[i].playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackReports[i].playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackPaused
Send this event to AVS when your client temporarily pauses audio on the Content channel to accommodate a higher priority input/output. Resume Playback when the prioritized activity completes by sending a PlaybackResumed
event. For more information on prioritizing audio input/outputs, see Interaction Model.
PlaybackPaused
after a Recognize
event to reduce latency.Sample Message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackPaused", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are invalid. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackStarted
A PlaybackStarted
event informs AVS that your device has actually started the playback of an audio stream. Send the PlaybackStarted
to AVS after you processes a Play
directive.
PlaybackStarted
event per URL. If you receive a playlist URL (composed of multiple URLs) only send one PlaybackStarted
event.Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackStarted", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are invalid. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackNearlyFinished
A PlaybackNearlyFinished
event informs AVS that when your device has almost finished an audio stream.
Send a PlaybackNearlyFinished
event when your device is ready to buffer/download the next stream in your playback queue. Only send this event after you"ve sent a PlaybackStarted
event. Alexa responds to PlaybackNearlyFinished
with one of the following:
- A
Play
directive containing the next stream. - An HTTP 204 response code.
PlaybackNearlyFinished
event to AVS. This lowers the risk of exceeding the expiryTime
and can reduce the frequency of playback stutters that might occur when downloading and processing more than one Play
directives at the same time.Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackNearlyFinished", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are invalid. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
ProgressReportDelayElapsed
Send the ProgressReportDelayElapsed
event to AVS if your Play
directive has the a progressReportDelayInMilliseconds
parameter. Send this event at the specified interval from the start of the stream, not from a Play
offset value contained in offsetInMilliseconds
:
- If the
Play
directive containsprogressReportDelayInMilliseconds
with a value of20000
, send theProgressReportDelayElapsed
event with a value of 20,000 milliseconds from the start of the track. - If the
Play
directive contains anoffsetInMilliseconds
value of10000
andprogressReportDelayInMilliseconds
value20000
, send theProgressReportDelayElapsed
with a value of 10,000 milliseconds into playback.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "ProgressReportDelayElapsed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
ProgressReportIntervalElapsed
The ProgressReportIntervalElapsed
event is in place to confirm that the UpdateProgressReportInterval
directive is received and processed. This event sends in response to receiving a UpdateProgressReportInterval
directive.
You only send the ProgressReportIntervalElapsed
event to AVS if your Play
directive has the a progressReportDelayInMilliseconds
parameter. Send this event at the specified interval from the start of the stream, not from Plays
offset value contained in offsetInMilliseconds
For Example:
- If the
Play
directive containsprogressReportIntervalInMilliseconds
with a value of20000
, send theProgressReportIntervalElapsed
event with a value of 20,000 milliseconds from the start of the track. - If the
Play
directive contains anoffsetInMilliseconds
value of10000
andprogressReportIntervalInMilliseconds
value20000
, send theProgressReportIntervalElapsed
with a value of 10,000 milliseconds into playback.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "ProgressReportIntervalElapsed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}" "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} }, "playbackReports": [ { "startOffsetInMilliseconds": {{LONG}}, "endOffsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } }, ... ] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the Now Playing section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
playbackReports |
A batch of objects representing metadata about playback since the last |
list |
playbackReports[i].startOffsetInMilliseconds |
Starting offset for the duration of playback being reported.. |
long |
playbackReports[i].endOffsetInMilliseconds |
Ending offset for the duration of playback being reported.. |
long |
playbackReports[i].playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackReports[i].playbackAttributes.codec |
Encoding of the stream. |
string |
playbackReports[i].playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackReports[i].playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
ProgressReportIntervalUpdated
Send the ProgressReportIntervalUpdated
to AVS after your handle a UpdateProgressReportInterval
directive.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "ProgressReportIntervalUpdated", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes |
Identifies specific parameters of an incoming audio stream |
object |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream played. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio played. Hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio played. Bits-per-second. |
long |
PlaybackStutterStarted
If your AudioPlayer component receives data slower than it's able to read the data, you must send a PlaybackStutterStarted
event.
- Send this event after a
PlaybackStarted
event. - After AudioPlayer receives this event, transition it the buffer_underrun state.
- AudioPlayer must remain in the buffer_underrun state until the buffer is full enough to resume playback.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackStutterStarted", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackStutterFinished
Send the PlaybackStutterFinished
to AVS when the buffer is full enough to resume playback of a stream. When audio playback resumes, you don"t have to send another PlaybackStarted
.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackStutterFinished", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "stutterDurationInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
stutterDurationInMilliseconds |
Identifies the duration of a stutter in milliseconds. |
long |
playbackAttributes |
Identifies specific parameters of an incoming audio stream |
object |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackFinished
Send this to AVS when your client finishes playback of a stream. After the player transitions to the FINISHED state and emits a PlaybackFinished
event for the final track in a play queue, it can optionally transition to the IDLE state.
This event is not sent when:
- Playback stops. Either locally or as the result of a
Stop
directive. - Navigating between streams. For example, next and previous.
PlaybackFinished
event per URL. If you receive a playlist URL (composed of multiple URLs) only send one PlaybackFinished
eventExample message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackFinished", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} }, "playbackReports": [ { "startOffsetInMilliseconds": {{LONG}}, "endOffsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } }, ... ] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream.
|
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
playbackReports |
A batch of objects representing metadata about playback since the last |
list |
playbackReports[i].startOffsetInMilliseconds |
Starting offset for the duration of playback being reported. |
long |
playbackReports[i].endOffsetInMilliseconds |
Ending offset for the duration of playback being reported. |
long |
playbackReports[i].playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackReports[i].playbackAttributes.codec |
Encoding of the stream. |
string |
playbackReports[i].playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackReports[i].playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackFailed
Send this event to AVS whenever you encounter an error while attempting to play a stream. In cases where a stream is playing and the next stream fails to buffer, the currentPlaybackToken
might be different from the token
in the payload.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackFailed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "currentPlaybackState": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playerActivity": "{{STRING}}", "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } }, "error": { "type": "{{STRING}}", "message": "{{STRING}}" }, "playbackReports": [ { "startOffsetInMilliseconds": {{LONG}}, "endOffsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}", "samplingRateInHertz": {{LONG}}, "dataRateInBitsPerSecond": {{LONG}} } }, ... ] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
currentPlaybackState.token |
An opaque token provided by the |
string |
currentPlaybackState.offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values are not accepted. |
long |
currentPlaybackState. |
Identifies the player state.
|
string |
currentPlaybackState.playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
currentPlaybackState.playbackAttributes.codec |
Encoding of the stream. |
string |
currentPlaybackState.playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
currentPlaybackState.playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
error.type |
Identifies the specific type of error. The table below provides details for each error type. |
string |
error.message |
A description of the error the device has encountered. This is used for logging purposes only. For HTTP related errors, the error message should contain the HTTP error response body if present. |
string |
playbackReports |
A batch of objects representing metadata about playback since the last |
list |
playbackReports[i].startOffsetInMilliseconds |
Starting offset for the duration of playback being reported. |
long |
playbackReports[i].endOffsetInMilliseconds |
Ending offset for the duration of playback being reported. |
long |
playbackReports[i].playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackReports[i].playbackAttributes.codec |
Encoding of the stream. |
string |
playbackReports[i].playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackReports[i].playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
Error Types
Parameter | Description |
---|---|
MEDIA_ERROR_UNKNOWN |
An unknown error occurred. |
MEDIA_ERROR_INVALID_REQUEST |
The server recognized the request as being malformed. For example, bad request, unauthorized, forbidden, not found, etc. |
MEDIA_ERROR_SERVICE_UNAVAILABLE |
The client was unable to reach the service. |
MEDIA_ERROR_internal_SERVER_ERROR |
The server accepted the request, but was unable to process the request as expected. |
MEDIA_ERROR_internal_DEVICE_ERROR |
There was an internal error on the client. |
PlaybackResumed
Send this event to AVS when playback resumes following a PlaybackPaused
event. For more information on prioritizing audio input/outputs, see the Interaction Model.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackResumed", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "offsetInMilliseconds": {{LONG}}, "playbackAttributes": { "name": "{{STRING}}", "codec": "{{STRING}}" "samplingRateInHertz": {{LONG}} "dataRateInBitsPerSecond": {{LONG}} } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided in the |
string |
offsetInMilliseconds |
Identifies a track's current offset in milliseconds. The value sent must be equal to or greater than zero. Negative values aren't accepted. |
long |
playbackAttributes.name |
Identifier for an audio representation played from manifest, for ABR stream formats. Used to display an audio quality badge in the "Now Playing" section. |
string |
playbackAttributes.codec |
Encoding of the stream. |
string |
playbackAttributes.samplingRateInHertz |
Sampling rate for the audio in hertz. |
long |
playbackAttributes.dataRateInBitsPerSecond |
Bit rate for the audio in bits per second. |
long |
PlaybackQueueCleared
Send the PlaybackQueueCleared
event to AVS after your client handles a CLEAR_ALL
ClearQueue
directive.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "PlaybackQueueCleared", "messageId": "{{STRING}}" }, "payload": { } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Send an empty payload.
StreamMetadataExtracted
If you play an audio stream that contains metadata, you must translate the key/value pairs into a JSON object.
- Represent strings and numbers as JSON strings and booleans as JSON booleans.
- Filter out any tags containing binary data. For example, don't send the image, image preview, attachment, or application data tags to AVS.
Example message
{ "event": { "header": { "namespace": "AudioPlayer", "name": "StreamMetadataExtracted", "messageId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "metadata": { "{{STRING}}": "{{STRING}}", "{{STRING}}": {{BOOLEAN}}, "{{STRING}}": "{{string NUMBER}}" } } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
An opaque token provided by the |
string |
metadata |
Contains key/value pairs associated with the metadata received. |
object |
Last updated: May 25, 2023