# 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`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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. Value must be between `0` and `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

> [!NOTE]
> **Note:** States are only relevant if the attribute `commandOnlyVolume` is false.

Entities with this trait may report the following
states as part of the [`QUERY`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| States | Type | Description |
|---|---|---|
| `currentVolume` | *Integer* | **Required.** The current volume percentage. It must be between `>0` and `volumeMaxLevel`. Minimum value: `0`. |
| `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`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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`. Minimum value: `0`. |

#### 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-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.