feat!: add StreamConfigBuilder with cross-platform configuration support

[roderickvd]

This PR introduces an StreamConfigBuilder with support for platform-specific audio configuration options. This addresses recurring requests for fine-grained control over backend-specific settings while maintaining cross-platform compatibility. At the same time, it improves ergonomics of stream creation.

Motivation

There is a recurring interest in exposing platform-specific audio configuration options:

• use set_buffer_size_near to calculate fixed alsa buffer size #990 - ALSA buffer size configuration issues requiring set_buffer_size_near
• feat(android): add input_preset to StreamConfig #995 - Android input_preset configuration for AEC support
• Realtime CLI spectrogram example #987 - WASAPI raw audio stream configuration needs
• ALSA: fix buffer size / period size configuration #917 - ALSA period/buffer size configuration problems

Users have consistently needed platform-specific control over:

• ALSA: Period counts, access types (RW vs MMap; interleaved vs. non-interleaved)
• JACK: Client names, automatic port connections, server startup
• WASAPI: Exclusive vs shared mode

Not yet added:

• Android: Input presets for AEC and noise cancellation

Currently, these options are either impossible to configure or would require hard-coded defaults or introduction of environment variables.

Solution

All existing APIs remain unchanged. The new builder and platform configuration are purely additive:

use cpal::{StreamConfigBuilder, SampleRate, SampleFormat, BufferSize};

// - builds on all platforms
// - offers more ergonomic stream creation
// - allows platform-specific options
let stream = device.default_output_config()?
    .with_buffer_size(BufferSize::Fixed(256))
    .on_alsa(|alsa| alsa.periods(2))                  // No-op on non-Linux
    .on_wasapi(|wasapi| wasapi.exclusive_mode(true))  // No-op on non-Windows  
    .on_jack(|jack| jack.client_name("app"))          // No-op without JACK
    .build_output_stream(/* callbacks */)?;

As opportunistic refactoring, the following feature flags were re-added:

• jack - Enable JACK audio backend support
• audio_thread_priority - Enable real-time thread priority for ALSA/WASAPI

And documentation was updated for readability and correctness.

[Copilot]

Pull Request Overview

This PR introduces a StreamConfigBuilder with support for platform-specific audio configuration options, improving ergonomics of stream creation while maintaining full cross-platform compatibility. The builder enables fine-grained control over backend-specific settings without requiring conditional compilation.

Key Changes

• Added StreamConfigBuilder with fluent API for configuring audio streams
• Extended platform support to include JACK on all compatible platforms
• Introduced platform-specific configuration wrappers (ALSA, JACK, WASAPI)

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/lib.rs	Core builder implementation and device extensions for improved stream creation API
src/traits.rs	Added Clone requirement to DeviceTrait for builder pattern support
src/platform/mod.rs	Extended JACK support to macOS and Windows platforms
src/host/wasapi/mod.rs	Added WASAPI-specific configuration for exclusive mode support
src/host/wasapi/device.rs	Implemented WASAPI configuration methods for stream building
src/host/jack/mod.rs	Added JACK-specific configuration for client management
src/host/jack/device.rs	Implemented JACK configuration methods with custom client options
src/host/alsa/mod.rs	Added ALSA-specific configuration for periods and access types
Cargo.toml	Updated feature flags and dependencies for new backend support

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The _buffer_size parameter is prefixed with an underscore but is used in the method body, indicating it should not be marked as unused.

Suggested change

	pub fn with_buffer_size(mut self, _buffer_size: BufferSize) -> Self {
	// Create a new config with the updated buffer size
	let supported_config = SupportedStreamConfig::new(
	self.config.channels(),
	self.config.sample_rate(),
	self.config.buffer_size(),
	pub fn with_buffer_size(mut self, buffer_size: BufferSize) -> Self {
	// Create a new config with the updated buffer size
	let supported_config = SupportedStreamConfig::new(
	self.config.channels(),
	self.config.sample_rate(),
	buffer_size,

[Copilot]

This method signature change from returning &SupportedBufferSize to SupportedBufferSize could be a breaking change for existing users who expect a reference.

Suggested change

	pub fn buffer_size(&self) -> SupportedBufferSize {
	self.buffer_size
	pub fn buffer_size(&self) -> &SupportedBufferSize {
	&self.buffer_size

[Copilot]

[nitpick] Consider refactoring this function to use a configuration struct instead of many individual parameters to improve readability and maintainability.

[Copilot]

[nitpick] Using None, None for optional parameters makes the code unclear. Consider using named parameters or a configuration struct to improve readability.

[roderickvd]

Note to self: consider making configurable whether CoreAudio follows default audio device changes or not (#1012).

[roderickvd]

Instead of this we could use extension traits. These would add backend-specific methods without polluting the core trait:

// Core trait - stays platform-agnostic
pub trait DeviceTrait {
    fn name(&self) -> Result<String, DeviceNameError>;
    // ... other core methods
}

// Backend-specific extension trait
#[cfg(target_os = "windows")]
pub trait WasapiDeviceExt {
    /// Access the underlying Windows IMMDevice COM interface.
    fn immdevice(&self) -> &IMMDevice;
}

// Implement the extension only for the WASAPI Device
#[cfg(target_os = "windows")]
impl WasapiDeviceExt for crate::platform::wasapi::Device {
    fn immdevice(&self) -> &IMMDevice {
        &self.device
    }
}

Then how to use:

use cpal::{Device, DeviceTrait}; // Core API

// Works on all platforms
fn portable_code(device: &Device) {
    let name = device.name().unwrap();
    println!("Device: {}", name);
}

// Platform-specific code
#[cfg(target_os = "windows")]
fn windows_specific(device: &Device) {
    use cpal::platform::WasapiDeviceExt;
    let imm_device = device.immdevice();
    // ... do Windows-specific stuff
}

#[cfg(not(target_os = "windows"))]
fn windows_specific(_device: &Device) {
    // ... no-op
}

Or similarly one could create fn platform_specific_setup() for various targets.