|
| 1 | +# Upgrading from v0.16 to v0.17 |
| 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 | +- [ ] Replace `SampleRate(n)` with plain `n` values |
| 8 | +- [ ] Update `windows` crate to >= 0.59, <= 0.62 (Windows only) |
| 9 | +- [ ] Update `alsa` crate to 0.10 (Linux only) |
| 10 | +- [ ] Remove `wee_alloc` feature from Wasm builds (if used) |
| 11 | +- [ ] Wrap CoreAudio streams in `Arc` if you were cloning them (macOS only) |
| 12 | +- [ ] Handle `BuildStreamError::StreamConfigNotSupported` for `BufferSize::Fixed` (JACK, strict validation) |
| 13 | +- [ ] Update device name matching if using ALSA (Linux only) |
| 14 | + |
| 15 | +**Recommended migrations:** |
| 16 | +- [ ] Replace deprecated `device.name()` calls with `device.description()` or `device.id()` |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## 1. SampleRate is now a u32 type alias |
| 21 | + |
| 22 | +**What changed:** `SampleRate` changed from a struct to a `u32` type alias. |
| 23 | + |
| 24 | +```rust |
| 25 | +// Before (v0.16) |
| 26 | +use cpal::SampleRate; |
| 27 | +let config = StreamConfig { |
| 28 | + channels: 2, |
| 29 | + sample_rate: SampleRate(44100), |
| 30 | + buffer_size: BufferSize::Default, |
| 31 | +}; |
| 32 | + |
| 33 | +// After (v0.17) |
| 34 | +let config = StreamConfig { |
| 35 | + channels: 2, |
| 36 | + sample_rate: 44100, |
| 37 | + buffer_size: BufferSize::Default, |
| 38 | +}; |
| 39 | +``` |
| 40 | + |
| 41 | +**Impact:** Remove `SampleRate()` constructor calls. The type is now just `u32`, so use integer literals or variables directly. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## 2. Device::name() deprecated (soft deprecation) |
| 46 | + |
| 47 | +**What changed:** `Device::name()` is deprecated in favor of `id()` and `description()`. |
| 48 | + |
| 49 | +```rust |
| 50 | +// Old (still works but shows deprecation warning) |
| 51 | +let name = device.name()?; |
| 52 | + |
| 53 | +// New: For user-facing display |
| 54 | +let desc = device.description()?; |
| 55 | +println!("Device: {}", desc); // or desc.name() for just the name |
| 56 | + |
| 57 | +// New: For stable identification and persistence |
| 58 | +let id = device.id()?; |
| 59 | +let id_string = id.to_string(); // Save this |
| 60 | +// Later... |
| 61 | +let device = host.device_by_id(&id_string.parse()?)?; |
| 62 | +``` |
| 63 | + |
| 64 | +**Impact:** Deprecation warnings only. The old API still works in v0.17. Update when convenient to prepare for future versions. |
| 65 | + |
| 66 | +**Why:** Separates stable device identification (`id()`) from human-readable names (`description()`). |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## 3. CoreAudio Stream no longer Clone (macOS) |
| 71 | + |
| 72 | +**What changed:** On macOS, `Stream` no longer implements `Clone`. Use `Arc` instead. |
| 73 | + |
| 74 | +```rust |
| 75 | +// Before (v0.16) - macOS only |
| 76 | +let stream = device.build_output_stream(&config, data_fn, err_fn, None)?; |
| 77 | +let stream_clone = stream.clone(); |
| 78 | + |
| 79 | +// After (v0.17) - all platforms |
| 80 | +let stream = Arc::new(device.build_output_stream(&config, data_fn, err_fn, None)?); |
| 81 | +let stream_clone = Arc::clone(&stream); |
| 82 | +``` |
| 83 | + |
| 84 | +**Why:** Removed as part of making `Stream` implement `Send` on macOS. |
| 85 | + |
| 86 | +--- |
| 87 | + |
| 88 | +## 4. BufferSize behavior changes |
| 89 | + |
| 90 | +### BufferSize::Default now uses host defaults |
| 91 | + |
| 92 | +**What changed:** `BufferSize::Default` now defers to the audio host/device defaults instead of applying cpal's opinionated defaults. |
| 93 | + |
| 94 | +**Impact:** Buffer sizes may differ from v0.16, affecting latency characteristics: |
| 95 | +- **Latency will vary** based on host/device defaults (which may be lower, higher, or similar) |
| 96 | +- **May underrun or have different latency** depending on what the host chooses |
| 97 | +- **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. |
| 98 | + |
| 99 | +**Migration:** If you experience underruns or need specific latency, use `BufferSize::Fixed(size)` instead of relying on defaults. |
| 100 | + |
| 101 | +**Platform-specific notes:** |
| 102 | +- **ALSA:** Previously used cpal's hardcoded 25ms periods / 100ms buffer, now uses device defaults |
| 103 | +- **All platforms:** Default buffer sizes now match what the host audio system expects |
| 104 | + |
| 105 | +### BufferSize::Fixed validation changes |
| 106 | + |
| 107 | +**What changed:** Several backends now have different validation behavior for `BufferSize::Fixed`: |
| 108 | + |
| 109 | +- **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) |
| 110 | +- **JACK:** Must exactly match server buffer size (was: silently ignored) |
| 111 | +- **Emscripten/WebAudio:** Validates min/max range |
| 112 | +- **ASIO:** Stricter lower bound validation |
| 113 | + |
| 114 | +```rust |
| 115 | +// Handle validation errors |
| 116 | +let mut config = StreamConfig { |
| 117 | + channels: 2, |
| 118 | + sample_rate: 44100, |
| 119 | + buffer_size: BufferSize::Fixed(512), |
| 120 | +}; |
| 121 | + |
| 122 | +match device.build_output_stream(&config, data_fn, err_fn, None) { |
| 123 | + Ok(stream) => { /* success */ }, |
| 124 | + Err(BuildStreamError::StreamConfigNotSupported) => { |
| 125 | + config.buffer_size = BufferSize::Default; // Fallback |
| 126 | + device.build_output_stream(&config, data_fn, err_fn, None)? |
| 127 | + }, |
| 128 | + Err(e) => return Err(e), |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +**JACK users:** Use `BufferSize::Default` to automatically match the server's configured size. |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +## 5. Dependency updates |
| 137 | + |
| 138 | +Update these dependencies if you use them directly: |
| 139 | + |
| 140 | +```toml |
| 141 | +[dependencies] |
| 142 | +cpal = "0.17" |
| 143 | + |
| 144 | +# Platform-specific (if used directly): |
| 145 | +alsa = "0.10" # Linux only |
| 146 | +windows = { version = ">=0.59, <=0.62" } # Windows only |
| 147 | +audio_thread_priority = "0.34" # All platforms |
| 148 | +``` |
| 149 | + |
| 150 | +--- |
| 151 | + |
| 152 | +## 6. ALSA device enumeration changed (Linux) |
| 153 | + |
| 154 | +**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. |
| 155 | + |
| 156 | +* v0.16: Only card names ("Loopback", "HDA Intel PCH") |
| 157 | +* v0.17: All aplay -L devices (default, hw:CARD=X,DEV=Y, plughw:, front:, surround51:, etc.) |
| 158 | + |
| 159 | +**Impact:** Many more devices will be enumerated. Device names/IDs will be much more detailed. Update any code that matches specific ALSA device names. |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## 7. Wasm wee_alloc feature removed |
| 164 | + |
| 165 | +**What changed:** The optional `wee_alloc` feature was removed for security reasons. |
| 166 | + |
| 167 | +```toml |
| 168 | +# Before (v0.16) |
| 169 | +cpal = { version = "0.16", features = ["wasm-bindgen", "wee_alloc"] } |
| 170 | + |
| 171 | +# After (v0.17) |
| 172 | +cpal = { version = "0.17", features = ["wasm-bindgen"] } |
| 173 | +``` |
| 174 | + |
| 175 | +--- |
| 176 | + |
| 177 | +## Notable Non-Breaking Improvements |
| 178 | + |
| 179 | +v0.17 also includes significant improvements that don't require code changes: |
| 180 | + |
| 181 | +- **Stable device IDs:** New `device.id()` returns persistent device identifiers that survive reboots/reconnections. Use `host.device_by_id()` to reliably select saved devices. |
| 182 | +- **Streams are Send+Sync everywhere:** All platforms now support moving/sharing streams across threads |
| 183 | +- **24-bit sample formats:** Added `I24`/`U24` support on ALSA, CoreAudio, WASAPI, ASIO |
| 184 | +- **Custom host support:** Implement your own `Host`/`Device`/`Stream` for proprietary platforms |
| 185 | +- **Predictable buffer sizes:** CoreAudio and AAudio now ensure consistent callback buffer sizes |
| 186 | +- **Expanded sample rate support:** ALSA supports 12, 24, 352.8, 384, 705.6, and 768 kHz |
| 187 | +- **WASAPI advanced interop:** Exposed `IMMDevice` for Windows COM interop scenarios |
| 188 | +- **Platform improvements:** macOS loopback recording (14.6+), improved ALSA audio callback performance, improved timestamp accuracy, iOS AVAudioSession integration, JACK on all platforms |
| 189 | + |
| 190 | +See [CHANGELOG.md](CHANGELOG.md) for complete details and [examples/](examples/) for updated usage patterns. |
| 191 | + |
| 192 | +--- |
| 193 | + |
| 194 | +## Getting Help |
| 195 | + |
| 196 | +- Full details: [CHANGELOG.md](CHANGELOG.md) |
| 197 | +- Examples: [examples/](examples/) |
| 198 | +- Issues: https://github.com/RustAudio/cpal/issues |
0 commit comments