Alexa.MediaMetadata Interface 3

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

Copied to clipboard.

{
    "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

mediaIds

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.

Copied to clipboard.

{
  "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

media

Collection of media objects that describe the media recordings that have been created or updated.
Can be empty if none of the requested recordings are found.

Array of Media objects

Yes

errors

Media recordings that aren't available at request time.

Array of objects

No

errors.mediaId

Identifies the media recording.

String

Yes

error.status

Identifies why this media recording isn't available.
Valid values:

  • 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.

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

Copied to clipboard.

{
  "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

mediaIds

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

Copied to clipboard.

{
  "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

mediaIds

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

media.id

Unique identifier for this media recording. The identifier must be unique across all devices owned by a user within the domain of the skill.
Valid values: Up to 255 characters. Must contain letters, numbers, or underscore only.

String

Yes

media.cause

Indicates the reason why the media was created or updated.
Valid values: MOTION_DETECTED (motion was detected), AUDIO_DETECTED (audio was detected), PERSON_DETECTED (a person was detected), APP_INTERACTION (customer interacted with an app), VOICE_INTERACTION (customer initiated a voice interaction with Alexa), or RULE_TRIGGER (a device rule was initiated).

String

Yes

media.name

Name for the media recording, either assigned by the user or auto-generated by the endpoint.

String

No

startTime

Time that the media recording started.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

endTime

Time that the media recording ended.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

videoCodec

Video codec used for the recording.
Amazon recommends an MP4 with H264 video codec. Valid values: H264, HLS.

String

No

audioCodec

Audio codec used for the recording.
Valid values: G711, AAC, NONE.

String

No

uri

Defines the location and expiry of the recording.

Object

Yes

uri.value

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

uri.expireTime

Time that the URI expires.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. Amazon recommends the time to expiration is 10 minutes.

String

Yes

thumbnailUri

URI to a thumbnail image captured from the video.

Object

No

thumbnailUri.value

URI string for the image. Must be an HTTPS URI.

String

Yes

thumbnailUri.expireTime

Time that the thumbnail URI expires.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes