Home > Alexa > Alexa Skills Kit

Alexa.Speaker Interface

overview

The Speaker interface provides directives that are used to set or adjust the volume and mute/unmute a capable entertainment device.

Implement this interface for devices that can set and adjust the volume to any integer value in a continuous range of values. If a device can only adjust the volume in discrete steps, it should implement StepSpeaker.

Directives

The following table shows the directive support depending on the type of skill you are implementing.

Directive Skill Type
SetVolume Smart Home
AdjustVolume Smart Home
SetMute Smart Home

SetVolume

Request to set volume to the specified value, which is the absolute volume level scaled from 0 to 100.

“Alexa, set the volume of device to 50”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "SetVolume",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<the identifier of the target endpoint>",
      "cookie": {

      }
    },
    "payload": {
      "volume": 50
    }
  }
}

Payload Details

Field Description Type Required
volume An integer that indicates the requested volume, scaled from 0, the minimum volume, to 100, which is the maximum volume. integer with a range of 0 to 100 Yes

AdjustVolume

A request to perform a relative volume adjustment. A positive value increases the value, a negative value reduces the volume.

“Alexa, turn the volume down on device by 20”

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "AdjustVolume",
      "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
      "volume": -20,
      "volumeDefault": false
    }
  }
}

Payload Details

Field Description Type Required
volume An integer that indicates the requested relative change in volume on a scale of 0-100. A negative number indicates a reduction in volume, and a positive number indicates an increase in volume. integer with a range of -100 to 100 Yes
volumeDefault A flag that indicates whether the value in the volume field was explicitly specified by the user. If false, the value was explicitly specified by the user. If true, the value is a default value. boolean Yes

SetMute

Request that the specified device be muted or unmuted.

“Alexa, mute device

“Alexa, unmute device

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "SetMute",
      "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<the identifier of the target endpoint>",
      "cookie": {     }
    },
    "payload": {
      "mute": true
    }
  }
}

Payload Details

Field Description Type Required
mute true to indicate the device should be muted; false to indicate the device should be unmuted. boolean Yes

Properties and Events

Reportable Properties

Property Name Property Type Description
volume VolumeLevel The volume level of an endpoint expressed as scaled value between 0 and 100.
muted MuteState The mute state of an endpoint; true for muted, false for unmuted

Alexa.Response Event

You must send an Alexa.Response event when a SetVolume, AdjustVolume, or SetMute directive is successfully handled. The event should contain the same correlation token as the request, and report the current values of volume and muted in the context.

Example Response

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.Speaker",
        "name": "volume",
        "value": 50,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": false,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "payload": {
    }
  }
}

If an error occurs, return the appropriate error message name for the header.name property.

Interface Description
Alexa.StepSpeaker Messages for setting volume to a discrete step setting.