Alexa Blogs

Want the latest?

alexa topics

Recent Posts

Archive

How to Control Your Content with the Video Skill API

June 08, 2017

David Isbitski

Today we announced that we now enable video providers to control content with the Video Skill API, a new addition to the Alexa Skills Kit. Here is an overview of how to create video skills for Alexa so that your customers can easily find and consume video content without invoking a specific skill.

How It Works

The Video Skill API is available at the same top level that Alexa uses to build video experiences on Fire TV. This means your customers can open their favorite app and then use their Amazon Echo or other Alexa device to issue commands like “Alexa, find comedies,” “Alexa, tune to HBO,” or “Alexa, play episodes of Modern Family.” Customers can see the commands fulfilled instantly on their preferred streaming video devices.

The Video Skill API also includes a mechanism to enable catalog ingestion for improved accuracy and session management for request targeting based on real usage. The API offers simplified logic to handle requests to any one of potentially multiple video skills that a customer has set up, so your customers can make simple requests like ‘Alexa, Play Manchester by the Sea,’ and Alexa will know what to do.

The Video Skill API is launching today with the following capabilities:

  • Channel Navigation
  • Playing Content
  • Searching Content
  • Playback Controls

Creating an Alexa Video Skill

You create a video skill in the Amazon Developer Portal and then configure an AWS Lambda function. The Video Skill API sends your Lambda function requests and your code inspects the request, takes any necessary actions and then sends back a response. The following diagram shows the different components of the Video Skill API.

For a step-by-step guide to creating the custom Alexa skill and associated Lambda function code check out our guide here.

Discovering Devices

You will need to implement the Alexa.Discovery interface to allow your skill to request and identify the devices associated with your customer’s account. This interface lets a customer discover devices that can be controlled by your skill when they ask “Alexa, discover my smart home devices.” Your Alexa.Discovery Response would then return information about your device and what capabilities it has.

For more information on setting up your device for discovery, please see the Alexa.Discovery documentation here.

Playing Content

Playing video content is done through the SearchAndPlay directive as part of the Alexa.RemoteVideoPlayer namespace.

The SearchAndPlay directive signals that the customer has asked Alexa to ‘play’ an item. SearchAndPlay results in playback of the specifically requested title, or a title that best matches the requested entity. If there are no matched titles, search results are returned. Customer utterances that trigger a SearchAndPlay directive are “Alexa, watch title,” “Alexa, play title,” “Alexa, stream title,” or “Alexa, start title.”

Handling Ambiguous Play Requests

SearchAndPlay supports multiple entity types, including Title, Franchise, Actor, Director, Sports Team, Sport, League, Media Types, and Events. This means a customer can request playback for an ambiguous entity, for example: “Alexa, Play a popular comedy” or “Alexa, Play a Casey Affleck 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 Casey Affleck movie. Alternatively, you can generate a list of the top 10 comedies or Casey Affleck movies and randomly select one for the customer to avoid repetition. Or, you can go straight to search results for that ambiguous entity. This is up to the you, however it’s recommended that you accommodate a customer’s play request if at all possible.

Here is what a request from a customer for “Play Manchester by the Sea” would look like:

{
  "directive": {
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "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"
        },
        "name": "Manchester by the Sea",
        "type": "Video",
        "uri": "entity://provider/show/manchesterbythesea"
      }],
      "timeWindow": {
        "end": "2016-09-07T23:59:00+00:00",
        "start": "2016-09-01T00:00:00+00:00"
      }
    }
  }
}

When the SearchAndPlay directive successfully completes, you should respond with an Alexa.Response message. Here is an example of a successful response:

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

For more information on playing video content, please see the Alexa.RemoteVideoPlayer documentation here.

Searching Content

Searching through video content is done through the SearchAndDisplayResults directive as part of the Alexa.RemoteVideoPlayer namespace. The SearchAndDisplayResults directive enables you 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.

Here is what a request from a customer for “Alexa, show me UW Husky games” would look like:

{
    "directive": {
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
            "endpointId": "videoDevice-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
                    },
                    "name": "games",
                    "type": "Event",
                    "uri": "entity://provider/event/games"
                },
                {
                    "externaIds": {
                        "gracenote": "ST0000000666661"
                    },
                    "name": "UW Huskies",
                    "type": "SportsTeam",
                    "uri": "entity://provider/sportsteam/someURI"
                }
            ],
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

Similar to the SearchAndPlay request, you respond with an Alexa.Response that indicates the request completed successfully.

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

For more information on searching video content, please see the Alexa.RemoteVideoPlayer documentation here.

Playback Controls

Controlling video playback is done through the Playback control directives included in the Alexa.PlaybackController namespace. These directives focus on manipulating the stream of content being played such as pausing or resuming playback. When your skill receives one of these directives, you should take a transport control action on the video that is currently playing.

