Alexa.PlaybackController Interface 3
Implement the Alexa.PlaybackController
interface in your Alexa skill so that users can play, stop, and navigate playback for audio or video content. After the endpoint performs the requested action, your skill reports the playback state of the endpoint to Alexa by using the Alexa.PlaybackStateReporter
interface.
For the list of languages that the Alexa.PlaybackController
and Alexa.PlaybackStateReporter
interfaces support, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
The Alexa.PlaybackController
interface uses the pre-built voice interaction model. After the user says one of the following utterances, Alexa sends a corresponding directive to your skill.
The following examples show some user utterances:
أليكسا، قدّمي على الجهاز
أليكسا، اللي بعده
أليكسا، وقفي
أليكسا، إستمرّي
أليكسا، شغّلي الجهاز
أليكسا، اللي قبله على الجهاز
أليكسا، رجّعي على الجهاز
اليكسا، رجعي 40 ثانية
أليكسا، ابدأي من البداية
Alexa, fast forward on device.
Alexa, next.
Alexa, pause device.
Alexa, resume device.
Alexa, play device.
Alexa, previous on device.
Alexa, rewind on device.
Alexa, start over.
Alexa, stop device.
Alexa, avance surnom de l'appareil.
Alexa, suivant€ sur nom de l'appareil.
Alexa, mets sur pause.
Alexa, joue sur nom de l'appareil.
Alexa, précédent€.
Alexa, rembobine.
Alexa, recommence.
Alexa, stop.
Alexa, spul vor auf dem Gerät vor.
Alexa, nächstes Lied/Video/Foto auf dem Gerät.
Alexa, pause.
Alexa, abspielen.
Alexa, vorheriges.
Alexa, fortsetzen.
Alexa, spul zurück.
Alexa, neu starten
Alexa, stopp Gerät.
Alexa, आगे बढ़ाओ
Alexa, अगला
Alexa, pause करो
Alexa, चलाओ
Alexa, पिछला
Alexa, जारी रखो
Alexa, rewind करना
Alexa, फिर से चलाओ
Alexa, stop करो
Alexa, vai avanti.
Alexa, metti in pausa.
Alexa, riproduci.
Alexa, torna indietro.
Alexa, riprendi.
Alexa, manda indietro.
Alexa, ricomincia.
Alexa, stop.
アレクサ、<デバイス名>を早送りにして
アレクサ、<デバイス名>で次の曲/ビデオ/写真にして
アレクサ、次
アレクサ、<デバイス名>を止めて
アレクサ、<デバイス名>を再開して
アレクサ、<デバイス名>で再生して
アレクサ、<デバイス名>を前にして
アレクサ、<デバイス名>を巻き戻して
アレクサ、<デバイス名>で最初から再生して
アレクサ、<デバイス名>を止めて
Alexa, avançar.
Alexa, próximo.
Alexa, pausar.
Alexa, reproduzir.
Alexa, anterior.
Alexa, continuar.
Alexa, voltar.
Alexa, começar de novo.
Alexa, parar.
Alexa, ativa o modo de repetição contínua.
Alexa, adelanta.
Alexa, siguiente.
Alexa, pausa.
Alexa, pon.
Alexa, anterior.
Alexa, continúa.
Alexa, rebobina.
Alexa, empieza de nuevo.
Alexa, para.
Alexa, spoel vooruit op device.
Alexa, volgende.
Alexa, pauzeer device.
Alexa, hervat device.
Alexa, speel device.
Alexa, vorige op device.
Alexa, spoel terug op device.
Alexa, start opnieuw.
Alexa, stop device.
Reportable properties
The Alexa.PlaybackController
and Alexa.PlaybackStateReporter
interfaces use the playbackState
property as the primary property. You identify that you support the property in your discovery response.
The playbackState
defines the current state of the endpoint that performs the requested action. The following example shows that the endpoint is playing the requested content.
{
"name": "playbackState",
"value": {
"state": "PLAYING"
}
}
The following table shows the valid values for playbackState
.
State | Description |
---|---|
|
The endpoint is playing the media. |
|
The endpoint paused the media. |
|
The endpoint isn't playing the media. |
Discovery
You describe endpoints that support Alexa.PlaybackController
and Alexa.PlaybackStateReporter
by using the standard discovery mechanism described in Alexa.Discovery
.
In the Alexa.PlaybackController
interface, you indicate the operations that the endpoint supports by including a supportedOperations
array. Include one or more operation values: Play
, Pause
, Stop
, StartOver
, Previous
, Next
, Rewind
, FastForward
. In the Alexa.PlaybackStateReporter
interface, you indicate that you support the playbackState
property.
Use TV
, STREAMING_DEVICE
, GAME_CONSOLE
, or another appropriate display category. For the full list of display categories, see display categories.
Discover response example
The following example shows an Alexa.Discover.Response
message for a device that supports the Alexa.PlaybackController
, Alexa.PlaybackStateReporter
, and Alexa.EndpointHealth
interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Manufacturer of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"properties": {},
"supportedOperations": ["Play", "Pause", "Stop", "Next", "Previous", "FastForward", "Rewind", "StartOver"]
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackStateReporter",
"version": "3",
"properties": {
"supported": [{
"name": "playbackState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
The Alexa.PlaybackController
interface supports directives to navigate and play video and audio content. For video content, include the playbackState
in the response.
FastForward directive
Support the FastForward
directive so that users can request to fast-forward the current content.
FastForward directive example
After the user says, "Alexa, fast forward on device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "FastForward",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
FastForward directive payload
The FastForward
directive doesn't define any payload parameters.
FastForward response
If you handle a FastForward
directive successfully, respond with an Alexa.Response
event.
The following example shows a FastForward
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PAUSED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
FastForward error handling
If you can't handle a FastForward
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Next directive
Support the Next
directive so that users can request to go to the next item in content playback.
Next directive example
After the user says, "Alexa, next," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Next",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Next directive payload
The Next
directive doesn't define any payload parameters.
Next response
If you handle a Next
directive successfully, respond with an Alexa.Response
event.
The following example shows a Next
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "STOPPED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Next error handling
If you can't handle a Next
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Pause directive
Support the Pause
directive so that users can request to pause the playback of audio or video content.
Pause directive example
After the user says, "Alexa, pause device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Pause",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Pause directive payload
The Pause
directive doesn't define any payload parameters.
Pause response
If you handle a Pause
directive successfully, respond with an Alexa.Response
event.
The following example shows a Pause
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PAUSED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Pause error handling
If you can't handle a Pause
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Play directive
Support the Play
directive so that users can request to play or resume play of audio or video content.
Play directive example
After the user says, "Alexa, play device" or "Alexa, resume device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Play",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Play directive payload
The Play
directive doesn't define any payload parameters.
Play response
If you handle a Play
directive successfully, respond with an Alexa.Response
event.
The following example shows a Play
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Play error handling
If you can't handle a Play
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Previous directive
Support the Previous
directive so that users can request to go to the previous item in content playback.
Previous directive example
After the user says, "Alexa, previous on device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Previous",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Previous directive payload
The Previous
directive doesn't define any payload parameters.
Previous response
If you handle a Previous
directive successfully, respond with an Alexa.Response
event.
The following example shows a Previous
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "STOPPED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Previous error handling
If you can't handle a Previous
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Rewind directive
Support the Rewind
directive so that users can request to rewind the current content.
Rewind directive example
After the user says, "Alexa, rewind on device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Rewind",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Rewind directive payload
The Rewind
directive doesn't define any payload parameters.
Rewind response
If you handle a Rewind
directive successfully, respond with an Alexa.Response
event.
The following example shows a Rewind
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PAUSED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Rewind error handling
If you can't handle a Rewind
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
StartOver directive
Support the StartOver
directive so that users can request to start playback from the beginning of the audio or visual content.
StartOver directive example
After the user says, "Alexa, start over on device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "StartOver",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
StartOver directive payload
The StartOver
directive doesn't define any payload parameters.
StartOver response
If you handle a StartOver
directive successfully, respond with an Alexa.Response
event.
The following example shows a StartOver
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
StartOver error handling
If you can't handle a StartOver
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
Stop directive
Support the Stop
directive so that users can request to stop playback of audio or video content.
Stop directive example
After the user says, "Alexa, stop device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Stop",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint id",
"cookie": {}
},
"payload": {}
}
}
Stop directive payload
The Stop
directive doesn't define any payload parameters.
Stop response
If you handle a Stop
directive successfully, respond with an Alexa.Response
event.
The following example shows a Stop
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "STOPPED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Stop error handling
If you can't handle a Stop
directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse
event. For general errors, respond with a generic Alexa.ErrorResponse
event.
State reporting
Alexa sends a ReportState
directive to request information about the state of an endpoint. When Alexa sends a ReportState
directive, you send a StateReport
event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
StateReport response example
The following example shows the current state of the endpoint after a Play
directive request to play content on the device.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send an Alexa.ChangeReport
event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see State Reporting for Video Skills.
ChangeReport event example
The following example shows that the playback state of the endpoint changed when the user stopped the content play.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "STOPPED"
},
"timeOfSample": "2021-12-01T18:20:00.00Z",
"uncertaintyInMilliseconds": 500
}]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:00:00.00Z",
"uncertaintyInMilliseconds": 0
}]
}
}
Related topics
Last updated: Aug 23, 2024