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.
Discovery
AddOrUpdateReport example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "00000000-0000-0000-0000-000000000000"
},
"payload": {
"endpoints": [
{
"endpointId": "appliance-001",
"friendlyName": "Entertainment System",
"description": "BrandName by Sample Manufacturer",
"manufacturerName": "Sample Manufacturer",
"displayCategories": [
"TV"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Speaker",
"version": "3",
"properties": {
"supported": [
{
"name": "volume"
},
{
"name": "muted"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"properties": {},
"supportedOperations": [
"Play",
"Pause",
"Stop"
],
"proactivelyReported": true,
"retrievable": true
},
{
"type": "AlexaInterface",
"interface": "Alexa.InputController",
"version": "3",
"inputs": [
{
"name": "HDMI1"
},
{
"name": "HDMI2"
}
],
"proactivelyReported": true,
"retrievable": true
},
{
"type": "AlexaInterface",
"interface": "Alexa.ChannelController",
"version": "3",
"properties": {
"supported": [
{
"name": "channel"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
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:
Related Interfaces
| Interface | Description |
|---|---|
| Alexa.StepSpeaker | Messages for setting volume to a discrete step setting. |
