FR: Add volume and mute controls to Device

[micolous]

I want to be able to use this library to control the volume and mute state of input and output Devices, ie:

let input_device = host.default_input_device().unwrap();
println!("microphone mute state: {}", input_device.get_mute());
input_device.set_mute(true);

let output_device = host.default_output_device().unwrap();
println!("output device volume: {} dB, {}%",
    output_device.get_volume_db(),
    output_device.get_volume_scalar() * 100);

// Set output volume to -10dB
output_device.set_volume_db(-10.);
// Set output volume to "scalar" 50% of maximum
output_device.set_volume_scalar(0.5);

[Be-ing]

I'm not sure this should be cpal's responsibility. For ideal gain staging, volume should be set in hardware. I doubt it is possible to do this in a portable way. Of course cpal could simply apply a gain reduction to the samples as a fallback, but that would likely get confusing for the user if it does not interact with the OS or sound server's volume control.

[Be-ing]

Duplicate of #436?

[micolous]

I'm interested in very simple, device-level controls. I think #436 is asking about than mixing audio sources from different applications.

Device-level mixer controls is fairly straight forward to implement, and I've had a crack at doing this for CoreAudio (macOS, based on coreaudio-rs) and Windows APIs. Doing Linux wouldn't be too difficult either, but I'd need to get a Linux box running that has audio devices. 😄

Moving this functionality "upstream" as it were into a library like this means that I don't need to worry so much about writing unsafe platform-specific code, and that everyone in the Rust ecosystem can benefit from it.

[GoodWork0903]

Hi everyone,
I also want to control device volume using this library.
Because we can use this library Cross Platform.
Can I use CPAL to control volume?
Thank you

[Ralith]

That sounds like a significant increase in scope. CPAL is already starved for maintenance resources at its current scope.

[GoodWork0903]

I see.
I think that CPAL can extend

[abique]

I think it is out of scope.
You can't do it with ASIO, and if you want it for your own buffers, just do it yourself.

[xephyris]

Stumbled upon this thread while researching for this feature for a project.

For anyone interested in adding basic cross platform volume controls to their program, I have created a crate cpvc that supports getting and setting the volume as well as getting device names on macOS, Windows, and Linux (pulseaudio only at the moment).

While mute controls have not been implemented, there is cpvc will report the volume as 0 if the device is muted regardless of the unmuted volume set.

This is mainly for output audio devices only at the moment.

For anyone interested, here is the link: https://crates.io/crates/cpvc

[roderickvd]

Thanks for the mention @xephyris!

I think that support for volume control in cpal is nice when it works with bindings (as opposed to using system commands) as:

1. in the end it's just another control next to "play, pause, stop"
2. users do ask for hardware volume support
3. even when not in hardware, it's useful to have per-app volume controls (like on mobile) or be able to controls system volume

I also agree with comments above that maintainership is stretched very thin now. So focusing now on getting the existing PRs through. Will be happy to get more support to do that too.

[xephyris]

Thanks for the reply.

I was originally planning on developing cpvc more as a standalone crate, instead of an addition to cpal. This way, there wouldn't be any extra load on the maintainers.

Right now, I have implemented it both a version using rust bindings as well as a version using system commands.

If there is interest in it being integrated into cpal, I would be happy to create a new PR!

[roderickvd]

I'm interested but have to focus on other work first, so will be limited in bandwidth, but happy to entertain it.

I spent a couple of hours with Claude and this is what we came up with:

Volume Control API Proposal for cpal

This proposal adds optional volume control support to cpal, exposing only what audio hosts natively provide without any software fallbacks or simulation.

Design Principles

• Optional by design: Volume control availability varies significantly across hosts
• No software fallbacks: Only expose what hosts natively support
• Device-centric enumeration: Volume controls are discovered from devices, not hosts
• Follows cpal patterns: Uses existing trait patterns, error handling, and type conventions
• Bare-bones philosophy: No simulation, conversion, or workarounds - pure host API exposure

Core API Types

// Volume level representation (0.0 = silence, 1.0 = maximum)
// Following cpal's type alias pattern (like SampleRate, ChannelCount)
pub type VolumeLevel = f32;

