Alexa.PlaybackController Interface
The PlaybackController interface describes messages that are used to play, stop, and navigate playback for audio or video content.
- Discovery
- Directives
- Properties and Events
- Additional Sample Code
- Related Interfaces
Discovery
You must specify the directives your endpoint supports when you describe it in your discovery response. You indicate the operations the endpoint supports by including a supportedOperations array.
Supported operations values:
Example discovery response with supportedOperations
{
"event": {
"header": {
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"abc-123-def-456"
},
"payload":{
"endpoints":[
{
"capabilities":
[
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"supportedOperations" : ["Play", "Pause", "Stop"]
}
]
...
}
]
}
}
}
Directives
The control and query directives in this interface have different language support depending on the skill type:
| Skill type | Language Support |
|---|---|
| Video skills | English (UK), English (U.S), French, German |
| Smart home skills | English - all locales, French, German |
See Develop Smart Home Skills for Multiple Languages for more information about language support for smart home skills.
FastForward
Request to fast forward the current content.
English
User: Alexa, fast forward on device
German (Deutsche)
User: Alexa, spule auf dem gerät vor
French (français)
User: Alexa, mets en avance rapide l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "FastForward",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Next
Request to go to the next item in content playback.
English
User: Alexa, next song/video/photo on device
User: Alexa, go forward on device
German (Deutsche)
User: Alexa, nächstes lied/video/foto auf dem gerät
User: Alexa, geh vorwärts auf dem gerät
French (français)
User: Alexa, mets la chanson/la video/la photo suivante sur l’appareil
User: Alexa, mets en avance rapide sur l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Next",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Pause
Request to pause the playback of audio or video content.
English
User: Alexa, pause device
German (Deutsche)
User: Alexa, pausiere gerät
French (français)
User: Alexa, pause l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Pause",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Play
Request to play or resume play of audio or video content.
English
User: Alexa, resume device
User: Alexa, play device
German (Deutsche)
User: Alexa, gerät fortsetzen
User: Alexa, gerät abspielen
French (français)
User: Alexa, Remets lecture sur l’appareil
User: Alexa, mets lecture sur l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Play",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Previous
Request to go to the previous item in content playback.
English
User: Alexa, previous on device
German (Deutsche)
User: Alexa, geh zurück auf gerät
French (français)
User: Alexa, chaîne précédente
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Previous",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Rewind
Request to rewind the current content.
English
User: Alexa, rewind on device
German (Deutsche)
User: Alexa, spule auf Gerät zurück
French (français)
User: Alexa, reviens en arrière sur l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Rewind",
"messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
StartOver
A request to start playback from the beginning of the audio or visual content.
English
User: Alexa, start over on device
German (Deutsche)
User: Alexa, gerät neustarten
French (français)
User: Alexa, reprends la lecture sur l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "StartOver",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
},
"payload": {}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Stop
Request to stop playback of audio or video content.
English
User: Alexa, stop device
German (Deutsche)
User: Alexa, stoppe gerät
French (français)
User: Alexa, arrête l’appareil
Example request
{
"directive": {
"header": {
"namespace": "Alexa.PlaybackController",
"name": "Stop",
"messageId": "abc-123-def-456",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
| None | No required or optional fields in the payload. | N/A | N/A |
Properties and Events
For this capability, you must reply:
- Synchronously, which means you send a Response to Alexa from the Lambda function.
When you send a Response, you should include the state of the interface properties in the context of the message.
Properties
The Alexa.PlaybackController interface doesn't define any reportable properties at this time.
Response
If any of the directives in this interface successfully complete, you should send a response event.
Example Response
{
"context": {
"properties": []
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
},
"endpoint":{
"endpointId":"appliance-001"
},
"payload":{ }
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo:
Related Interfaces
| Interface | Description |
|---|---|
| Alexa.RemoteVideoPlayer | Provides directives for searching and playing content. |
| Alexa.PlaybackStateReporter | Provides events for reporting the state of playback endpoints. |