Alexa.Speaker Interface
Implement the Alexa.Speaker
interface in your Alexa skill so that users can control the volume of their entertainment devices that contain audio speakers. For more information about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.
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 languages that the Speaker
interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
When you use the Alexa.Speaker
interface, the voice interaction model is already built for you. The following examples show some user utterances:
Alexa, set the volume of the speakers to 50.
Alexa, turn the volume down on the stereo by 20.
Alexa, turn the volume down on Living Room TV.
Alexa, mute speakers.
Alexa, unmute speakers.
After the user says one of these utterances, Alexa sends a corresponding directive to your skill.
Properties
The volume property
The Alexa.Speaker
interface uses the volume
property to represent the audio volume level of a device. The property is an integer and valid values from 0 to 100 inclusive. If the volume
property is used to represent a change, then valid values are from -100 to 100 inclusive. In that case, a positive value increases the volume and a negative value decreases the volume.
Example volume property
{
"name": "volume",
"value": 50
}
The muted property
The Alexa.Speaker
interface uses the muted
property to indicate whether the audio of a device is muted or not. The property is a boolean; true if the device is muted, false if the device is not muted.
Example muted property
{
"name": "muted",
"value": false
}
Discovery
You describe endpoints that support Alexa.Speaker
using the standard discovery mechanism described in Alexa.Discovery.
Set retrievable
to true for the properties that you report when Alexa sends your skill a state report request.
Set proactivelyReported
to true for the properties that you proactively report to Alexa in a change report.
Use SPEAKER
, TV
, STREAMING_DEVICE
, GAME_CONSOLE
, or other appropriate display category. For the full list of display categories, see display categories.
Discover response example
The following example shows a Discover.Response
message for a speaker device that supports the Alexa.Speaker
and Alexa.PowerController interfaces. For the full list of recommended interfaces for an entertainment device, see Smart Home Skill Device Templates.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "Smart Speaker by Speaker Maker",
"friendlyName": "Computer speaker",
"displayCategories": ["SPEAKER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.Speaker",
"version": "3",
"properties": {
"supported": [
{
"name": "volume"
},
{
"name": "muted"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
SetVolume directive
Support the SetVolume
directive so that users can set the volume on their devices.
The following example shows a user utterance:
Alexa, set the volume of Living Room TV to 50.
SetVolume directive payload details
Field | Description | Type |
---|---|---|
volume |
The volume to set the device to. | Integer |
SetVolume directive example
The following example illustrates a SetVolume
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.Speaker",
"name": "SetVolume",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"volume": 50
}
}
}
SetVolume response event
If you handle a SetVolume
directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.
SetVolume response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<endpoint id>"
},
"payload": {}
},
"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
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
SetVolume directive error handling
If you can't handle a SetVolume
directive successfully, respond with an Alexa.ErrorResponse event.
AdjustVolume directive
Support the AdjustVolume
directive so that users can adjust the volume on their devices.
The following example shows a user utterance:
Alexa, turn the volume down on Living Room TV by 20.
AdjustVolume directive payload details
Field | Description | Type |
---|---|---|
volume |
The amount by which to change the volume, relative to the current volume. | Integer |
volumeDefault |
False if the user specified the amount by which to change the volume; otherwise true. | Boolean |
AdjustVolume directive example
The following example illustrates an AdjustVolume
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.Speaker",
"name": "AdjustVolume",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"volume": -20,
"volumeDefault": false
}
}
}
AdjustVolume response event
If you handle an AdjustVolume
directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.
AdjustVolume response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.Speaker",
"name": "volume",
"value": 30,
"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
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
AdjustVolume directive error handling
If you can't handle an AdjustVolume
directive successfully, respond with an Alexa.ErrorResponse event.
SetMute directive
Support the SetMute
directive so that users can mute and unmute their devices.
The following example shows a user utterance:
Alexa, mute Living Room TV.
SetMute directive payload details
Field | Description | Type |
---|---|---|
mute |
True to mute the device, false to unmute the device. | Boolean |
SetMute directive example
The following example illustrates a SetMute
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.Speaker",
"name": "SetMute",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"mute": true
}
}
}
SetMute response event
If you handle a SetMute
directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.
SetMute response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.Speaker",
"name": "volume",
"value": 30,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.Speaker",
"name": "muted",
"value": true,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
SetMute directive error handling
If you can't handle a SetMute
directive successfully, respond with an Alexa.ErrorResponse event.
State reporting
Alexa sends a ReportState
directive to request information about the state of an endpoint. When Alexa sends a ReportState
directive, you send a StateReport
event in response. The response contains the current state of all of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
StateReport response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.Speaker",
"name": "volume",
"value": 30,
"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
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
Change reporting
You send a ChangeReport
event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "VOICE_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.Speaker",
"name": "volume",
"value": 40,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.Speaker",
"name": "muted",
"value": false,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}