Alexa.EqualizerControllerインターフェース

Alexa.EqualizerControllerインターフェース

AlexaスキルにAlexa.EqualizerControllerインターフェースを実装すると、ユーザーはイコライザーの帯域やスマートエンターテイメントデバイスのサウンドモードを設定したり調整したりすることができます。エンターテイメントデバイスのスキルの詳細については、エンターテイメントデバイス用のスマートホームスキルを作成するを参照してください。

EqualizerControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

発話

Alexa.EqualizerControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。以下に、ユーザーの発話の例を示します。

Alexa, set bass to -2 on the speakers.
Alexa, increase bass on the stereo.
Alexa, increase bass by 3 on the stereo.
Alexa, reset bass on the TV.
Alexa, reset equalizer on the speakers.
Alexa, set mode to movie on the TV.

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

ユーザーがこのような発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

プロパティ

bandsプロパティ

Alexa.EqualizerControllerインターフェースは、bandsプロパティを使用してデバイス上のイコライザーのさまざまな帯域および各帯域のレベルを指定します。bandsプロパティは、bandオブジェクトの配列です。

Bandオブジェクトの詳細

フィールド 説明 型
name 帯域の名前です。BASS、TREBLE、MIDRANGEのいずれかになります。 文字列
value イコライザー帯域の専用周波数の値（レベル）です。デバイスが検出応答でサポートしているレベルの範囲を指定します。 整数
levelDirection 帯域を調整する際、現在の設定に対してレベルを調整する方向を表します。UP、DOWNのいずれかになります。 文字列
levelDelta 帯域を調整する際、現在の設定に対してレベルを調整する量を表します。levelDeltaを指定しない場合、レベルをデフォルトの量で調整します。 整数

Bandsプロパティの例

この例では3つの帯域の現在値をレポートしています。

クリップボードにコピーされました。

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

modeプロパティ

Alexa.EqualizerControllerインターフェースのmodeプロパティを設定すると、デバイスのイコライザーモードを指定できます。プロパティは文字列で、有効な値はMOVIE、MUSIC、NIGHT、SPORT、TVのいずれかです。

Modeプロパティの例

クリップボードにコピーされました。

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

検出

Alexa.EqualizerControllerをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからの状態レポートリクエストに応じてスキルがレポートする場合は、プロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートする場合はプロパティのproactivelyReportedをtrueに設定します。

SPEAKER、TV、STREAMING_DEVICE、GAME_CONSOLEなどの適切な表示カテゴリーを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

EqualizerControllerには、標準の検出応答フィールドのほかに、次のフィールドを含むconfigurationsオブジェクトを含めます。少なくともbands、modesのいずれかを指定する必要があります。

フィールド 説明 型
bands デバイスがサポートする帯域です。デバイスがプリセットのイコライザーモードのみをサポートする場合、このフィールドを省略します。 オブジェクト
bands.supported デバイスがサポートする帯域名です。有効な値は、BASS、TREBLE、MIDRANGEです。 配列
bands.range デバイスがサポートする帯域レベルの範囲の最小値と最大値です。 オブジェクト
modes デバイスがサポートするプリセットのイコライザーモードです。デバイスが帯域のみをサポートする場合、このフィールドを省略します。 オブジェクト
modes.supported デバイスがサポートするモード名です。有効な値は、MOVIE、MUSIC、NIGHT、SPORT、TVのいずれかです。 配列

検出応答の例

以下は、Alexa.EqualizerControllerインターフェースとAlexa.PowerControllerインターフェースをサポートするテレビを表すDiscover.Responseメッセージの例です。テレビに推奨されるすべてのインターフェースの一覧については、スマートホームスキル用のデバイステンプレートを参照してください。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "テレビメーカーのスマートテレビ",
          "friendlyName": "リビングのテレビ",
          "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"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

SetModeディレクティブ

SetModeディレクティブをサポートすると、ユーザーがデバイスのオーディオモードを設定できます。

以下は、ユーザーの発話の例です。

Alexa, set mode to movie on the Living Room TV.

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

SetModeディレクティブペイロードの詳細

フィールド 説明 型
mode デバイスに設定するモードです。 文字列

SetModeディレクティブの例

次の例は、Alexaがスキルに送信するSetModeディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "SetMode",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
       "mode": "MOVIE"
    }
  }
}

SetMode応答イベント

SetModeディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、認可トークンにスコープを含めます。

SetMode応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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ディレクティブのエラー処理

SetModeディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。ユーザーがデバイスでサポートしていないモードをリクエストした場合、エラータイプにはINVALID_VALUEを使用します。

SetBandsディレクティブ

SetBandsディレクティブをサポートすると、ユーザーがデバイスのイコライザー帯域を設定できます。

以下は、ユーザーの発話の例です。

Alexa, set bass to -2 on the Living Room TV.

アレクサ、テレビの低音域を2に設定して

SetBandsディレクティブペイロードの詳細

フィールド 説明 型
bands デバイスに設定する帯域と各帯域のレベルです。 配列

SetBandsディレクティブの例

次の例は、Alexaがスキルに送信するSetBandsディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "SetBands",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS",
          "value": -2
        }
      ]
    }
  }
}

SetBands応答イベント

SetBandsディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、認可トークンにスコープを含めます。

SetBands応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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ディレクティブのエラー処理

SetBandsディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。ユーザーがデバイスでサポートしていない値や帯域をリクエストした場合、エラータイプにはINVALID_VALUEを使用します。

AdjustBandsディレクティブ

AdjustBandsディレクティブをサポートすると、ユーザーはデバイスのイコライザー帯域を現在の設定に対して相対的に調整できます。

以下は、ユーザーの発話の例です。

Alexa, increase bass by 3 on the Living Room TV.

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

AdjustBandsディレクティブペイロードの詳細

フィールド 説明 型
bands デバイスで変更する帯域と各帯域のレベル調整です。 配列

AdjustBandsディレクティブの例

以下の例は、Alexaがスキルに送信するAdjustBandsディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "AdjustBands",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS",
          "levelDelta": 3,
          "levelDirection": "UP"
        }
      ]
    }
  }
}

AdjustBands応答イベント

AdjustBandsディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、認可トークンにスコープを含めます。

AdjustBands応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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ディレクティブのエラー処理

AdjustBandsディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。ユーザーがデバイスでサポートしていない帯域をリクエストした場合、エラータイプにはINVALID_VALUEを使用します。

ResetBandsディレクティブ

ResetBandsディレクティブをサポートすると、ユーザーがデバイスのイコライザー帯域をデフォルト値にリセットできます。

以下は、ユーザーの発話の例です。

Alexa, reset bass on the Living Room TV.

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

ResetBandsディレクティブペイロードの詳細

フィールド 説明 型
bands デバイスでリセットする帯域です。 配列

ResetBandsディレクティブの例

次の例は、Alexaがスキルに送信するResetBandsディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.EqualizerController",
      "name": "ResetBands",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "bands": [
        {
          "name": "BASS"
        },
        {
          "name": "MIDRANGE"
        },
        {
          "name": "TREBLE"
        }
      ]
    }
  }
}

ResetBands応答イベント

ResetBandsディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、認可トークンにスコープを含めます。

ResetBands応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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ディレクティブのエラー処理

ResetBandsディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。ユーザーがデバイスでサポートしていない帯域をリクエストした場合、エラータイプにはINVALID_VALUEを使用します。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

StateReport応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

ChangeReportイベントの例

クリップボードにコピーされました。

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイント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
      }
    ]
  }
}

このページは役に立ちましたか？

最終更新日: 2021 年 10 月 26 日