Merge branch 'master' of https://github.com/RustAudio/cpal

Author: kettle11

.github/workflows/cpal.yml

@@ -60,7 +60,7 @@ jobs:
 
   cargo-publish:
     if: github.event_name == 'release'
-    needs: [test-native, test-cross, test-wasm, test-android, test-ios]
+    needs: [test-native, test-cross, test-wasm, test-android, test-ios, test-windows-versions]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -196,15 +196,9 @@ jobs:
         with:
           tool: cross
 
-      - name: Check without features
-        run: cross check --target ${{ matrix.target }} --workspace --no-default-features --verbose
-
       - name: Test without features
         run: cross test --target ${{ matrix.target }} --workspace --no-default-features --verbose
 
-      - name: Check all features
-        run: cross check --target ${{ matrix.target }} --workspace --all-features --verbose
-
       - name: Test all features
         run: cross test --target ${{ matrix.target }} --workspace --all-features --verbose
 
@@ -318,3 +312,51 @@ jobs:
 
       - name: Build iOS example
         run: cd examples/ios-feedback && xcodebuild -scheme cpal-ios-example -configuration Debug -derivedDataPath build -sdk iphonesimulator
+
+  # Windows crate compatibility testing
+  test-windows-versions:
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - windows-version: "0.59.0"
+          - windows-version: "0.60.0"
+          - windows-version: "0.61.3"
+          # Skip 0.62.x since we already test current version in test-native
+    name: test-windows-v${{ matrix.windows-version }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install dependencies
+        run: |
+          choco install llvm
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: windows-v${{ matrix.windows-version }}
+
+      - name: Lock windows crate to specific version
+        shell: bash
+        run: |
+          # Generate Cargo.lock first if it doesn't exist
+          cargo generate-lockfile
+
+          # Use cargo update --precise to lock the windows crate to a specific version
+          cargo update --precise ${{ matrix.windows-version }} windows
+
+          # Verify the version was locked correctly
+          echo "Locked windows crate version:"
+          cargo tree | grep "windows v" || echo "Windows crate not found in dependency tree"
+
+          # Also check Cargo.lock
+          echo "Cargo.lock entry:"
+          grep -A 5 "name = \"windows\"" Cargo.lock | head -10
+
+      - name: Check WASAPI with windows v${{ matrix.windows-version }}
+        run: |
+          cargo check --verbose

CHANGELOG.md

@@ -14,6 +14,7 @@
 - CI: Fix cargo publish to trigger on GitHub releases instead of every master commit.
 - CI: Replace cargo install commands with cached tool installation for faster builds.
 - CI: Update actions to latest versions (checkout@v5, rust-cache@v2).
+- CI: Verify compatibility with windows crates since v0.58.
 - 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.
 - CoreAudio: Add `i8`, `i32` and `I24` sample format support (24-bit samples stored in 4 bytes).
@@ -24,7 +25,7 @@
 - iOS: Fix example by properly activating audio session.
 - WASAPI: Expose `IMMDevice` from WASAPI host Device.
 - WASAPI: Add `I24` and `U24` sample format support (24-bit samples stored in 4 bytes).
-- WASAPI: Update `windows` to 0.62.
+- WASAPI: Update `windows` to >= 0.58, <= 0.62.
 - Wasm: Removed optional `wee-alloc` feature for security reasons.
 
 # Version 0.16.0 (2025-06-07)

Cargo.toml

@@ -38,8 +38,11 @@ hound = "3.5"
 ringbuf = "0.4.8"
 clap = { version = "4.5", features = ["derive"] }
 
+# Support a range of versions in order to avoid duplication of this crate. Make sure to test all
+# versions when bumping to a new release, and only increase the minimum when absolutely necessary.
+# When updating this, also update the "windows-version" matrix in the CI workflow.
 [target.'cfg(target_os = "windows")'.dependencies]
-windows = { version = "0.62", features = [
+windows = { version = ">=0.58, <=0.62", features = [
     "Win32_Media_Audio",
     "Win32_Foundation",
     "Win32_Devices_Properties",

src/host/alsa/mod.rs

@@ -22,8 +22,8 @@ use crate::{
     SupportedStreamConfigRange, SupportedStreamConfigsError, I24, U24,
 };
 
-// ALSA Latency Model and Period Configuration
-// ===========================================
+// ALSA Buffer Size Behavior
+// =========================
 //
 // ## ALSA Latency Model
 //
@@ -35,34 +35,20 @@ use crate::{
 // period worth of data has been consumed by hardware, ALSA triggers a callback to refill
 // that period in the software buffer.
 //
-// **Effective Latency**: With N periods total, (N-1) periods contain "latency" (data waiting
-// to be played), while 1 period is always being transferred to/from hardware. Therefore:
-// `effective_latency = (total_periods - 1) × period_size`
+// ## BufferSize::Fixed Behavior
 //
-// **User Expectation**: When user requests buffer size X, they expect ~X frames of latency,
-// not ~X frames of total buffering. Our goal is: `period_size × (periods - 1) ≈ user_buffer`
+// When `BufferSize::Fixed(x)` is specified, cpal attempts to configure the period size
+// to approximately `x` frames to achieve the requested callback size. However, the
+// actual callback size may differ from the request:
 //
-// ## Period Configuration Strategy
+// - ALSA may round the period size to hardware-supported values
+// - Different devices have different period size constraints
+// - The callback size is not guaranteed to exactly match the request
+// - If the requested size cannot be accommodated, ALSA will choose the nearest
+//   supported configuration
 //
-// **Goal**: Achieve user-requested latency with precision and device compatibility.
-//
-// **Step 1 - Query Device Limits**: Check the device's maximum period size to determine
-// which approaches are viable.
-//
-// **Step 2 - Prefer Double Buffering**: When user_buffer ≤ max_period_size, configure
-// 2 periods of user_buffer size each. This is the simplest configuration with direct
-// period size control.
-//
-// **Step 3 - Multi-Period When Required**: When user_buffer > max_period_size, calculate
-// the minimum periods needed and distribute the latency across them. This maintains
-// precision while respecting hardware constraints.
-//
-// **Step 4 - Fallback for Compatibility**: If precise approaches fail device validation,
-// use buffer-size-only configuration. Accept latency deviation to ensure functional audio.
-//
-// **Validation**: Accept exact matches for even period sizes, and ±1 for odd period sizes
-// (due to hardware alignment constraints). Reject results that deviate significantly
-// from the target latency.
+// This mirrors the behavior documented in the cpal API where `BufferSize::Fixed(x)`
+// requests but does not guarantee a specific callback size.
 
 pub type SupportedInputConfigs = VecIntoIter<SupportedStreamConfigRange>;
 pub type SupportedOutputConfigs = VecIntoIter<SupportedStreamConfigRange>;
@@ -945,7 +931,7 @@ fn process_output(
                 error_callback(err.into());
                 continue;
             }
-            Ok(result) if result as usize != stream.period_frames => {
+            Ok(result) if result != stream.period_frames => {
                 let description = format!(
                     "unexpected number of frames written: expected {}, \
                         result {result} (this should never happen)",
@@ -1198,109 +1184,6 @@ fn fill_with_equilibrium(buffer: &mut [u8], sample_format: SampleFormat) {
     }
 }
 
-// Try period configuration with specified period size and count
-fn try_period_configuration(
-    pcm_handle: &alsa::pcm::PCM,
-    hw_params: &alsa::pcm::HwParams,
-    target_period_size: u32,
-    target_periods: u32,
-) -> Option<usize> {
-    hw_params
-        .set_period_size_near(target_period_size as _, alsa::ValueOr::Nearest)
-        .ok()?;
-    hw_params
-        .set_periods(target_periods, alsa::ValueOr::Nearest)
-        .ok()?;
-    pcm_handle.hw_params(hw_params).ok()?;
-
-    let device_period_size = hw_params.get_period_size().ok()? as u32;
-    let device_periods = hw_params.get_periods().ok()? as u32;
-
-    // Period count must be exactly what we requested
-    if device_periods != target_periods {
-        return None;
-    }
-
-    // Period size validation: exact for even, ±1 for odd
-    let period_size_ok = if target_period_size % 2 == 0 {
-        device_period_size == target_period_size
-    } else {
-        let acceptable_range = (target_period_size.saturating_sub(1))..=(target_period_size + 1);
-        acceptable_range.contains(&device_period_size)
-    };
-
-    if period_size_ok {
-        Some(device_period_size as usize)
-    } else {
-        None // Device constraint issue
-    }
-}
-
-// Configure periods based on device capabilities
-fn configure_periods(
-    pcm_handle: &alsa::pcm::PCM,
-    hw_params: &alsa::pcm::HwParams,
-    user_buffer_frames: u32,
-    config: &StreamConfig,
-) -> Result<(), BackendSpecificError> {
-    // Query device maximum period size to determine approach
-    let max_period_size = hw_params
-        .get_period_size_max()
-        .map_err(|_| BackendSpecificError {
-            description: "Could not query device period size limits".to_string(),
-        })? as u32;
-
-    // Approach 1: Double buffering if user buffer fits within device limits
-    if user_buffer_frames <= max_period_size {
-        if let Some(_) = try_period_configuration(&pcm_handle, &hw_params, user_buffer_frames, 2) {
-            return Ok(());
-        }
-    }
-
-    // Approach 2: Multi-period with calculated period count and size
-    if user_buffer_frames > max_period_size {
-        // Calculate minimum periods needed: ceil(user_buffer / max_period_size) + 1
-        let min_periods = (user_buffer_frames + max_period_size - 1) / max_period_size + 1;
-        let target_period_size = user_buffer_frames / std::cmp::max(min_periods - 1, 1);
-
-        if let Some(_) =
-            try_period_configuration(&pcm_handle, &hw_params, target_period_size, min_periods)
-        {
-            return Ok(());
-        }
-    }
-
-    // Approach 3: Fallback - let ALSA choose everything based on buffer size
-    fallback_buffer_size(&pcm_handle, &hw_params, user_buffer_frames, config)
-}
-
-// Fallback: Use ALSA's buffer size approach when period-based approaches fail
-fn fallback_buffer_size(
-    pcm_handle: &alsa::pcm::PCM,
-    base_hw_params: &alsa::pcm::HwParams,
-    user_buffer_frames: u32,
-    config: &StreamConfig,
-) -> Result<(), BackendSpecificError> {
-    // Create fresh hw_params to avoid inheriting period constraints from previous attempts
-    let hw_params = alsa::pcm::HwParams::any(pcm_handle)?;
-    hw_params.set_access(base_hw_params.get_access()?)?;
-    hw_params.set_format(base_hw_params.get_format()?)?;
-    hw_params.set_rate(base_hw_params.get_rate()?, alsa::ValueOr::Nearest)?;
-    hw_params.set_channels(base_hw_params.get_channels()?)?;
-
-    // Only set buffer size - let ALSA choose optimal period size and count
-    hw_params
-        .set_buffer_size_near(user_buffer_frames as _)
-        .map_err(|_| BackendSpecificError {
-            description: format!(
-                "Buffer size '{:?}' is not supported by this backend",
-                config.buffer_size
-            ),
-        })?;
-
-    pcm_handle.hw_params(&hw_params).map_err(Into::into)
-}
-
 fn set_hw_params_from_format(
     pcm_handle: &alsa::pcm::PCM,
     config: &StreamConfig,
@@ -1364,14 +1247,22 @@ fn set_hw_params_from_format(
     hw_params.set_rate(config.sample_rate.0, alsa::ValueOr::Nearest)?;
     hw_params.set_channels(config.channels as u32)?;
 
-    // Smart period configuration: adapt to device capabilities for consistent latency
-    if let BufferSize::Fixed(user_buffer_frames) = config.buffer_size {
-        configure_periods(&pcm_handle, &hw_params, user_buffer_frames, config)?;
-    } else {
-        // Default buffer size - let device choose everything
-        pcm_handle.hw_params(&hw_params)?;
+    // Configure period size based on buffer size request
+    // When BufferSize::Fixed(x) is specified, we request a period size of x frames
+    // to achieve approximately x-sized callbacks. ALSA may adjust this to the nearest
+    // supported value based on hardware constraints.
+    if let BufferSize::Fixed(buffer_frames) = config.buffer_size {
+        hw_params.set_period_size_near(buffer_frames as _, alsa::ValueOr::Nearest)?;
     }
 
+    // We shouldn't fail if the driver isn't happy here.
+    // `default` pcm sometimes fails here, but there's no reason to as we
+    // provide a direction and 2 is strictly the minimum number of periods.
+    let _ = hw_params.set_periods(2, alsa::ValueOr::Greater);
+
+    // Apply hardware parameters
+    pcm_handle.hw_params(&hw_params)?;
+
     Ok(hw_params.can_pause())
 }
 

src/host/wasapi/device.rs

@@ -337,7 +337,7 @@ impl Device {
     /// Ensures that `future_audio_client` contains a `Some` and returns a locked mutex to it.
     fn ensure_future_audio_client(
         &self,
-    ) -> Result<MutexGuard<Option<IAudioClientWrapper>>, windows::core::Error> {
+    ) -> Result<MutexGuard<'_, Option<IAudioClientWrapper>>, windows::core::Error> {
         let mut lock = self.future_audio_client.lock().unwrap();
         if lock.is_some() {
             return Ok(lock);

src/host/wasapi/stream.rs

@@ -345,8 +345,6 @@ fn boost_current_thread_priority(buffer_size: BufferSize, sample_rate: crate::Sa
 
 #[cfg(not(feature = "audio_thread_priority"))]
 fn boost_current_thread_priority(_: BufferSize, _: crate::SampleRate) {
-    use windows::Win32::Foundation::HANDLE;
-
     unsafe {
         let thread_handle = Threading::GetCurrentThread();
 

src/lib.rs

@@ -220,22 +220,36 @@ where
 /// one frame contains two samples (left and right channels).
 pub type FrameCount = u32;
 
-/// The buffer size controls the latency between your application and the audio hardware.
+/// The buffer size requests the callback size for audio streams.
 ///
-/// This controls the size of the software buffer that cpal uses to transfer audio
-/// data between your application and the hardware device. This is distinct from
-/// end-to-end audio latency, which includes additional processing delays.
+/// This controls the approximate size of the audio buffer passed to your callback.
+/// The actual callback size depends on the host/platform implementation and hardware
+/// constraints, and may differ from or vary around the requested size.
 ///
-/// [`Default`] uses the host's default buffer size, which may be surprisingly
-/// large, leading to higher buffering latency. If low latency is desired,
-/// [`Fixed(FrameCount)`] should be used in accordance with the [`SupportedBufferSize`]
-/// range produced by the [`SupportedStreamConfig`] API.
+/// ## Callback Size Expectations
+///
+/// When you specify [`BufferSize::Fixed(x)`], you are **requesting** that callbacks
+/// receive approximately `x` frames of audio data. However, **no guarantees can be
+/// made** about the actual callback size:
+///
+/// - The host may round to hardware-supported values
+/// - Different devices have different constraints
+/// - The callback size may vary between calls (especially on mobile platforms)
+/// - The actual size might be larger or smaller than requested
+///
+/// ## Latency Considerations
+///
+/// [`BufferSize::Default`] uses the host's default buffer size, which may be
+/// surprisingly large, leading to higher latency. If low latency is desired,
+/// [`BufferSize::Fixed`] should be used with a small value in accordance with
+/// the [`SupportedBufferSize`] range from [`SupportedStreamConfig`].
 ///
 /// Smaller buffer sizes reduce latency but may increase CPU usage and risk audio
-/// dropouts if the callback cannot keep up with the requested buffer size.
+/// dropouts if the callback cannot process audio quickly enough.
 ///
-/// [`Default`]: BufferSize::Default
-/// [`Fixed(FrameCount)`]: BufferSize::Fixed
+/// [`BufferSize::Default`]: BufferSize::Default
+/// [`BufferSize::Fixed`]: BufferSize::Fixed
+/// [`BufferSize::Fixed(x)`]: BufferSize::Fixed
 /// [`SupportedBufferSize`]: SupportedStreamConfig::buffer_size
 /// [`SupportedStreamConfig`]: SupportedStreamConfig
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]