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.

Warning: With app-only integrations, instead of using 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.

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).

Note: Watch out for this edge case. The user might be watching content in your app, and say "Alexa, pause" and then subsequently quit your app. The user then says "Alexa, resume on <your app>"; ideally, your app should be able to launch and resume playback.

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

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

App-only Integrations
Cloudside Integrations

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