AudioPlayer 1.0


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"
}

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.

Directives

Play

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}}",
            "stream": {
                  "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

Stop

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

ClearQueue

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

Events

PlaybackStopped

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

PlaybackStarted

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

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

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

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

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

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

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][#stop-directive] 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

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.

PlaybackPaused

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

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

PlaybackQueueCleared

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

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

Was this page helpful?

Last updated: Nov 27, 2023