From b3907a46c44dce5521a4db733623482ccd554e6e Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Thu, 13 Nov 2025 23:14:41 -0500 Subject: [PATCH 1/3] chore: bump version to 0.17.0 and add upgrade guide --- Cargo.toml | 2 +- UPGRADING.md | 201 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 UPGRADING.md diff --git a/Cargo.toml b/Cargo.toml index 72ca18332..ac7decdf7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cpal" -version = "0.16.0" +version = "0.17.0" description = "Low-level cross-platform audio I/O library in pure Rust." repository = "https://github.com/RustAudio/cpal" documentation = "https://docs.rs/cpal" diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 000000000..de8fcc98a --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,201 @@ +# Upgrading from v0.16 to v0.17 + +This guide covers breaking changes requiring code updates. See [CHANGELOG.md](CHANGELOG.md) for the complete list of changes and improvements. + +## Breaking Changes Checklist + +- [ ] Replace `SampleRate(n)` with plain `n` values +- [ ] Update `windows` crate to >= 0.59, <= 0.62 (Windows only) +- [ ] Update `alsa` crate to 0.10 (Linux only) +- [ ] Remove `wee_alloc` feature from Wasm builds (if used) +- [ ] Wrap CoreAudio streams in `Arc` if you were cloning them (macOS only) +- [ ] Handle `BuildStreamError::StreamConfigNotSupported` for `BufferSize::Fixed` (JACK, strict validation) +- [ ] Update device name matching if using ALSA (Linux only) + +**Recommended migrations:** +- [ ] Replace deprecated `device.name()` calls with `device.description()` or `device.id()` + +--- + +## 1. SampleRate is now a u32 type alias + +**What changed:** `SampleRate` changed from a struct to a `u32` type alias. + +```rust +// Before (v0.16) +use cpal::SampleRate; +let config = StreamConfig { + channels: 2, + sample_rate: SampleRate(44100), + buffer_size: BufferSize::Default, +}; + +// After (v0.17) +let config = StreamConfig { + channels: 2, + sample_rate: 44100, + buffer_size: BufferSize::Default, +}; +``` + +**Impact:** Remove `SampleRate()` constructor calls. The type is now just `u32`, so use integer literals or variables directly. + +--- + +## 2. Device::name() deprecated (soft deprecation) + +**What changed:** `Device::name()` is deprecated in favor of `id()` and `description()`. + +```rust +// Old (still works but shows deprecation warning) +let name = device.name()?; + +// New: For user-facing display +let desc = device.description()?; +println!("Device: {}", desc); // or desc.name() for just the name + +// New: For stable identification and persistence +let id = device.id()?; +let id_string = id.to_string(); // Save this +// Later... +let device = host.device_by_id(&id_string.parse()?)?; +``` + +**Impact:** Deprecation warnings only. The old API still works in v0.17. Update when convenient to prepare for future versions. + +**Why:** Separates stable device identification (`id()`) from human-readable names (`description()`). + +--- + +## 3. CoreAudio Stream no longer Clone (macOS) + +**What changed:** On macOS, `Stream` no longer implements `Clone`. Use `Arc` instead. + +```rust +// Before (v0.16) - macOS only +let stream = device.build_output_stream(&config, data_fn, err_fn, None)?; +let stream_clone = stream.clone(); + +// After (v0.17) - all platforms +let stream = Arc::new(device.build_output_stream(&config, data_fn, err_fn, None)?); +let stream_clone = Arc::clone(&stream); +``` + +**Why:** Removed as part of making `Stream` implement `Send` on macOS. + +--- + +## 4. BufferSize behavior changes + +### BufferSize::Default now uses host defaults + +**What changed:** `BufferSize::Default` now defers to the audio host/device defaults instead of applying cpal's opinionated defaults. + +**Impact:** Buffer sizes may differ from v0.16, affecting latency characteristics: +- **Lower latency** in most cases (hosts typically choose sensible defaults) +- **May underrun** on resource-constrained systems previously relying on larger cpal defaults +- **Better integration** with system audio configuration (e.g., PulseAudio, PipeWire, JACK) + +**Migration:** If you experience underruns or need specific latency, use `BufferSize::Fixed(size)` instead of relying on defaults. + +**Platform-specific notes:** +- **ALSA:** Previously used cpal's hardcoded 25ms periods / 100ms buffer, now uses device defaults +- **All platforms:** Default buffer sizes now match what the host audio system expects + +### BufferSize::Fixed validation stricter + +**What changed:** Several backends now reject invalid `BufferSize::Fixed` requests instead of silently adjusting: + +- **ALSA:** Validates against hardware constraints (was: rounded to nearest) +- **JACK:** Must exactly match server buffer size (was: silently ignored) +- **Emscripten/WebAudio:** Validates min/max range +- **ASIO:** Stricter lower bound validation + +```rust +// Handle validation errors +let mut config = StreamConfig { + channels: 2, + sample_rate: 44100, + buffer_size: BufferSize::Fixed(512), +}; + +match device.build_output_stream(&config, data_fn, err_fn, None) { + Ok(stream) => { /* success */ }, + Err(BuildStreamError::StreamConfigNotSupported) => { + config.buffer_size = BufferSize::Default; // Fallback + device.build_output_stream(&config, data_fn, err_fn, None)? + }, + Err(e) => return Err(e), +} +``` + +**JACK users:** Use `BufferSize::Default` to automatically match the server's configured size. + +--- + +## 5. Dependency updates + +Update these dependencies if you use them directly: + +```rust +[dependencies] +cpal = "0.17" + +# Platform-specific (if used directly): +alsa = "0.10" # Linux only +windows = { version = ">=0.58, <=0.62" } # Windows only +audio_thread_priority = "0.34" # All platforms +``` + +--- + +## 6. ALSA device enumeration changed (Linux) + +**What changed:** Device enumeration now returns all devices from `aplay -L`. v0.16 had a regression that only returned card names, missing all device variants. + +```rust +# v0.16: Only card names ("Loopback", "HDA Intel PCH") +# v0.17: All aplay -L devices (default, hw:CARD=X,DEV=Y, plughw:, front:, surround51:, etc.) +``` + +**Impact:** Many more devices will be enumerated. Device names/IDs will be much more detailed. Update any code that matches specific ALSA device names. + +--- + +## 7. Wasm wee_alloc feature removed + +**What changed:** The optional `wee_alloc` feature was removed for security reasons. + +```rust +# Before (v0.16) +cpal = { version = "0.16", features = ["wasm-bindgen", "wee_alloc"] } + +# After (v0.17) +cpal = { version = "0.17", features = ["wasm-bindgen"] } +``` + +--- + +## Notable Non-Breaking Improvements + +v0.17 also includes significant improvements that don't require code changes: + +- **Stable device IDs:** New `device.id()` returns persistent device identifiers that survive reboots/reconnections. Use `host.device_by_id()` to reliably select saved devices. +- **Streams are Send+Sync everywhere:** All platforms now support moving/sharing streams across threads +- **24-bit sample formats:** Added `I24`/`U24` support on ALSA, CoreAudio, WASAPI, ASIO +- **Custom host support:** Implement your own `Host`/`Device`/`Stream` for proprietary platforms +- **WebAudio AudioWorklet:** Lower latency web audio backend when Wasm atomics are enabled +- **Predictable buffer sizes:** CoreAudio and AAudio now ensure consistent callback buffer sizes +- **Expanded sample rate support:** ALSA supports 12, 24, 352.8, 384, 705.6, and 768 kHz +- **WASAPI advanced interop:** Exposed `IMMDevice` for Windows COM interop scenarios +- **Platform improvements:** macOS loopback recording (14.6+), better ALSA performance, improved timestamp accuracy, iOS AVAudioSession integration, JACK on all platforms + +See [CHANGELOG.md](CHANGELOG.md) for complete details and [examples/](examples/) for updated usage patterns. + +--- + +## Getting Help + +- Full details: [CHANGELOG.md](CHANGELOG.md) +- Examples: [examples/](examples/) +- Issues: https://github.com/RustAudio/cpal/issues From 448fa271bd89c60e441e4d8aa80dceb65c74f4a0 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Mon, 8 Dec 2025 22:20:28 +0100 Subject: [PATCH 2/3] docs: fix UPGRADING.md code block languages and bullets --- UPGRADING.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index de8fcc98a..3b10414e2 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -137,7 +137,7 @@ match device.build_output_stream(&config, data_fn, err_fn, None) { Update these dependencies if you use them directly: -```rust +```toml [dependencies] cpal = "0.17" @@ -153,10 +153,8 @@ audio_thread_priority = "0.34" # All platforms **What changed:** Device enumeration now returns all devices from `aplay -L`. v0.16 had a regression that only returned card names, missing all device variants. -```rust -# v0.16: Only card names ("Loopback", "HDA Intel PCH") -# v0.17: All aplay -L devices (default, hw:CARD=X,DEV=Y, plughw:, front:, surround51:, etc.) -``` +* v0.16: Only card names ("Loopback", "HDA Intel PCH") +* v0.17: All aplay -L devices (default, hw:CARD=X,DEV=Y, plughw:, front:, surround51:, etc.) **Impact:** Many more devices will be enumerated. Device names/IDs will be much more detailed. Update any code that matches specific ALSA device names. @@ -166,7 +164,7 @@ audio_thread_priority = "0.34" # All platforms **What changed:** The optional `wee_alloc` feature was removed for security reasons. -```rust +```toml # Before (v0.16) cpal = { version = "0.16", features = ["wasm-bindgen", "wee_alloc"] } From 8e3fe8b5fc78053947ad583130009707cd671c59 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Sat, 20 Dec 2025 19:55:57 +0100 Subject: [PATCH 3/3] chore: prepare release v0.17.0 and bump asio-sys to 0.2.4 --- CHANGELOG.md | 4 ++-- UPGRADING.md | 17 ++++++++--------- asio-sys/CHANGELOG.md | 2 +- asio-sys/Cargo.toml | 5 ++--- 4 files changed, 13 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 392ea0624..975abbdf7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.17.0] - 2025-12-20 ### Added @@ -1017,7 +1017,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Initial commit. -[unreleased]: https://github.com/RustAudio/cpal/compare/v0.16.0...HEAD +[0.17.0]: https://github.com/RustAudio/cpal/compare/v0.16.0...v0.17.0 [0.16.0]: https://github.com/RustAudio/cpal/compare/v0.15.3...v0.16.0 [0.15.3]: https://github.com/RustAudio/cpal/compare/v0.15.2...v0.15.3 [0.15.2]: https://github.com/RustAudio/cpal/compare/v0.15.1...v0.15.2 diff --git a/UPGRADING.md b/UPGRADING.md index 3b10414e2..a5b61dfb4 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -92,9 +92,9 @@ let stream_clone = Arc::clone(&stream); **What changed:** `BufferSize::Default` now defers to the audio host/device defaults instead of applying cpal's opinionated defaults. **Impact:** Buffer sizes may differ from v0.16, affecting latency characteristics: -- **Lower latency** in most cases (hosts typically choose sensible defaults) -- **May underrun** on resource-constrained systems previously relying on larger cpal defaults -- **Better integration** with system audio configuration (e.g., PulseAudio, PipeWire, JACK) +- **Latency will vary** based on host/device defaults (which may be lower, higher, or similar) +- **May underrun or have different latency** depending on what the host chooses +- **Better integration** with system audio configuration: cpal now respects configured settings instead of imposing its own buffers. For example, on ALSA, PipeWire quantum settings (via the pipewire-alsa device) are now honored instead of being overridden. **Migration:** If you experience underruns or need specific latency, use `BufferSize::Fixed(size)` instead of relying on defaults. @@ -102,11 +102,11 @@ let stream_clone = Arc::clone(&stream); - **ALSA:** Previously used cpal's hardcoded 25ms periods / 100ms buffer, now uses device defaults - **All platforms:** Default buffer sizes now match what the host audio system expects -### BufferSize::Fixed validation stricter +### BufferSize::Fixed validation changes -**What changed:** Several backends now reject invalid `BufferSize::Fixed` requests instead of silently adjusting: +**What changed:** Several backends now have different validation behavior for `BufferSize::Fixed`: -- **ALSA:** Validates against hardware constraints (was: rounded to nearest) +- **ALSA:** Now uses `set_buffer_size_near()` for improved hardware compatibility with devices requiring byte-alignment, power-of-two sizes, or other alignment constraints (was: exact size via `set_buffer_size()`, which would reject unsupported sizes) - **JACK:** Must exactly match server buffer size (was: silently ignored) - **Emscripten/WebAudio:** Validates min/max range - **ASIO:** Stricter lower bound validation @@ -143,7 +143,7 @@ cpal = "0.17" # Platform-specific (if used directly): alsa = "0.10" # Linux only -windows = { version = ">=0.58, <=0.62" } # Windows only +windows = { version = ">=0.59, <=0.62" } # Windows only audio_thread_priority = "0.34" # All platforms ``` @@ -182,11 +182,10 @@ v0.17 also includes significant improvements that don't require code changes: - **Streams are Send+Sync everywhere:** All platforms now support moving/sharing streams across threads - **24-bit sample formats:** Added `I24`/`U24` support on ALSA, CoreAudio, WASAPI, ASIO - **Custom host support:** Implement your own `Host`/`Device`/`Stream` for proprietary platforms -- **WebAudio AudioWorklet:** Lower latency web audio backend when Wasm atomics are enabled - **Predictable buffer sizes:** CoreAudio and AAudio now ensure consistent callback buffer sizes - **Expanded sample rate support:** ALSA supports 12, 24, 352.8, 384, 705.6, and 768 kHz - **WASAPI advanced interop:** Exposed `IMMDevice` for Windows COM interop scenarios -- **Platform improvements:** macOS loopback recording (14.6+), better ALSA performance, improved timestamp accuracy, iOS AVAudioSession integration, JACK on all platforms +- **Platform improvements:** macOS loopback recording (14.6+), improved ALSA audio callback performance, improved timestamp accuracy, iOS AVAudioSession integration, JACK on all platforms See [CHANGELOG.md](CHANGELOG.md) for complete details and [examples/](examples/) for updated usage patterns. diff --git a/asio-sys/CHANGELOG.md b/asio-sys/CHANGELOG.md index d7a4e895c..ad78f2d9f 100644 --- a/asio-sys/CHANGELOG.md +++ b/asio-sys/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.2.4] - 2025-12-20 ### Fixed - Fixed docs.rs documentation build by generating stub bindings when building for docs.rs diff --git a/asio-sys/Cargo.toml b/asio-sys/Cargo.toml index e863a50a2..702b9f7dc 100644 --- a/asio-sys/Cargo.toml +++ b/asio-sys/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "asio-sys" -version = "0.2.3" +version = "0.2.4" authors = ["Tom Gowan "] description = "Low-level interface and binding generation for the steinberg ASIO SDK." repository = "https://github.com/RustAudio/cpal/" @@ -8,8 +8,7 @@ documentation = "https://docs.rs/asio-sys" license = "Apache-2.0" keywords = ["audio", "sound", "asio", "steinberg"] edition = "2021" -rust-version = "1.70" -build = "build.rs" +rust-version = "1.82" [build-dependencies] bindgen = "0.72"