feat: rename StreamTrait::play to start, add draining stop

.github/workflows/quality.yml

@@ -56,7 +56,7 @@ jobs:
           # Android - Oboe backend
           - target: armv7-linux-androideabi
             name: Android
-            features: ""
+            features: --features realtime
             os: ubuntu-latest
 
           # iOS - CoreAudio (iOS) backend

CHANGELOG.md

@@ -7,28 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `StreamTrait::stop` ends a stream gracefully, draining buffered audio before halting (blocking up to a caller-supplied timeout). Dropping a stream still halts immediately without draining.
+
 ### Changed
 
 - Migrated to Rust 2024.
 - `DeviceTrait` and `StreamTrait` now require `Send + Sync` as supertrait bounds.
+- `StreamTrait::play` is renamed to `start`.
 - **WASAPI**: The `windows` and `windows-core` dependencies are now both pinned to 0.62.
 
 ### Deprecated
 
+- `StreamTrait::play` is deprecated in favor of `start`.
 - `assert_stream_send!` and `assert_stream_sync!` are deprecated; `StreamTrait: Send + Sync` makes them redundant.
 
 ### Fixed
 
 - Timestamps now stay monotonic across device and graph changes.
 - **ALSA**: A nonzero but sub-millisecond stream timeout is no longer treated as a non-blocking poll.
 - **AudioWorklet**: Fix `Stream` operations to work when called from any thread.
-- **WebAudio**: Fix unsound `Send + Sync` on `Stream` when compiled with `+atomics`.
-- **WebAudio**: Fix `Host::is_available()` always returning `true`, even in non-window contexts.
 - **CoreAudio**: Bump `objc2-core-foundation` dependency lower bound to 0.3.1.
+- **CoreAudio**: Fix stale audio output when a data callback wrote a partial buffer.
 - **iOS**: Timestamps now include hardware latency and update when the audio route changes.
 - **JACK**: Timestamps now include port latency.
-- **WASAPI**: The `windows` and `windows-core` dependencies are now both pinned to 0.62.
+- **PipeWire**: Fix streams starting audio before `start()` is called.
 - **WASAPI**: Reported buffer sizes are no longer off by one frame.
+- **WebAudio**: Fix unsound `Send + Sync` on `Stream` when compiled with `+atomics`.
+- **WebAudio**: Fix `Host::is_available()` always returning `true`, even in non-window contexts.
 
 ## [0.18.1] - 2026-06-07
 

UPGRADING.md

@@ -6,6 +6,8 @@ This guide covers breaking changes requiring code updates. See [CHANGELOG.md](CH
 
 - [ ] If you implement a custom host, ensure your `Device` and `Stream` types are `Send + Sync`.
 - [ ] Remove any calls to the deprecated `assert_stream_send!` and `assert_stream_sync!` macros.
+- [ ] Rename `StreamTrait::play` calls to `start` (the old name still works but is deprecated).
+- [ ] If you implement a custom host, add a `StreamTrait::stop` implementation.
 
 ## 1. `DeviceTrait` and `StreamTrait` require `Send + Sync`
 
@@ -15,6 +17,25 @@ This only affects authors of `custom` host implementations. Users of built-in ho
 
 **Impact:** Remove any `assert_stream_send!` and `assert_stream_sync!` calls from your custom host; they are now deprecated. If your `Device` or `Stream` type contains raw pointers or other non-`Send`/non-`Sync` internals (e.g. COM handles, JS objects), audit that concurrent access is actually safe, then add `unsafe impl Send` and `unsafe impl Sync`.
 
+## 2. `StreamTrait::play` renamed to `start`, and a new `stop` method
+
+**What changed:** `StreamTrait::play` is renamed to [`start`]. The old `play` remains as a deprecated default method that forwards to `start`, so existing code keeps compiling with a deprecation warning. A new [`stop`] method performs a *draining* stop.
+
+`start`, `pause`, and `stop` now form the transport controls:
+
+- `start` begins or resumes the stream (the rename reflects that it applies to capture streams too, not just playback).
+- `pause` halts the data callback as soon as possible without waiting for buffered audio to finish.
+- `stop(timeout)` drains: on output streams it lets buffered audio finish playing, blocking the calling thread until the buffer empties or `timeout` elapses, then halts. `None` waits indefinitely; `Some(Duration::ZERO)` halts immediately without draining. All three leave the stream resumable; dropping the stream still halts immediately without draining.
+
+**Impact (built-in host users):** Replace `stream.play()` with `stream.start()`. Optionally adopt `stream.stop(timeout)` where you want playback to end cleanly rather than be cut off.
+
+**Impact (custom host authors):** Rename your `StreamTrait::play` implementation to `start`. Add a `stop` implementation; if your host has no audio buffered outside the data callback, it can simply call `self.pause()`.
+
+Draining is best-effort and varies by backend: most built-in output backends respect the drain window. The exceptions are WebAudio, AudioWorklet, and ASIO, where `stop` halts immediately and `timeout` is ignored. On capture streams, `stop` also halts immediately.
+
+[`start`]: https://docs.rs/cpal/latest/cpal/traits/trait.StreamTrait.html#tymethod.start
+[`stop`]: https://docs.rs/cpal/latest/cpal/traits/trait.StreamTrait.html#tymethod.stop
+
 ---
 
 # Upgrading from v0.17 to v0.18

examples/android/src/lib.rs

@@ -65,7 +65,7 @@ where
         err_fn,
         None,
     )?;
-    stream.play()?;
+    stream.start()?;
 
     std::thread::sleep(std::time::Duration::from_millis(1000));
 

examples/audioworklet-beep/src/lib.rs

@@ -94,7 +94,7 @@ where
             None,
         )
         .unwrap();
-    stream.play().unwrap();
+    stream.start().unwrap();
     stream
 }
 

examples/beep.rs

@@ -147,10 +147,14 @@ where
         err_fn,
         None,
     )?;
-    stream.play()?;
+    stream.start()?;
 
     std::thread::sleep(std::time::Duration::from_millis(1000));
 
+    // Stop gracefully: let any audio already buffered play out (up to 200 ms) before the stream is
+    // halted, rather than cutting off mid-buffer the way dropping the stream would.
+    stream.stop(Some(std::time::Duration::from_millis(200)))?;
+
     Ok(())
 }
 

examples/custom.rs

@@ -194,7 +194,7 @@ impl fmt::Display for MyDevice {
 }
 
 impl StreamTrait for MyStream {
-    fn play(&self) -> Result<(), Error> {
+    fn start(&self) -> Result<(), Error> {
         self.controls.pause.store(false, Ordering::Relaxed);
         Ok(())
     }
@@ -204,6 +204,12 @@ impl StreamTrait for MyStream {
         Ok(())
     }
 
+    fn stop(&self, _timeout: Option<std::time::Duration>) -> Result<(), Error> {
+        // This example has no audio buffered outside the callback, so stop is an immediate halt.
+        self.controls.pause.store(true, Ordering::Relaxed);
+        Ok(())
+    }
+
     fn now(&self) -> StreamInstant {
         let elapsed = self.start.elapsed();
         StreamInstant::new(elapsed.as_secs(), elapsed.subsec_nanos())
@@ -232,7 +238,7 @@ fn main() {
     let config = device.default_output_config().unwrap();
 
     let stream = make_stream(&device, config.into()).unwrap();
-    stream.play().unwrap();
+    stream.start().unwrap();
     std::thread::sleep(std::time::Duration::from_millis(4000));
 }
 

examples/feedback.rs

@@ -145,8 +145,8 @@ fn main() -> anyhow::Result<()> {
         "Starting the input and output streams with `{}` milliseconds of latency.",
         opt.latency
     );
-    input_stream.play()?;
-    output_stream.play()?;
+    input_stream.start()?;
+    output_stream.start()?;
 
     // Run for 10 seconds before closing.
     println!("Playing for 10 seconds... ");

examples/ios-feedback/src/feedback.rs

@@ -76,8 +76,8 @@ pub fn run_example() -> Result<(), anyhow::Error> {
 
     // Play the streams.
     println!("Starting the input and output streams with `{LATENCY_MS}` milliseconds of latency.");
-    input_stream.play()?;
-    output_stream.play()?;
+    input_stream.start()?;
+    output_stream.start()?;
 
     // for the purposes of this demo, leak these so that after returning the audio units will
     // keep running

examples/record_wav.rs

@@ -159,7 +159,7 @@ fn main() -> Result<(), anyhow::Error> {
         }
     };
 
-    stream.play()?;
+    stream.start()?;
 
     // Let recording go for roughly three seconds.
     std::thread::sleep(std::time::Duration::from_secs(opt.duration));

examples/synth_tones.rs

@@ -14,7 +14,7 @@ use cpal::{
 
 fn main() -> anyhow::Result<()> {
     let stream = stream_setup_for()?;
-    stream.play()?;
+    stream.start()?;
     std::thread::sleep(std::time::Duration::from_millis(4000));
     Ok(())
 }

examples/wasm-beep/src/lib.rs

@@ -91,7 +91,7 @@ where
             None,
         )
         .unwrap();
-    stream.play().unwrap();
+    stream.start().unwrap();
     stream
 }
 

src/host/aaudio/mod.rs

@@ -7,7 +7,7 @@ use std::{
     hash::{Hash, Hasher},
     sync::{
         Arc, Mutex,
-        atomic::{AtomicI32, Ordering},
+        atomic::{AtomicBool, AtomicI32, Ordering},
     },
     time::Duration,
     vec::IntoIter as VecIntoIter,
@@ -138,6 +138,7 @@ pub struct Device(Option<AudioDeviceInfo>);
 pub struct Stream {
     inner: Arc<Mutex<AudioStream>>,
     direction: DeviceDirection,
+    draining: Arc<AtomicBool>,
 }
 
 // SAFETY: AudioStream can be safely sent between threads. The AAudio C API is thread-safe
@@ -319,6 +320,9 @@ where
     let error_callback_for_stream = error_callback.clone();
     let error_callback_for_data = error_callback.clone();
 
+    let draining = Arc::new(AtomicBool::new(false));
+    let draining_for_data = draining.clone();
+
     #[cfg(feature = "realtime")]
     let mut rt_checked = false;
     #[cfg(feature = "realtime")]
@@ -358,16 +362,18 @@ where
                 );
                 return ndk::audio::AudioCallbackResult::Stop;
             };
-            let cb_info = InputCallbackInfo {
-                timestamp: InputStreamTimestamp {
-                    callback: now_stream_instant(),
-                    capture: input_stream_instant(stream, sample_rate),
-                },
-            };
-            (data_callback)(
-                &unsafe { Data::from_parts(data as *mut _, n_samples, sample_format) },
-                &cb_info,
-            );
+            if !draining_for_data.load(Ordering::Relaxed) {
+                let cb_info = InputCallbackInfo {
+                    timestamp: InputStreamTimestamp {
+                        callback: now_stream_instant(),
+                        capture: input_stream_instant(stream, sample_rate),
+                    },
+                };
+                (data_callback)(
+                    &unsafe { Data::from_parts(data as *mut _, n_samples, sample_format) },
+                    &cb_info,
+                );
+            }
             ndk::audio::AudioCallbackResult::Continue
         }))
         .error_callback(Box::new(move |_stream, error| {
@@ -382,6 +388,7 @@ where
     Ok(Stream {
         inner: Arc::new(Mutex::new(stream)),
         direction: DeviceDirection::Input,
+        draining,
     })
 }
 
@@ -409,6 +416,9 @@ where
     let error_callback_for_stream = error_callback.clone();
     let error_callback_for_data = error_callback.clone();
 
+    let draining = Arc::new(AtomicBool::new(false));
+    let draining_for_data = draining.clone();
+
     #[cfg(feature = "realtime")]
     let mut rt_checked = false;
     #[cfg(feature = "realtime")]
@@ -456,17 +466,18 @@ where
                 std::slice::from_raw_parts_mut(data as *mut u8, byte_count).fill(0);
             }
 
-            // Deliver audio data to user callback
-            let cb_info = OutputCallbackInfo {
-                timestamp: OutputStreamTimestamp {
-                    callback: now_stream_instant(),
-                    playback: output_stream_instant(stream, sample_rate),
-                },
-            };
-            (data_callback)(
-                &mut unsafe { Data::from_parts(data as *mut _, n_samples, sample_format) },
-                &cb_info,
-            );
+            if !draining_for_data.load(Ordering::Relaxed) {
+                let cb_info = OutputCallbackInfo {
+                    timestamp: OutputStreamTimestamp {
+                        callback: now_stream_instant(),
+                        playback: output_stream_instant(stream, sample_rate),
+                    },
+                };
+                (data_callback)(
+                    &mut unsafe { Data::from_parts(data as *mut _, n_samples, sample_format) },
+                    &cb_info,
+                );
+            }
 
             // Dynamic buffer tuning for output streams
             // See: https://developer.android.com/ndk/guides/audio/aaudio/aaudio#tuning-buffers
@@ -539,6 +550,7 @@ where
     Ok(Stream {
         inner: Arc::new(Mutex::new(stream)),
         direction: DeviceDirection::Output,
+        draining,
     })
 }
 
