Speaker 1.0
The Speaker interface exposes Alexa Voice Service (AVS) directives and events that adjust volume and mute/unmute a client's speaker.
About volume
Within the context of the Speaker interface, the volume
parameter represents the volume of a device, as recognized by Alexa. Alexa represents volume with a long value from 0
to 100
.
Your user interface can use any volume scale that you choose, such as a range from 0
to 10
. However, Alexa still sends and receives a volume
value from 0
to 100
. For example, imagine your device uses a range from 0
to 10
. If a user sets the volume to 8
on your device, you should report the equivalent percentage value to Alexa. In this example, you would report a volume
value of 80
.
Capability assertion
A device can implement Speaker 1.0 on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery. However, Alexa continues to support existing integrations using the Capabilities API.
Example object
{ "type": "AlexaInterface", "interface": "Speaker", "version": "1.0" }
Context
Alexa expects a client to report volume
and muted
state information for each Speaker interface event that requires context.
To learn more about reporting Context, see Context Overview.
Example message
{ "header": { "namespace": "Speaker", "name": "VolumeState" }, "payload": { "volume": {{LONG}}, "muted": {{BOOLEAN}} } }
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | Identifies current speaker volume.
Accepted values: 0 to 100 |
long |
muted | The mute status. Identifies if a speaker is muted or unmuted. | boolean |
Directives
SetVolume
This directive instructs your client to make an absolute volume adjustment, using a scale of 0
to 100
. The device must send the VolumeChanged
event in response to the SetVolume
directive.
Example message
{ "directive": { "header": { "namespace": "Speaker", "name": "SetVolume", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "volume": {{LONG}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
dialogRequestId | A unique ID used to correlate directives sent in response to a specific Recognize event. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | The absolute volume level.
Accepted values: Any value between 0 (min) and 100 (max). |
long |
AdjustVolume
This directive instructs your client to make a relative volume adjustment. The AdjustVolume
directive is a value from -100
to 100
and is always relative to the current volume setting on the device.
- If a device receives an
AdjustVolume
directive with a positive value, it increases volume on the device by the specified amount. - If a device receives an
AdjustVolume
directive with a negative value, it reduces the device volume by the specified amount.
The device must send the VolumeChanged
event in response to the AdjustVolume
directive.
0
(mute) or higher than 100
(full volume). If the volume of a device is already set to 20
, and the device receives an AdjustVolume
directive value of -30
, the device volume is set to 0
. Similarly, if the volume of a device is already set to 20
, and the device receives an AdjustVolume
directive value of 90
, the device volume is set to 100
.Example message
{ "directive": { "header": { "namespace": "Speaker", "name": "AdjustVolume", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "volume": {{LONG}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
dialogRequestId | A unique ID used to correlate directives sent in response to a specific Recognize event. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | The relative volume adjustment. Used to increase or decrease volume in relation to the current volume setting.
Accepted values: Any value between -100 and 100 , inclusive. |
long |
SetMute
This directive instructs your client to mute the device speaker.
Example message
{ "directive": { "header": { "namespace": "Speaker", "name": "SetMute", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "muted": {{BOOLEAN}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
dialogRequestId | A unique ID used to correlate directives sent in response to a specific Recognize event. |
string |
Payload parameters
Parameter | Description | Type |
---|---|---|
muted | Mute or unmute a device speaker. Accepted values: true mute the speaker; false unmute the speaker. |
boolean |
Events
VolumeChanged
The device must send a VolumeChanged
event to Alexa when any of the following conditions occur:
- The device receives and processes either a
SetVolume
orAdjustVolume
directive. - A trigger outside of an Alexa directive changes the device volume. Examples of triggers include a user pressing a button on a remote control, a user setting the volume on a GUI, a locally defined schedule, or an instruction sent by your companion app.
When handling a long press on a remote or GUI, only send a VolumeChanged
event for the final volume value when the long press has completed. This typically occurs when a user holds the volume up or down button on a remote control and the volume of the device quickly increments or decrements through a range.
volume
must be a value between 0
(min) and 100
(max), inclusive. For example, if a voice request from a user sets the volume to 8
, your device will receive 80
for the volume value, regardless of what numeric identifier your device or user interface uses to represent the volume setting.Example message
{ "event": { "header": { "namespace": "Speaker", "name": "VolumeChanged", "messageId": "{{STRING}}" }, "payload": { "volume": {{LONG}}, "muted": {{BOOLEAN}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | The absolute volume level.
Accepted values: Any long value between 0 (min) and 100 (max). |
long |
muted | Mute or unmute a device speaker. Accepted values: true mute the speaker; false unmute the speaker. |
boolean |
MuteChanged
Send the MuteChanged
event to AVS when the following occur:
- The device receives a
SetMute
directive to indicate that the mute status of the device speaker has changed. - A user mutes or unmutes the device locally, indicating that the mute status of the device speaker has changed.
Example message
{ "event": { "header": { "namespace": "Speaker", "name": "MuteChanged", "messageId": "{{STRING}}" }, "payload": { "volume": {{LONG}}, "muted": {{BOOLEAN}} } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
volume | The absolute volume level.
Accepted values: Any long value between 0 (min) and 100 (max) |
long |
muted | Mute or unmute a device speaker. Accepted values: true mute the speaker; false unmute the speaker. |
boolean |
Last updated: Jan 13, 2021