AudioPlayer 1.5

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

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: added analyzers list.
Support for passing HTTP header information in an audio stream, enabling DRM and other authenticated resources
- CHANGED Play directive: added httpHeaders object to audioItem.stream object.
Support for instructing a device to end playback of an audio stream ahead of the stream's full length
- CHANGED Play directive: added endOffsetInMilliseconds field to audioItem.stream object.

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, `com.amazon.mediaplayer`. Devices using the same player software should populate this value with the same identifier.	string
buildType	The audio player build type. Accepted values: • `RELEASE`: production software shipped to users • `DEBUG`: beta/trial software • `EXPERIMENTAL`: internal development	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. `0` isn't a valid value.	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 `Play` directive.
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: • Reporting playback progress to AVS. • Sending stream metadata to AVS.
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 `PlaybackFinished` event to AVS, and subsequently, transition from the PLAYING state to finished when each stream is finished playing. AudioPlayer must transition from FINISHED to PLAYING when: • The client receives a `Play` directive. • The next stream in the playback queue starts playing, following a `PlaybackStarted` event.
STOPPED	Stream interrupted. There are four instances when AudioPlayer must transition to the STOPPED state: • An issue with the stream is encountered and playback fails. • The client receives a `Stop` directive from AVS. • A `ClearQueue` directive with a `clearBehavior` of `CLEAR_ALL` is received. • A `Play` directive with a `playBehavior` of `REPLACE_ALL` is received.

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 the IDLE state to PLAYING state.
When an audio stream restarts after it stops: Play transitions your device from the STOPPED state to the PLAYING state.
When an audio stream receives a change request: Play sends with a playBehavior of REPLACE_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.

Note: When adding streams to your playback queue, make sure that the token for the playing stream matches the 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 queue

Example 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": {
          "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 `Recognize` event.	string

Payload parameters

Important: Your client must accommodate and act on all payload parameters supported by 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. Possible values: • `REPLACE_ALL`: The device must (1) immediately begin playback of the new stream in this `Play` directive, (2) remove any previously enqueued streams, (3) if another stream was playing, stop it and send a corresponding `PlaybackStopped` event. • `ENQUEUE`: The device must add the new stream in this `Play` directive to the end of the current queue. • `REPLACE_ENQUEUED`: The device must replace all streams in the queue with the stream in this `Play` directive, but not interrupt any currently playing streams.	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. Possible values: • `ALERT`: the audio content is for a musical alarm	string
playRequestor.id	If `playRequestor.type` is `ALERT`, this field matches the `token` of the alarm set through the `SetAlert` directive.	string
analyzers	An optional list of configuration elements that allows on-device audio analyzers to process provided audio content. Audio Analyzers are capability interfaces that exist under the Alexa.Analyzer.Audio namespace. One such example is the `Alexa.Analyzer.Audio.PowerLevers` analyzer. This list only contains audio analyzers that are explicitly supported in Alexa.Discovery, as part of the `Discover.Response` event. The configuration is specific to the content being played by this directive and doesn't apply to subsequent `Play` requests. Any supported audio analyzer that's not explicitly permitted, through a configuration entry in this list, must not process the audio content in this directive.	object
analyzers.items.interface	The name of a capability interface under the `Alexa.Analyzers.Audio` namespace	string
analyzers.items.enabled	Enable or disable the audio analyzer specified in the interface field. Possible values: • `YES` - Enable the content analyzer and process the associated audio content. • `NO` - Disable the content analyzer and process the associated audio content.	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 `Play` directive includes the `streamFormat` in the payload when there is an associated binary audio attachment. This parameter doesn't appear if the associated audio is a stream. Accepted value: `AUDIO_MPEG`	string
audioItem.stream.offsetInMilliseconds	A timestamp in milliseconds indicating where in the stream the client must start playback. For example, when `offsetInMilliseconds` is set to `0`, this indicates playback of the stream must start at 0, or the start of the stream. Any other value indicates that playback must start from the provided offset.	long
audioItem.stream.endOffsetInMilliseconds	A timestamp in milliseconds indicating where in the stream the client must stop playback, if provided. If `endOffsetInMilliseconds` is greater than the duration of the associated stream, the client must play the entire stream.	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 `ProgressReportDelayElapsed` event to AVS. `ProgressReportDelayElapsed` must only be sent once at the specified Interval. Note: Some music providers do not require this report. If the report is not required, `progressReportDelayInMilliseconds` will not appear in the payload.	long
audioItem.stream.progressReport.progressReportIntervalInMilliseconds	Specifies in milliseconds when to emit a `ProgressReportIntervalElapsed` event to AVS. `ProgressReportIntervalElapsed` must be sent periodically at the specified Interval. Note: Some music providers do not require this report. If the report is not required, `progressReportIntervalInMilliseconds` will not appear in the payload.	long
audioItem.stream.caption	Generates captions for the attached audio content.	object
audioItem.stream.caption.type	The caption format. Possible value: WEBVTT	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 `Play` directive	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 `key` header name. Maximum length 256 characters. Accepted values: `Authorization` and strings prefixed with `x-`. For example, `x-auth-token`.	string
audioItem.stream.httpHeaders.key.value	Encryption `key` header value. Maximum length 4096 characters. For example, `ejtsN6...`	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	`manifest` header name. Maximum length 256 characters. Accepted values: `Authorization` and strings prefixed with `x-`. For example, `x-auth-token`.	string
audioItem.stream.httpHeaders.manifest.value	`manifest` header value. Maximum length 4096 characters. For example, `ejtsN6...`	string
audioItem.stream.httpHeaders.audioSegment	List of headers used when fetching audio chunks described in the `manifest`. Maximum of 20 name:value pairs.	list
audioItem.stream.httpHeaders.audioSegment.name	`audioSegment` header name. Maximum length 256 characters. Accepted values: `Authorization` and strings prefixed with `x-`. For example, `x-auth-token`.	string
audioItem.stream.httpHeaders.audioSegment.value	`audioSegment` header value. Maximum length 4096 characters. For example, `ejtsN6...`	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. The `key`, `manifest` and `audioSegment` headers take priority over the `all` header. Header name-value pairs set in the `all` header are overwritten by name-value pairs set in the `key`, `manifest`, and `audioSegment` headers.	list
audioItem.stream.httpHeaders.all.name	`all` header name. Maximum length 256 characters. Accepted values: `Authorization` and strings prefixed with `x-`. For example, `x-auth-token`.	string
audioItem.stream.httpHeaders.all.value	`all` header value. Maximum length 4096 characters. For example, `ejtsN6...`	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. Possible values: • `PAUSE`: pauses the playing media. • `ATTENUATE`: attenuates the volume of the playing media.	string

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

