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

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"
}, 

Response JSON

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.

Sample Code

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:

• AudioPlayer on Echo Show and Echo Spot
• PlaybackController Request Reference
• Enhance your Audio Skill Visuals for Echo Show and Echo Spot
• Image Guidelines for Echo Show and Echo Spot

Make Money by Creating Engaging Skills Customers Love

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.

Build a New Skill, Earn Developer Perks

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.