Alexa.PlaybackController Interface (VSK Fire TV)
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.
PlaybackController
, it's recommended that you use Android MediaSession for transport controls instead. Media sessions provides the same features with less latency and a more consistent customer experience. See Step 2: Integrate with MediaSession for details.- Utterances for Transport Controls Directives
- Handling PlaybackController Directives
- Request Example
- Experience Types
- Handling PlaybackController Directives
- Response Example
- Declaring Capability Support for this Interface
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.
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pause |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
Play |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
stop |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
Resume |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
Start over |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
Fast Forward |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
Rewind |
The media rewinds 10 seconds. |
Previous Required for certification |
Previous |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
Next |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pause / mets sur pause |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
joue |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
arrête / stop / stoppe |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
Not supported |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
recommence |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
avance fast forward |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
rewind rembobine |
The media rewinds 10 seconds. |
Previous Required for certification |
précédent(e) |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
prochain(e) suivant(e) next |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pause / mets sur pause |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
joue |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
arrête / stop / stoppe |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
Not supported |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
recommence |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
avance |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
rembobine |
The media rewinds 10 seconds. |
Previous Required for certification |
précédent(e) |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
prochain(e) suivant(e) next |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pause pausier [DeviceLocation] pausier auf? [DeviceType] pause auf? [DeviceLocation]? [DeviceBrand] pausier [AppName] pausier überall |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
spiel auf? [DeviceBrand] spiel auch? auf [DeviceType] [DeviceBrand]? spiel hier auch spiel etwas anderes |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
stopp halt an hör auf stopp [DeviceLocation] stopp [DeviceBrand] stopp [DeviceType] stoppe auf dem [DeviceLocation] [DeviceBrand] |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
fortsetzen das fortsetzen |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
neu starten spiel vom anfang start von vorn von anfang an abspielen von vorne auf [DeviceBrand] abspielen beginne erneut noch mal von vorne noch einmal beginnen |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
spul vor spul auf? [AppName] vor |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
spul zurück spul [AppName] zurück spul auf? [DeviceBrand] zurück spul [DeviceBrand] [Duration] zurück |
The media rewinds 10 seconds. |
Previous Required for certification |
vorherige vorheriges zurück eins zurück geh zurück geh zum vorherigen vorheriges auf dem [DeviceLocation]? [DeviceBrand] spring/geh zurück/nach hinten auf [AppName] vorheriges auf [DeviceLocation] [DeviceType] vorheriges video/kanal auf [DeviceLocation] [DeviceType] überall vorheriges auf allen [DeviceType] vorheriges |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
nächste nächstes das nächste spring/geh vor spring/geh vorwärts vor überspring das eins weiter/vorwärts weiter spring nach vorn spring nach vorn auf [AppName]/[DeviceBrand] nächstes im [DeviceLocation] nächstes auf [DeviceLocation]? [DeviceType]/[DeviceBrand] gib mir das nächste von [AppName] nächstes auf allen [DeviceType] |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pause रोको एक second रुक जाओ एक second wait करना एक second pause हो जाओ ठहरना ज़रा थम जा freeze[Anaphor] को रोक दो[AppName] को pause कर दो मेरे [DeviceLocation] [Device] को pause करना मेरे [DeviceLocation] [DeviceType] को pause करना[DeviceLocation] पे/पर Device को रोक दो ज़रा |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
[SportsTeam] का [Event] लगा/चला दो [ActiveUserTrigger] [DeviceBrand] पर लगाओ/चलाओ [Country] में जो [SortType] है लगाओ/चलाओ [Country] से [Date] के [SortType] लगा/बजा देना [Anaphor] [Device] पर बजाएँ/लगाएँ [ListPosition] [Anaphor] लगा/बजा दीजिये [Country] के [City] में [SortType] है बजाओ/लगाओ [League] [Event] लगा/बजा दीजिये [Anaphor] play करो [ActiveUserTrigger] [Date] ही के [SortType] बजाओ [SportsTeam] versus [SportsTeamOpponent] का Event लगा दे [League] [Event] का [Version] चलाओ [Anaphor] [ActiveUserTrigger] [Device] पर लगा दो [ListPosition] बजा दो [Sport] [Event] लगाइए/बजाइए [Date] [Anaphor] play करो [DeviceLocation] पे [DeviceBrand] बजाओ/लगाओ |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
चुप हो जाओ/बस कर/quiet/चुप/शांत/शांति/shush/मुँह बंद करो stop [Anaphor] बंद करो/रोको [Anaphor] [Anaphor] stop/बंद करो/रोको [Anaphor] [MediaType] बंद करना stop [AppName] [AppName] बंद stop [Device] [Device] रोको stop [LocationNonSpecificQuantity] [LocationNonSpecificQuantity] stop/रोको stop [DeviceLocation] [DeviceLocation] stop/रोको stop [MediaType] [MediaType] stop/रोको |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
जारी रखो resume करो |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
फिर से चलाओ फिर से शुरू करो |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
[AppName] पर थोड़ा आगे कर दो[AppName] में fast forward करें[Anaphor] आगे/forward करनाfast forward करो[Anaphor] आगे करना ज़रा[Anaphor] वाले को आगे बढ़ाओ |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
थोड़ा reverse/rewind/पीछे करोrewind[AppName] को rewind करो[Anaphor] reverse/rewind/पीछे करो[DeviceLocation] के [Device] को rewind करना |
The media rewinds 10 seconds. |
Previous Required for certification |
previous/पीछे/पिछला/पिछलीprevious/पीछे/पिछला/पिछली वाली recipe [VisualModeTrigger][Anaphor] वापस जाओprevious/पीछे/पिछला/पिछली [Anaphor] पर वापिस जाओ पिछला वाला [Episode][Anaphor] पहला वाला [Episode] पर जानाprevious [LocationNonSpecificQuantity][LocationNonSpecificQuantity] previous/पीछे/पिछला/पिछली वाला लगाओ[DeviceBrand] पे पिछलाprevious/पीछे/पिछला/पिछली वाला [DeviceBrand][Anaphor] [DeviceBrand] पर previous/पीछे/पिछला/पिछली वाला[DeviceLocation] के [DeviceBrand] पर पिछला वाला[AppName] में पिछली वाली पर वापस जाओprevious/पीछे/पिछला/पिछली वाला [AppName] पर जा[ActiveUserTrigger] [Quantifier] [DeviceType] में पीछे जाओ पिछला [MediaType] play करो |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
[GroupDeviceBrand] [HomeAutomationType] पर अगला लगाओ[GroupDeviceBrand] पर अगला लगाओ[GroupDeviceBrand] वाले [HomeAutomationType] पर अगला चलाना[AppName] पर इसके बाद वाला दो[AppName] पर मुझे next वाला दे देनाnext recipe अगली recipe[DeviceLocation] पर इसके बाद वाला दो[LocationNonSpecificQuantity] अगला चलाओ अगला/next [Episode] play करो[DeviceLocation] पर DeviceBrand अगला वाला दो |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
metti in pausa / voglio mettere in pausa / posso mettere in pausa |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
riproduci /metti / fai partire
|
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
stop / ferma / spegni / smetti / basta / stoppa |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
riprendi |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
ricomincia |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
manda avanti / vai avanti / avanti veloce |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
vai indietro / mandalo indietro / indietro veloce / torna indietro |
The media rewinds 10 seconds. |
Previous Required for certification |
ritorna al precedente / vai indietro di uno / precedente / torna indietro / indietro |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
prossima / seguente / avanti / salta / successivo |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
ポーズ 一旦停止 一旦止めて[Anaphor]で一時停止[AppName]を一旦停止[DeviceLocation]の[DeviceBrand]をポーズして[DeviceLocation]の[DeviceType]を一時停止[DeviceBrand]をポーズして[DeviceType]を一旦停止して |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
[SportsTeam]の[Event]を再生して[Country]で[SortType]のやつかけて[Country]で[Date][SortType]のやつ流して[ListPosition]の[Anaphor]再生[Country]の[City]で[SortType]のやつストリームして[City]で[SortType]のやつ再生して[League]の[Event]かけて[MediaPlayer]で[AppName]を再生して[ActiveUserTrigger][SortType]を再生して[SportsTeam]対[SportsTeamOpponent]の[Event]をかけて[Version]の[League]の[Event]をストリームして[Sport]の[Event]を再生して[ActiveUserTrigger][DeviceBrand]でストリームして[DeviceBrand]でかけて[DeviceLocation]の[DeviceBrand]で流して |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
ストップ/して とめて 停止して もういい もういいや もういいよ もういいです 黙れ 中止 中止して 終了/して/[Quantifier]止めて[DeviceLocation]での再生を止めて[DeviceLocation]の[DeviceBrand]での再生をストップ[DeviceBrand]の再生止めて[DeviceType]をとめて[AppName]を終了[Anaphor]止めて |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
再開して |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
最初から始めて |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
[AppName]早送り[MediaType]を早送りして |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
巻き戻して [AppName]巻き戻して[MediaType]巻き戻し [DeviceLocation]の[DeviceType]巻き戻し |
The media rewinds 10 seconds. |
Previous Required for certification |
|
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
次 スキップ 次に行って[DeviceLocation]で次に行って[DeviceLocation]の[DeviceBrand]で次に行って[LocationNonSpecificQuantity]で次を再生[Episode]を再生して[VideoName]の[Episode]を再生[DeviceBrand]で再生 |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pausar/interromper |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
tocar/assistir/reproduzir
|
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
parar |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
continuar/ continue/continua |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
começar/começa/comece de novo |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
avançar/ ir para frente |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
voltar/retroceder/rebobinar |
The media rewinds 10 seconds. |
Previous Required for certification |
|
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
próximo/próxima |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
Feature | Sample Utterances | Expected Response |
---|---|---|
Pause Required for certification |
pausa |
The media pauses, similar to pressing the Pause button on your web player or remote control. |
Play Required for certification |
pon reproduce |
The media plays, similar to pressing the Play button on your web player or remote control. |
Stop Required for certification |
para |
The media stops, similar to pressing the Stop button on your web player or remote control. |
Resume Required for certification |
continúa |
The media resumes play, similar to pressing the Play button on your web player or remote control. |
Start over Required for certification |
empieza de nuevo vuelve a empezar comienza de nuevo vuelve a iniciar vuelve a comenzar |
The media starts over, adjusting the seek position back to the beginning of the media. |
Fast Forward Required for certification |
adelanta |
The media fast-forwards 10 seconds. |
Rewind Required for certification |
rebobina |
The media rewinds 10 seconds. |
Previous Required for certification |
anterior |
The previous episode plays. If this isn't possible, the user is taken to whatever was earlier in the current playlist. |
Next Required for certification |
siguiente salta muestra el siguiente siguiente en el sonos próxima en el jardín |
The next episode plays. If this isn't possible, the user is taken to whatever is next in the current playlist. |
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
EXTRA_DIRECTIVE_NAMESPACE: Alexa.PlaybackController
EXTRA_DIRECTIVE_NAME: <transport control command>
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payload
payload
contains one optional field:
"payload": {
"experience": {
"mode": "VOICE_OPTIMIZED",
}
}
For <transport control command>, the value can be any of the following:
pause
play
stop
resume
rewind
fastForward
previous
next
startOver
payload
contains an empty object: {}
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "<transport control command>",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "VSKTV",
"cookie": {
}
},
"payload": {
"experience": {
"mode": "VOICE_OPTIMIZED",
}
}
}
}
For <transport control command>
, 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:
if (response != null && sendResponse) {
Intent success = new Intent().putExtra(VSKIntentConstants.EXTRA_DIRECTIVE_STATUS, didSucceed);
try {
response.send(context, 0, success);
} catch(PendingIntent.CanceledException e) {
//we probably took too long to respond, log error
}
}
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.
Send a response back to Alexa when you receive a transport control directive from the PlaybackController
interface.
{
"context": {
"properties": []
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
},
"endpoint":{
"endpointId":"VSKTV"
},
"payload":{ }
}
}
If you cannot complete the customer request for some reason, reply with an error. See Error Handling for more details.
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:
For Alexa to send PlaybackController
directives to your Lambda, you must indicate support for it in your response to the Discover
directive sent through the Alexa.Discovery
interface. More details are provided in Alexa.Discovery
.
Last updated: Jun 09, 2021