AudioPlayer 1.4


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

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.

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

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

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.

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.

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.

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.

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

Was this page helpful?

Last updated: Nov 27, 2023