Alexa.EqualizerController Interface 3

Implement the Alexa.EqualizerController interface in your Alexa skill so that users can set and adjust the equalizer bands and sound modes of a smart entertainment device. For more details about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.

For the list of languages that the Alexa.EqualizerController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.EqualizerController interface uses the pre-built voice interaction model. After the customer says one of the following utterances, Alexa sends a corresponding directive to your skill.

The following examples show some user utterances:

Alexa, set bass to minus two on the speakers.
Alexa, increase bass on the stereo.
Alexa, increase bass by three on the stereo.
Alexa, reset bass on the TV.
Alexa, reset equalizer on the speakers.
Alexa, set mode to movie on the TV.

Alexa, règle les basses sur deux sur les haut-parleurs.
Alexa, augmente les basses sur la stéréo.
Alexa, augmente les basses par trois sur la stéréo.
Alexa, réinitialise les basses sur la télé.
Alexa, réinitialise l'égaliseur sur les haut-parleurs.
Alexa, mets le téléviseur en mode film.

Alexa, stelle (den) Bass auf minus zwei auf (dem) Lautsprecher.
Alexa, erhöhe den Bass (auf) der Stereoanlage.
Alexa, erhöhe den Bass (auf) der Stereoanlage um drei.
Alexa, Bass auf dem Fernseher zurücksetzen.
Alexa, Equalizer auf den Lautsprechern zurücksetzen.
Alexa, setze den Modus auf Film auf dem Fernseher.

Alexa, स्पीकर पर बास को माइनस दो पर सेट करें।
Alexa, स्टीरियो पर बास बढ़ाओ।
Alexa, स्टीरियो पर बास को तीन से बढ़ाएं।
Alexa, टीवी पर बास रीसेट करें
Alexa, स्पीकर पर इक्वलाइज़र रीसेट करें।
Alexa, टीवी पर मूवी के लिए मोड सेट करें।

Alexa, imposta i bassi su meno due sugli altoparlanti.
Alexa, aumenta i bassi sullo stereo.
Alexa, aumenta di tre i bassi sullo stereo.
Alexa, reimposta i bassi sulla TV.
Alexa, resetta l'equalizzatore sugli altoparlanti.
Alexa, imposta la modalità su film sulla TV.

アレクサ、スピーカーの低音域をマイナス2にして
アレクサ、ステレオの低音域を上げて
アレクサ、ステレオの低音域を3上げて
アレクサ、テレビの低音域をリセットして
アレクサ、イコライザーをリセットして
アレクサ、テレビをシネマモードにして

Alexa, diminua os graves em dois nos alto-falantes.
Alexa, aumenta os graves no estéreo.
Alexa, aumente os graves em três no estéreo.
Alexa, resetar os graves na t.v.
Alexa, reinicie o equalizador nos alto-falantes.
Alexa, coloque a t.v. no modo filme.

Alexa, pon los graves a menos dos en los altavoces.
Alexa, aumenta los graves en el estéreo.
Alexa, aumenta los graves del estéreo en tres.
Alexa, restablece los graves en la TV.
Alexa, restablece el ecualizador en los altavoces.
Alexa, configura el modo de película en el televisor.

Reportable properties

The Alexa.EqualizerController interface supports the bands and mode properties. You identify that you support the properties in your discovery response.

Bands property

The Alexa.EqualizerController interface uses the bands property to represent the different bands, and the level of each, for the equalizer on a device. The bands property is an array of Band objects.

The following example reports the current value of three bands.

Copied to clipboard.

{
  "name": "bands",
  "value": [
    {
      "name": "BASS",
      "value": 0
    },
    {
      "name": "MIDRANGE",
      "value": 3
    },
    {
      "name": "TREBLE",
      "value": 1
    }
  ]
},

The following table shows the definition of the Band object.

Property Description Type
name Name of the band.
Valid values: BASS, TREBLE, or MIDRANGE.		 String
value Indicates the discrete frequency value (level) of the equalizer band. You specify the range of levels that your device supports in your discovery response. Integer
levelDirection When adjusting a band, the direction to adjust the level relative to the current setting.
Valid values: UP or DOWN.		 String
levelDelta When adjusting a band, the amount by which to adjust the level relative to the current setting. If levelDelta, isn't specified, adjust the level by the default amount. Integer

