Alexa.EqualizerController Interface
The Alexa.EqualizerController interface provides directives that are used to set or adjust the equalizer bands and apply a sound mode to a smart entertainment device. Implement this interface for devices that can set and adjust one or more equalizer bands to any integer value in a continuous range of values.
For the list of locales that are supported for the EqualizerController interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.EqualizerController interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, set bass to -2 on the speakers.
Alexa, increase bass on the stereo.
Alexa, increase bass by 3 on the stereo.
Alexa, reset bass on the TV.
Alexa, reset equalizer on the speakers.
Alexa, set mode to movie on the TV.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery
When you provide a discovery response for an equalizer device, you specify the supported properties, but also configuration values such as the bands and modes the equalizer supports.
Configuration details
The configurations object contains the configuration of available bands, including range values and/or the sound modes supported by the endpoint.
- The
bandsattribute represents the different equalizer bands supported by the endpoint, and their ranges. - The
modesattribute is a list of equalizer modes supported by the endpoint. For example: "MUSIC".
The endpoint should return a list of bands and mode names supported by the endpoint. The endpoint can support any of the following combination:
- Both bands and modes
- Bands only
- Modes only
| Property | Description | Type | Required |
|---|---|---|---|
bands |
Contains the bands supported by this endpoint. | Object | Either bands, modes, or both can be specified. |
bands.supported |
List of objects that specify a name attribute for the band. | A list of objects in the format: "name": "bandName", valid values for bandName are BASS, MIDRANGE, TREBLE. | No |
bands.range |
An object that specifies a minimum and maximum value | object | Yes, if a band is specified |
range.minimum |
The minimum value that can be set for this band. | Integer | Yes, if range specified |
range.maximum |
The maximum value that can be set for this band. | Integer | Yes, if range specified. |
modes |
Contains a list of equalizer modes supported by this endpoint. | object | Either bands, modes or both can be specified. |
modes.supported |
List of objects that specify a name attribute for the mode. | A list of objects in the format: "name": "modeName". Valid values for modeName are MOVIE, MUSIC, NIGHT, SPORT, TV. | No |
Example: DiscoveryResponse
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
},
"payload": {
"endpoints": [
{
"endpointId": "device-001",
"friendlyName": "Living Room",
"description": "Living Room Speaker",
"manufacturerName": "Sample Manufacturer",
"displayCategories": [
"SPEAKER"
],
"cookie": {
"extraDetail1": "optionalDetailToReferenceThisDevice",
"extraDetail2": "There can be multiple entries",
"extraDetail3": "Use for reference purposes",
"extraDetail4": "Not a suitable place to maintain device state"
},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.EqualizerController",
"version": "3",
"configurations": {
"bands": {
"supported": [
{
"name": "BASS"
},
{
"name": "MIDRANGE"
},
{
"name": "TREBLE"
}
],
"range": {
"minimum": -6,
"maximum": 6
}
},
"modes": {
"supported": [
{
"name": "MOVIE"
},
{
"name": "MUSIC"
},
{
"name": "SPORT"
}
]
}
},
"properties": {
"supported": [
{
"name": "bands"
},
{
"name": "modes"
}
]
}
}
]
}
]
}
}
}
Directives
SetBands
Request to set band to the specified value.
User: Alexa, set bass to -2 on device
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.EqualizerController",
"name": "SetBands",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
"correlationToken": "PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "endpoint-001",
"cookie": {
}
},
"payload": {
"bands": [
{
"name": "BASS",
"value": -2
}
]
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
bands |
Specifies the name and desired value for the equalizer band to set. | List | Yes |
bands.name |
The name of the equalizer band. Must be supported by the endpoint. | String. Valid values: BASS, MIDRANGE, TREBLE. | Yes |
bands.value |
The discrete frequency value to set for the band specified by name. |
Integer | Yes |
AdjustBands
Request for a relative equalizer adjustment. The AdjustBands directive is always relative to the current band setting. The levelDirection value indicates whether the adjustment should be up or down and the levelDelta value indicates how much the band should be adjusted.
User: Alexa, increase bass on device
User: Alexa, increase bass by 3 on device
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.EqualizerController",
"name": "AdjustBands",
"messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
"correlationToken": "PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "endpoint-001",
"cookie": {}
},
"payload": {
"bands": [
{
"name": "BASS",
"levelDelta": 3,
"levelDirection": "UP"
}
]
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
bands |
The payload object that contains the name and value of the targeted equalizer band. | List of objects | Yes |
bands.name |
Represents the name of the equalizer band to adjust. | String. Valid values: BASS, MIDRANGE, TREBLE. | Yes |
bands.levelDelta |
Represents adjustment value for the specified equalizer band. | Integer | No |
bands.levelDirection |
Specifies how the band should be adjusted. | String. Valid values: UP, DOWN | Yes |
ResetBands
Request to reset the bands or a specified equalizer band to their default value.
User: Alexa, reset bass on device
User: Alexa, reset equalizer on device
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.EqualizerController",
"name": "ResetBands",
"messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "endpoint-001",
"cookie": {}
},
"payload": {
"bands": [
{
"name": "BASS"
},
{
"name": "MIDRANGE"
},
{
"name": "TREBLE"
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
bands |
Contains the name(s) of the bands to reset. | List of bands in the format "name" : "bandName". Valid bands are BASS, TREBLE, MIDRANGE. | Yes |
SetMode
Request to set the sound mode for an endpoint.
User: Alexa, set mode to movie on device
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.EqualizerController",
"name": "SetMode",
"messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "endpoint-001",
"cookie": {}
},
"payload": {
"mode": "MOVIE"
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
mode |
Name of the mode or equalizer mode support by the endpoint. | String. Valid values: MOVIE, MUSIC, NIGHT, SPORT, TV. | Yes |
Properties and Events
For this capability, you must either reply:
- Synchronously, which means you send a Response event to Alexa from the Lambda function.
- Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a
scopewith an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.
When you send a Response, you should include the state of the interface properties in the context of the message.
Reportable Properties
| Property Name | Description | Type |
|---|---|---|
bands |
Indicates the current configuration of the equalizer bands and the values for each band. | EqualizerBands |
mode |
Indicates the equalizer mode of the endpoint. | EqualizerMode |
Response
You must send a Response event when a SetBands, AdjustBands, ResetBands or SetMode directive is successfully handled. The event should contain the same correlation token as the request, and report the current values of bands and mode in the context.
Example Response
{
"context": {
"properties": [
{
"namespace": "Alexa.EqualizerController",
"name": "bands",
"value": [
{
"name": "BASS",
"value": -2
},
{
"name": "MIDRANGE",
"value": 4
},
{
"name": "TREBLE",
"value": 0
}
],
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EqualizerController",
"name": "mode",
"value": "MOVIE",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"event": {
"header": {
"messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
"correlationToken": "PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint-001"
},
"payload": {}
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. If a directive contains a band or mode that isn't supported by the endpoint, return an INVALID_VALUE error. For additional errors, see Error.Response.