GetPlayableItemsMetadata Directives (VSK MM)

Immediately after Alexa receives your Lambda's response to GetPlayableItems, the VideoContentProvider API sends a GetPlayableItemsMetadata directive as a follow-up to get metadata for the items returned in GetPlayableItems.

The following diagram shows the Alexa directive and Lambda response.

GetPlayableItemsMetadataItems Directive and Lambda GetPlayableItemsMetadataResponse

Utterances for GetPlayableItemsMetadata Directives

No utterances prompt Alexa to send GetPlayableItemsMetadata directives. Instead, Alexa sends this directive as a follow-up after receiving your Lambda's response to GetPlayableItems.

Handling GetPlayableItemsMetadata Directives

The purpose of GetPlayableItemsMetadata is to retrieve metadata necessary to initiate playback of the requested item. Your Lambda response should include basic metadata so that Alexa can render the correct voice response and initiate playback of the content.

Similar to GetDisplayableItemsMetadata, the GetPlayableItemsMetadata directive contains only the content id values for which Alexa needs metadata (to play the media). Your response should not include any metadata that would be needed to display search results.

GetPlayableItemsMetadata Example

The following is a sample GetPlayableItemsMetadata directive. In this example, Alexa requests metadata for a mediaIdentifier with a value of recordingId://provider1.dvr.rp.1234-2345-63434-asdf. Only return metadata for those entity id values specified in the GetPlayableItemsMetadata directive.

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifier": {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                }
        }
    }
}

The directive for a channel change GetPlayableItemsMetadata is identical except that the mediaIdentifier might have a different id, such as this:

"payload": {
    "locale": "en-US",
    "mediaIdentifier": {
            "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
        }
}

In this case, the id is related to a channel rather than a specific media title.

Lambda Response

Your Lambda's response, GetPlayableItemsMetadataResponse, should contain only metadata information required for playback and for rendering any success prompts before playing the video. Although the GetPlayableItemsMetadataResponse is highly similar to GetDisplayableItemsMetadataResponse, the GetPlayableItemsMetadataResponse contains the playbackContextToken. This token contains an identifier that Alexa will pass on to your web player. The playbackContextToken is an identifier you choose related to your media.

Alexa sends the playbackContextToken to your web player, and your web player can convert the identifier into a playback URL. This process is explained in Step 4: Understand How Your Web Player Gets the Media Playback URL. In the code example above, the playbackContextToken is a stringified object (a key-value pair consisting of streamUrl and title parameters) because this is the format the sample web player expects:

"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",

Depending on how you code your web player to process this identifier, you might simply use a string or some other format.

The responses for ON_DEMAND (VOD) media differs from the responses for LIVE (linear) media. Not only does the contentType differ, LIVE responses contain networkDetails.

Example Response for an ON_DEMAND TV Show

The following response shows an example for video-on-demand (VOD) content.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "The Big Bang Theory",
                    "contentType": "ON_DEMAND",
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "2",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "The Terminator Decoupling"
                    },
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "absoluteViewingPositionMilliseconds": 1232340
                }
            ]
        }
    }
}

Example Response for a LIVE movie

The following response shows an example response for video-on-demand (VOD) content.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Example Response for Channel Change Scenario

The following is an example response for a channel change scenario.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Payload Descriptions

The following table describes the payload for a GetPlayableItemsMetadataResponse response.

Payload Descriptions
Field Description Data Type
searchResults
required
The list of search results List
name
required

The name of the video. This is used to render a prompt to the user about the video that is going to be played. For example, "Here's Interstellar."

Example: Interstellar

String
contentType

ContentType specifies the content type for the video that was returned in the search results. If you send a recorded movie or TV show, the contentType is set to RECORDING. If the result contains information about a live TV show, then the contentType is set to LIVE. If the result contains an on-demand content, then the contentType is set to ON_DEMAND.

ContentType is also used to render a prompt to the user. For example, if the contentType is LIVE, Alexa renders a prompt such as, "Here's the Academy Awards now airing on CBS, from your DVR." If the contentType is RECORDING, Alexa renders a prompt such as, "Here's the Academy Awards from your DVR."

Examples: RECORDING, LIVE, ON_DEMAND

Enum
playbackContextToken
required

Token that allows mapping of entities back to your system for further identification. You can send any string identifier as long as you can map it back to identify an entity on your side. This token is opaque to Alexa and is sent to the device for playback purposes. It can be the same media identifier that was used to fetch the metadata information (if that is what is needed for playback), or it can be a different serialized string with additional information that is required for playback.

Note: If you're using the sample web player, the playbackContextToken must be a JSON object converted to a string. The object must contain streamUrl and title key-value pairs. See Step 4: Understand How Your Web Player Gets the Media Playback URL for details.

Opaque string
parentalControl
required

Parental Control information based on the user and the video.

Object
pinControl
required

This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.

  • REQUIRED: This means that parental control applies to this item based on the user's setting. When this is set, there is a lock icon displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.
  • NOT_REQUIRED: This means that parental control does not apply to this item based on the user's setting.

Examples: REQUIRED, NOT_REQUIRED

Enum
networkDetails

Network details gives information about the network the program is airing from. For example, a new episode of "The Big Bang Theory" airing from CBS, or a live soccer game airing from ESPN. For on-demand content, this could be, for example, Prime Video displaying Game of thrones results from HBO. If the result item represents a live show (contentType = LIVE) on a channel, this object contains its metadata.

List
channel

Information about the channel the video is currently airing on.

Object
callSign (channel)
Specifies a channel by call sign such as PBS.

Example: PBS

String
affiliateCallSign
Specifies a channel by local affiliate call sign such as KCTS9.

Example: KCTS9

channelMetadata

Provides additional information about the specified channel.

Object
name (channelMetadata)
Another value that identifies the channel, such as "FOX". String
airingDetails

This object contains information on when content airs.

List
isLiveBroadcast

Whether this content is airing in real time. Set this true for live events like watching an NFL football game, or award shows like Oscars or Emmys, etc., that are happening in real time.

Set this false for content that was filmed prior to the original airing time. For example, a new episode of Big Bang theory that airs every Thursday. This must also be set to false for content that was once streamed in real time, like a football game in the past, but is no longer happening in real time.

Examples: true, false

boolean
start

The start time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.
end

The end time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.
networkDetails

Network details gives information about the network the program is airing from. For example, a new episode of "The Big Bang Theory" airing from CBS, or a live soccer game airing from ESPN. For on-demand content, this could be, for example, Prime Video displaying Game of thrones results from HBO. If the result item represents a live show (contentType = LIVE) on a channel, this object contains its metadata.

List
series

The metadata about the series if this item is part of a series. This information should be populated for TV shows only. If available, the information here is used to render prompts to the user for example, "Here's 'The Big Bang Theory' Season 1, episode 4.

Object
seasonNumber

The season number of the video.

Example: 1

String
episodeNumber

The episode number of the video.

Example: 3

String
episodeName

The episode name.

Example: 4

String
seriesName
absoluteViewingPositionMilliseconds
required

Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously.

Example: 1248625

Long