feat: add Stream::buffer_size() and improve AAudio buffer configuration

Add buffer_size() method to Stream trait that returns the number of
frames passed to each data callback invocation (actual size or upper
limit depending on platform).

AAudio improvements:
- BufferSize::Default now explicitly configures using optimal burst size
  from AudioManager, following Android low-latency audio best practices
- buffer_size() query falls back to burst size if frames_per_data_callback
  was not explicitly set
- Refactored buffer configuration to eliminate code duplication

Addresses #1042
Relates to #964, #942

Author: roderickvd

CHANGELOG.md

@@ -5,6 +5,13 @@ 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]
+
+### Added
+
+- `StreamTrait::buffer_size` method to query the callback buffer size (actual size or upper limit depending on platform).
+- **AAudio**: `BufferSize::Default` now explicitly configures using the optimal burst size from AudioManager.
+
 ## [0.17.0] - 2025-12-20
 
 ### Added
@@ -1017,6 +1024,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.17.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

src/host/aaudio/mod.rs

@@ -277,13 +277,22 @@ fn configure_for_device(
     };
     builder = builder.sample_rate(config.sample_rate.try_into().unwrap());
 
-    // Note: Buffer size validation is not needed - the native AAudio API validates buffer sizes
-    // when `open_stream()` is called.
-    match &config.buffer_size {
-        BufferSize::Default => builder,
-        BufferSize::Fixed(size) => builder
-            .frames_per_data_callback(*size as i32)
-            .buffer_capacity_in_frames((*size * 2) as i32), // Double-buffering
+    let buffer_size = match config.buffer_size {
+        BufferSize::Default => {
+            // Use the optimal burst size from AudioManager:
+            // https://developer.android.com/ndk/guides/audio/audio-latency#buffer-size
+            AudioManager::get_frames_per_buffer().ok()
+        }
+        BufferSize::Fixed(size) => Some(size),
+    };
+
+    if let Some(size) = buffer_size {
+        builder
+            .frames_per_data_callback(size as i32)
+            .buffer_capacity_in_frames((size * 2) as i32) // Double-buffering
+    } else {
+        // If we couldn't determine a buffer size, let AAudio choose defaults
+        builder
     }
 }
 
@@ -606,4 +615,20 @@ impl StreamTrait for Stream {
                 .map_err(PauseStreamError::from),
         }
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        let stream = match self {
+            Self::Input(stream) => stream.lock().ok()?,
+            Self::Output(stream) => stream.lock().ok()?,
+        };
+
+        // If frames_per_data_callback was not explicitly set (returning 0),
+        // fall back to the burst size as that's what AAudio uses by default.
+        match stream.get_frames_per_data_callback() {
+            Some(size) if size > 0 => Some(size as crate::FrameCount),
+            _ => stream
+                .get_frames_per_burst()
+                .map(|f| f as crate::FrameCount),
+        }
+    }
 }

src/host/alsa/mod.rs

@@ -1220,6 +1220,9 @@ impl StreamTrait for Stream {
         self.inner.channel.pause(true).ok();
         Ok(())
     }
+    fn buffer_size(&self) -> Option<FrameCount> {
+        Some(self.inner.period_frames as FrameCount)
+    }
 }
 
 // Convert ALSA frames to FrameCount, clamping to valid range.

src/host/asio/mod.rs

@@ -153,4 +153,8 @@ impl StreamTrait for Stream {
     fn pause(&self) -> Result<(), PauseStreamError> {
         Stream::pause(self)
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        Stream::buffer_size(self)
+    }
 }

src/host/asio/stream.rs

@@ -37,6 +37,15 @@ impl Stream {
         self.playing.store(false, Ordering::SeqCst);
         Ok(())
     }
