Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Alexa.Speaker Interface

The Alexa.Speaker interface provides directives that are used to set the volume, adjust the volume, mute, and unmute an entertainment device. Implement this interface for devices that can set the volume to any integer value in a continuous range of values. If your device can only adjust the volume in discrete steps, implement the StepSpeaker interface instead.

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

Utterances

When you use the Alexa.Speaker interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, set the volume of the speakers to 50.
Alexa, turn the volume down on the stereo by 20.
Alexa, mute speakers.
Alexa, unmute speakers.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Directives

SetVolume

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

User: 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": "access-token-from-skill"
      },
      "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.

User: Alexa, turn the volume down on device by 20

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "AdjustVolume",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "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.

User: Alexa, mute device

User: Alexa, unmute device

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "SetMute",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "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 capability, you must reply:

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

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

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": "abc-123-def-456",
      "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 Alexa.ErrorResponse 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.