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

PLAYING

The endpoint is playing the media.

PAUSED

The endpoint paused the media.

STOPPED

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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
    "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 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 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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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": "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.

Copied to clipboard.

{
    "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 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.

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
    "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
        }]
    }
}