+
+    pub fn buffer_size(&self) -> Option<crate::FrameCount> {
+        let streams = self.asio_streams.lock().ok()?;
+        streams
+            .output
+            .as_ref()
+            .or(streams.input.as_ref())
+            .map(|s| s.buffer_size as crate::FrameCount)
+    }
 }
 
 impl Device {

src/host/coreaudio/ios/mod.rs

@@ -274,11 +274,14 @@ impl StreamTrait for Stream {
                 let err = BackendSpecificError { description };
                 return Err(err.into());
             }
-
             stream.playing = false;
         }
         Ok(())
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        Some(get_device_buffer_frames() as crate::FrameCount)
+    }
 }
 
 struct StreamInner {

src/host/coreaudio/macos/device.rs

@@ -1007,7 +1007,9 @@ fn setup_callback_vars(
 ///
 /// Buffer frame size is a device-level property that always uses Scope::Global + Element::Output,
 /// regardless of whether the audio unit is configured for input or output streams.
-fn get_device_buffer_frame_size(audio_unit: &AudioUnit) -> Result<usize, coreaudio::Error> {
+pub(crate) fn get_device_buffer_frame_size(
+    audio_unit: &AudioUnit,
+) -> Result<usize, coreaudio::Error> {
     // Device-level property: always use Scope::Global + Element::Output
     // This is consistent with how we set the buffer size and query the buffer size range
     let frames: u32 = audio_unit.get_property(

src/host/coreaudio/macos/mod.rs

@@ -261,6 +261,14 @@ impl StreamTrait for Stream {
 
         stream.pause()
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        let stream = self.inner.lock().ok()?;
+
+        device::get_device_buffer_frame_size(&stream.audio_unit)
+            .ok()
+            .map(|size| size as crate::FrameCount)
+    }
 }
 
 #[cfg(test)]

src/host/jack/stream.rs

@@ -220,6 +220,10 @@ impl StreamTrait for Stream {
         self.playing.store(false, Ordering::SeqCst);
         Ok(())
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        Some(self.async_client.as_client().buffer_size() as crate::FrameCount)
+    }
 }
 
 type InputDataCallback = Box<dyn FnMut(&Data, &InputCallbackInfo) + Send + 'static>;

src/host/wasapi/stream.rs

@@ -29,6 +29,11 @@ pub struct Stream {
     // This event is signalled after a new entry is added to `commands`, so that the `run()`
     // method can be notified.
     pending_scheduled_event: Foundation::HANDLE,
+
+    // Number of frames in the WASAPI buffer.
+    //
+    // Note: the actual callback size is variable and may be less than this value.
+    max_frames_in_buffer: u32,
 }
 
 // SAFETY: Windows Event HANDLEs are safe to send between threads - they are designed for
@@ -115,6 +120,8 @@ impl Stream {
         .expect("cpal: could not create input stream event");
         let (tx, rx) = channel();
 
+        let max_frames_in_buffer = stream_inner.max_frames_in_buffer;
+
         let run_context = RunContext {
             handles: vec![pending_scheduled_event, stream_inner.event],
             stream: stream_inner,
@@ -130,6 +137,7 @@ impl Stream {
             thread: Some(thread),
             commands: tx,
             pending_scheduled_event,
+            max_frames_in_buffer,
         }
     }
 
@@ -148,6 +156,8 @@ impl Stream {
         .expect("cpal: could not create output stream event");
         let (tx, rx) = channel();
 
+        let max_frames_in_buffer = stream_inner.max_frames_in_buffer;
+
         let run_context = RunContext {
             handles: vec![pending_scheduled_event, stream_inner.event],
             stream: stream_inner,
@@ -163,6 +173,7 @@ impl Stream {
             thread: Some(thread),
             commands: tx,
             pending_scheduled_event,
+            max_frames_in_buffer,
         }
     }
 
@@ -198,6 +209,12 @@ impl StreamTrait for Stream {
             .map_err(|_| crate::error::PauseStreamError::DeviceNotAvailable)?;
         Ok(())
     }
+
+    fn buffer_size(&self) -> Option<crate::FrameCount> {
+        // WASAPI uses event-driven callbacks with variable callback sizes.
+        // We return the total buffer size allocated by Windows as an upper bound.
+        Some(self.max_frames_in_buffer as crate::FrameCount)
+    }
 }
 
 impl Drop for StreamInner {