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

After the user says one of these utterances, Alexa sends a corresponding directive to your skill.

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.

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 Living Room TV.

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.

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 Living Room TV.

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 Living Room 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
      }
    ]
  }
}