Alexa.RemoteVideoPlayer Interface

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

For the list of locales that are supported for the RemoteVideoPlayer interface, see List of Capability Interfaces and Supported Locales.

• Directives
  • SearchAndPlay
  • SearchAndDisplayResults
  • Handling Ambiguous Play Requests
• Alexa.Response Event
  • Response Performance Requirements
• Related Interfaces

Directives

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.

User: Alexa, watch title
User: Alexa, titel anschauen

User: Alexa, play title
User: Alexa, titel abspielen

User: Alexa, stream title
User: Alexa, titel streamen

User: Alexa, start title
User: Alexa, titel starten

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": "abc-123-def-456",
      "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

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.

User: Alexa, show me the movie Manchester by the Sea
User: Alexa, zeige mir den film Manchester by the Sea

Example Request:

{
    "directive": {
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "appliance-001",
            "cookie": {}
        },
        "header": {
            "messageId": "abc-123-def-456",
             "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "name": "SearchAndDisplayResults",
            "namespace": "Alexa.RemoteVideoPlayer",
            "payloadVersion": "3"
        },
        "payload": {
            "entities": [
                   {
                    "externaIds": {
                        "gracenote": "ST0000000666661"
                    },
                    "name": "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

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:

User: Alexa, play a popular comedy
User: Alexa, spiele eine beliebte Komödie ab

-or-

User: Alexa, play a Billy Bob Thornton movie
User: Alexa, spiele einen film mit Billy Bob Thornton

The Video Skill API is flexible in that, despite ambiguity, you can decide how to act on a 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

You can choose how to respond, 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": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

Payload description

No payload content required

Response Performance Requirements

The table describes the latency limits for search and play request responses by call percentage.

See the Testing Guide for more details.

Related Interfaces