Mode property

The Alexa.EqualizerController interface uses the mode property to indicate the equalizer mode of the device, if the user sets one. The property is a string and valid values are MOVIE, MUSIC, NIGHT, SPORT, TV.

The following example shows a mode property.

Copied to clipboard.

{
  "name": "mode",
  "value": "MOVIE"
}

Discovery

You describe endpoints that support Alexa.EqualizerController by 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.

To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Configurations object

In addition to the usual discovery response fields, for Alexa.EqualizerController, include a configurations object that contains the following fields. You must specify at least one of bands or modes.

Property Description Type
bands Bands that your device supports. Omit this field if your device only supports pre-set equalizer modes. Object
bands.supported Names of the bands that your device supports.
Valid values are BASS, TREBLE, and MIDRANGE.		 Array
bands.range Minimum and maximum values for the range of band levels that your device supports. Object
modes Pre-set equalizer modes that your device supports. Omit this field if your device supports bands only. Object
modes.supported Names of the modes that your device supports.
Valid values: MOVIE, MUSIC, NIGHT, SPORT, TV.		 Array

Range object

Use range to represent a range of values.

The following example shows the minimum and maximum values for a range.

{
  "name": "range",
  "value": {
    "minimum": -100,
    "maximum": 100
  }
}

Discover response example

The following example shows a Discover.Response message for a television that supports the Alexa.EqualizerController and Alexa.PowerController interfaces. For the full list of recommended interfaces for a television, see Smart Home Skill Device Templates.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Smart Television by Television Maker",
          "friendlyName": "Living Room TV",
          "displayCategories": ["TV"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EqualizerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "bands"
                  },
                  {
                    "name": "mode"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configurations": {
                "bands": {
                  "supported": [
                    {
                      "name": "BASS"
                    },
                    {
                      "name": "MIDRANGE"
                    },
                    {
                      "name": "TREBLE"
                    }
                  ],
                  "range": {
                    "minimum": -6,
                    "maximum": 6
                  }
                },
                "modes": {
                  "supported": [
                    {
                      "name": "MOVIE"
                    },
                    {
                      "name": "MUSIC"
                    },
                    {
                      "name": "SPORT"
                    }
                  ]
                }
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.EqualizerController interface directives to your skill.

SetMode directive

Support the SetMode directive so that users can set the audio mode of their devices.

The following example shows a user utterance:

Alexa, set mode to movie on the TV.

Alexa, mets le téléviseur en mode film.

Alexa, setze den Modus auf Film auf dem Fernseher.

Alexa, टीवी पर मूवी के लिए मोड सेट करें।

Alexa, imposta la modalità su film sulla TV.

アレクサ、テレビをシネマモードにして

Alexa, coloque a t.v. no modo filme.

Alexa, configura el modo de película en el televisor.

SetMode directive example

The following example shows a SetMode directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "SetMode",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
       "mode": "MOVIE"
    }
  }
}

SetMode directive payload

The following table shows the payload details for the SetMode directive.

Property Description Type
mode Indicates the mode to set the device to. String

SetMode response

If you handle a SetMode directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties. You can respond synchronously or asynchronously. If you respond asynchronously, include a scope with an authorization token.

The following example shows a SetMode response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "mode",
        "value": "MOVIE",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": 0
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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
      }
    ]
  }
}

SetMode directive error handling

If you can't handle a SetMode directive successfully, respond with an Alexa.ErrorResponse event. Use the INVALID_VALUE error type if the user requests a mode that your device doesn't support.

SetBands directive

Support the SetBands directive so that users can set the equalizer bands on their devices.

The following example shows a user utterance:

Alexa, set bass to minus two on the Living Room TV.

Alexa, règle les basses sur deux sur les haut-parleurs.

Alexa, stelle (den) Bass auf minus zwei auf (dem) Lautsprecher.

Alexa, लिविंग रूम टीवी पर बेस को माइनस दो पर सेट करो

Alexa, imposta i bassi su meno due sugli altoparlanti.

アレクサ、スピーカーの低音域をマイナス2にして

Alexa, diminua os graves em dois nos alto-falantes.

