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:

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.

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

​Utterances

​Reportable properties

​Discovery

​Discover response example

​Directives

​FastForward directive

​FastForward directive example

​FastForward directive payload

​FastForward response

​FastForward error handling

​Next directive

​Next directive example

​Next directive payload

​Next response

​Next error handling

​Pause directive

​Pause directive example

​Pause directive payload

​Pause response

​Pause error handling

​Play directive

​Play directive example

​Play directive payload

​Play response

​Play error handling

​Previous directive

​Previous directive example

​Previous directive payload

​Previous response

​Previous error handling

​Rewind directive

​Rewind directive example

​Rewind directive payload

​Rewind response

​Rewind error handling

​StartOver directive

​StartOver directive example

​StartOver directive payload

​StartOver response

​StartOver error handling

​Stop directive

​Stop directive example

​Stop directive payload

​Stop response

​Stop error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Reportable properties

Discovery

Discover response example

Directives

FastForward directive

FastForward directive example

FastForward directive payload

FastForward response

FastForward error handling

Next directive

Next directive example

Next directive payload

Next response

Next error handling

Pause directive

Pause directive example

Pause directive payload

Pause response

Pause error handling

Play directive

Play directive example

Play directive payload

Play response

Play error handling

Previous directive

Previous directive example

Previous directive payload

Previous response

Previous error handling

Rewind directive

Rewind directive example

Rewind directive payload

Rewind response

Rewind error handling

StartOver directive

StartOver directive example

StartOver directive payload

StartOver response

StartOver error handling

Stop directive

Stop directive example

Stop directive payload

Stop response

Stop error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics