AudioPlayer 1.5


The AudioPlayer interface of the Alexa Voice Service (AVS) and exposes directives and events for capturing and interacting with audio stream.

When you ask Alexa to play music, the AudioPlayer interface monitors the resulting audio stream to make sure it plays back correctly. This includes understanding when an audio stream starts, stops, pauses, or fails.

For example, if you ask "Alexa, play my favorite 90s playlist on Amazon Music", a Play directive starts the playlist. As it progresses, AudioPlayer reports any changes to the audio stream, allowing your device to respond appropriately. Changes might include notifying your device when the track is nearly finished, or when playback starts and stops.

This page provides reference details for AudioPlayer events and directives.

  • For conceptual information about AudioPlayer events and directives, see the AudioPlayer overview.
  • For information about mapping playback controls to buttons see the PlaybackController interface.

Version changes

  • Support for a skill or content owner to tag an audio stream as suitable for on-device audio analysis
    • CHANGED Play directive: 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.

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": {
          "key": [
            {
            "name": "{{STRING}}",
            "value": "{{STRING}}"
            }
         ],
          "manifest": [
            {
              "name:": "{{STRING}}",
              "value:": "{{STRING}}"
            }
          ],
          "audioSegment": [
            {
              "name:": "{{STRING}}",
              "value:": "{{STRING}}"
            }
          ],
          "all": [
            {
              "name:": "{{STRING}}",
              "value:": "{{STRING}}"
            }
          ]
        }
      },
      "progressReport": {
        "progressReportDelayInMilliseconds": {{LONG}},
        "progressReportIntervalInMilliseconds": {{LONG}}
      },
      "token": "{{STRING}}",
      "expectedPreviousToken": "{{STRING}}",
      "interruptedBehavior": "{{STRING}}"
    }
  }
}

Binary Audio Attachment

Not all Play directives contain a binary audio attachment. If a directive includes an audio attachment, the url value returns with a cid prefix.

The following headers precede the binary audio attachment.

Content-Type: application/octet-stream
Content-ID: {{Audio Item CID}}
{{BINARY AUDIO ATTACHMENT}}

Header parameters

Parameter Description Type

messageId

A unique ID used to represent a specific message.

string

dialogRequestId

A unique ID used to correlate directives sent in response to a specific Recognize event.

string

Payload parameters

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. Acceptable value: "key","manifest", "audioSegment", "all". See Support for passing HTTP header in an audio stream.

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

Support for passing HTTP header in an audio stream

When parsing playlists, Alexa uses several categories of derived URLs. These URLs are for obtaining encryption keys, for manifests, and for audio segments. These categories form the groups for the HTTP headers that can be added to the play directive.

The httpHeaders is a JSON object that nests the headers in "key","manifest", "audioSegment" and "all" categories. When present in a play directive, it determines headers to be added to URL requests when processing the play directive.

Example httpHeaders object

"httpHeaders": {
    "key": [
        {
            "name": "Authorization",
            "value": "ejtsN6..."
        },
        ...
    ],
    "manifest": [
        {
            "name": "Authorization",
            "value": "ejtsN6..."
        },
        ...
    ],
    "audioSegment": [
        {
            "name": "Authorization",
            "value": "ejtsN6..."
        },
        ...
    ],
    "all": [
        {
            "name": "Authorization",
            "value": "ejtsN6..."
        },
        ...
    ],
}    

Stop

AVS sends a Stop directive to your client to stop playback of an audio stream. You might receive a Stop directive as the result of a voice request, a physical button press or GUI affordance.

Example message

{% raw %}{
    "directive": {
        "header": {
            "namespace": "AudioPlayer",
            "name": "Stop",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
        }
    }
}

Header parameters

Parameter Description Type

messageId

A unique ID used to represent a specific message.

string

dialogRequestId

A unique ID used to correlate directives sent in response to a specific 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.

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.

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.

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.

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.

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


Was this page helpful?

Last updated: Nov 27, 2023