Your Alexa Dashboards Settings

Alexa.RemoteVideoPlayer Interface

The RemoteVideoPlayer interface describes messages that are used to search and play video content.

Directives

The directives in this interface are supported for video skills.

The control and query directives in this interface are supported in skills that target the following languages:

  • English (U.K.)
  • English (U.S.)
  • German

See Develop Smart Home Skills in Multiple Languages for more information.

SearchAndPlay

Requests to play a specific piece of content. This message contains the desired media object and URI obtained described as an entity. This message contains an array of entities that specifies what to search and play.

“Alexa, watch title”

“Alexa, play title”

“Alexa, stream title”

“Alexa, start title”

Example Request

This example shows a request for a specific piece of content, “Manchester by the Sea”

{
  "directive": {
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "videoDevice-001",
      "cookie": {         
      }
    },
    "header": {
      "messageId": "5f2477e6-8f57-4606-af18-6990b8646794",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "name": "SearchAndPlay",
      "namespace": "Alexa.RemoteVideoPlayer",
      "payloadVersion": "3"
    },
    "payload": {
      "entities": [{
        "externalIds": {
          "gracenote": "MV000000099001"
        },
        "value": "Manchester by the Sea",
        "type": "Video"
      }],
      "timeWindow": {
        "end": "2016-09-07T23:59:00+00:00",
        "start": "2016-09-01T00:00:00+00:00"
      }
    }
  }
}

Payload description

Property Description Type Required
entities An array of entity objects to play array of Entity objects such as a Title, Franchise, Actor, Team or Media Type. For more information, see the entity type descriptions. Yes
timeWindow Provides the time window for the content the customer wants to play list of end and start times Yes
timeWindow.end The end time for the content search. string containing a time in ISO 8601 format Yes
timeWindow.start The start time for the content search. string containing a time in ISO 8601 format Yes

SearchAndDisplayResults

Requests to search and then display the results of a search in a way that is appropriate for your application. This means that you could provide the user with a side-loaded search screen, send the results to a companion mobile app, or display them on a device. This message contains an array of entities that specifies what to search for.

“Alexa, show me University of Washington Huskies games”

{
    "directive": {
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "appliance-001",
            "cookie": {}
        },
        "header": {
            "messageId": "b91ed654-5929-4bd1-996d-b1762395a644",
             "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "name": "SearchAndDisplayResults",
            "namespace": "Alexa.RemoteVideoPlayer",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [{
                    "externalIds": {
                        "gracenote": 100
                    },
                    "value": "games",
                    "type": "Event"
                 },
                {
                    "externaIds": {
                        "gracenote": "ST0000000666661"
                    },
                    "value": "University of Washington Huskies",
                    "type": "SportsTeam"
                }
            ],
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

Payload description

Property Description Type Required
entities An array of entity objects to play array ofEntity objects such as a Title, Franchise, Actor, Team or Media Type. For more information, see the entity type descriptions. Yes
timeWindow Provides the time window for the content the customer wants to play. For example if a customer wants to play an episode from last week, time window would indicate the preceding week. list of end time and a start times No
timeWindow.end The end time for the content search. string containing a time in ISO 8601 format No
timeWindow.start The start time for the content search. string containing a time in ISO 8601 format No

Handling Ambiguous Play Requests

Similar to SearchAndDisplayResults, SearchAndPlay supports multiple entity types, including a content title, franchise name, actor, director, sports team, media type and more. This means one of these directives may contain an ambiguous entity request. For example, a customer could request:

“Alexa, play a popular comedy”

-or-

“Alexa, play a Billy Bob Thornton movie”.

The Video Skill API is flexible in that, despite the ambiguity, you can decide how to act on the request. For example, you can:

  • Begin playing a popular comedy or Bob Thornton movie
  • Generate a list of the top 10 comedies or Bob Thornton movies and randomly select one for the customer to avoid repetition
  • Go straight to search results for that ambiguous entity

The way you respond is your choice, however it’s recommended that you accommodate a customer’s play request if at all possible.

Alexa.Response Event

When a SearchAndPlay or SearchAndDisplayResults directive successfully completes, you should respond with an Alexa.Response message.

Successful Response Example

{
    "context": {
        "properties": []
    },
    "event": {
        "endpoint": {
            "scope": {
                "type": "DirectedUserId",
                "directedUserId": "access-token-from-Amazon"
            },
            "endpointId": "videoDevice-001"
        },
        "header": {
            "messageId": "d47ab57a-aa33-4f16-99b6-2ba39c72f374",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

Payload description

No payload content required

Response Performance Requirements

You must respond to a search or search and play request in a timely manner. The following table describes the latency limits for responses by call percentage. .

Call Percentage Latency Limit
(in milliseconds)
50% 50 ms
90% 100 ms
99% 200 ms
Interface Description
Alexa.PlaybackController Provides directives for playing and moving around in a set of content; rewinding, fast forwarding and more.