Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
When users make transport control utterances (e.g., Stop, Rewind, Play, etc.), the Alexa.PlaybackController interface sends transport control directives (Pause, Play, Stop, Resume, Next, Previous, FastForward, Rewind, StartOver) to provide instructions for controlling media.

Utterances for Transport Controls Directives

Alexa sends transport control directives to your app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances. As with other directives, when you receive a Discover directive, you must specify the PlaybackController capabilities that your video skill supports.

Handling PlaybackController Directives

There are several types of directives that the PlaybackController interface sends, each described in the following sections.

Request Example

payload contains one optional field:
For , the value can be any of the following:
  • pause
  • play
  • stop
  • resume
  • rewind
  • fastForward
  • previous
  • next
  • startOver
payload contains an empty object: {}

Experience Types

The payload contains one optional field, the experience object. Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote. The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.
  • VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.
  • DEFAULT: The default displays of all search results list format, regardless of the device used for the search.
To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

Handling PlaybackController Directives

PlaybackController directives contain transport control commands used during media playback. Many of the actions are similar to the equivalent actions when a user would press the equivalent button on a remote control. The following sections provide the expected guidance for handling the various PlaybackController directives.

Pause Directives

pause should take the same action as if the user had pressed the Pause button on the remote.

Play Directives

play should take the same action as if the user had pressed the Play button on the remote.

Stop Directives

stop should request to stop playback of audio or video content.

Resume Directives

resume should take the same action as if the user had unpaused playback through their remote (that is, pressing the “play” button after having already paused playback earlier).

Next Directives

next should take the user to the next episode. If that’s not possible, it should take the user to the next related video content that you choose to show the viewer (or whatever’s next in the playlist you choose to use).

Previous Directives

previous should take the user to the previous episode. If that’s not possible, it take the user to whatever was earlier in the playlist you choose to use.

Fast-Forward Directives

fastForward should fast-forward playback by 30 seconds. Do not take the user to a fast-forward screen with a slowly moving cursor as if they were fast-forwarding via the remote. Also, do not require the user to say “Alexa, play” after having already requested to fast-forward via voice. Users prefer to simply fast-forward 30 seconds and resume playback automatically when they use this command. If you want to fast-forward more, you can use the SeekController Directives.

Rewind Directives

rewind should rewind playback by 30 seconds. Do not take the user to a Rewind screen with a slowly moving cursor as if they were rewinding via the remote. Also, do not require the user to say “Alexa, play” after having already requested to rewind via voice. Users prefer to simply rewind 30 seconds and resume playback automatically when they use this command. If you want to rewind more, you can use the SeekController Directives.

StartOver Directives

startOver should start playback from the beginning of the audio or visual content.

Response Example

If your app handled the directive successfully, your BroadcastReceiver class should send a success intent back with a success status, like this:
For more details, see Step 7: Add a Broadcast Receiver. Also see the AlexaDirectiveReceiver class in the sample app for a more specific code example.

Declaring Capability Support for this Interface

To receive PlaybackController directives in your app, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:
Last modified on June 9, 2021