// Decibel representation for precise audio control
pub type DecibelLevel = f32;

// Volume control errors - bare-bones, no "not supported" simulation
#[derive(Debug)]
pub enum VolumeError {
    /// Device has been disconnected
    DeviceNotAvailable,
    /// Invalid channel index
    InvalidChannel,
    /// Invalid volume level (outside valid range)
    InvalidLevel,
    /// Operation not supported by this volume control
    NotSupported,
    /// Host-specific error
    BackendSpecific(String),
}

#[derive(Debug)]
pub enum VolumeControlsError {
    /// Device has been disconnected  
    DeviceNotAvailable,
    /// Host-specific error
    BackendSpecific(String),
}

#[derive(Debug)]
pub enum VolumeControlNameError {
    /// Device has been disconnected
    DeviceNotAvailable,
    /// Host-specific error
    BackendSpecific(String),
}

Device Volume Control Integration

use crate::traits::DeviceTrait;

// Extend existing DeviceTrait with volume control enumeration
pub trait DeviceTrait {
    type VolumeControls: Iterator<Item = Self::VolumeControl>;
    type VolumeControl: VolumeControlTrait;

    // ... existing methods (name, supported_input_configs, etc.) ...

    /// Enumerate volume controls associated with this device.
    /// 
    /// Returns an empty iterator if the device doesn't support volume control.
    /// Different hosts have different device-to-volume-control relationships:
    /// - WASAPI: 1:1 relationship (each device has one endpoint volume)
    /// - ALSA: 1:many relationship (device may have Master, PCM, Speaker controls)  
    /// - CoreAudio: 1:1 or 1:many (depending on device capabilities)
    /// - ASIO/JACK: Empty iterator (no native volume control)
    fn volume_controls(&self) -> Result<Self::VolumeControls, VolumeControlsError>;

    /// Get the default/primary volume control for this device.
    /// 
    /// Returns None if the device doesn't support volume control.
    /// For devices with multiple volume controls, returns the most appropriate one:
    /// - ALSA: Prefers "Master", falls back to "PCM", "Speaker", etc.
    /// - WASAPI: Returns the endpoint volume control
    /// - CoreAudio: Returns the master volume control
    fn default_volume_control(&self) -> Option<Self::VolumeControl>;
}

Volume Control Operations

/// Trait for controlling audio volume on a specific volume control.
/// 
/// Volume controls represent actual hardware or OS-level volume controls.
/// Operations may fail if the underlying hardware doesn't support them.
pub trait VolumeControlTrait {
    /// Get the human-readable name of this volume control.
    /// 
    /// Examples: "Master", "PCM", "Speaker", "Headphones"
    fn name(&self) -> Result<String, VolumeControlNameError>;

    // === BASIC VOLUME OPERATIONS ===

    /// Get the current volume level (0.0 = silence, 1.0 = full scale).
    fn volume(&self) -> Result<VolumeLevel, VolumeError>;

    /// Set the volume level (0.0 = silence, 1.0 = full scale).
    /// 
    /// May be quantized to hardware-supported steps.
    fn set_volume(&self, level: VolumeLevel) -> Result<(), VolumeError>;

    /// Get the current mute state.
    fn is_muted(&self) -> Result<bool, VolumeError>;

    /// Set the mute state.
    fn set_mute(&self, muted: bool) -> Result<(), VolumeError>;

    // === PER-CHANNEL OPERATIONS ===

    /// Get the number of channels this volume control supports.
    /// 
    /// Returns VolumeError::NotSupported if per-channel control is unavailable.
    fn channel_count(&self) -> Result<u32, VolumeError>;

    /// Get the volume level for a specific channel.
    fn channel_volume(&self, channel: u32) -> Result<VolumeLevel, VolumeError>;

    /// Set the volume level for a specific channel.
    fn set_channel_volume(&self, channel: u32, level: VolumeLevel) -> Result<(), VolumeError>;

    /// Get the mute state for a specific channel.
    fn is_channel_muted(&self, channel: u32) -> Result<bool, VolumeError>;

