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 aDiscover directive, you must specify the PlaybackController capabilities that your video skill supports.
Handling PlaybackController Directives
There are several types of directives that thePlaybackController interface sends, each described in the following sections.
Request Example
- App-only Integrations
- Cloudside Integrations
payload contains one optional field:pauseplaystopresumerewindfastForwardpreviousnextstartOver
payload contains an empty object: {}Experience Types
The payload contains one optional field, theexperience 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.
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
- App-only Integrations
- Cloudside Integrations
AlexaDirectiveReceiver class in the sample app for a more specific code example.Declaring Capability Support for this Interface
- App-only Integrations
- Cloudside Integrations
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:
