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.

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.

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