feat!: add StreamConfigBuilder with cross-platform configuration support #1010

roderickvd · 2025-09-11T19:52:55Z

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 · 2025-09-11T20:48:05Z

src/lib.rs

+    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(),


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 · 2025-09-11T20:48:05Z

src/lib.rs

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


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 · 2025-09-11T20:48:05Z

src/host/jack/stream.rs


 impl LocalProcessHandler {
-    #[allow(too_many_arguments)]
+    #[allow(clippy::too_many_arguments)]


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

Copilot · 2025-09-11T20:48:06Z

src/host/alsa/mod.rs

    {
        let stream_inner =
-            self.build_stream_inner(conf, sample_format, alsa::Direction::Capture)?;
+            self.build_stream_inner(conf, sample_format, alsa::Direction::Capture, None, None)?;


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

- Add ergonomic StreamConfigBuilder API for stream configuration - Add platform-specific configuration types: - AlsaStreamConfig: configure periods and access types (RW/MMap modes) - JackStreamConfig: configure client names and port auto-connection - WasapiStreamConfig: configure exclusive/shared mode - Add device-tied stream building methods on SupportedStreamConfig - Add convenience methods: Device::default_input/output_config() - Add platform builder methods: .on_alsa(), .on_jack(), .on_wasapi() - Add jack feature flag for JACK audio backend support - Add audio_thread_priority feature flag for ALSA/WASAPI real-time scheduling - Update documentation with Quick Start guide and cross-platform examples - Maintain backward compatibility with existing Device::build_*_stream APIs This introduces a major ergonomic improvement for cross-platform audio configuration while preserving the existing low-level APIs.

This mostly reverts #990 for device compatibility, by letting ALSA calculate the period size from the device default period count. Forcing the period count to 2 caused underruns on some systems.

roderickvd · 2025-09-23T19:57:08Z

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

roderickvd marked this pull request as draft September 11, 2025 19:53

roderickvd added enhancement host - wasapi host - alsa host - jack labels Sep 11, 2025

roderickvd force-pushed the feat/cross-platform-builder branch from 278e12c to 5ec0841 Compare September 11, 2025 20:29

roderickvd mentioned this pull request Sep 11, 2025

fix: simplify ALSA buffer size and period configuration logic #1009

Merged

roderickvd requested a review from Copilot September 11, 2025 20:46

Copilot AI reviewed Sep 11, 2025

View reviewed changes

roderickvd force-pushed the feat/cross-platform-builder branch from 5ec0841 to cbd8e2a Compare September 11, 2025 20:49

roderickvd changed the title ~~feat: add StreamConfigBuilder with cross-platform configuration support~~ feat!: add StreamConfigBuilder with cross-platform configuration support Sep 17, 2025

roderickvd mentioned this pull request Sep 21, 2025

[Question] Handling device disconnects #1012

Open

This was referenced Sep 24, 2025

AAudio AudioPerformanceMode::LowLatency #1015

Closed

feat(android): add input_preset to StreamConfig #995

Open

fix(aaudio): ensure consistent callback buffer sizes with double-buffering #1025

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat!: add StreamConfigBuilder with cross-platform configuration support #1010

feat!: add StreamConfigBuilder with cross-platform configuration support #1010

Uh oh!

roderickvd commented Sep 11, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Sep 11, 2025

Uh oh!

Copilot AI Sep 11, 2025

Uh oh!

Copilot AI Sep 11, 2025

Uh oh!

Copilot AI Sep 11, 2025

Uh oh!

roderickvd commented Sep 23, 2025

Uh oh!

Uh oh!

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

feat!: add StreamConfigBuilder with cross-platform configuration support #1010

Are you sure you want to change the base?

feat!: add StreamConfigBuilder with cross-platform configuration support #1010

Uh oh!

Conversation

roderickvd commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

roderickvd commented Sep 23, 2025

Uh oh!

Uh oh!

roderickvd commented Sep 11, 2025 •

edited

Loading