Alexa.MediaMetadata Interface 3
Alexa.MediaMetadata
interface on March 15, 2023. For more details, see Deprecated Features. Security cameras or video doorbells typically create a media recording when motion or sound is detected. Implement the Alexa.MediaMetadata
interface in your Alexa skill to notify Alexa when a new media recording is added to the camera history, or an existing media recording is deleted from history. Your skill can also respond to requests for information about a particular media recording. For more details about security skills, see Smart Home Security Overview.
Alexa stores the list of media recordings that you provide and responds to requests to view recordings. Alexa stores only the list of recording metadata. The recordings are typically stored in your device cloud.
To notify Alexa when a new recording is available for a customer, send an event to the Alexa event gateway and identify the user that the event message is associated with.
For the list of languages that the Alexa.MediaMetadata
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
When you use the Alexa.MediaMetadata
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, show the last activity at my front door.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Reportable properties
The Alexa.MediaMetadata
interface doesn't define any reportable properties.
Discovery
When you respond to a discovery request for a skill that controls a camera, you describe the camera's ability to support camera history with the Alexa.MediaMetadata
capability. Typically you combine this capability with Alexa.CameraStreamController
.
Discover response example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
},
"payload": {
"endpoints": [{
"endpointId": "uniqueIdOfCameraEndpoint",
"manufacturerName": "Manufacturer of the endpoint",
"friendlyName": "Camera",
"description": "a description that is shown to the customer",
"displayCategories": [
"CAMERA"
],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"customIdentifier": "Optional custom identifier for the device"
},
"cookie": {
"key1": "arbitrary key/value pairs for skill to reference this endpoint.",
"key2": "There can be multiple entries",
"key3": "but they should only be used for reference purposes.",
"key4": "This is not a suitable place to maintain current endpoint state."
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.MediaMetadata",
"version": "3",
"proactivelyReported": true
},
{
"type": "AlexaInterface",
"interface": "Alexa.CameraStreamController",
"version": "3",
"cameraStreamConfigurations": [{
"protocols": [ "RTSP" ],
"resolutions": [{
"width": 1920,
"height": 1080
},
{
"width": 1280,
"height": 720
}
],
"authorizationTypes": [ "BASIC" ],
"videoCodecs": [
"H264",
"MPEG2"
],
"audioCodecs": [ "G711" ]
},
{
"protocols": [ "RTSP" ],
"resolutions": [{
"width": 1920,
"height": 1080
},
{
"width": 1280,
"height": 720
}
],
"authorizationTypes": [ "NONE" ],
"videoCodecs": [ "H264" ],
"audioCodecs": [ "AAC" ]
}
]
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3"
}
]
}]
}
}
}
Directives and events
The Alexa.MediaMetadata
interface defines the following directives and events.
GetMediaMetadata directive
Sent when Alexa needs to update information about the media recording, such as updating the URL.
GetMediaMetadata directive example
The following example illustrates a GetMediaMetadata
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "GetMediaMetadata",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "token-from-skill"
},
"filters": {
"mediaIds": ["media Ids"]
}
}
}
}
GetMediaMetadata payload
Property | Description | Type | Required |
---|---|---|---|
|
Filter the media items based on the provided media identifiers. |
Array of String |
No |
GetMediaMetadata response
If the GetMediaMetadata
directive was successfully handled, you should respond with an GetMediaMetadata.Response
event. This response provides metadata that describes the requested items.
For this capability, you can reply:
- Synchronously, when you send a GetMediaMetadata.Response event to Alexa from the skill's Lambda function.
- Asynchronously, when you send MediaCreatedOrUpdated or MediaDeleted events to the Alexa event gateway. When you reply asynchronously, you must include a
scope
with an authorization token to identify the customer.
The following example shows a GetMediaMetadata.Response
.
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "GetMediaMetadata.Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"media": [{
"id": "media Id from the request",
"cause": "cause of media creation",
"recording": {
"name": "Optional video name",
"startTime": "2018-06-29T19:20:41Z",
"endTime": "2018-06-29T19:21:41Z",
"videoCodec": "H264",
"audioCodec": "AAC",
"uri": {
"value": "https://somedomain/somevideo.mp4",
"expireTime": "2018-06-29T19:31:41Z"
},
"thumbnailUri": {
"value": "https://somedomain/someimage.png",
"expireTime": "2018-06-29T19:31:41Z"
}
}
}],
"errors": [{
"mediaId": "media id from the request",
"status": "reason for error"
}]
}
}
}
GetMediaMetadata response payload
Property | Description | Type | Required |
---|---|---|---|
|
Collection of media objects that describe the media recordings that have been created or updated. |
Array of Media objects |
Yes |
|
Media recordings that aren't available at request time. |
Array of objects |
No |
|
Identifies the media recording. |
String |
Yes |
|
Identifies why this media recording isn't available.
|
String |
Yes |
MediaCreatedOrUpdated event
The MediaCreatedOrUpdated
event notifies Alexa that a media recording was created or updated. Send this event as an HTTP POST
to the Alexa event gateway. For more details, see Send Events to the Alexa Event Gateway. Responses to this event are described in the Success Response and Errors section.
MediaCreatedOrUpdated event example
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "MediaCreatedOrUpdated",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "endpoint-001"
},
"payload": {
"media": {
"id": "UUID",
"cause": "MOTION_DETECTED",
"recording": {
"name": "Optional video name",
"startTime": "2018-06-29T19:20:41Z",
"endTime": "2018-06-29T19:21:41Z",
"videoCodec": "H264",
"audioCodec": "AAC",
"uri": {
"value": "https://somedomain/someimage.png",
"expireTime": "2018-06-29T19:31:41Z"
},
"thumbnailUri": {
"value": "https://somedomain/someimage.png",
"expireTime": "2018-06-29T19:31:41Z"
}
}
}
}
}
}
MediaCreatedOrUpdated event payload
Property | Description | Type | Required |
---|---|---|---|
|
Media recording that you created or updated. |
Media object |
Yes |
MediaDeleted event
Use the MediaDeleted
event to notify Alexa that a media recording has been deleted. Send this event as an HTTP POST
to the Alexa event gateway. For more details, see Send Events to the Alexa Event Gateway and event response.
MediaDeleted event example
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "MediaDeleted",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "access-token-from- skill"
},
"mediaIds": ["mediaId1", "mediaId2"]
}
}
}
MediaDeleted event payload
Include the following property in the request body.
Property | Description | Type | Required |
---|---|---|---|
|
Array of media identifiers that describe the media items that have been deleted. |
Array of String |
No |
Media object
A media object includes the following properties.
Property | Description | Type | Required |
---|---|---|---|
|
Unique identifier for this media recording. The identifier must be unique across all devices owned by a user within the domain of the skill. |
String |
Yes |
|
Indicates the reason why the media was created or updated. |
String |
Yes |
|
Name for the media recording, either assigned by the user or auto-generated by the endpoint. |
String |
No |
|
Time that the media recording started. |
String |
Yes |
|
Time that the media recording ended. |
String |
Yes |
|
Video codec used for the recording. |
String |
No |
|
Audio codec used for the recording. |
String |
No |
|
Defines the location and expiry of the recording. |
Object |
Yes |
|
Short-lived URI location for the recording. Must be an HTTPS URI. The hostname in the URI should match the common name or subject alternative name provided in the SSL certificate. |
String |
Yes |
|
Time that the URI expires. |
String |
Yes |
|
URI to a thumbnail image captured from the video. |
Object |
No |
|
URI string for the image. Must be an HTTPS URI. |
String |
Yes |
|
Time that the thumbnail URI expires. |
String |
Yes |