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.

Note: You can't adjust the volume of a device to a value lower than 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 or AdjustVolume 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.

Important: 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