Developer Console
Gracias por tu visita. Esta página solo está disponible en inglés.

GetPlayableItemsMetadata Directives (VSK Echo Show)

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 live 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