Alexa.MediaMetadata Interface

Security cameras typically create a media recording when motion or sound is detected. You implement the Alexa.MediaMetadata interface 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.

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. For more information about skills that interact with cameras, see Build Smart Home Camera Skills.

For the list of locales that are supported for the MediaMetadata interface, see List of Capability Interfaces and Supported Locales.

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",
          "modelName": "the model name of the endpoint",
          "friendlyName": "Camera",
          "description": "a description that is shown to the customer",
          "displayCategories": [
            "CAMERA"
          ],
          "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 Request:

{
  "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 item(s).

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 are not available at request time, and why they are not 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 has been deleted.
  • NOT_FOUND: Indicates the requested recording cannot be found in the list of stored recordings.
  • SUBSCRIPTION_ERROR Indicates that the requested recording is not 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 cannot 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 information, 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 information, 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. An MP4 with H264 codec is recommended. We do support 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
Topic Description
CameraStreamController Capability for basic camera functionality.
Build Smart Home Camera Skills Describes concepts and details of building smart home skills for security cameras.
Authenticate a Customer to Alexa Using Permissions Describes the process for obtaining bearer token to identify users to Alexa.
Send Events to the Alexa Event Gateway Describes how to send events to Alexa regarding new, updated, or deleted media recordings.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment