智能家居音量 trait 架构

action.devices.traits.Volume - 此 trait 适用于能够调节音量（例如将音量设为特定级别、静音或取消静音）的设备。

设备属性

具有此 trait 的设备可能会在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent，请参阅intent 执行方式。

属性 类型 说明
volumeMaxLevel 整数

必填。

最大音量级别，假设基准为 0（静音）。Google 助理会相应地调整副词命令（例如“将电视音量调高一点”）。
volumeCanMuteAndUnmute 布尔值

必填。

指示设备是否可以静音和取消静音。静音是一个单独的选项，因为“静音”行为会将音量设为 0，同时记住之前的音量，以便取消静音时恢复该音量。这反映在音量状态中：如果音量为 5，并且用户将音量静音，则音量保持为 5，并且 isMuted 为 true。
volumeDefaultPercentage 整数

（默认值：40）

用户或制造商定义的默认音量的音量（以百分比表示）。比例必须介于 0 到 100 之间。
levelStepSize 整数

（默认值：1）

相对音量查询（例如“调高 <device_name> 的音量”）的默认步长。
commandOnlyVolume 布尔值

（默认值：false）

指示设备是使用单向（true）还是双向（false）通信进行操作。例如，如果控制器在发送请求后可以确认新的设备状态，则此字段的值为 false。如果无法确认请求是否已成功执行或无法获取设备的状态（例如，如果设备是传统的红外遥控器），请将此字段设为 true。

示例

可静音并报告当前状态的音箱设备

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

设备状态

具有此 trait 的实体可能会在 QUERY 操作期间报告以下状态。如需详细了解如何处理 QUERY intent，请参阅intent 执行方式。

州 类型 说明
currentVolume 整数

必填。

当前音量百分比。必须介于 >0 到 volumeMaxLevel 之间。
isMuted 布尔值

如果 volumeCanMuteAndUnmute 属性设为 true，则为必填字段。如果设备处于静音状态，则为 true；否则为 false。如果 isMuted 为 true，设备仍会针对记忆的点返回 currentVolume。

示例

可静音并报告当前状态的音箱设备

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

设备命令

具有此 trait 的设备可能会在 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。

示例

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

{
  "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 命令。