アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。順次日本語化を進めてまいりますので、ご理解のほどよろしくお願いいたします。

Alexa.EqualizerController

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.

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 bands attribute represents the different equalizer bands supported by the endpoint, and their ranges.
  • The modes attribute 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

The control and query directives in this interface are supported in skills that target the following languages:

  • English (US)

See Develop Smart Home Skills in Multiple Languages for more information.

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