{
    "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 `Recognize` event.	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 a CLEAR_ALL directive and sends a PlaybackQueueCleared 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 `Recognize` event.	string

Payload parameters

Parameter	Description	Type
clearBehavior	A string value used to determine clear queue behavior. Accepted values: • `CLEAR_ENQUEUED` • `CLEAR_ALL`	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 a playBehavior of REPLACE_ALL.
A ClearQueue directive with a clearBehavior of CLEAR_ALL.

Note: Only send this event when a stream ends as a result of receiving one of the directives listed above. Don't send this event when a stream has finished playing. Instead, see 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `ProgressReportIntervalElapsed` or `PlaybackStarted` event, whichever was more recent.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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.

Note: Send 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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.

Note: Only send one 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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.

Tip: You might want to consider waiting until the previous song has buffered before sending a 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 contains progressReportDelayInMilliseconds with a value of 20000, send the ProgressReportDelayElapsed event with a value of 20,000 milliseconds from the start of the track.
If the Play directive contains an offsetInMilliseconds value of 10000 and progressReportDelayInMilliseconds value 20000, send the ProgressReportDelayElapsed 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 contains progressReportIntervalInMilliseconds with a value of 20000, send the ProgressReportIntervalElapsed event with a value of 20,000 milliseconds from the start of the track.
If the Play directive contains an offsetInMilliseconds value of 10000 and progressReportIntervalInMilliseconds value 20000, send the ProgressReportIntervalElapsed 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `ProgressReportIntervalElapsed` or `PlaybackStarted` event, whichever was more recent.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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.

Note: Only send one PlaybackFinished event per URL. If you receive a playlist URL (composed of multiple URLs) only send one PlaybackFinished event

Example 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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `ProgressReportIntervalElapsed` or `PlaybackStarted` event, whichever was more recent.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive that represents the stream that failed to playback.	string
currentPlaybackState.token	An opaque token provided by the `Play` directive.	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. playerActivity	Identifies the player state. Accepted values: `PLAYING`, `STOPPED`, `PAUSED`, `FINISHED`, `BUFFER_UNDERRUN`, or `IDLE`.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `ProgressReportIntervalElapsed` or `PlaybackStarted` event, whichever was more recent.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive.	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. Accepted values: `FLAC`, `VORBIS`, `OPUS`, `AAC`, `MP3`, `PCM`, `AC3`, `DTS`, `MHA1`, `EC-3`, `AC-3`, `MHA1`, `MHA2`, `MHM1`, `MP4.40`, `MP4.40.2`, `MP4.40.5`	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 `Play` directive.	string
metadata	Contains key/value pairs associated with the metadata received.	object