Your Alexa Dashboards
Sign In
?
Sign In
Your Alexa Dashboards Support

Alexa.Speaker Interface

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

This control and query directives in this interface are supported in skills that target the following language:

  • English (US)

See Develop Smart Home Skills in Multiple Languages for more information.

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",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "device-001",
      "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",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "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",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "device-001",
      "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

For this interface, you must reply:

  • Synchronously, which means you send a Response to Alexa in from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message

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

Response

You must send an 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",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint":{
       "endpointId":"appliance-001"
    },
    "payload":{ }
 }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Error.Response for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

Speaker

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