AudioPlayer 1.4

Warning: This page doesn't describe the latest version of the AudioPlayer interface. If this isn't what you're looking for, use the Version Selector at the top of the page to navigate to the correct version.

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, so your device responds 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 on AudioPlayer events and directives, see the AudioPlayer overview.
For information on mapping playback controls to buttons see the PlaybackController interface.

Version changes

Support for device-reported player software information and playback telemetry, enabling enhanced audio streams and new music service providers
- ADDED fingerprint configuration parameter
- CHANGED the following messages by adding a new playbackAttributes field:
  - PlaybackStarted event
  - PlaybackNearlyFinished event
  - ProgressReportDelayElapsed event
  - ProgressReportIntervalElapsed event
  - PlaybackStutterStarted event
  - PlaybackStutterFinished event
  - PlaybackFinished event
  - PlaybackFailed event
  - PlaybackStopped event
  - PlaybackPaused event
  - PlaybackResumed event
- CHANGED the following messages by adding a new playbackReports field:
  - ProgressReportIntervalElapsed event
  - PlaybackFinished event
  - PlaybackFailed event
  - PlaybackStopped event
- ADDED ProgressReportIntervalUpdated event
- ADDED UpdateProgressReportInterval directive
Support for attenuation versus pausing of interrupted playback
- CHANGED Play directive to include a new interruptedBehavior field
Added metadata about music playback initiation
- CHANGED Play directive to include a new playRequestor field
Support for captions of spoken content
- CHANGED Play directive to include a new caption field

Capability assertion

AudioPlayer 1.4 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue 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, represented as a string. `0` is not a valid value. Increment with each new release of the specified player `package`. Report to AVS whenever the player on the device gets updated.	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.

Sample Message


{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackState"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playerActivity": "{{STRING}}",
    "playbackAttributes": {
      "name": "{{STRING}}",
      "codec": "{{STRING}}",
      "samplingRateInHertz": {{LONG}},
      "dataRateInBitsPerSecond": {{LONG}}
    }
  }
}

Payload Parameters

Parameter	Description	Type
token	A token that indicates what's playing. You must match the token for the media item that's playing. Otherwise, match the content in the last `Play` directive received.	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
playerActivity	Audio player activity. Accepted Values: `IDLE`,`PLAYING`,`STOPPED`,`PAUSED`,`BUFFER_UNDERRUN`,`FINISHED`	string
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

Player Activity	Description
IDLE	Nothing playing and there are no enqueued items.
PLAYING	Stream playing.
PAUSED	Stream paused.
BUFFER_UNDERRUN	Buffer underrun.
FINISHED	Stream finished playing.
STOPPED	Stream interrupted.

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's stopped: 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 while 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.

Sample Message

JSON


{
  "header": {
    "namespace": "AudioPlayer",
    "name": "Play",
    "messageId": "{{string}",
    "dialogRequestId": "{{STRING}}"
  },
  "payload": {
    "playBehavior": "{{STRING}}",
    "playRequestor": {
      "type": {{STRING}},
      "id": {{STRING}},
    "audioItem": {
      "audioItemId": "{{STRING}}",
      "stream": {
        "url": "{{STRING}}",
        "streamFormat": "AUDIO_MPEG",
        "offsetInMilliseconds": {{LONG}},
        "expiryTime": "{{STRING}}",
        "caption": {
          "content": {{STRING}},
          "type": "{{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 was not 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`, then this field will match the `token` of the alarm set through the `SetAlert` directive.	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.url	Identifies the location of audio content. If the audio content is a binary audio attachment, the value will be a unique identifier for the content, which is formatted as follows: `"cid:"`. Otherwise the value will be a remote http/https location.	string
audioItem.stream.streamFormat	`streamFormat` is included in the payload when the `Play` directive has an associated binary audio attachment. This parameter will not appear if the associated audio is a stream. Accepted Value: AUDIO_MPEG	string
audioItem.stream.offsetInMilliseconds	A timestamp 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.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.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.caption	If AVS includes this object, the device can use it to generate captions for the attached audio content.	object
audioItem.stream.caption.type	The caption format. Possible Value: WEBVTT
audioItem.stream.caption.content	The time-encoded caption text for the attached audio content.	string
audioitem.stream.interruptedBehavior	Specify how your device responds when playback gets interrupted. Possible Values: `PAUSE`: pauses the playing media `ATTENUATE`: attenuates (lowers) 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.

Sample 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.

NOTES

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.

Sample 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 on	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.

Sample 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` and `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 terminates 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.

Sample 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 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

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 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 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.

Sample 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.

Sample 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.

Sample 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.

NOTE: 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.

Sample 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.

Sample 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.

NOTES

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.

Sample 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.

Sample 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
stutterDurationIn Milliseconds	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

Sample 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.

NOTE: 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.

Sample 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

Value	Description
MEDIA_ERROR_UNKNOWN	An unknown error occurred.
MEDIA_ERROR_INVALID_REQUEST	The server recognized the request as being malformed. E.g. 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.

Sample 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 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

PlaybackQueueCleared

Send this event PlaybackQueueCleared to AVS after your client handles a CLEAR_ALL ClearQueue directive.

Sample 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.

NOTES

Represent strings and numbers as JSON strings. 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.

Sample 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

Last updated: Apr 22, 2021