feat: add StreamConfigBuilder with cross-platform configuration support

- 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.

Author: roderickvd

CHANGELOG.md

@@ -1,15 +1,24 @@
 # Unreleased
 
-- Added `Sample::bits_per_sample` method.
-- ALSA(process_output): Pass `silent=true` to `PCM.try_recover`, so it doesn't write to stderr.
-- ALSA: Fix BufferSize::Fixed by selecting the nearest supported frame count.
-- ALSA: Change BufferSize::Default to use the device defaults instead of 4 periods of 25 ms.
+- Add `audio_thread_priority` feature flag for real-time thread priority on ALSA/WASAPI.
+- Add `Sample::bits_per_sample` method.
+- Add `StreamConfigBuilder` with platform-specific options.
+- Add device-tied stream building methods: `SupportedStreamConfig::build_input_stream()` and `build_output_stream()`.
+- `BufferSize` now impls `Default`.
+- Remove deprecated `oboe-shared-stdcxx` feature flag.
+- ALSA: Add `AlsaStreamConfig` for periods and access types.
+- ALSA: Fix `BufferSize::Fixed` by selecting the nearest supported frame count.
+- ALSA: Change `BufferSize::Default` to use the device defaults.
 - ALSA: Change card enumeration to work like `aplay -L` does.
+- ALSA(process_output): Pass `silent=true` to `PCM.try_recover`, so it doesn't write to stderr.
 - ASIO: Fix linker flags for MinGW cross-compilation.
 - CoreAudio: Change `Device::supported_configs` to return a single element containing the available sample rate range when all elements have the same `mMinimum` and `mMaximum` values.
 - CoreAudio: Change default audio device detection to be lazy when building a stream, instead of during device enumeration.
 - iOS: Fix example by properly activating audio session.
-- WASAPI: Expose IMMDevice from WASAPI host Device.
+- JACK: Add `jack` feature flag to enable JACK audio backend support.
+- JACK: Add `JackStreamConfig` for client names and port connections.
+- WASAPI: Add `WasapiStreamConfig` for exclusive mode support.
+- WASAPI: Expose `IMMDevice` from WASAPI host Device.
 
 # Version 0.16.0 (2025-06-07)
 

Cargo.toml

@@ -10,13 +10,18 @@ edition = "2021"
 rust-version = "1.70"
 
 [features]
-asio = ["asio-sys", "num-traits"] # Only available on Windows. See README for setup instructions.
+# ASIO backend (Windows only). See README for setup instructions.
+asio = ["dep:asio-sys", "dep:num-traits"]
 
-# Deprecated, the `oboe` backend has been removed
-oboe-shared-stdcxx = []
+# Real-time thread priority for audio threads on ALSA/WASAPI
+audio_thread_priority = ["dep:audio_thread_priority"]
+
+# JACK Audio backend
+jack = ["dep:jack"]
 
 [dependencies]
 dasp_sample = "0.11"
+jack = { version = "0.13.0", optional = true }
 
 [dev-dependencies]
 anyhow = "1.0"
@@ -46,7 +51,6 @@ num-traits = { version = "0.2.6", optional = true }
 alsa = "0.9"
 libc = "0.2"
 audio_thread_priority = { version = "0.33.0", optional = true }
-jack = { version = "0.13.0", optional = true }
 
 [target.'cfg(any(target_os = "macos", target_os = "ios"))'.dependencies]
 mach2 = "0.4" # For access to mach_timebase type.

README.md

@@ -17,8 +17,8 @@ This library currently supports the following:
 Currently, supported hosts include:
 
 - Linux (via ALSA or JACK)
-- Windows (via WASAPI by default, see ASIO instructions below)
-- macOS (via CoreAudio)
+- Windows (via WASAPI by default, JACK or ASIO, see instructions below)
+- macOS (via CoreAudio or JACK)
 - iOS (via CoreAudio)
 - Android (via AAudio)
 - Emscripten
@@ -27,16 +27,30 @@ Note that on Linux, the ALSA development files are required. These are provided
 as part of the `libasound2-dev` package on Debian and Ubuntu distributions and
 `alsa-lib-devel` on Fedora.
 
