Alexa.MediaMetadata Interface
Security cameras 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 recordings. 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 more details, see Authenticate a Customer to Alexa with Permissions.
For the list of languages that the MediaMetadata interface supports, see List of Alexa Interfaces and Supported Languages.
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.
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 MediaMetadata capability. Typically you combine this capability with the CameraStreamController capability.
DiscoveryResponse example containing Alexa.CameraStreamController, and MediaMetadata
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
},
"payload": {
"endpoints": [
{
"endpointId": "uniqueIdOfCameraEndpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"friendlyName": "Camera",
"description": "a description that is shown to the customer",
"displayCategories": [
"CAMERA"
],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model" : "the model of the device",
"customIdentifier": "your 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.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"
},
{
"type": "AlexaInterface",
"interface": "Alexa.MediaMetadata",
"version": "3",
"proactivelyReported": true
}
]
}
]
}
}
}
Directives
GetMediaMetadata
Sent when Alexa needs to update information about the media recording, such as updating the URL.
Example GetMediaMetadata request
The following example illustrates a GetMediaMetadata directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "GetMediaMetadata",
"messageId": "123-456-789",
"correlationToken": "token",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "token-from-skill"
},
"filters": {
"mediaIds": ["media Ids"]
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
mediaIds |
Filter the media items based on the provided media identifiers. | String array | No |
The typical response to a GetMediaMetadata directive is a GetMediaMetadata.Response event.
Properties and events
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
scopewith an authorization token to identify the customer.
Properties
There are no reportable properties currently defined for this interface.
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.
Example: GetMediaMetadata.Response
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "GetMediaMetadata.Response",
"messageId": "UUID",
"correlationToken": "token",
"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"
}]
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
media |
A collection of media objects that describe the media recordings that have been created or updated. | A list of media object entries. Can be empty if none of the requested recordings are found. | Yes |
errors |
Provides media recordings that aren't available at request time, and why they aren't available. | Object array | No |
errors.mediaId |
The identifier for the media recording. | String | No |
error.status |
Identifies why this media recording is not supported. | String. Supported values are DELETED, NOT_FOUND, SUBSCRIPTION_ERROR, INTERNAL_ERROR | No |
Error status descriptions:
- DELETED: Indicates the requested recording is deleted.
- NOT_FOUND: Indicates the requested recording isn't found in the list of stored recordings.
- SUBSCRIPTION_ERROR Indicates that the requested recording isn't available due to subscription issues. For example, a premium subscription is required to access a week old recording.
- INTERNAL_ERROR: Indicates an internal service error has occurred and the requested recording can't be provided.
MediaCreatedOrUpdated
Notifies Alexa that a media recording has been 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.
Example: MediaCreatedOrUpdated event
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "MediaCreatedOrUpdated",
"messageId": "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"
}
}
}
}
}
}
Message headers
| Header name | Description | Example |
|---|---|---|
Authorization |
Bearer token provided by Amazon, used to identify this user. See Authenticate a Customer to Alexa Using Permissions. | Bearer Atza\|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR |
Content-Type |
Identifies the contents of the message body. Accepted value: application/json | Content-Type: application/json |
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
media |
The media recording that you created or updated. | A media object. | Yes |
MediaDeleted
Notifies 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. Responses to this event are described in the Success Response and Errors section.
Example: MediaDeleted
Authorization: Bearer Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
Content-Type: application/json
{
"event": {
"header": {
"namespace": "Alexa.MediaMetadata",
"name": "MediaDeleted",
"messageId": "UUID",
"payloadVersion": "3"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "access-token-from- skill"
},
"mediaIds": ["mediaId1", "mediaId2"]
}
}
}
Message headers
| Header name | Description | Example |
|---|---|---|
Authorization |
Bearer token provided by Amazon, used to identify this user. See Authenticate a Customer to Alexa Using Permissions | Bearer Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR |
Content-Type |
Identifies the contents of the message body. Accepted value: application/json | Content-Type: application/json |
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
mediaIds |
An array of media identifiers that describe the media items that have been deleted. | String array that contains media IDs. | Yes |
Media object
A media object contains the following fields.
| Field | Description | Type | Required |
|---|---|---|---|
media.id |
A unique identifier for this media recording. The identifier must be unique across all devices owned by a user within the domain for the skill. | String less than 256 characters. Must contain letters, numbers or underscore only. | Yes |
media.cause |
Indicates the reason why the media was created or updated. Valid values are MOTION_DETECTED (motion was detected), AUDIO_DETECTED (audio was detected), PERSON_DETECTED (a person was detected), APP_INTERACTION (customer interacted with an application), VOICE_INTERACTION (customer initiated a voice interaction with Alexa), or RULE_TRIGGER (a device rule was initiated). |
enum | Yes |
media.name |
A name for the media recording, either assigned by the user or auto-generated by the endpoint. | String | No |
startTime |
The time that the media recording started. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
endTime |
The time that the media recording ended. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
videoCodec |
The video codec used for the recording. Amazon recommends an MP4 with H264 codec. Also supported is HLS which are compatible with ExoPlayer 1.5.9. | String. Supported value: H264 | No |
audioCodec |
Audio codec used for the recording. | String. Supported values: G711, AAC, NONE | No |
uri |
Object that provides the location and expiry of the recording. | Object | Yes |
uri.value |
A short-lived URI for the recording. Must be a HTTPS URI, and the hostname should match the common name or subject alternative name provided in the SSL certificate. | String | Yes |
uri.expireTime |
The time that the URI expires. The recommended time to expiration is 10 minutes. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
thumbnailUri |
Object that contains a URI to an image captured from the video that can be used as a thumbnail. | Object | No |
thumbnailUri.value |
URI string for the image. Must be HTTPS. | String | Yes |
thumbnailUri.expireTime |
The time that the thumbnail URI expires. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |