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:

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.

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.

Note: When adding streams to your playback queue, you must ensure that the token for the currently playing stream matches the expectedPreviousToken in the stream being added to the queue. If the tokens do not match the stream must be ignored. However, if no expectedPreviousToken is returned, the stream must be added to the queue.

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:

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.

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

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:

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.

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.

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.

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.

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.

Note: This event is only sent when a stream is terminated 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).

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.

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

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.

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

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.