EqualizerController 1.0

This interface allows a product to adjust equalizer settings using Alexa, such as decibel (dB) levels and modes.

Capability assertion

EqualizerController 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.

{
    "type": "AlexaInterface",
    "interface": "EqualizerController",
    "version": "1.0",
    "configurations": {
        "bands": {
            "supported": [
                {
                    "name": "{{STRING}}"
                },
                // This array should contain an object for
                // each supported band.
            ],
            "range": {
                "minimum": {{INTEGER}},
                "maximum": {{INTEGER}}
            }
        },
        "modes": {
            "supported": [
                {
                    "name": "{{STRING}}"
                },
                // This array should contain an object for
                // each supported mode.
            ]
        }
    }
}

Configuration Parameters

Parameter Description Type
bands Contains a list of supported equalizer bands. object
bands.supported List of objects. Includes all supported equalizer bands. list
bands.supported.name[i] Specifies a supported equalizer band.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string
bands.range An object that contains minimum and maximum decibel levels for each supported equalizer band. list
bands.range.minimum Minimum supported decibel level. integer
bands.range.maximum Maximum supported decibel level. integer
modes Contains a list of supported modes. object
modes.supported List of objects. Includes all supported modes. list
modes.supported.name[i] Specifies a supported mode.
Accepted values: "MOVIE", "MUSIC", "NIGHT", "SPORT", "TV".		 string

Context

Alexa expects a client to report EqualizerController state with each event that requires context. To learn more about reporting context, see Context Overview.

Sample Message

{
    "header": {
        "namespace": "EqualizerController",
        "name": "EqualizerState"
    },
    "payload": {
        "bands": [
            {
                "name": "{{STRING}}",
                "level": {{INTEGER}}
            },
            // This list should contain each supported band
            // and its current level.
        ],
        "mode": "{{STRING}}"
    }
}

Payload Parameters

Parameter Description Type
bands A list of bands that the product supports. list
bands.name[i] Identifies a supported band.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string
bands.level[i] The level for the specified band. integer
mode Specifies a supported mode.
Accepted values: "MOVIE", "MUSIC", "NIGHT", "SPORT", "TV".		 string

Directives

SetBands

Instructs a client to make an absolute adjustment to an equalizer band or bands. Each object within bands contains the name of a band and the absolute equalizer level.

Sample Message

{
    "directive": {
        "header": {
            "namespace": "EqualizerController",
            "name": "SetBands",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "bands": [
                {
                    "name": "{{STRING}}",
                    "level": {{INTEGER}}
                }
            ]
        }
    }
}

Payload Parameters

Parameter Description Type
bands A list of equalizer bands that require an absolute adjustment to decibel levels. list
bands.name[i] Identifies an equalizer band that requires an absolute adjustment to its decibel level.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string
bands.level[i] Specifies the decibel level for an equalizer band. integer

AdjustBands

Instructs a client to make a relative adjustment to an equalizer band or bands. Each object within bands contains the name of a band, the levelDelta, and the levelDirection.

Sample Message

{
    "directive": {
        "header": {
            "namespace": "EqualizerController",
            "name": "AdjustBands",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "bands": [
                {
                    "name": "{{STRING}}",
                    "levelDelta": {{INTEGER}},
                    "levelDirection": "{{STRING}}"
                }
            ]
        }
    }
}

Payload Parameters

Parameter Description Type
bands A list of equalizer bands that require a relative adjustment to decibel levels. list
bands.name[i] Identifies an equalizer band that requires a relative adjustment to its decibel level.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string
bands.levelDelta[i] Specifies the decibel level for an equalizer band.
Accepted values: A positive integer.		 integer
bands.levelDirection[i] Specifies the decibel level for an equalizer band.
Accepted values: "UP", "DOWN".		 string

ResetBands

Instructs a client to reset an equalizer band or bands. Default levels for each band are product-specific and are set by the client, not by Alexa.

Sample Message

{
    "directive": {
        "header": {
            "namespace": "EqualizerController",
            "name": "ResetBands",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "bands": [
                {
                    "name": "{{STRING}}"
                }
            ]
        }
    }
}

Payload Parameters

Parameter Description Type
bands A list of equalizer bands that need to be reset. list
bands.name[i] Identifies an equalizer band. If present, the level for that equalizer band must be reset to the default value for that product.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string

SetMode

Instructs a client to enter a specific equalizer mode.

Sample Message

{
    "directive": {
        "header": {
            "namespace": "EqualizerController",
            "name": "SetMode",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "mode": "{{STRING}}"
        }
    }
}

Payload Parameters

Parameter Description Type
mode Specifies a supported mode.
Accepted values: "MOVIE", "MUSIC", "NIGHT", "SPORT", "TV".		 string

Events

EqualizerChanged

This event provides Alexa with the current decibel levels for supported equalizer bands. It is sent:

  • When the client adjusts decibel levels after receiving any of these directives:
  • When equalizer bands are adjusted locally (button press or GUI affordance) or via a mobile app

Sample Message

{
    "event": {
        "header": {
            "namespace": "EqualizerController",
            "name": "EqualizerChanged",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "bands": [
                {
                    "name": "{{STRING}}",
                    "level": {{INTEGER}}
                },
                // This should be a complete list of
                // supported equalizer bands.
            ],
            "mode": "{{STRING}}"
        }
    }
}

Payload Parameters

Parameter Description Type
bands A list of supported equalizer bands. list
bands.name[i] Specifies a supported equalizer band.
Accepted values: "BASS", "MIDRANGE", "TREBLE".		 string
bands.level[i] Specifies the decibel level for an equalizer band. integer
mode Specifies a supported mode.
Accepted values: "MOVIE", "MUSIC", "NIGHT", "SPORT", "TV".		 string
Was this page helpful?

Last updated: Nov 27, 2023