@@ -760,7 +772,8 @@ impl Hash for Device {
 }
 
 impl StreamTrait for Stream {
-    fn play(&self) -> Result<(), Error> {
+    fn start(&self) -> Result<(), Error> {
+        self.draining.store(false, Ordering::Relaxed);
         let stream = self.inner.lock().map_err(|_| {
             Error::with_message(ErrorKind::StreamInvalidated, "Stream lock poisoned")
         })?;
@@ -798,6 +811,36 @@ impl StreamTrait for Stream {
         }
     }
 
+    fn stop(&self, timeout: Option<Duration>) -> Result<(), Error> {
+        self.draining.store(true, Ordering::Relaxed);
+
+        let stream = self.inner.lock().map_err(|_| {
+            Error::with_message(ErrorKind::StreamInvalidated, "Stream lock poisoned")
+        })?;
+
+        if self.direction != DeviceDirection::Output {
+            stream.request_stop().context("Failed to stop stream")?;
+            return Ok(());
+        }
+
+        // Duration::ZERO: flush (discard) instead of drain; return immediately.
+        if timeout == Some(Duration::ZERO) {
+            stream.request_flush().context("Failed to flush stream")?;
+            return Ok(());
+        }
+
+        // AAudio output drains remaining audio during the Stopping state.
+        stream.request_stop().context("Failed to stop stream")?;
+        let wait_nanos = timeout.map_or(i64::MAX, |t| t.as_nanos().min(i64::MAX as u128) as i64);
+        match stream.wait_for_state_change(ndk::audio::AudioStreamState::Stopping, wait_nanos) {
+            Ok(_) => Ok(()),
+            Err(ndk::audio::AudioError::Timeout) => stream
+                .request_flush()
+                .context("Failed to flush stream after timeout"),
+            Err(e) => Err(e).context("Failed to wait for stream to stop"),
+        }
+    }
+
     fn now(&self) -> StreamInstant {
         now_stream_instant()
     }