AudioPlayer 1.0

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

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.

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

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.

Note: When adding streams to your playback queue, make sure that the token for the playing stream matches the expectedPreviousToken in the stream added to the queue. If the tokens don't match, you must ignore the stream. If expectedPreviousToken isn't returned, add the stream the playback queue.

Sample Message

JSON


{
    "header": {
        "namespace": "AudioPlayer",
        "name": "Play",
        "messageId": "{{STRING 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

Important: Your client must accommodate and act on all payload parameters supported by Play, and must not break if key/value pairs in the JSON are missing.

Parameter	Description	Type
playBehavior	Determines how a device handles queueing and playback of a stream. 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

Note: This event is only sent when a stream stops as a result of receiving one of the directives listed above. Typically, this is the result of a user action. This event must not be sent when a stream has finished playing (see PlaybackFinished).

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.

Note: Only send one PlaybackStarted event per URL. If you receive a playlist URL (composed of multiple URLs) only send one PlaybackStarted event

Sample Message

{
    "event": {
        "header": {
            "namespace": "AudioPlayer",
            "name": "PlaybackStarted",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "token": "{{STRING}}",
            "offsetInMilliseconds": {{LONG}}
        }
    }
}

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

Tip: As a best practice, you may want to consider waiting until the previous song has buffered before sending a PlaybackNearlyFinished event to Alexa. This lowers the risk of exceeding the expiryTime and can reduce the frequency of playback stutters that may occur when downloading and processing multiple Play directives at the same time.

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)

Note: For each URL that AVS sends, it expects no more than one PlaybackFinished event. If you receive a playlist URL (composed of multiple URLs) only send one PlaybackFinished event

Sample Message

{
    "event": {
        "header": {
            "namespace": "AudioPlayer",
            "name": "PlaybackFinished",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "token": "{{STRING}}",
            "offsetInMilliseconds": {{LONG}}
        }
    }
}

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.

Note: PlaybackPaused should be sent after a Recognize event to reduce latency.

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

Last updated: Jul 22, 2021