The AudioPlayer and PlaybackController interfaces in the Alexa Skills Kit (ASK) provide directives and requests for streaming audio and monitoring playback progression. Your skill can send audio directives to start and stop audio playback. Customers can easily control audio playback by voice with simple commands, like “Alexa, stop” and “Alexa, resume.” On Echo Show and Echo Spot, customers can also control the playback using the touch controls on the display.
This post covers how to add touch-control support for your audio skills when used on Echo Show and Echo Spot.
AudioPlayer with Touch Controls Displayed
When customers touch the device screen during audio playback, the Previous, Pause/Play, and Next touch controls are displayed, allowing customers to pause and resume the current audio stream or navigate to the previous/next audio stream.
Depending on the control element tapped, Alexa sends your skill the PlaybackController.NextCommandIssued
, PlaybackController.PlayCommandIssued
or PlaybackController.PreviousCommandIssued
request, which your skill should respond to. The Pause touch control on Echo Show and Echo Spot handles the pause automatically and does not send your skill a request.
Below are example JSONs for these request types.
Request JSON with request type “PlaybackController.PlayCommandIssued”. Sent when user taps on the “Play” touch control.
"context": {
"AudioPlayer": {
"offsetInMilliseconds": 22202,
"playerActivity": "STOPPED",
"token": "this-is-the-audio-token"
}
},
"request": {
"locale": "en-IN",
"requestId": "amzn1.echo-api.request.<value>",
"timestamp": "2018-05-25T17:44:49Z",
"type": "PlaybackController.PlayCommandIssued"
},
Request JSON with request type “PlaybackController.NextCommandIssued”. Sent when user taps on the “Next” touch control.
"context": {
"AudioPlayer": {
"offsetInMilliseconds": 22202,
"playerActivity": "STOPPED",
"token": "this-is-the-audio-token"
}
},
"request": {
"locale": "en-IN",
"requestId": "amzn1.echo-api.request.<value>",
"timestamp": "2018-05-28T03:42:51Z",
"type": "PlaybackController.NextCommandIssued"
},
Request JSON with request type “PlaybackController.PreviousCommandIssued”. Sent when user taps on the “Previous” touch control.
"context": {
"AudioPlayer": {
"offsetInMilliseconds": 22202,
"playerActivity": "STOPPED",
"token": "this-is-the-audio-token"
}
},
"request": {
"locale": "en-IN",
"requestId": "amzn1.echo-api.request.<value>",
"timestamp": "2018-05-28T03:42:51Z",
"type": "PlaybackController.PreviousCommandIssued"
},
When your skill receives one of the above requests, it should send a response with an AudioPlayer.Play
directive. For example, with an audio podcast skill, send a directive to resume playback of the current podcast in response to a PlaybackController.PlayCommandIssued
request or send a directive to play the next podcast episode in response to a PlaybackController.NextCommandIssued
request.
{
"directives": [
{
"type": "AudioPlayer.Play",
"playBehavior": "REPLACE_ALL",
"audioItem": {
"stream": {
"url": "https://my-audio-hosting-site.com/audio/sample-song.mp3",
"token": "this-is-the-audio-token",
"offsetInMilliseconds": 22202
}
}
}
],
"shouldEndSession": true
}
To resume playback of the current audio stream, first determine the track's current offset when the PlaybackController.PlayCommandIssued
request was sent, using the offsetInMilliseconds
property supplied in the request. Specify this offset in the offsetInMilliseconds
property of the AudioPlayer.Play
response. If the audio stream URL is for a live audio stream, set offsetInMilliseconds
to null
.
When responding to any PlaybackController
request, you can only respond with AudioPlayer
directives. The response cannot include any of the standard properties such as outputSpeech
, card
, or reprompt
. Sending a response with these unsupported properties causes an error.
Here is a sample Node.js code showing how the PlaybackController.PlayCommand
requests is handled. In this example, when the user taps on the “Play” touch control, the skill resumes the audio playback from the previously paused location as indicated in the offsetInMilliseconds
property in the PlaybackController
request.
exports.handler = function (event, context) {
if (event.request.type === "PlaybackController.PlayCommandIssued") {
buildPlaybackControllerResponse(streamUrl, event.context.AudioPlayer.token,
event.context.AudioPlayer.offsetInMilliseconds, context);
}
};
function buildPlaybackControllerResponse(url, token, offset, context) {
var response = {
directives: [{
type: "AudioPlayer.Play",
playBehavior: "REPLACE_ALL",
audioItem: {
stream: {
url: url,
token: token,
offsetInMilliseconds: offset
}
}
}],
shouldEndSession: true
};
context.succeed( { response: response } );
}
For more information about the AudioPlayer Interface, PlaybackController requests and audio skills, check out the following resources:
You can make money through Alexa skills using in-skill purchasing or Amazon Pay for Alexa Skills. You can also make money for eligible skills that drive some of the highest customer engagement with Alexa Developer Rewards. Download our guide to learn which product best meets your needs.
Bring your big idea to life with Alexa and earn perks through our tiered rewards system. Publish a new skill in June and earn an AWS IoT button. Add in-skill purchasing to any published skill and earn an Alexa-enabled device for the car. Learn more about our promotion and start building today.