AudioPlayer Interface

    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

    AudioPlayer 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, 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 inturrupted.

    Play directive

    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. Your 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 includs 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}}"
            "inturruptedBehavior": "{{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.inturruptedBehavior Specify how your device responds when playback gets inturrupted.

    Possible Values:
    PAUSE: pauses the playing media
    ATTENUATE: attenuates (lowers) the volume of the playing media
    string

    PlaybackStarted event

    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 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, 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 event

    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 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, 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 event

    You only need to send the ProgressReportDelayElapsed 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 a Play offset value contained in offsetInMilliseconds.

    For Example:

    • 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, 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 event

    The ProgressReportIntervalElapsed event is in place to confirm that the UpdateProgressReportInterval event is received and processed.

    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, 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, 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 event

    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, 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 event

    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, 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 event

    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, 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 event

    Send this to AVS when your client finishes playback of a stream.

    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, 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, 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 event

    Send this event to AVS whenever you encounters 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, 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, 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.

    Stop directive

    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

    PlaybackStopped event

    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, 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, 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 event

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

    PlaybackResumed event

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

    ClearQueue directive

    AVS sends the ClearQueue to your client to clear the playback queue.

    The ClearQueue directive has two behaviors:

    1. CLEAR_ENQUEUED: Clears the queue and continues to plays the stream
    2. CLEAR_ALL: clears the entire playback queue and stops the playing stream - if applicable.

    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

    PlaybackQueueCleared event

    Send this event PlaybackQueueCleared to AVS after your client handles a 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 event

    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

    UpdateProgressReportInterval directive

    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

      For example, if you ask "Alexa, play my favorite 90s playlist on Amazon Music," an Audioplayer.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.

      Capability Assertion

      AudioPlayer 1.0 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.0"
      }
      

      AudioPlayer context

      To handle events and directives properly, AVS must understand what your device is trying to do at any given time. AVS handles this functionality with a feature called context. To learn more about reporting Context, see Context Overview.

      For each AudioPlayer event that requires context, your client must report the associated playerActivity and offsetInMilliseconds for the media that's playing. For example let's pretend a song is playing and a user barges in to ask the time. You handle this situation by sending a context event with a playerActivity of PAUSED and the appropriate offsetInMilliseconds needed to handle the request.

      Sample Message

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

      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 Identifies the component state of AudioPlayer. <td>string
      Player Activity Description
      IDLE Nothing playing and there are no enqueued items.
      PLAYING Stream playing.
      PAUSED Stream paused.
      BUFFER_UNDERRUN Buffer underrun.
      FINISHED Streams finished playing.
      STOPPED Stream interrupted.

      Play directive

      AVS sends a Play directive to your device every time Alexa starts audio playback. The Play directive is a multipart message made up of two formats - a JSON directive and a binary audio attachment.

      Sample Message

      JSON

      
      {
          "header": {
              "namespace": "AudioPlayer",
              "name": "Play",
              "messageId": "{{STRING PROVIDED BY CLIENT}}",
              "dialogRequestId": "{{STRING PROVIDED BY CLOUD}}"
          },
          "payload": {
              "playBehavior": "{{STRING}}",
              "audioItem": {
                  "audioItemId": "{{STRING}}",
                  "streams": [
                      {
                          "url": "{{STRING}}",
                          "streamFormat": "AUDIO_MPEG",
                          "offsetInMilliseconds": "{{LONG}}",
                          "expiryTime": "{{STRING}}",
                           "progressReport": {
                              "progressReportDelayInMilliseconds": {{LONG}},
                              "progressReportIntervalInMilliseconds": {{LONG}}
                          },
                          "token": "{{STRING}}",
                          "expectedPreviousToken": "{{STRING}}"
                      }
                  ]
              }
          }
      }
      }
      

      Binary Audio Attachment

      The following headers precede the 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.

      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. Accepted values: REPLACE_ALL, ENQUEUE, and REPLACE_ENQUEUED.
      • REPLACE_ALL: Immediately begin playback of the stream returned with the Play directive, and replace current and enqueued streams. When a stream is playing and you receive a Play directive with a playBehavior of REPLACE_ALL you must send a PlaybackStopped event to AVS.
      • ENQUEUE: Adds a stream to the end of the current queue.
      • REPLACE_ENQUEUED: Replace all streams in the queue. This doesn't impact the playing stream.
      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. Please 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. Please 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

      PlaybackStarted Event

      A PlaybackStarted event informs AVS that your device has actually started the playback of an audio stream. Send the PlaybackStarted to AVS after your client processes a Play directive.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "PlaybackStarted",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{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

      PlaybackNearlyFinished Event

      The PlaybackNearlyFinished event must be sent when your client is ready to buffer/download the next stream in your playback queue. Your client must ensure that this event is only sent following a PlaybackStarted event for the currently playing stream. Alexa will respond to this event 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}}
              }
          }
      }
      

      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

      ProgressReportDelayElapsed Event

      The ProgressReportDelayElapsed event must be sent to AVS if progressReportDelayInMilliseconds is present in the Play directive. The event must be sent once at the specified interval from the start of the stream (not from the offsetInMilliseconds). For example, if the Play directive contains progressReportDelayInMilliseconds with a value of 20000, the ProgressReportDelayElapsed event must be sent 20,000 milliseconds from the start of the track. However, if the Play directive contains an offsetInMilliseconds value of 10000 and progressReportDelayInMilliseconds value 20000, the event must be sent 10,000 milliseconds into playback. This is because the progress report is sent from the start of a stream, not the Play directive's offset.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "ProgressReportDelayElapsed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{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

      ProgressReportIntervalElapsed Event

      The ProgressReportIntervalElapsed event must be sent to AVS if progressReportIntervalInMilliseconds is present in the Play directive. The event must be sent periodically at the specified interval from the start of the stream (not from the offsetInMilliseconds). For example, if the Play directive contains progressReportIntervalInMilliseconds with a value of 20000, the ProgressReportIntervalElapsed event must be sent 20,000 milliseconds from the start of the track, and every 20,000 milliseconds until the stream ends. However, if the Play directive contains an offsetInMilliseconds value of 10000 and a progressReportIntervalInMilliseconds value of 20000, the event must be sent 10,000 milliseconds from the start of playback, and every 20,000 milliseconds after that until the stream ends. This is because the interval specified is from the start of the stream, not the Play directive's offset.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "ProgressReportIntervalElapsed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{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

      PlaybackStutterStarted Event

      The PlaybackStutterStarted event must be sent to AVS, following a PlaybackStarted event, when the client's AudioPlayer component is being fed data slower than it is being read. The component must transition to the buffer_underrun state once this event has been sent and remain in this 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}}
              }
          }
      }
      

      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

      PlaybackStutterFinished Event

      The PlaybackStutterFinished event must be sent to AVS when the buffer is full enough to resume playback of a stream. AVS doesn't expect a subsequent PlaybackStarted event when audio playback resumes.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "PlaybackStutterFinished",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{LONG}},
                  "stutterDurationInMilliseconds": {{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

      PlaybackFinished Event

      The PlaybackFinished event must be sent to AVS when your client finishes playback of a stream.

      This event is not sent when:

      • Playback is stopped (either locally or as the result of a Stop directive)
      • Navigating between streams (next/previous)

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "PlaybackFinished",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{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

      PlaybackFailed Event

      The PlaybackFailed event must be sent to AVS whenever your client encounters an error while attempting to play a stream. It is possible for the currentPlaybackToken to be different from the token in the payload in cases where a stream is playing and the next stream fails to buffer.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "PlaybackFailed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "currentPlaybackState": {
                      "token": "{{STRING}}",
                      "offsetInMilliseconds": {{LONG}},
                      "playerActivity": "{{STRING}}"
                  },
                  "error": {
                      "type": "{{STRING}}",
                      "message": "{{STRING}}"
                  }
              }
          }
      }
      

      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 Contains key/value pairs for the playbackState object. object
      playbackState.token An opaque token provided by the Play directive. string
      playbackState.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
      playbackState.playerActivity Identifies the player state.
      Accepted values: PLAYING, STOPPED, PAUSED, FINISHED, BUFFER_UNDERRUN, or IDLE.
      string
      error Contains key/value pairs for error messages. object
      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

      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.

      Stop Directive

      The Stop directive is sent to your client to stop playback of an audio stream. Your client may 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

      PlaybackStopped Event

      The PlaybackStopped event must be sent 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}}
              }
          }
      }
      

      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

      PlaybackPaused Event

      The PlaybackPaused event must be sent when your client temporarily pauses audio on the Content channel to accommodate a higher priority input/output. Playback must resume when the prioritized activity completes; at which point your client must send 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}}
              }
          }
      }
      

      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

      PlaybackResumed Event

      The PlaybackResumed event must be sent to AVS when playback resumes following a PlaybackPaused event (when playback is temporarily paused on the Content channel to accommodate a higher priority input/output). For more information on prioritizing audio input/outputs, see Interaction Model.

      Sample Message

      {
          "event": {
              "header": {
                  "namespace": "AudioPlayer",
                  "name": "PlaybackResumed",
                  "messageId": "{{STRING}}"
              },
              "payload": {
                  "token": "{{STRING}}",
                  "offsetInMilliseconds": {{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

      ClearQueue Directive

      The ClearQueue directive is sent from AVS to your client to clear the playback queue. The ClearQueue directive has two behaviors: CLEAR_ENQUEUED, which clears the queue and continues to play the currently playing stream; and CLEAR_ALL, which clears the entire playback queue and stops the currently playing stream (if applicable).

      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

      PlaybackQueueCleared Event

      The PlaybackQueueCleared event must be sent to AVS after your client handles a 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

      An empty payload must be sent.

      StreamMetadataExtracted Event

      If metadata is available for an audio stream that your client receives and starts playing: your client should take the key/value pairs received as raw data and translate those pairs into a JSON object. In this JSON object, strings and numbers should be represented as JSON strings, and booleans should be represented as JSON booleans. Your client should filter out any tags containing binary data. For example, your client should not 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