智能家居音量特征架构
action.devices.traits.Volume
- 此特征属于能够更改音量的设备(例如,将音量设为特定级别、静音或取消静音)。
设备属性
具有此特征的设备可以在 SYNC
操作中报告以下属性。如需详细了解如何处理 SYNC
intent,请参阅 intent 执行方式。
属性 | 类型 | 说明 |
---|---|---|
volumeMaxLevel |
整数 |
必填。 最大音量(假设基线为 0(静音)。Google 助理会相应地调整谓词命令(例如“让电视稍微大声点”)。 |
volumeCanMuteAndUnmute |
Boolean |
必填。 指示设备是否可以将音量静音和取消静音。“静音”是一个单独的选项,因为“静音”行为将音量设为 0,同时记住上一个音量,以便“取消静音”功能能够恢复该音量。这反映在音量状态下。如果音量为 5,并且用户为静音,则音量保持为 5 并且 |
volumeDefaultPercentage |
整数 |
(默认: 用户或制造商定义的默认音量的音量(以百分比为单位)。范围必须为 0-100。 |
levelStepSize |
整数 |
(默认: 相关音量查询(例如“<设备名称>的音量调高”功能)的默认步进大小。 |
commandOnlyVolume |
Boolean |
(默认: 指示设备是以单向 (true) 还是双向 (false) 通信方式运行。例如,如果控制器可以在发送请求后确认新设备状态,则此字段为 false。如果无法确认请求是否成功执行或获取设备的状态(例如,如果设备是传统红外线遥控器),请将此字段设置为 true。 |
示例
可以静音并报告当前状态的扬声器设备
{ "volumeMaxLevel": 11, "volumeCanMuteAndUnmute": true, "levelStepSize": 2, "commandOnlyVolume": false, "volumeDefaultPercentage": 6 }
设备状态
具有此特征的实体可以在 QUERY
操作中报告以下状态。如需详细了解如何处理 QUERY
intent,请参阅 intent 执行方式。
州 | 类型 | 说明 |
---|---|---|
currentVolume |
整数 |
必填。 当前的音量百分比。该值必须介于 |
isMuted |
Boolean |
如果 |
示例
可以静音并报告当前状态的扬声器设备
{ "currentVolume": 5, "isMuted": false }
设备命令
具有此特征的设备可能会在 EXECUTE
操作中响应以下命令。如需详细了解如何处理 EXECUTE
intent,请参阅 intent 执行方式。
action.devices.commands.mute
将设备静音或取消静音。
参数
参数 | 类型 | 说明 |
---|---|---|
mute |
Boolean |
必填。 将设备设为静音还是取消静音。 |
示例
将音响设备静音
{ "command": "action.devices.commands.mute", "params": { "mute": true } }
action.devices.commands.setVolume
根据volumeMaxLevel
,将音量设置为请求的级别。
参数
参数 | 类型 | 说明 |
---|---|---|
volumeLevel |
整数 |
必填。 新的音量,从 |
示例
设置扬声器设备的绝对音量
{ "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
命令。