Alexa.PlaybackStateReporter Interface
The Alexa.PlaybackStateReporter
interface defines properties and describes messages for reporting the playback state of audio or video content. This interface does not define any directives or events specifically, but reports the state of the endpoint, when playbackState
changes or when Alexa requests the current state of the endpoint. For more information, see the guidelines in State Reporting for Video Skills.
For the list of locales that are supported for the PlaybackStateReporter
interface, see List of Capability Interfaces and Supported Locales.
Discovery
You must specify that playbackState
is proactivelyReported
and retrievable
in your discovery response.
Example: Discover.Response
{
"event": {
"header": {
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"abc-123-def-456"
},
"payload":{
"endpoints":[
{
"endpointId":"uniqueIdOfEndpoint",
"friendlyName":"Living Room TV",
"description":"a description that is shown to the customer",
"displayCategories": [ "TV" ],
"cookie": {
},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackStateReporter",
"version": "1.0",
"properties": {
"supported": [
{
"name": "playbackState"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
]
}
]
}
}
}
Directives
This interface does not define any directives, but responds to Alexa's requests for endpoint state.
ReportState
A ReportState
directive is sent to request the state of an endpoint.
Example ReportState Request
The following example shows a request for the current state of an endpoint with the ID appliance-001
.
{
"directive": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "ReportState",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "appliance-001",
"cookie": {},
"scope":{
"type":"BearerToken",
"token":"access-token-from-skill"
}
},
"payload": {
}
}
}
Properties and Events
Properties
Property Name | Type | Description |
---|---|---|
playbackState |
PlaybackState | Indicates whether the content is PLAYING, PAUSED, or STOPPED. |
StateReport event
Use a StateReport
event to report the value of all of the endpoint properties in response to a ReportState
directive. For more information, see Understand State and Change Reporting.
Example: StateReport
The following example shows a StateReport
that reports the value of powerState
and playbackState
.
{
"context": {
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "StateReport",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {}
}
}
ChangeReport event
Use a ChangeReport
event to report when the value of one of the endpoint properties changes for any reason. Report additional unchanged property values in the context of the message.
Send ChangeReport
events to the Alexa event gateway. For more information about how to do this, see Send Events to the Event Gateway.
Example: ChangeReport
The following example shows a ChangeReport
where the playbackState
changed, and the powerState
was unchanged.
{
"context": {}
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}]
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "ChangeReport",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "token-from-Amazon"
},
"endpointId": "endpoint-001"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [{
"namespace": "Alexa.PlaybackStateReporter",
"name": "playbackState",
"value": {
"state": "PLAYING"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}]
}
}
}
}
Related Interfaces
Interface | Description |
---|---|
Alexa.PlaybackController | Provides directives for playing, pausing, stopping media playback. |