智能家居音量特征架构

action.devices.traits.Volume - 此特征属于能够更改音量的设备（例如，将音量设置为特定级别、静音或取消静音）。

设备 ATTRIBUTE

具有此特征的设备可能会报告以下 属性作为 SYNC 操作的一部分。如需详细了解如何处理 SYNC intent，请参阅 intent 实现。

属性	类型	说明
volumeMaxLevel	整数	必填。 最大音量级别，假设基准为 0（静音）。Google 助理会相应地调整副词命令（例如“将电视音量调高一点”）。
volumeCanMuteAndUnmute	布尔值	必填。 指示设备是否可以静音和取消静音。静音是一个单独的选项，因为“静音”行为会将音量设置为 0，同时记住之前的音量，以便取消静音时恢复音量。这反映在音量状态中 - 如果音量为 5，并且用户静音，则音量仍为 5，并且 isMuted 为 true。
volumeDefaultPercentage	整数	（默认值：40） 用户或制造商定义的默认音量的音量（以百分比表示）。比例必须为 0-100。 值必须介于 0 和 100 之间。
levelStepSize	整数	（默认值：1） 相对音量查询（例如“将 <device_name> 的音量调高”）的默认步长。
commandOnlyVolume	布尔值	（默认值：false） 指示设备是使用单向 (true) 还是双向 (false) 通信。例如，如果控制器在发送请求后可以确认新设备状态，则此字段为 false。如果无法确认请求是否成功执行或获取设备的状态（例如，如果设备是传统红外遥控器），请将此字段设置为 true。

示例

可以静音并报告当前状态的扬声器设备

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

设备状态

具有此特征的实体可能会报告以下 状态作为 QUERY 操作的一部分。如需详细了解如何处理 QUERY intent，请参阅 intent 实现。

状态	类型	说明
currentVolume	整数	必填。 当前音量百分比。它必须介于 >0 和 volumeMaxLevel 之间。 最小值：0。
isMuted	布尔值	如果 volumeCanMuteAndUnmute 属性设置为 true，则为必填项。如果设备已静音，则为 true；否则为 false。如果 isMuted 为 true，设备仍会返回记忆点的 currentVolume。

示例

可以静音并报告当前状态的扬声器设备

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

设备命令

具有此特征的设备可能会响应以下 命令作为 EXECUTE 操作的一部分。如需详细了解如何处理 EXECUTE intent，请参阅 intent 实现。

action.devices.commands.mute

将设备静音或取消静音。

参数

参数	类型	说明
mute	布尔值	必填。 是否将设备静音或取消静音。

示例

将扬声器设备静音

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

action.devices.commands.setVolume

根据 volumeMaxLevel 将音量设置为请求的级别。

参数

参数	类型	说明
volumeLevel	整数	必填。 新音量，介于 0 到 volumeMaxLevel 之间。 最小值：0。

示例

设置扬声器设备的绝对音量

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

action.devices.commands.volumeRelative

根据 volumeMaxLevel 将音量调高或调低 n 步。对于使用相对比例的命令，Google 助理会适当地选择 n 以缩放至可用步数。例如，“将电视音量调高很多”将设置比“将电视音量调高一点”更多的步数。

参数

参数	类型	说明
relativeSteps	整数	必填。 负数表示“调低”。

示例

在仅命令模式下设置扬声器设备的相对音量

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

设备错误

请参阅完整的 错误和异常列表。

• volumeAlreadyMax：设备在音量已达到最高时收到 VolumeUp 命令。
• volumeAlreadyMin：设备在音量已达到最低时收到 VolumeDown 命令。