Alexa.PlaybackController Interface
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.
Utterances
The Alexa.PlaybackController interface uses the pre-built voice interaction model.
The following examples show some user utterances:
Alexa, fast forward on device.
Alexa, next song/video/photo on device.
Alexa, go forward on device.
Alexa, pause device.
Alexa, resume device.
Alexa, play device.
Alexa, previous on device.
Alexa, rewind on device.
Alexa, start over on device.
Alexa, stop device.
Alexa, avance rapide sur nom de l'appareil.
Alexa, chanson/vidéo/photo suivante sur nom de l'appareil.
Alexa, suivant sur nom de l'appareil.
Alexa, pause nom de l'appareil.
Alexa, remets la lecture sur nom de l'appareil.
Alexa, joue sur nom de l'appareil.
Alexa, précédent sur nom de l'appareil.
Alexa, reviens en arrière sur nom de l'appareil.
Alexa, recommence sur nom de l'appareil.
Alexa, arrête nom de l'appareil.
Alexa, spule auf dem Gerät vor.
Alexa, nächstes Lied/Video/Foto auf dem Gerät.
Alexa, geh auf dem Gerät nach vorne.
Alexa, pausiere Gerät.
Alexa, Gerät fortsetzen.
Alexa, spiele Gerät ab.
Alexa, gehe auf Gerät zurück.
Alexa, spule auf Gerät zurück.
Alexa, Gerät neustarten.
Alexa, stoppe Gerät.
アレクサ、＜デバイス名＞を早送りにして
アレクサ、＜デバイス名＞で次の曲/ビデオ/写真にして
アレクサ、＜デバイス名＞を次にして
アレクサ、＜デバイス名＞を止めて
アレクサ、＜デバイス名＞を再開して
アレクサ、＜デバイス名＞で再生して
アレクサ、＜デバイス名＞を前にして
アレクサ、＜デバイス名＞を巻き戻して
アレクサ、＜デバイス名＞で最初から再生して
アレクサ、＜デバイス名＞を止めて
After the user says one of these utterances, Alexa sends a corresponding directive to your skill.
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": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "a description that is shown in the Alexa app",
"friendlyName": "Living Room TV",
"displayCategories": ["TV"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the 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.2",
"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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
FastForward error handling
If you can't handle a FastForward directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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 song/video/photo on device," Alexa sends the following directive to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Next",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Next error handling
If you can't handle a Next directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Pause error handling
If you can't handle a Pause directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Play error handling
If you can't handle a Play directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Previous error handling
If you can't handle a Previous directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Rewind error handling
If you can't handle a Rewind directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
StartOver error handling
If you can't handle a StartOver directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Stop error handling
If you can't handle a Stop directive successfully, respond with an Alexa.Video.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to video.
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": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an 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:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"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": "a unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 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:50Z",
"uncertaintyInMilliseconds": 500
}]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-12-01T18:20:50Z",
"uncertaintyInMilliseconds": 0
}]
}
}