| Lift freeq's AV media plane out of sleek 90f8b89 nandi 19d ago | 1 | # Upgrading from v0.17 to v0.18 |
| 2 | |
| 3 | This guide covers breaking changes requiring code updates. See [CHANGELOG.md](CHANGELOG.md) for the complete list of changes and improvements. |
| 4 | |
| 5 | ## Breaking Changes Checklist |
| 6 | |
| 7 | - [ ] Add wildcard arms to exhaustive `match` expressions on cpal error enums |
| 8 | - [ ] Optionally handle the new `DeviceBusy` variant for retryable device errors |
| 9 | - [ ] Change `build_*_stream` call sites to pass `StreamConfig` by value (drop the `&`) |
| 10 | - [ ] For custom hosts, change `DeviceTrait` implementations to accept `StreamConfig` by value. |
| 11 | |
| 12 | ## 1. Error enums are now `#[non_exhaustive]` |
| 13 | |
| 14 | **What changed:** Public error enums in `cpal` are now marked `#[non_exhaustive]`. |
| 15 | |
| 16 | ```rust |
| 17 | // Before (v0.17) |
| 18 | match device.default_output_config() { |
| 19 | Ok(config) => config, |
| 20 | Err(DefaultStreamConfigError::DeviceNotAvailable) => panic!("device gone"), |
| 21 | Err(DefaultStreamConfigError::StreamTypeNotSupported) => panic!("unsupported"), |
| 22 | Err(DefaultStreamConfigError::BackendSpecific { err }) => panic!("{err}"), |
| 23 | } |
| 24 | |
| 25 | // After (v0.18) |
| 26 | loop { |
| 27 | match device.default_output_config() { |
| 28 | Ok(config) => break config, |
| 29 | Err(DefaultStreamConfigError::DeviceBusy) => { |
| 30 | std::thread::sleep(std::time::Duration::from_millis(100)); |
| 31 | } |
| 32 | Err(DefaultStreamConfigError::DeviceNotAvailable) => panic!("device gone"), |
| 33 | Err(DefaultStreamConfigError::StreamTypeNotSupported) => panic!("unsupported"), |
| 34 | Err(DefaultStreamConfigError::BackendSpecific { err }) => panic!("{err}"), |
| 35 | Err(_) => panic!("unknown error"), |
| 36 | } |
| 37 | } |
| 38 | ``` |
| 39 | |
| 40 | **Why:** This lets cpal add new variants in future minor releases without a SemVer-breaking change. |
| 41 | |
| 42 | ## 2. New `DeviceBusy` variant |
| 43 | |
| 44 | **What changed:** On ALSA, `EBUSY`/`EAGAIN` errors from device open calls now produce `DeviceBusy` instead of `DeviceNotAvailable`. This may be added to other hosts in the future. |
| 45 | |
| 46 | **Why:** Unlike `DeviceNotAvailable` (device is gone), `DeviceBusy` signals a transient condition. Retrying after a short delay may succeed, as shown in the example above. |
| 47 | |
| 48 | ## 3. `StreamConfig` is now passed by value |
| 49 | |
| 50 | **What changed:** `StreamConfig` now implements `Copy`, and all `DeviceTrait` stream-building methods accept it by value. |
| 51 | |
| 52 | ```rust |
| 53 | // Before (v0.17) |
| 54 | let stream = device.build_output_stream(&config, data_fn, err_fn, None)?; |
| 55 | |
| 56 | // After (v0.18) |
| 57 | let stream = device.build_output_stream(config, data_fn, err_fn, None)?; |
| 58 | ``` |
| 59 | |
| 60 | **Impact:** Remove the `&` at every `build_*_stream` call site. Because `StreamConfig` is `Copy`, you can reuse the same binding across multiple calls without cloning. |
| 61 | |
| 62 | If you implement `DeviceTrait` on your own type (via the `custom` feature), update your `build_input_stream_raw` and `build_output_stream_raw` signatures from `config: &StreamConfig` to `config: StreamConfig`. Any `config.clone()` calls before `move` closures can also be removed. |
| 63 | |
| 64 | --- |
| 65 | |
| 66 | # Upgrading from v0.16 to v0.17 |
| 67 | |
| 68 | ## Breaking Changes Checklist |
| 69 | |
| 70 | - [ ] Replace `SampleRate(n)` with plain `n` values |
| 71 | - [ ] Update `windows` crate to >= 0.59, <= 0.62 (Windows only) |
| 72 | - [ ] Update `alsa` crate to 0.11 (Linux only) |
| 73 | - [ ] Remove `wee_alloc` feature from Wasm builds (if used) |
| 74 | - [ ] Wrap CoreAudio streams in `Arc` if you were cloning them (macOS only) |
| 75 | - [ ] Handle `BuildStreamError::StreamConfigNotSupported` for `BufferSize::Fixed` (JACK, strict validation) |
| 76 | - [ ] Update device name matching if using ALSA (Linux only) |
| 77 | |
| 78 | **Recommended migrations:** |
| 79 | - [ ] Replace deprecated `device.name()` calls with `device.description()` or `device.id()` |
| 80 | |
| 81 | --- |
| 82 | |
| 83 | ## 1. SampleRate is now a u32 type alias |
| 84 | |
| 85 | **What changed:** `SampleRate` changed from a struct to a `u32` type alias. |
| 86 | |
| 87 | ```rust |
| 88 | // Before (v0.16) |
| 89 | use cpal::SampleRate; |
| 90 | let config = StreamConfig { |
| 91 | channels: 2, |
| 92 | sample_rate: SampleRate(44100), |
| 93 | buffer_size: BufferSize::Default, |
| 94 | }; |
| 95 | |
| 96 | // After (v0.17) |
| 97 | let config = StreamConfig { |
| 98 | channels: 2, |
| 99 | sample_rate: 44100, |
| 100 | buffer_size: BufferSize::Default, |
| 101 | }; |
| 102 | ``` |
| 103 | |
| 104 | **Impact:** Remove `SampleRate()` constructor calls. The type is now just `u32`, so use integer literals or variables directly. |
| 105 | |
| 106 | ## 2. Device::name() deprecated (soft deprecation) |
| 107 | |
| 108 | **What changed:** `Device::name()` is deprecated in favor of `id()` and `description()`. |
| 109 | |
| 110 | ```rust |
| 111 | // Old (still works but shows deprecation warning) |
| 112 | let name = device.name()?; |
| 113 | |
| 114 | // New: For user-facing display |
| 115 | let desc = device.description()?; |
| 116 | println!("Device: {}", desc); // or desc.name() for just the name |
| 117 | |
| 118 | // New: For stable identification and persistence |
| 119 | let id = device.id()?; |
| 120 | let id_string = id.to_string(); // Save this |
| 121 | // Later... |
| 122 | let device = host.device_by_id(&id_string.parse()?)?; |
| 123 | ``` |
| 124 | |
| 125 | **Impact:** Deprecation warnings only. The old API still works in v0.17. Update when convenient to prepare for future versions. |
| 126 | |
| 127 | **Why:** Separates stable device identification (`id()`) from human-readable names (`description()`). |
| 128 | |
| 129 | ## 3. CoreAudio Stream no longer Clone (macOS) |
| 130 | |
| 131 | **What changed:** On macOS, `Stream` no longer implements `Clone`. Use `Arc` instead. |
| 132 | |
| 133 | ```rust |
| 134 | // Before (v0.16) - macOS only |
| 135 | let stream = device.build_output_stream(&config, data_fn, err_fn, None)?; |
| 136 | let stream_clone = stream.clone(); |
| 137 | |
| 138 | // After (v0.17) - all platforms |
| 139 | let stream = Arc::new(device.build_output_stream(&config, data_fn, err_fn, None)?); |
| 140 | let stream_clone = Arc::clone(&stream); |
| 141 | ``` |
| 142 | |
| 143 | **Why:** Removed as part of making `Stream` implement `Send` on macOS. |
| 144 | |
| 145 | ## 4. BufferSize behavior changes |
| 146 | |
| 147 | ### BufferSize::Default now uses host defaults |
| 148 | |
| 149 | **What changed:** `BufferSize::Default` now defers to the audio host/device defaults instead of applying cpal's opinionated defaults. |
| 150 | |
| 151 | **Impact:** Buffer sizes may differ from v0.16, affecting latency characteristics: |
| 152 | - **Latency will vary** based on host/device defaults (which may be lower, higher, or similar) |
| 153 | - **May underrun or have different latency** depending on what the host chooses |
| 154 | - **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. |
| 155 | |
| 156 | **Migration:** If you experience underruns, fast-forwarding behavior or need specific latency, use `BufferSize::Fixed(size)` instead of relying on possibly misconfigured system defaults. |
| 157 | |
| 158 | **Platform-specific notes:** |
| 159 | - **ALSA:** Previously used cpal's hardcoded 25ms periods / 100ms buffer, now uses device defaults |
| 160 | - **All platforms:** Default buffer sizes now match what the host audio system expects |
| 161 | |
| 162 | ### BufferSize::Fixed validation changes |
| 163 | |
| 164 | **What changed:** Several backends now have different validation behavior for `BufferSize::Fixed`: |
| 165 | |
| 166 | - **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) |
| 167 | - **JACK:** Must exactly match server buffer size (was: silently ignored) |
| 168 | - **Emscripten/WebAudio:** Validates min/max range |
| 169 | - **ASIO:** Stricter lower bound validation |
| 170 | |
| 171 | ```rust |
| 172 | // Handle validation errors |
| 173 | let mut config = StreamConfig { |
| 174 | channels: 2, |
| 175 | sample_rate: 44100, |
| 176 | buffer_size: BufferSize::Fixed(512), |
| 177 | }; |
| 178 | |
| 179 | match device.build_output_stream(&config, data_fn, err_fn, None) { |
| 180 | Ok(stream) => { /* success */ }, |
| 181 | Err(BuildStreamError::StreamConfigNotSupported) => { |
| 182 | config.buffer_size = BufferSize::Default; // Fallback |
| 183 | device.build_output_stream(&config, data_fn, err_fn, None)? |
| 184 | }, |
| 185 | Err(e) => return Err(e), |
| 186 | } |
| 187 | ``` |
| 188 | |
| 189 | **JACK users:** Use `BufferSize::Default` to automatically match the server's configured size. |
| 190 | |
| 191 | ## 5. Dependency updates |
| 192 | |
| 193 | Update these dependencies if you use them directly: |
| 194 | |
| 195 | ```toml |
| 196 | [dependencies] |
| 197 | cpal = "0.17" |
| 198 | |
| 199 | # Platform-specific (if used directly): |
| 200 | alsa = "0.11" # Linux only |
| 201 | windows = { version = ">=0.59, <=0.62" } # Windows only |
| 202 | audio_thread_priority = "0.34" # All platforms |
| 203 | ``` |
| 204 | |
| 205 | ## 6. ALSA device enumeration changed (Linux) |
| 206 | |
| 207 | **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. |
| 208 | |
| 209 | * v0.16: Only card names ("Loopback", "HDA Intel PCH") |
| 210 | * v0.17: All aplay -L devices (default, hw:CARD=X,DEV=Y, plughw:, front:, surround51:, etc.) |
| 211 | |
| 212 | **Impact:** Many more devices will be enumerated. Device names/IDs will be much more detailed. Update any code that matches specific ALSA device names. |
| 213 | |
| 214 | ## 7. Wasm wee_alloc feature removed |
| 215 | |
| 216 | **What changed:** The optional `wee_alloc` feature was removed for security reasons. |
| 217 | |
| 218 | ```toml |
| 219 | # Before (v0.16) |
| 220 | cpal = { version = "0.16", features = ["wasm-bindgen", "wee_alloc"] } |
| 221 | |
| 222 | # After (v0.17) |
| 223 | cpal = { version = "0.17", features = ["wasm-bindgen"] } |
| 224 | ``` |
| 225 | |
| 226 | ## Notable Non-Breaking Improvements |
| 227 | |
| 228 | v0.17 also includes significant improvements that don't require code changes: |
| 229 | |
| 230 | - **Stable device IDs:** New `device.id()` returns persistent device identifiers that survive reboots/reconnections. Use `host.device_by_id()` to reliably select saved devices. |
| 231 | - **Streams are Send+Sync everywhere:** All platforms now support moving/sharing streams across threads |
| 232 | - **24-bit sample formats:** Added `I24`/`U24` support on ALSA, CoreAudio, WASAPI, ASIO |
| 233 | - **Custom host support:** Implement your own `Host`/`Device`/`Stream` for proprietary platforms |
| 234 | - **Predictable buffer sizes:** CoreAudio and AAudio now ensure consistent callback buffer sizes |
| 235 | - **Expanded sample rate support:** ALSA supports 12, 24, 352.8, 384, 705.6, and 768 kHz |
| 236 | - **WASAPI advanced interop:** Exposed `IMMDevice` for Windows COM interop scenarios |
| 237 | - **Platform improvements:** macOS loopback recording (14.6+), improved ALSA audio callback performance, improved timestamp accuracy, iOS AVAudioSession integration, JACK on all platforms |
| 238 | |
| 239 | See [CHANGELOG.md](CHANGELOG.md) for complete details and [examples/](examples/) for updated usage patterns. |
| 240 | |
| 241 | --- |
| 242 | |
| 243 | ## Getting Help |
| 244 | |
| 245 | - Full details: [CHANGELOG.md](CHANGELOG.md) |
| 246 | - Examples: [examples/](examples/) |
| 247 | - Issues: https://github.com/RustAudio/cpal/issues |