Alexa.EqualizerController Interface 3

Implement the Alexa.EqualizerController interface in your Alexa add-on so that users can set and adjust the equalizer bands and sound modes of a smart entertainment device. For more details about entertainment device add-ons, see Connect Your Device Cloud with Smart Home Add-ons 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 add-on. The following examples show some user utterances:

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.

{
  "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.

{
  "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 add-on 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 Device Templates.

{
  "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 add-on.

SetMode directive

Support the SetMode directive so that users can set the audio mode of their devices. The following example shows a user utterance:

SetMode directive example

The following example shows a SetMode directive that Alexa sends to your add-on.

{
  "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.

{
  "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:30.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "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:

SetBands directive example

The following example shows a SetBands directive that Alexa sends to your add-on.

{
  "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.

{
  "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:25: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:18:40.12Z",
        "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:

AdjustBands directive example

The following example shows an AdjustBands directive that Alexa sends to your add-on.

{
  "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.

{
  "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:32: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:18:40.12Z",
        "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:

ResetBands directive example

The following example shows a ResetBands directive that Alexa sends to your add-on.

{
  "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.

{
  "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:40: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:18:40.12Z",
        "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

{
  "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-03T17:50: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:18:40.12Z",
        "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

{  
  "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-03T18: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:18:40.12Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.EqualizerController Interface 3

Utterances

Reportable properties

Bands property

Mode property

Discovery

Configurations object

Range object

Discover response example

Directives

SetMode directive

SetMode directive example

SetMode directive payload

SetMode response

SetMode directive error handling

SetBands directive

SetBands directive example

SetBands directive payload

SetBands response

SetBands directive error handling

AdjustBands directive

AdjustBands directive example

AdjustBands directive payload

AdjustBands response

AdjustBands directive error handling

ResetBands directive

ResetBands directive example

ResetBands directive payload

ResetBands response

ResetBands directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Reportable properties

​Bands property

​Mode property

​Discovery

​Configurations object

​Range object

​Discover response example

​Directives

​SetMode directive

​SetMode directive example

​SetMode directive payload

​SetMode response

​SetMode directive error handling

​SetBands directive

​SetBands directive example

​SetBands directive payload

​SetBands response

​SetBands directive error handling

​AdjustBands directive

​AdjustBands directive example

​AdjustBands directive payload

​AdjustBands response

​AdjustBands directive error handling

​ResetBands directive

​ResetBands directive example

​ResetBands directive payload

​ResetBands response

​ResetBands directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Reportable properties

Bands property

Mode property

Discovery

Configurations object

Range object

Discover response example

Directives

SetMode directive

SetMode directive example

SetMode directive payload

SetMode response

SetMode directive error handling

SetBands directive

SetBands directive example

SetBands directive payload

SetBands response

SetBands directive error handling

AdjustBands directive

AdjustBands directive example

AdjustBands directive payload

AdjustBands response

AdjustBands directive error handling

ResetBands directive

ResetBands directive example

ResetBands directive payload

ResetBands response

ResetBands directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics