GetPlayableItems Directives for Channel Navigation (VSK Echo Show)

When users say utterances to change the channel (e.g., "Watch PBS") the VideoContentProvider API sends a GetPlayableItems directive to your Lambda with information about the desired channel to play.

The expected response from your Lambda is a GetPlayableItemsResponse, as shown in the following diagram.

• Utterances for GetPlayableItems (Channel Navigation)
• GetPlayableItems Example (Channel Navigation)
• Payload Descriptions
  • Entity Types
  • Experience Types
• Lambda Response
• Response Example (Channel Navigation)
• Payload Descriptions

Utterances for GetPlayableItems (Channel Navigation)

When users say the following channel change utterances, Alexa sends a GetPlayableItems directive to your Lambda. It's similar to the regular GetPlayableItems directive but with properties specific to channels.

Note that here implementations for multimodal devices differ from Fire TV apps when it comes to channels. With Fire TV apps, there is a separate directive for channel navigation (ChangeChannel), whereas multimodal implementations use GetPlayableItems for both play utterances and channel navigation utterances, but with different properties.

GetPlayableItems Example (Channel Navigation)

The following is an example of a GetPlayableItems directive for a specific channel. The payload has fields unique to channel scenarios.

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Channel",
                    "value": "PBS",
                    "externalIds": {
                        "imdb": "tt4574334"
                    },
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": "123"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "start": "2016-09-01T00:00:00+00:00",
                "end": "2016-09-07T23:59:00+00:00"
            }
        }
    }
}

Note that entities with "type": "Channel" contain information for a television channel.

Payload Descriptions

The following table describes the payload for a GetPlayableItems directive.

 {
  "type": "Channel",
  "value": "PBS",
  "externalIds": {
      "imdb": "tt4574334"
  },
  "entityMetadata": {
      "channelCallSign": "KBTC",
      "channelNumber": "123"
  }
} 

Entity Types

The entities object consists of a list of objects, each of which contains a type and a value along with other possible data such as external IDs. The following values are possible for the type value: Actor, App, Channel, Character, Director, Episode, Event, Franchise, Genre, League, MediaType, ProductionCompany, Season, Sport, SportsTeam, Video, Popularity, Recency, and VideoResolution. Details about the payloads for each entity type are provided in the sections below.

Actor

Actor represents an actor credited in video media content; for example, Casey Affleck might contain the following:

App

App represents the explicit app name specified by the user in utterance; for example, "Manchester by the Sea on Prime" might contain the following:

Channel

Channel represents the identifying data for a television channel; for example, "PBS" might contain the following:

Character

A Character represented in video media content.

Director

Director represents the director name for the video media content; for example, "Kenneth Lonergan" might contain the following:

Episode

Episode represents the episode number for serial content like TV Shows; for example, the eighth episode of "Transparent" would have episode number 8.

Event

An Event is a reference to a type of event; examples would include sports, music, or other types of events. For example, searching for "Football games" would search for a game event entity and a football sport entity.

Franchise

A Franchise is a video entity which can represent a number of video entities, like movies or TV shows. For example, take the fictional franchise "Intergalactic Wars" which represents a collection of movie trilogies, as well as animated and live action TV shows. This entity type was introduced to account for requests by customers such as "Find Intergalactic Wars movies", which would search for all "Intergalactic Wars" programs of the MOVIE value for MediaType, rather than attempting to match to a single title.

Genre

Genre represents the genre of video media content such as action, drama or comedy. For example, the Action genre might contain the following:

League

League represents the categorical information for a sporting league; for example, NCAA is a league that might contain the following:

MediaType

MediaType represents the media type category of a particular piece of content; for example, the MediaType for "Manchester by the Sea" would be MOVIE.

ProductionCompany

ProductionCompany represents the production company name for the video media content; for example, Marvels, Disney.

Season

Season represents the season number for serial content like TV Shows; for example, the season two of "Transparent" would have season number 2.

Sport

Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:

SportsTeam

SportsTeam represents the categorical information of a professional sports team; for example, "University of Washington Huskies" is a sports team that might contain the following:

Video

Video represents the identifying data for the piece of video content; for example, "Manchester by the Sea" might contain the following:

Popularity

Popularity indicates whether the user asks for popular content.

Recency

The resolved values for Recency indicate whether the user asks for new or old content.

VideoResolution

VideoResolution represents the requested video resolution in one of the following standards:

• SD (480p)
• HD (720p-1080p)
• 4k (2160p)
• 8k (4320p)

Note that multimodal devices have the following additional entity types: LISTTYPE, SORTTYPE.

LISTTYPE is populated when users wants to browse their Watchlist or Library. For example, utterances like "Show me my Watchlist" or "Show me my Video Library." LISTTYPE can have the following enum values:

• WATCHLIST: For "Show me my Watchlist" — used to show videos the user has added to their watchlist.
• LIBRARY: For "Show me my Video Library" — used to show videos that are in the users' library. Typically, these are the videos that have been purchased by the user.

SORTTYPE is used to give additional information about the request that should be used during the searches and how results need to be sorted. For example, for "Show me recommended movies," Alexa needs recommendations from the content provider. SORTTYPE can have the following enum value:

• RECOMMENDED: This value is populated for utterances like "Show me recommended movies," or "Show me recommended action movies," etc.

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.

The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.

• VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.

• DEFAULT: The default displays of all search results list format, regardless of the device used for the search.

To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

Lambda Response

After receiving a GetPlayableItems directive, your Lambda must return a GetPlayableItemsResponse response that follows the structure here. The response structure in this case is similar to the response returned for the GetDisplayableItems directive.

Follow these guidelines in your response: 

• Remember that the goal of the GetPlayableItems directive is to get a single item that can be played for the directive. 

• If there is only one item to play, you can just return that one item, and Alexa will play the item. 

• If it's not clear which item to play, you can choose to return multiple items in the response. Alexa will ask the user to choose which one to play. For example, if the user says, "Play Star Wars," there can be multiple movies in the Star Wars franchise returned in the response or multiple movies and TV shows pertaining to Star Wars. if you return multiple results, Alexa sends a GetDisplayableItemsMetadata directive to fetch the metadata and display search results. Note that the number of results returned in the first call should not exceed the resultLimit parameter specified in the directive.

• If the only result found is not playable because the user is not entitled to play the title, or because a subscription is required, you can return that one item. Alexa fetches metadata and renders a prompt to either buy or rent or subscribe once Alexa finds that this item is not playable. After that, the user can trigger the purchase workflow to buy/rent the title and play it afterwards.

• If multiple results are found that are not playable, you can choose to return all the results, and Alexa will either disambiguate with the user about which item to play, or render an informational prompt to buy, rent, or subscribe to the items.

• If multiple results are found, with some playable and some not, then you should favor the playable one and return the playable result so that it can be played on the device.

Response Example (Channel Navigation)

The following is an example GetPlayableItemsResponse related to a channel change scenario.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetPlayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}

Payload Descriptions

The following table describes the payload fields in a GetPlayableItemsResponse.

Last updated: Nov 02, 2020