Alexa, pon los graves a menos dos en los altavoces.

SetBands directive example

The following example shows a SetBands directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "SetBands",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS",
          "value": -2
        }
      ]
    }
  }
}

SetBands directive payload

The following table shows the payload details for the SetBands directive.

Property Description Type
bands Indicates the bands, and level for each, to set on the device. Array

SetBands response

If you handle a SetBands directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties. You can respond synchronously or asynchronously. If you respond asynchronously, include a scope with an authorization token.

The following example shows a SetBands response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "mode",
        "value": "MOVIE",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": -2
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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
      }
    ]
  }
}

SetBands directive error handling

If you can't handle a SetBands directive successfully, respond with an Alexa.ErrorResponse event. Use the INVALID_VALUE error type if the user requests a value or band that your device doesn't support.

AdjustBands directive

Support the AdjustBands directive so that users can adjust the equalizer bands on their devices, relative to their current settings.

The following example shows a user utterance:

Alexa, increase bass by three on the stereo.

Alexa, augmente les basses par trois sur la stéréo.

Alexa, erhöhe den Bass (auf) der Stereoanlage um drei.

Alexa, स्टीरियो पर बास को तीन से बढ़ाएं।

Alexa, aumenta di tre i bassi sullo stereo.

アレクサ、ステレオの低音域を3上げて

Alexa, aumente os graves em três no estéreo.

Alexa, aumenta los graves del estéreo en tres.

AdjustBands directive example

The following example shows an AdjustBands directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "AdjustBands",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS",
          "levelDelta": 3,
          "levelDirection": "UP"
        }
      ]
    }
  }
}

AdjustBands directive payload

The following table shows the payload details for the AdjustBands directive.

Property Description Type
bands Indicates the bands, and level adjustment for each, to change on the device. Array

AdjustBands response

If you handle an AdjustBands directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties. You can respond synchronously or asynchronously. If you respond asynchronously, include a scope with an authorization token.

The following example shows a AdjustBands response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "mode",
        "value": "MOVIE",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": 1
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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
      }
    ]
  }
}

AdjustBands directive error handling

If you can't handle an AdjustBands directive successfully, respond with an Alexa.ErrorResponse event. Use the INVALID_VALUE error type if the user requests a band that your device doesn't support.

ResetBands directive

Support the ResetBands directive so that users can reset the equalizer bands on their devices to their default values.

The following example shows a user utterance:

Alexa, reset bass on the TV.

Alexa, réinitialise les basses sur la télé.

Alexa, Bass auf dem Fernseher zurücksetzen.

Alexa, टीवी पर बास रीसेट करें

Alexa, reimposta i bassi sulla TV.

アレクサ、テレビの低音域をリセットして

Alexa, resetar os graves na t.v.

Alexa, restablece los graves en la TV.

ResetBands directive example

The following example shows a ResetBands directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "ResetBands",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS"
        },
        {
          "name": "MIDRANGE"
        },
        {
          "name": "TREBLE"
        }
      ]
    }
  }
}

ResetBands directive payload

The following table shows the payload details for the ResetBands directive.

Property Description Type
bands Indicates the bands to reset on the device. Array

ResetBands response

If you handle a ResetBands directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties. You can respond synchronously or asynchronously. If you respond asynchronously, include a scope with an authorization token.

The following example shows a ResetBands response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "mode",
        "value": "MOVIE",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": 0
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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
      }
    ]
  }
}

ResetBands directive error handling

If you can't handle a ResetBands directive successfully, respond with an Alexa.ErrorResponse event. Use the INVALID_VALUE error type if the user requests a band that your device doesn't support.

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 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 example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "mode",
        "value": "MOVIE",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": 0
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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 report changes proactively 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

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "VOICE_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.EqualizerController",
            "name": "mode",
            "value": "SPORT",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EqualizerController",
        "name": "bands",
        "value": [
          {
            "name": "BASS",
            "value": 0
          },
          {
            "name": "MIDRANGE",
            "value": 3
          },
          {
            "name": "TREBLE",
            "value": 1
          }
        ],
        "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
      }
    ]
  }
}
Was this page helpful?

Last updated: Nov 22, 2023