Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Speaker Interface (v1.0)

The Speaker interface exposes directives and events that adjust volume and mute/unmute a client's speaker. Alexa supports two methods for volume adjustment, which are exposed through the SetVolume and AdjustVolume directives.

About volume

Within the context of the Speaker Interface, volume represents the volume of a device, as recognized by Alexa, and is represented by a long value from 0 to 100.

While the user interface of your device may use any volume scale that you choose, such as from 0 to 10, Alexa sends/receives a volume value from 0 to 100. For example, if a user sets the volume to "8" on your device's scale from 0 to 10, the volume value used by Alexa should be "80", similar to a percentage.

Capabilities API

To use version 1.0 of the Speaker interface, declare this version in your call to the Capabilities API. For additional details, see Capabilities API.

Sample Object

{
    "type": "AlexaInterface",
    "interface": "Speaker",
    "version": "1.0"
}

Speaker Context

Alexa expects a client to report volume and muted state information for the Speaker interface with each event that requires context.

To learn more about reporting Context, see Context Overview.

Sample 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 Identifies mute state of the client's speaker. boolean

SetVolume Directive

This directive instructs your client to make an absolute volume adjustment, using a scale of 0 to 100 for volume.

Sample 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 scaled from 0 (min) to 100 (max).
Accepted values: Any value between 0 and 100.
long

AdjustVolume Directive

This directive instructs your client to make a relative volume adjustment. The AdjustVolume directive is a value from from -100 to 100 and is always relative to the current volume setting on the device. When a device receives an AdjustVolume directive with a positive value, it increases volume on the device by the specified amount, or if a device receives an AdjustVolume directive with a negative value, it reduces the device volume by the specified amount.

Sample 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. A positive or negative long value used to increase or decrease volume in relation to the current volume setting.
Accepted values: Any value between -100 and 100, inclusive.
long

VolumeChanged Event

Your device must send a VolumeChanged event to Alexa when any of the following conditions occur:

  • Your device receives either a SetVolume or AdjustVolume directive and processes that directive to indicate that the speaker volume on your product has been adjusted/changed.
  • A user locally adjusts the volume on your device.

Sample 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 scaled from 0 (min) to 100 (max).
Accepted values: Any long value between 0 and 100
long
mute A boolean value is used to mute/unmute a product's speaker. The value is true when the speaker is muted, and false when unmuted. boolean

SetMute Directive

This directive is sent from Alexa to your client to mute the product's speaker.

Sample Message

{
    "directive": {
        "header": {
            "namespace": "Speaker",
            "name": "SetMute",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "mute": {{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
mute A boolean value is used to mute/unmute a product's speaker. The value is true when the speaker is muted, and false when unmuted. boolean

MuteChanged Event

The MuteChanged event must be sent to AVS when:

  • A SetMute directive is received and processed to indicate that the mute status of the product's speaker has changed.
  • Your product is muted/unmuted locally to indicate that the mute status of the product's speaker has changed.

Sample 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 scaled from 0 (min) to 100 (max).
Accepted values: Any long value between 0 and 100
long
mute A boolean value is used to mute/unmute a product's speaker. The value is true when the speaker is muted, and false when unmuted.
Accepted values:TRUE or FALSE
boolean