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
                }]
            }
        }
    }
}
Interface Description
Alexa.PlaybackController Provides directives for playing, pausing, stopping media playback.