スマートホームの Volume トレイトのスキーマ

action.devices.traits.Volume - このトレイトは、音量の変更（特定のレベルに設定、ミュート、ミュート解除など）できるデバイスに使用します。

デバイスの属性

このトレイトを持つデバイスは、SYNC オペレーションの一部として次の属性を報告できます。SYNC インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。

属性	タイプ	説明
volumeMaxLevel	Integer	必須。 ベースラインを 0（ミュート）とした場合の最大音量レベル。アシスタントは補助的なコマンド（「テレビを少し大きくして」など）を調整します。
volumeCanMuteAndUnmute	ブール値	必須。 デバイスが音量をミュートおよびミュート解除できるかどうかを示します。ミュートは独立したオプションで、ミュートは音量を 0 にして、前の音量を記憶します。ミュートを解除すると、音声は復元します。これは音量の状態に反映され、音量が 5 でユーザーがミュートした場合でも、音量は 5 のままで、isMuted が true になります。
volumeDefaultPercentage	Integer	（デフォルト: 40） ユーザーまたはメーカーが定義したデフォルトのボリュームのボリューム（%）。スケールは 0～100 にする必要があります。
levelStepSize	Integer	（デフォルト: 1） 「<デバイス名> で音量アップ」など、相対的な音量クエリのデフォルトのステップサイズです。
commandOnlyVolume	ブール値	（デフォルト: false） デバイスが一方向（真）または双方向（偽）の通信のどちらで動作しているかを示します。たとえば、コントローラがリクエストの送信後に新しいデバイスの状態を確認できる場合、このフィールドは false になります。リクエストが正常に実行されたかどうかを確認できない場合、またはデバイスの状態を取得できない場合（デバイスが従来の赤外線リモコンである場合など）は、このフィールドを true に設定します。

例

ミュートして現在の状態を報告するスピーカー デバイス

{
  "volumeMaxLevel": 11,
  "volumeCanMuteAndUnmute": true,
  "levelStepSize": 2,
  "commandOnlyVolume": false,
  "volumeDefaultPercentage": 6
}

デバイスのステータス

このトレイトを使用するエンティティは、QUERY オペレーションの一部として次の状態を報告できます。QUERY インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。

状態	タイプ	説明
currentVolume	Integer	必須。 現在の音量のパーセンテージ。>0～volumeMaxLevel の範囲で指定してください。
isMuted	ブール値	volumeCanMuteAndUnmute 属性が true に設定されている場合は必須です。デバイスがミュートされている場合は true。そうでない場合は false。isMuted が true の場合、デバイスは保存されたポイントの currentVolume を返します。

例

ミュートして現在の状態を報告するスピーカー デバイス

{
  "currentVolume": 5,
  "isMuted": false
}

デバイスのコマンド

このトレイトを持つデバイスは、EXECUTE オペレーションの一環として次のコマンドに応答できます。EXECUTE インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。

action.devices.commands.mute

デバイスをミュートまたはミュート解除する

パラメータ

パラメータ	タイプ	説明
mute	ブール値	必須。 デバイスをミュートするかミュート解除するかを指定します。

例

スピーカー デバイスをミュートする

{
  "command": "action.devices.commands.mute",
  "params": {
    "mute": true
  }
}

action.devices.commands.setVolume

volumeMaxLevel に基づいて、音量を要求されたレベルに設定します。

パラメータ

パラメータ	タイプ	説明
volumeLevel	Integer	必須。 新しいボリューム: 0～volumeMaxLevel。

例

スピーカー デバイスの絶対音量を設定する

{
  "command": "action.devices.commands.setVolume",
  "params": {
    "volumeLevel": 6
  }
}

action.devices.commands.volumeRelative

volumeMaxLevel に基づいて、音量を n ステップ上げるか、または下げます。相対スケールを使用するコマンドの場合、アシスタントは適切な n を選択して、利用可能なステップにスケーリングします。たとえば、[テレビをかなり大きくする] に設定すると、テレビを大音量にするよりも多くの手順が設定されます。

パラメータ

パラメータ	タイプ	説明
relativeSteps	Integer	必須。 「下降」。

例

スピーカー モードのコマンドの音量で相対音量を設定する

{
  "command": "action.devices.commands.volumeRelative",
  "params": {
    "relativeSteps": -1
  }
}

デバイスエラー

エラーと例外の全一覧をご覧ください。

• volumeAlreadyMax: デバイスがすでに最大音量になっているときに、VolumeUp コマンドを受け取ります。
• volumeAlreadyMin: デバイスがすでに最小音量になっているときに、VolumeDown コマンドを受け取ります。