+For JACK support, install the JACK development libraries on Linux
+(`libjack-jackd2-dev` on Debian/Ubuntu) or download JACK from
+[jackaudio.org](https://jackaudio.org/downloads/) for macOS/Windows.
+
 ## Compiling for Web Assembly
 
-If you are interested in using CPAL with WASM, please see [this guide](https://github.com/RustAudio/cpal/wiki/Setting-up-a-new-CPAL-WASM-project) in our Wiki which walks through setting up a new project from scratch.
+If you are interested in using CPAL with WASM, please see
+[this guide](https://github.com/RustAudio/cpal/wiki/Setting-up-a-new-CPAL-WASM-project)
+in our Wiki which walks through setting up a new project from scratch.
 
 ## Feature flags for audio backends
 
-Some audio backends are optional and will only be compiled with a [feature flag](https://doc.rust-lang.org/cargo/reference/features.html).
+Some audio backends and features are optional and will only be compiled with a
+[feature flag](https://doc.rust-lang.org/cargo/reference/features.html).
+
+### Audio Backend Features
+
+- **ASIO**: `asio` - Enable ASIO support (Windows only)
+- **JACK**: `jack` - Enable JACK audio support
+
+### Additional Features
 
-- JACK (on Linux): `jack`
-- ASIO (on Windows): `asio`
+- **Real-time Thread Priority**: `audio_thread_priority` - Enable real-time
+thread priority for ALSA/WASAPI audio threads (may require elevated privileges)
 
 ## ASIO on Windows
 
@@ -51,13 +65,20 @@ WASAPI.
 
 ### Locating the ASIO SDK
 
-The location of ASIO SDK is exposed to CPAL by setting the `CPAL_ASIO_DIR` environment variable.
+The location of ASIO SDK is exposed to CPAL by setting the `CPAL_ASIO_DIR`
+environment variable.
 
-The build script will try to find the ASIO SDK by following these steps in order:
+The build script will try to find the ASIO SDK by following these steps in
+order:
 
 1. Check if `CPAL_ASIO_DIR` is set and if so use the path to point to the SDK.
-2. Check if the ASIO SDK is already installed in the temporary directory, if so use that and set the path of `CPAL_ASIO_DIR` to the output of `std::env::temp_dir().join("asio_sdk")`.
-3. If the ASIO SDK is not already installed, download it from <https://www.steinberg.net/asiosdk> and install it in the temporary directory. The path of `CPAL_ASIO_DIR` will be set to the output of `std::env::temp_dir().join("asio_sdk")`.
+2. Check if the ASIO SDK is already installed in the temporary directory, if so
+use that and set the path of `CPAL_ASIO_DIR` to the output of
+`std::env::temp_dir().join("asio_sdk")`.
+3. If the ASIO SDK is not already installed, download it from
+<https://www.steinberg.net/asiosdk> and install it in the temporary directory.
+The path of `CPAL_ASIO_DIR` will be set to the output of
+`std::env::temp_dir().join("asio_sdk")`.
 
 In an ideal situation you don't need to worry about this step.
 
@@ -70,22 +91,25 @@ In an ideal situation you don't need to worry about this step.
 2. Add the LLVM `bin` directory to a `LIBCLANG_PATH` environment variable. If
    you installed LLVM to the default directory, this should work in the command
    prompt:
-   ```
+   ```cmd
    setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"
    ```
 3. If you don't have any ASIO devices or drivers available, you can [**download
    and install ASIO4ALL**](http://www.asio4all.org/). Be sure to enable the
    "offline" feature during installation despite what the installer says about
    it being useless.
-4. Our build script assumes that Microsoft Visual Studio is installed if the host OS for compilation is Windows. The script will try to find `vcvarsall.bat`
-   and execute it with the right host and target machine architecture regardless of the Microsoft Visual Studio version.
+4. Our build script assumes that Microsoft Visual Studio is installed if the
+   host OS for compilation is Windows. The script will try to find
+   `vcvarsall.bat` and execute it with the right host and target machine
+   architecture regardless of the Microsoft Visual Studio version.
    If there are any errors encountered in this process which is unlikely,
-   you may find the `vcvarsall.bat` manually and execute it with your machine architecture as an argument.
+   you may find the `vcvarsall.bat` manually and execute it with your machine
+   architecture as an argument.
    The script will detect this and skip the step.
 
    A manually executed command example for 64 bit machines:
 
-   ```
+   ```cmd
    "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
    ```
 
@@ -106,7 +130,7 @@ In an ideal situation you don't need to worry about this step.
 
 6. Make sure to enable the `asio` feature when building CPAL:
 
-   ```
+   ```shell
    cargo build --features "asio"
    ```
 
@@ -121,18 +145,26 @@ _Updated as of ASIO version 2.3.3._
 
 ### Cross compilation
 
-When Windows is the host and the target OS, the build script of `asio-sys` supports all cross compilation targets
-which are supported by the MSVC compiler. An exhaustive list of combinations could be found [here](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160#vcvarsall-syntax) with the addition of undocumented `arm64`, `arm64_x86`, `arm64_amd64` and `arm64_arm` targets. (5.11.2023)
+When Windows is the host and the target OS, the build script of `asio-sys`
+supports all cross compilation targets which are supported by the MSVC
+compiler. An exhaustive list of combinations could be found [here](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160#vcvarsall-syntax)
+with the addition of undocumented `arm64`, `arm64_x86`, `arm64_amd64` and
+`arm64_arm` targets. (5.11.2023)
 
-It is also possible to compile Windows applications with ASIO support on Linux and macOS.
+It is also possible to compile Windows applications with ASIO support on Linux
+and macOS.
 
-For both platforms the common way to do this is to use the [MinGW-w64](https://www.mingw-w64.org/) toolchain.
+For both platforms the common way to do this is to use the
+[MinGW-w64](https://www.mingw-w64.org/) toolchain.
 
-Make sure that you have included the `MinGW-w64` include directory in your `CPLUS_INCLUDE_PATH` environment variable.
-Make sure that LLVM is installed and include directory is also included in your `CPLUS_INCLUDE_PATH` environment variable.
+Make sure that you have included the `MinGW-w64` include directory in your
+`CPLUS_INCLUDE_PATH` environment variable.
+Make sure that LLVM is installed and include directory is also included in your
+`CPLUS_INCLUDE_PATH` environment variable.
 
-Example for macOS for the target of `x86_64-pc-windows-gnu` where `mingw-w64` is installed via brew:
+Example for macOS for the target of `x86_64-pc-windows-gnu` where `mingw-w64`
+is installed via brew:
 
-```
+```shell
 export CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH:/opt/homebrew/Cellar/mingw-w64/11.0.1/toolchain-x86_64/x86_64-w64-mingw32/include"
 ```

examples/synth_tones.rs

@@ -125,7 +125,7 @@ pub fn host_device_setup(
     let config = device.default_output_config()?;
     println!("Default output config : {config:?}");
 
-    Ok((host, device, config))
+    Ok((host, device, config.into()))
 }
 
 pub fn make_stream<T>(