As with any directive, these contain the directive name and payload along with required authorization data and a specified target. These directives are sent to the skill synchronously and are expected to either return a response with a result status or an error.

Use Cases

Action Directive "Alexa..."
Play/Resume PlaybackController.Play play, resume
Pause PlaybackController.Pause pause
Rewind/Fast-Forward (duration) SeekController.AdjustSeekPosition rewind 60 seconds, fast forward 4 minutes
Rewind (open-ended) PlaybackController.Rewind rewind
Fast-forward (open-ended) PlaybackController.FastForward fast forward
Previous PlaybackController.Previous previous, previous episode
Next PlaybackController.Next next, next episode

Here is what a request from a customer to pause the video would look like using the PlaybackController.Pause directive:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Pause",
      "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId" :  "videoDevice-001",
      "cookie": {
      }
    },
    "payload": {
    }
  }
}

If any of the directives in this interface successfully complete, you should send a response event. Here is an example:

{
  "context": {
    "properties": []
  },
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "DirectedUserId",
        "directedUserId": "some-Amazon-user-id"
       },
       "endpointId" :  "videoDevice-001"
    },
    "payload": {
    }
  }
}

For more information on controlling video playback, see the Alexa.PlaybackController documentation here.

Channel Navigation

The Alexa Video Skill API also allows your customer to change channels using the The ChangeChannel function included in the Alexa.ChannelController namespace. ChangeChannel communicates that the target device should change its channel. This directive payload contains a channel object and expects either a result status or an error (see Alexa.Video.ErrorResponse Event reference)

Payload Fields

Field Description Type Required
channel Describes a channel. object Yes
channel.number A number that identifies the specified channel such as 5 or 12.1. double No, but number, callSign, affiliateCallSign or uri must be specified.
channel.callSign Specifies a channel by call sign such as PBS. string No, but number, callSign, affiliateCallSign or uri must be specified.
channel.affiliateCallSign Specifies a channel by local affiliate call sign such as KCTS9. string No, but number, callSign, affiliateCallSign or uri must be specified.
channel.uri The URIof the channel such as "entity://provider/channel/12307" string No, but number, callSign, affiliateCallSign, or uri must be specified.
channelMetadata Provides additional information about the specified channel. object No
channelMetadata.name Another value that identifies the channel such as "FOX." string No
channelMetadata.image A URL to an image that describes the channel. string No

Here is an example of changing the channel when a customer asks “Change channel to PBS”:

{
  "directive": {
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "videoDevice-001",
      "cookie": {}
    },
    "header": {
      "messageId": "47971513-5e09-4c5f-826b-d1c2b75800a7",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/==",
      "name": "ChangeChannel",
      "namespace": "Alexa.ChannelController",
      "payloadVersion": "3"
    },
    "payload": {
      "channel": {
        "affiliateCallSign": "KBTC",
        "callSign": "KBTC",
        "channelImage": "http://s3.amazonaws.com/channel_images/pbs.png",
        "name": "PBS",
        "number": 123
      }
    }
  }
 }

Here is the response that would be returned:

{
  "context": {
    "properties": []  
  },
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "DirectedUserId",
        "directedUserId": "some-Amazon-user-id"
       },
       "endpointId" :  "videoDevice-001"
    },
    "payload": { }
  }
}

If the channel could not be found an Alexa.VideoError Response could be returned:


{
    "event": {
        "header": {
            "messageId": "4e02d3c8-85e8-4e32-8a1b-08c1d52122ad",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/==",
            "name": "ErrorResponse",
            "namespace": "Alexa.Video",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "DirectedUserId",
                "directedUserId": "some-Amazon-user-id"
            },
            "endpointId": "videoDevice-001"
        },
        "payload": {
            "message": "optional information about the error that will be logged by Alexa",
            "type": "NOT_SUBSCRIBED"
        }
    }
}

For more information on changing video channels, see the Alexa.ChannelController documentation here.

For more information about the Alexa Video Skill API, check out the following resources:

Build a Skill, Get an Echo Dot

The Alexa Skills Kit (ASK) enables developers to build capabilities, called skills, for Alexa. ASK is a collection of self-service APIs, documentation, tools, and code samples that make it fast and easy for anyone to add skills to Alexa. 

Developers have built more than 13,000 skills with ASK. Explore the stories behind some of these innovations, then start building your own skill. Once you publish your skill, apply to receive a free Echo Dot. This promotion is available in the US only. Check out our promotions in the UK, Germany, and India. 

Permalink |  Share

Want the latest?

alexa topics

Recent Posts

Archive

DevAssistant
Amazon Developer Assistant