Your Alexa Dashboards Settings

AudioPlayer Interface

The AudioPlayer interface provides directives for controlling audio playback through voice, and events to manage and monitor playback progression. If you are looking to map playback controls to buttons (physical or GUI), please reference the PlaybackController interface.

State Diagram

The following diagram illustrates state changes driven by AudioPlayer components. Boxes represent AudioPlayer states and the connectors indicate state transitions.

AudioPlayer has the following states:

IDLE: AudioPlayer is only in an idle state when a product is initially powered on or rebooted and prior to acting on a Play directive.

PLAYING: When your client initiates playback of an audio stream, AudioPlayer must transition from an idle state to playing.

If you receive a directive instructing your client to perform an action, such as pausing or stopping the audio stream, if the client has trouble buffering the stream, or if playback fails, AudioPlayer must transition to the appropriate state when the action is performed (and send an event to AVS). Otherwise, AudioPlayer must remain in the playing state until the current stream has finished.

Additionally, AudioPlayer must remain in the playing state when:

  • Reporting playback progress to AVS
  • Sending stream metadata to AVS

STOPPED: There are four instances when AudioPlayer must transition to the stopped state. While in the playing state, AudioPlayer must transition to stopped when:

  • An issue with the stream is encountered and playback fails
  • The client receives a Stop directive from AVS
  • A ClearQueue directive with a clearBehavior of CLEAR_ALL is received
  • A Play directive with a playBehavior of REPLACE_ALL is received

While in the paused or buffer_underrun states, AudioPlayer must transition to stopped when a ClearQueue directive to CLEAR_ALL is received.

AudioPlayer must transition from stopped to playing whenever your client receives a Play directive, starts playing an audio stream, and sends a PlaybackStarted event to the AVS.

PAUSED: AudioPlayer must transition to the paused state when audio on the Content channel is paused to accommodate a higher priority input/output (such as user or Alexa speech). Playback must resume when the prioritized activity completes. For more information on prioritizing audio input/outputs, see Interaction Model.

BUFFER_UNDERRUN: AudioPlayer must transition to the buffer_underrun state when the client is being fed data slower than it is being read. AudioPlayer must remain in this state until the buffer is full enough to resume playback, at which point it must return to the playing state.

FINISHED: When a stream is finished playing, AudioPlayer must transition to the finished state. This is true for every stream in your playback queue. Even if there are streams queued to play, your client is required to send a PlaybackFinished event to AVS, and subsequently, transition from the playing state to finished when each stream is finished playing.

AudioPlayer must transition from finished to playing when:

  • The client receives a Play directive
  • The next stream in the playback queue starts playing (following a PlaybackStarted event).
AudioPlayer State Diagram
Click to enlarge

Play Directive

The Play directive is sent to your client to initiate audio playback. It is a multipart message comprised of a JSON directive, and up to one audio stream or binary audio attachment.

The playBehavior parameter included in the directive’s payload can be used to determine how a client must handle queueing and playback of a stream. The accepted values provide hints for what action must be taken:

  • 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 does not impact the currently playing stream.

Sample Message

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

Play directives may have a corresponding binary audio attachment as one part of the multipart message. When a binary audio attachment is present, the value provided for url will include the following prefix: cid.

The following multipart headers will 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 Provides playback hints. 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.
  • ENQUEUE: Adds a stream to the end of the current queue.
  • REPLACE_ENQUEUED: Replace all streams in the queue. This does not impact the currently 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

The PlaybackStarted event must be sent to AVS after your client processes a Play directive and begins playback of the associated audio stream.

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

Additional Interfaces

Jump to the top of this document. Use the sidebar to navigate to additional interfaces.

Resources