AudioPlayer Interface Reference
The AudioPlayer
interface provides directives and requests for streaming audio and monitoring playback progression. Your skill can send directives to start and stop the playback. The Alexa service sends your skill AudioPlayer
requests to give you information about the playback state, such as when the track is nearly finished, or when playback starts and stops. Alexa also sends PlaybackController requests in response to hardware buttons such as on a remote control or the next/previous touch controls on Alexa-enabled devices with a screen.
Configure your skill for the AudioPlayer directives
When using these directives for audio playback, you must do the following:
- Indicate that your skill implements this interface when configuring the skill.
- In the developer console, navigate to Custom > Interfaces.
- Enable the Audio Player option and then click Save Interfaces. Be sure to click Build Model to re-build your interaction model.
- Implement the required built-in intents for pausing and resuming audio. Adding the AudioPlayer interface to your skill automatically adds these required intents to your model:
AMAZON.PauseIntent
AMAZON.ResumeIntent
In addition to the required built-in intents, your skill should gracefully handle the following additional built-in intents:
AMAZON.CancelIntent
AMAZON.LoopOffIntent
AMAZON.LoopOnIntent
AMAZON.NextIntent
AMAZON.PreviousIntent
AMAZON.RepeatIntent
AMAZON.ShuffleOffIntent
AMAZON.ShuffleOnIntent
AMAZON.StartOverIntent
Note that users can invoke these built-in intents without using your skill's invocation name (see below). If your skill is currently playing audio, or was the skill most recently playing audio, these intents are automatically sent to your skill. Your code needs to expect them and not return an error.
If any of these intents do not apply to your skill, handle it in a graceful way in your code. For instance, you could return a response with text-to-speech indicating that the command is not relevant to the skill. The specific message depends on the skill and whether the intent is one that might make sense at some point, for example:
- For a podcast skill, the
AMAZON.ShuffleOnIntent
intent might return the message: "I can't shuffle a podcast." - For version 1.0 of a music skill that doesn't yet support playlists and shuffling, the
AMAZON.ShuffleOnIntent
intent might return: "Sorry, I can't shuffle music yet."
AudioPlayer
directives and you extend the above built-in intents with your own sample utterances, these utterances work before the audio begins playing only. After the audio begins, the skill closes and the extended utterances don't work.Built-in intents for playback control
When your skill sends a Play
directive to begin playback, the Alexa service sends the audio stream to the device for playback. Once the session ends normally (for instance, if your response included the shouldEndSession
flag set to true
), Alexa remembers that your skill started the playback until the user does one of the following:
- Invokes audio playback with a different skill.
- Invokes another service that streams audio, such as the built-in music service or the flash briefing.
- Reboots the device.
During this time, users can invoke the following built-in playback control intents without using your skill's invocation name:
AMAZON.CancelIntent
AMAZON.LoopOffIntent
AMAZON.LoopOnIntent
AMAZON.NextIntent
AMAZON.PauseIntent
AMAZON.PreviousIntent
AMAZON.RepeatIntent
AMAZON.ResumeIntent
AMAZON.ShuffleOffIntent
AMAZON.ShuffleOnIntent
AMAZON.StartOverIntent
For example, note this scenario for a custom skill called "My Podcast Player". This skill defines an intent PlayLatestEpisode
mapped to the sample utterance "play the latest episode."
User: Alexa, ask My Podcast Player to play the latest episode.
Alexa opens a new skill session and sends the My Podcast Player skill the normal PlayLatestEpisode
.
My Podcast Player sends a Play
directive. The skill session closes and audio begins playing.
User: Alexa, next. (note no invocation name used.)
Alexa opens a new skill session and sends the My Podcast Player skill AMAZON.NextIntent
.
My Podcast Player takes appropriate action for 'next' and closes the skill session.
User: Alexa, pause. (again, no invocation name.)
Alexa opens a new skill session and sends the skill AMAZON.PauseIntent
.
My Podcast Player sends a Stop
directive and closes the skill session. The audio is stopped.
Although at this point the audio is not playing and there is no current session, the Alexa service is still tracking My Podcast Player as the skill that most recently streamed audio. Assuming the device remains on and the user does not use any other audio streaming skills or services, the following could take place at any time later:
User: Alexa, resume. (note no invocation name used.)
Alexa opens a new skill session and sends My Podcast Player the AMAZON.ResumeIntent
.
My Podcast Player takes appropriate action to determine the previously playing track and send a new Play
directive to restart playback.
This only applies to the built-in intents. The intents you define (such as the example PlayLatestEpisode
intent) must be invoked using a normal invocation phrase.
AMAZON.PauseIntent
instead of an AMAZON.StopIntent
.AudioPlayer on Alexa-enabled devices with a screen
These sections describe how an audio skill looks and behaves when used on an Alexa-enabled device with a screen.
Note that this does not require you to include the Display
interface. Devices with screens handle audio playback automatically.
Custom and default AudioPlayer display
AudioPlayer has a visual appearance on Alexa-enabled devices with a screen. You can optionally provide album art, a background image, track title, and subtitle when you send the Play
directive. In this case, the devices display the metadata as shown below. If no metadata is provided, the devices display a default player with a plain background and the skill's name.
For details about the metadata you can include, see the audioItem.metadata
property in the Play
directive.
Note that the AudioPlayer display shows touch controls (next, previous, and pause) when the user touches the device screen. Echo Show and Echo Spot are shown here, and Fire TV Cube is also supported.
Echo Show | Echo Spot |
---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
AudioPlayer and the touch controls
If the user touches the device screen while your skill is streaming audio, the audio touch controls are displayed for a short time. These controls provide access to next, previous, and pause.
The next, previous, and play controls behave like a hardware remote and send your skill the corresponding request:
PlaybackController.NextCommandIssued
PlaybackController.PreviousCommandIssued
PlaybackController.PlayCommandIssued
.
Your skill is responsible for handling those requests appropriately.
The pause control automatically stops the playback without sending your skill a request. However, your skill should still handle PlaybackController.PauseCommandIssued
, because other devices (such as hardware remotes) do send those requests.
AudioPlayer directives
AudioPlayer
provides the following directives:
Directive | Description |
---|---|
AudioPlayer.Play |
Sends Alexa a command to stream the audio file identified by the specified audioItem . |
AudioPlayer.Stop |
Stops any currently playing audio stream. |
AudioPlayer.ClearQueue |
Clears the queue of all audio streams. |
When including a directive in your response, set the type
property to the directive you want to send. Include directives in the directives
array in your response:
{
"type": "AudioPlayer.Play",
"playBehavior": "valid playBehavior value such as ENQUEUE",
"audioItem": {
"stream": {
"url": "https://cdn.example.com/url-of-the-stream-to-play",
"token": "opaque token representing this stream",
"expectedPreviousToken": "opaque token representing the previous stream",
"offsetInMilliseconds": 0,
"captionData": {
"content": "WEBVTT\n\n00:00.000 --> 00:02.107\n<00:00.006>My <00:00.0192>Audio <00:01.232>Captions.\n",
"type": "WEBVTT"
}
},
"metadata": {
"title": "title of the track to display",
"subtitle": "subtitle of the track to display",
"art": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-album-art-image.png"
}
]
},
"backgroundImage": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-background-image.png"
}
]
}
}
}
}
For the full response format, see Response Format.
LaunchRequest
or IntentRequest
, your response can include both AudioPlayer
directives and standard response properties such as outputSpeech
, card
, and reprompt
. For example, when you provide outputSpeech
in the same response as an Play
directive, Alexa speaks the provided text before beginning to stream the audio. Note that the rules are different when responding to AudioPlayer
requests.Note that the Alexa Simulator on the Test page doesn't render the audio playback, but the Skill I/O section shows the AudioPlayer
directives sent from your skill. Since the playback doesn't occur, you can't use the Alexa Simulator to test AudioPlayer
requests that are triggered by events in the playback, such as PlaybackNearlyFinished
.
AudioPlayer requests
AudioPlayer
sends the following requests to notify your skill about changes to the playback state:
Request Type | Description |
---|---|
AudioPlayer.PlaybackStarted |
Sent when Alexa begins playing the audio stream previously sent in a Play directive. This lets your skill verify that playback began successfully. |
AudioPlayer.PlaybackFinished |
Sent when the stream Alexa is playing comes to an end on its own. |
AudioPlayer.PlaybackStopped |
Sent when Alexa stops playing an audio stream in response to a voice request or an AudioPlayer directive. |
AudioPlayer.PlaybackNearlyFinished |
Sent when the currently playing stream is nearly complete and the device is ready to receive a new stream. |
AudioPlayer.PlaybackFailed |
Sent when Alexa encounters an error when attempting to play a stream. |
session
object, since they are not sent in the context of a skill session. Use the context
object to get details such as the applicationId
and userId
.{
"version": "1.0",
"context": {
"System": {
"application": {},
"user": {},
"device": {}
}
},
"request": {
"type": "AudioPlayer.PlaybackStarted",
"requestId": "amzn1.echo-api.request.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"timestamp": "2018-04-11T15:15:25Z",
"token": "1234AAAABBBBCCCCCDDDDEEEEEFFFF",
"offsetInMilliseconds": 0,
"locale": "en-US"
}
}
For the full request format, see Request Format.
AudioPlayer
requests, you can only respond with AudioPlayer
directives. The response cannot include any of the standard properties such as outputSpeech
. In addition, some requests limit the directives you can use, such as not allowing Play
. Sending a response with unsupported properties causes an error. See the request types below for the limits on each request.
.Also note that your service is not required to return a response to the AudioPlayer
requests.
Play directive
Sends Alexa a command to stream the audio file identified by the specified audioItem
. Use the playBehavior
parameter to determine whether the stream begins playing immediately, or is added to the queue.
Play
directive in a request.When sending a Play
directive, you normally set the shouldEndSession
flag in the response object to true
to end the session. If you set this flag to false
, Alexa sends the stream to the device for playback, then immediately pauses the stream to listen for the user's response.
{
"type": "AudioPlayer.Play",
"playBehavior": "valid playBehavior value such as ENQUEUE",
"audioItem": {
"stream": {
"url": "https://cdn.example.com/url-of-the-stream-to-play",
"token": "opaque token representing this stream",
"expectedPreviousToken": "opaque token representing the previous stream",
"offsetInMilliseconds": 0,
"captionData":{
"content": "WEBVTT\n\n00:00.000 --> 00:02.107\n<00:00.006>My <00:00.0192>Audio <00:01.232>Captions.\n",
"type": "WEBVTT"
}
},
"metadata": {
"title": "title of the track to display",
"subtitle": "subtitle of the track to display",
"art": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-album-art-image.png"
}
]
},
"backgroundImage": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-background-image.png"
}
]
}
}
}
}
Parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Set to |
|
yes |
|
Describes playback behavior. Accepted values:
|
|
yes |
|
Contains an object providing information about the audio stream to play. |
|
yes |
|
Contains an object representing the audio stream to play. |
|
yes |
|
Identifies the location of audio content at a remote |
|
yes |
|
An opaque token that represents the audio stream. This token cannot exceed 1024 characters. This token identifies the stream. Examples of when this token is used:
|
|
yes |
|
An opaque token that represents the expected previous stream. This should match the value of This property is required and allowed only when the |
|
yes (when |
|
The timestamp in the stream from which Alexa should begin playback. Set to 0 to start playing the stream from the beginning. Set to any other value to start playback from that associated point in the stream. |
|
yes |
|
An object with two fields, |
|
no |
|
The format of the string in the content field. Supported formats: WEBVTT |
|
no |
|
The time-encoded caption text. Supported formats: WEBVTT |
|
no |
|
Contains an object providing metadata about the audio to be displayed on the Alexa-enabled device with a screen. Note that this metadata displays only on the devices. It is not shown in the Alexa app. If you do not include this object, your skill uses the default audio display, which shows just the skill name on a gray background. This entire object is optional. However, if you do include Associate each new metadata item with a different See Guidelines for images for Alexa-enabled devices with a screen. Note that metadata is used on devices with screens regardless of whether you include the |
|
no |
|
The title text to display. This is typically used for the audio track title. |
|
no |
|
Subtitle text to display, such as a category or an artist name. |
|
no |
|
An Image object representing the album art to display. This object uses the same format as images used in the Display interface templates. On the Echo Show or Fire TV Cube, this is the smaller square image. On the Echo Spot, this is cropped into the circle shape and displayed as the background. For best results, follow the image guidelines and specifications. |
no |
|
|
An Image object representing the background image to display. This object uses the same format as images used in the Display interface templates. On the Echo Show or Fire TV Cube, this is the full background image. This image is not used on Echo Spot. For best results, follow the image guidelines and specifications. Note: Background images for
AudioPlayer skills get an automatic color overlay prior to rendering. The color comes from the skill's album cover color. Currently, there's nothing you can do to remove the color tint. |
no |
Audio stream requirements
The URL you provide in the audioItem.stream.url
property must meet these requirements:
- Audio file must be hosted at an Internet-accessible
HTTPS
endpoint on port 443. - The web server must present a valid and trusted SSL certificate. Self-signed certificates are not allowed. Many content hosting services provide this. For example, you could host your files at a service such as Amazon Simple Storage Service (Amazon S3) (an Amazon Web Services offering).
- If the stream is a playlist container that references additional streams, each stream within the playlist must also be hosted at an Internet-accessible
HTTPS
endpoint on 443 with a valid and trusted SSL certificate.
The supported formats for the audio file include AAC/MP4, MP3, PLS, M3U/M3U8, and HLS. Bitrates: 16kbps to 384 kbps.
Playlist progression with ENQUEUE
The audioItem.stream.expectedPreviousToken
property is required if playBehavior
is ENQUEUE
to handle situations in which requests to progress through a playlist and change tracks happen at the same time. The value of audioItem.stream.expectedPreviousToken
should match the audioItem.stream.token
property provided with the previous stream.
For example:
- The skill is streaming track 2 in a playlist of several tracks.
- The user says "Alexa, go back," which sends an
AMAZON.PreviousIntent
. - At about the same time, track 2 is nearly finished, so Alexa sends a
PlaybackNearlyFinished
request. - The skill handles the
AMAZON.PreviousIntent
first and sends a newPlay
directive with track 1. This track begins playing. The already-sentPlaybackNearlyFinished
request is now outdated, since it assumed that track 2 was playing. - The skill handles the now-outdated
PlaybackNearlyFinished
request and sends aPlay
directive with track 3, since this is the next track after the originally playing track 2. This request includesexpectedPreviousToken
set to track 2. - The
expectedPreviousToken
provided in the directive does not match thetoken
for the actively playing stream, so the device ignores this directive. - As track 1 finishes, Alexa sends a
PlaybackNearlyFinished
request. The skill responds with aPlay
directive for track 2. This track begins playing once track 1 finishes.
If this check was not in place, the directive sent in step 5 would put track 3 on the queue, which would cause the audio to skip from track 1 to track 3 when track 1 finishes.
audioItem.stream.expectedPreviousToken
when playBehavior
is any other value (REPLACE_ALL
or REPLACE_ENQUEUED
) causes an error.Guidelines for images for Alexa-enabled devices with a screen
If you provide images in the audioItem.metadata.art
and audioItem.metadata.backgroundImage
properties, note the following guidelines:
- When you send a track with new metadata, be sure to also change the
audioItem.stream.token
property for the track. - For the
audioItem.metadata.art
, use a square image for the best results. If the image is not square, it is displayed with extra black space on the device. Note that the image is cropped to a circle shape on the Echo Spot. - The images must meet the same requirements as images used in the
Display
interface directive. The only difference is the recommended minimum size shown below. - Provide the minimum recommended size as noted below to ensure that the image is never scaled up. If you provide a smaller image, the device must scale it up, which can make the image appear blurry.
- The
Image
object lets you provide multiple image URLs in thesource
array. As with the Display Interface, the device selects the image with the highest resolution to display. - The following properties for a particular image
source
on theImage
object are not used when displaying the background image and album art for audio and can be left out of the object:contentDescription
size
widthPixels
heightPixels
audioItem.stream.token
included in the Play
directive. Note that the metadata associated with a particular audioItem.stream.token
may be cached in the Alexa service for up to five days, so changes to the metadata (such as a different image, or a change to the title text) may not be reflected immediately on the device. For instance, you may notice this when testing if you experiment with different images or title text for the same audio stream. You can send a new Play
directive with a different audioItem.stream.token
to clear the cache.The following table notes the recommended minimum size for images used with Alexa-enabled devices with a screen.
Image | Recommended Minimum Size | Echo Show/Fire TV Cube | Echo Spot |
---|---|---|---|
Art image ( |
480 x 480 pixels |
Scaled to 300 x 300 and displayed as album art. |
Scaled to 480 x 480, cropped to a circle, and displayed as the background image with 70% opacity black scrim. |
Background image ( |
1024 x 640 pixels |
Scaled to 1024 x 640 and displayed as a background image. Your image is displayed as is on the Echo Show or Fire TV Cube, so apply any fading effects in your source image if needed. For instance, you could apply a 70% opacity black layer over your image to give it a faded appearance and make the text stand out. |
Not used. |
Stop directive
Stops the current audio playback.
{
"type": "AudioPlayer.Stop"
}
Parameter | Description | Type | Required |
---|---|---|---|
type |
Set to AudioPlayer.Stop |
string |
yes |
ClearQueue directive
Clears the audio playback queue. You can set this directive to clear the queue without stopping the currently playing stream, or clear the queue and stop any currently playing stream.
{
"type": "AudioPlayer.ClearQueue",
"clearBehavior" : "valid clearBehavior value such as CLEAR_ALL"
}
Parameter | Description | Type | Required |
---|---|---|---|
|
Set to |
|
yes |
|
Describes the clear queue behavior. Accepted values:
|
|
yes |
PlaybackStarted request
Sent when Alexa begins playing the audio stream previously sent in a Play
directive. This lets your skill verify that playback began successfully.
This request is also sent when Alexa resumes playback after pausing it for a voice request.
{
"type": "AudioPlayer.PlaybackStarted",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"token": "token representing the currently playing stream",
"offsetInMilliseconds": 0,
"locale": "a locale code such as en-US"
}
Parameters
Parameter | Description | Type |
---|---|---|
type |
AudioPlayer.PlaybackStarted |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
token |
An opaque token that represents the audio stream. You provide this token when sending the Play directive. |
string |
offsetInMilliseconds |
Identifies a track's offset in milliseconds when the PlaybackStarted request is sent. |
long |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
For the full request format, see Request Format.
Valid response types
Your skill can respond to PlaybackStarted
with a Stop
or ClearQueue
directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other
AudioPlayer
directives. - Any other directives from other interfaces, such a Dialog directive.
PlaybackFinished request
Sent when the stream Alexa is playing comes to an end on its own.
PlaybackStopped
instead of PlaybackFinished
.{
"type": "AudioPlayer.PlaybackFinished",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"token": "token representing the currently playing stream",
"offsetInMilliseconds": 0,
"locale": "a locale code such as en-US"
}
Parameters
Parameter | Description | Type |
---|---|---|
type |
AudioPlayer.PlaybackFinished |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
token |
An opaque token that represents the audio stream. You provide this token when sending the Play directive. |
string |
offsetInMilliseconds |
Identifies a track's offset in milliseconds when the PlaybackFinished request is sent. |
long |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid response types
Your skill can respond to PlaybackFinished
with a Stop
or ClearQueue
directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other
AudioPlayer
directives. - Any other directives from other interfaces, such a Dialog directive.
PlaybackStopped request
Sent when Alexa stops playing an audio stream in response to one of the following AudioPlayer
directives:
Stop
Play
with aplayBehavior
ofREPLACE_ALL
.ClearQueue
with aclearBehavior
ofCLEAR_ALL
.
This request is also sent if the user makes a voice request to Alexa, since this temporarily pauses the playback. In this case, the playback begins automatically once the voice interaction is complete.
PlaybackFinished
instead of PlaybackStopped
.{
"type": "AudioPlayer.PlaybackStopped",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"token": "token representing the currently playing stream",
"offsetInMilliseconds": 0,
"locale": "a locale code such as en-US"
}
Parameters
Parameter | Description | Type |
---|---|---|
type |
AudioPlayer.PlaybackStopped |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
token |
An opaque token that represents the audio stream. You provide this token when sending the Play directive. |
string |
offsetInMilliseconds |
Identifies a track's offset in milliseconds when the PlaybackStopped request is sent. |
long |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid response types
Your skill cannot return a response to PlaybackStopped
.
PlaybackNearlyFinished request
Sent when the device is ready to add the next stream to the queue.
To progress through a playlist of audio streams, respond to this request with a Play
directive for the next stream and set playBehavior
to ENQUEUE
or REPLACE_ENQUEUED
. This adds the new stream to the queue without stopping the current playback. Alexa begins streaming the new audio item once the currently playing track finishes.
{
"type": "AudioPlayer.PlaybackNearlyFinished",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"token": "token representing the currently playing stream",
"offsetInMilliseconds": 0,
"locale": "a locale code such as en-US"
}
Parameters
Parameter | Description | Type |
---|---|---|
type |
AudioPlayer.PlaybackNearlyFinished |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
token |
An opaque token that represents the audio stream that is currently playing. You provide this token when sending the Play directive. |
string |
offsetInMilliseconds |
Identifies a track's offset in milliseconds when the PlaybackNearlyFinished request is sent. |
long |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
Valid response types
Your skill can respond to PlaybackNearlyFinished
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a Dialog directive.
PlaybackFailed request
Sent when Alexa encounters an error when attempting to play a stream.
Syntax
{
"type": "AudioPlayer.PlaybackFailed",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"token": "token representing the currently playing stream",
"offsetInMilliseconds": 0,
"locale": "a locale code such as en-US",
"error": {
"type": "error code",
"message": "description of the error that occurred"
},
"currentPlaybackState": {
"token": "token representing stream playing when error occurred",
"offsetInMilliseconds": 0,
"playerActivity": "player state when error occurred, such as PLAYING"
}
}
This request type includes two token
properties – one as a property of the request
object, and one as a property of the currentPlaybackState
object. The request.token
property represents the stream that failed to play. The currentPlaybackState.token
property can be different if Alexa is playing a stream and the error occurs when attempting to buffer the next stream on the queue. In this case, currentPlaybackState.token
represents the stream that was successfully playing.
Parameters
Parameter | Description | Type |
---|---|---|
type |
AudioPlayer.PlaybackFailed |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
token |
An opaque token provided by the Play directive that represents the stream that failed to play. |
string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
error |
Contains an object with error information | 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. | string |
currentPlaybackState |
Contains an object providing details about the playback activity occurring at the time of the error. | object |
currentPlaybackState. token |
An opaque token that represents the audio stream currently playing when the error occurred. Note that this may be different from the value of the request.token property. |
string |
currentPlaybackState. offsetInMilliseconds |
Identifies a track's offset in milliseconds when the error occurred. | long |
currentPlaybackState. playerActivity |
Identifies the player state when the error occurred: PLAYING , PAUSED , FINISHED , BUFFER_UNDERRUN , or IDLE . |
string |
Error Type | Description |
---|---|
MEDIA_ERROR_UNKNOWN |
An unknown error occurred. |
MEDIA_ERROR_INVALID_REQUEST |
Alexa recognized the request as being malformed. E.g. bad request, unauthorized, forbidden, not found, etc. |
MEDIA_ERROR_SERVICE_UNAVAILABLE |
Alexa was unable to reach the URL for the stream. |
MEDIA_ERROR_INTERNAL_SERVER_ERROR |
Alexa accepted the request, but was unable to process the request as expected. |
MEDIA_ERROR_INTERNAL_DEVICE_ERROR |
There was an internal error on the device. |
Valid response types
Your skill can respond to PlaybackFailed
with any AudioPlayer directive.
The response cannot include:
- Any standard properties such as
outputSpeech
,card
, orreprompt
. - Any other directives from other interfaces, such a Dialog directive.
System.ExceptionEncountered request
If a response to an AudioPlayer
request causes an error, your skill is sent a System.ExceptionEncountered
request. Any directives included in the response are ignored.
{
"type": "System.ExceptionEncountered",
"requestId": "unique.id.for.the.request",
"timestamp": "timestamp of request in format: 2018-04-11T15:15:25Z",
"locale": "a locale code such as en-US",
"error": {
"type": "error code such as INVALID_RESPONSE",
"message": "description of the error that occurred"
},
"cause": {
"requestId": "unique identifier for the request that caused the error"
}
}
Parameters
Parameter | Description | Type |
---|---|---|
type |
System.ExceptionEncountered |
string |
requestId |
Represents a unique identifier for the specific request. | string |
timestamp |
Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. | string |
locale |
A string indicating the user's locale. For example: en-US . See supported locale codes. |
string |
error |
Contains an object with error information | object |
error.type |
Identifies the specific type of error (INVALID_RESPONSE , DEVICE_COMMUNICATION_ERROR , INTERNAL_ERROR ). |
string |
error.message |
A description of the error the device has encountered. | string |
cause.requestId |
The requestId for the request that caused the error |
string |
Valid Response Types
Your skill cannot return a response to System.ExceptionEncountered
.
Service Interface Reference (JSON)
Request Format and Standard Request Types:
- Request and Response JSON Reference
- Request Types Reference (LaunchRequest, IntentRequest, SessionEndedRequest)
- Alexa.Presentation.APL Interface
- Alexa.Presentation.APLT Interface
- Alexa.Presentation.HTML Interface
- AudioPlayer Interface (this document)
- Connections Interface
- Dialog Interface
- Messaging Interface
- PlaybackController Interface
- VideoApp Interface
Related topics
Last updated: Jan 31, 2023