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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

{
  "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 Request Access to the Alexa Event Gateway. 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

Copied to clipboard.

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 Request Access to the Alexa Event Gateway 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