    /// Set the mute state for a specific channel.
    fn set_channel_mute(&self, channel: u32, muted: bool) -> Result<(), VolumeError>;

    // === DECIBEL OPERATIONS ===

    /// Check if this volume control supports native decibel operations.
    /// 
    /// Native dB support available on:
    /// - ALSA (via snd_mixer dB functions)
    /// - WASAPI endpoint volume (IAudioEndpointVolume)
    /// - CoreAudio (some devices, via HAL dB properties)
    fn supports_decibel(&self) -> bool;

    /// Get the current volume in decibels.
    /// 
    /// Returns VolumeError::NotSupported if native dB control is unavailable.
    /// 0 dB = full scale, negative values = attenuation.
    fn volume_db(&self) -> Result<DecibelLevel, VolumeError>;

    /// Set the volume in decibels.
    /// 
    /// 0 dB = full scale, negative values = attenuation.
    /// May be quantized to hardware-supported steps.
    fn set_volume_db(&self, level: DecibelLevel) -> Result<(), VolumeError>;

    /// Get the decibel range supported by this volume control.
    /// 
    /// Returns (min_db, max_db) where max_db is typically 0.0.
    fn volume_db_range(&self) -> Result<(DecibelLevel, DecibelLevel), VolumeError>;
}

Host-Specific Implementation Notes

ALSA (Linux)

• Device Association: Parse PCM device name (e.g., "hw:0,0") to find card number, enumerate mixer controls for that card
• Volume Controls: Multiple per device - "Master", "PCM", "Speaker", "Headphone", etc.
• dB Support: Full native support via snd_mixer_selem_*_dB() functions
• Per-Channel: Supported where hardware provides it
• USB Devices: Create separate cards with device-specific mixer controls

WASAPI (Windows)

• Device Association: 1:1 relationship between IMMDevice and volume controls
• Volume Controls:
  • Endpoint volume (IAudioEndpointVolume) - system-wide device volume
  • Session volume (ISimpleAudioVolume) - per-application volume
• dB Support: Native dB support for endpoint volume only; session volume is linear
• Per-Channel: Supported via IChannelAudioVolume

CoreAudio (macOS)

• Device Association: 1:1 relationship between AudioDeviceID and volume controls
• Volume Controls: Master volume via HAL properties
• dB Support: Partial - available on some devices via kAudioDevicePropertyVolumeDecibels
• Per-Channel: Supported via per-channel HAL properties
• Limitations: Built-in audio may not support software volume control

ASIO

• Volume Controls: None - ASIO bypasses system audio layers by design
• Implementation: Returns empty iterator for volume_controls()

JACK

• Volume Controls: None - professional routing system without built-in mixing
• Implementation: Returns empty iterator for volume_controls()

WebAudio

• Volume Controls: Per-stream gain nodes
• dB Support: None - linear gain only
• Implementation: Could expose GainNode as volume control

Usage Examples

Basic Volume Control

use cpal::traits::{HostTrait, DeviceTrait};

let host = cpal::default_host();
let device = host.default_output_device().unwrap();

// Get the default volume control for this device
if let Some(volume_control) = device.default_volume_control() {
    println!("Volume control: {}", volume_control.name().unwrap());

    // Set volume to 50%
    volume_control.set_volume(0.5)?;

    // Mute the device
    volume_control.set_mute(true)?;

    // Check current volume
    let current_volume = volume_control.volume()?;
    println!("Current volume: {:.1}%", current_volume * 100.0);
}

Multiple Volume Controls (ALSA)

// Enumerate all volume controls for a device
for volume_control in device.volume_controls()? {
    let name = volume_control.name().unwrap_or_else(|_| "Unknown".to_string());
    let volume = volume_control.volume().unwrap_or(0.0);

    println!("Control '{}': {:.1}%", name, volume * 100.0);

    // Prefer Master control for main volume adjustment
    if name == "Master" {
        volume_control.set_volume(0.75)?;
    }
}

Per-Channel Volume Control

