settings > setPlayerSettings

Use setPlayerSettings in the settings namespace to set volumeMode, volumeScalingFactor, monoMode, and wifiDisable. See the playerSettings type for details.

Endpoint

GET

Request Parameters

This command requires a playerId to determine the target of the command. See Control for details.

Set player settings using the following parameters in the body. These are all optional.

Parameter Type Value
volumeMode enum Set the following values:

  • VARIABLE—the normal mode. The player enables volume controls and makes volume adjustments internally.
  • FIXED—disables volume controls. The player always outputs a fixed volume. This mode is useful for devices without a built-in amplifier, like the Sonos Connect.
  • PASS_THROUGH—enables volume controls in fixed output mode. When enabled, the player emits volume changes as playerVolume events, just as it would in the normal mode. However, the player doesn’t modify the audio signal. This currently works on the Sonos Amp and the Connect. This mode is useful if you offer a third party amp intended for devices without a build-in amplifier, like the Sonos Connect. With this mode, your amp can monitor volume changes from Sonos and automatically adjust the amplifier gain.
volumeScalingFactor float A scaling factor between 0.01 (1%) and 1.0 (100%) applied to compute the volume level. When set, this factor applies to each logical player. Only the primary player accepts this value. For example, the left speaker in a bonded pair or the main home theater speaker, such as the Playbar, in a 5.1 surround set.

  • If the value is out of range, you will receive a globalError.
  • If set on a non-primary player, you’ll receive an ERROR_NOT_CAPABLE globalError.
monoMode Boolean When true, enables mono mode on supported devices. Currently, only the Sonos Beam supports this setting in a supported setup, with no surrounds.

  • If you set this value on any other product you will receive an ERROR_NOT_CAPABLE
    globalError with reason “Command not supported on this device.”
  • If you set this value on a Sonos Amp that is not in a supported setup (for example, it has surrounds), you will receive an ERROR_NOT_CAPABLE globalError with reason “Command not supported in current setup.”
wifiDisable Boolean When true, disables the wireless radio for the device if it detects a valid Ethernet carrier.

  • If the command fails, the player returns an ERROR_COMMAND_FAILED globalError with a reason indicating either a netstart failure or a lack of Ethernet carrier.

Response

Returns an empty body if successful.

If not successful, returns a globalError.