Smart Home Volume Trait Schema

action.devices.traits.Volume - This trait belongs to devices which are able to change volume (for example, setting the volume to a certain level, mute, or unmute).

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
volumeMaxLevel Integer

Required.

The maximum volume level, assuming a baseline of 0 (mute). Assistant will adjust adverbial commands (e.g. 'make the tv a little louder') accordingly.
volumeCanMuteAndUnmute Boolean

Required.

Indicates if the device can mute and unmute the volume. Mute is a separate option as the 'mute' behavior takes the volume to 0 while remembering the previous volume, so that unmute restores it. This is reflected in volume state—if volume is 5, and the user mutes, the volume remains 5 and isMuted is true.
volumeDefaultPercentage Integer

(Default: 40)

The volume (in percentage) for the default volume defined by user or manufacturer. The scale must be 0-100.
levelStepSize Integer

(Default: 1)

The default step size for relative volume queries like 'volume up on <device_name>.
commandOnlyVolume Boolean

(Default: false)

Indicates if the device operates using one-way (true) or two-way (false) communication. For example, if the controller can confirm the new device state after sending the request, this field would be false. If it's not possible to confirm if the request is successfully executed or to get the state of the device (for example, if the device is a traditional infrared remote), set this field to true.

Examples

Speaker device that can be muted and reports current state

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

Device STATES

Entities with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
currentVolume Integer

Required.

The current volume percentage. It must be between >0 and volumeMaxLevel.
isMuted Boolean

Required if volumeCanMuteAndUnmute attribute is set to true. True if the device is muted; false otherwise. If isMuted is true, the device still returns currentVolume for the remembered point.

Examples

Speaker device that can be muted and reports current state

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

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.mute

Mutes or unmutes the device.

Parameters

Parameters Type Description
mute Boolean

Required.

Whether to mute a device or unmute a device.

Examples

Mute speaker device

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

action.devices.commands.setVolume

Set volume to the requested level, based on volumeMaxLevel.

Parameters

Parameters Type Description
volumeLevel Integer

Required.

New volume, from 0 to volumeMaxLevel.

Examples

Set absolute volume of speaker device

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

action.devices.commands.volumeRelative

Set volume up or down n steps, based on volumeMaxLevel. For commands that use a relative scale, the Assistant will select n appropriately to scale to the available steps. For example, Make the TV much louder will set a higher number of steps than Make the TV a tiny bit louder.

Parameters

Parameters Type Description
relativeSteps Integer

Required.

negative for 'decrease'.

Examples

Set relative volume of speaker device in command-only mode

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

Device ERRORS

See the full list of errors and exceptions.
  • volumeAlreadyMax: Device receives VolumeUp command when it is already at highest volume.
  • volumeAlreadyMin: Device receives VolumeDown command when it is already at lowest volume.