if let Some(volume_control) = device.default_volume_control() {
    // Check if per-channel control is available
    if let Ok(channel_count) = volume_control.channel_count() {
        println!("Device has {} channels", channel_count);

        // Set left channel (0) to 60%, right channel (1) to 80%
        if channel_count >= 2 {
            volume_control.set_channel_volume(0, 0.6)?; // Left
            volume_control.set_channel_volume(1, 0.8)?; // Right
        }

        // Mute specific channels
        volume_control.set_channel_mute(0, true)?; // Mute left channel
    }
}

Decibel Volume Control

if let Some(volume_control) = device.default_volume_control() {
    if volume_control.supports_decibel() {
        // Use precise dB control (available on ALSA, WASAPI endpoint, some CoreAudio)
        let (min_db, max_db) = volume_control.volume_db_range()?;
        println!("dB range: {} to {} dB", min_db, max_db);

        // Set to -12 dB (roughly 25% linear volume)
        volume_control.set_volume_db(-12.0)?;

        let current_db = volume_control.volume_db()?;
        println!("Current volume: {:.1} dB", current_db);
    } else {
        // Fall back to linear volume control
        volume_control.set_volume(0.25)?; // Approximately -12 dB
    }
}

Error Handling

match device.default_volume_control() {
    Some(volume_control) => {
        match volume_control.set_volume(0.5) {
            Ok(()) => println!("Volume set successfully"),
            Err(VolumeError::DeviceNotAvailable) => {
                println!("Device was disconnected");
            },
            Err(VolumeError::NotSupported) => {
                println!("This volume control doesn't support volume adjustment");
            },
            Err(VolumeError::InvalidLevel) => {
                println!("Volume level out of range");
            },
            Err(VolumeError::BackendSpecific(msg)) => {
                println!("Host-specific error: {}", msg);
            },
        }
    },
    None => {
        println!("This device doesn't support volume control");
    }
}

Cross-Platform Volume Control

fn set_device_volume(device: &Device, volume: f32) -> Result<(), Box<dyn std::error::Error>> {
    match device.default_volume_control() {
        Some(volume_control) => {
            // Try dB control first for better precision
            if volume_control.supports_decibel() {
                // Convert linear to dB: dB = 20 * log10(linear)
                let db = if volume > 0.0 {
                    20.0 * volume.log10()
                } else {
                    f32::NEG_INFINITY // Mute
                };

                volume_control.set_volume_db(db)?;
            } else {
                // Fall back to linear control
                volume_control.set_volume(volume)?;
            }

            println!("Volume set to {:.1}%", volume * 100.0);
            Ok(())
        },
        None => {
            println!("Device '{}' doesn't support volume control",
                     device.name().unwrap_or_else(|_| "Unknown".to_string()));
            Ok(())
        }
    }
}

Implementation Strategy

1. Implement basic volume/mute for ALSA, WASAPI, CoreAudio
2. Add per-channel support where available
3. Add native dB support for hosts that provide it
4. Consider WebAudio/mobile platform support

[xephyris]

This seems like a pretty interesting approach and an improvement on cpvc's implementation.

I am open to attempt adjusting the framework of cpvc to something similar. Unfortunately, I'm somewhat limited in time as well for what I can do, so progress may not be the quickest.

From my research, alsa, pipewire, and jack don't seem to have very great APIs for interacting with device volume, so my primary focus will be implementing this for pulseaudio.

Right now this is probably what I will be prioritizing:

1. Adding mute volume functions to cpvc
2. Migrate to using f32 for volume changes instead of percents
3. Implement selecting Audio Devices (hopefully in a manner similar to cpal)
4. Implementing per channel audio support
5. Adding changing volume by dB instead of linear

It also appears I will need to change the license for cpvc to be compatible for use in cpal.

If people are willing, I would be open to any PR's to add support for these other Linux audio frameworks.

If you have any suggestions or requests, I can try to implement them as well.

[roderickvd]

Cool, let's see where it takes us.

Here's a pretty full-featured ALSA mixer implementation: https://github.com/librespot-org/librespot/blob/dev/playback/src/mixer/alsamixer.rs

[Ralith]

#551 (comment) seems like a huge pile of complexity (in the API alone!) for something that's orthogonal to cpal's existing features. As a user I'd strongly prefer to see this stay a separate crate.