feat: rename StreamTrait::play to start, add draining stop by roderickvd · Pull Request #1258 · RustAudio/cpal

roderickvd · 2026-07-04T19:59:11Z

This PR introduces start/pause/stop semantics on StreamTrait with draining stop.

Playback

On playback streams, the difference between pausing and stopping is that:

pause halts as soon as possible, if necessary discarding buffered audio
stop(timeout) drains, letting buffered output finish before halting.

stop thus blocks until the buffer empties or timeout elapses.

Capture

Capture streams have nothing to drain and halt immediately on stop.

Behavior details

play is now deprecated and forwards to start.
A timeout of None waits indefinitely; Some(Duration::ZERO) halts without draining.
Stopped and paused streams are resumable with start.
Dropping a stream halts immediately without draining.

Backend support

All backends support draining stop, except WebAudio and AudioWorklet where the calling thread can't block.
On ALSA, pause now implements a soft-pause fallback when there is no hardware support.
While there:
- relaxed StreamState atomics in ASIO and JACK from Acquire/Release to Relaxed (no associated data payload).
- fixed PipeWire to no longer auto-start streams.

+    fn stop(&self, timeout: Option<Duration>) -> Result<(), Error> {
+        self.draining.store(true, Ordering::Relaxed);
+        crate::host::com::com_initialized();
+
+        if timeout != Some(Duration::ZERO) {
+            let wait = if let Some(ref client) = self.drain_audio_client {
+                unsafe {
+                    let padding = client.GetCurrentPadding().unwrap_or(0);
+                    let latency_hns = client.GetStreamLatency().unwrap_or(0);
+                    let mut buffered =
+                        Duration::from_nanos((latency_hns.max(0) as u64).saturating_mul(100));
+                    if let Ok(fmt) = client.GetMixFormat() {
+                        let sample_rate = (*fmt).nSamplesPerSec;
+                        Com::CoTaskMemFree(Some(fmt.cast()));


Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/host/wasapi/stream.rs:231

The unsafe Send justification comment is now out of date: Stream gained draining and fill_usec fields, but they are not mentioned in the list of Send fields. For unsafe impls, keeping this rationale accurate is important for future maintenance and auditing.

// SAFETY: Windows Event HANDLEs are safe to send between threads - they are designed for
// synchronization. All fields of Stream are Send:
// - JoinHandle<()> is Send
// - Sender<Command> is Send
// - Foundation::HANDLE is Send (Windows synchronization primitive)
// - Latch is Send

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated no new comments.

roderickvd mentioned this pull request Jul 4, 2026

v0.19 design goals #1220

Open

17 tasks

roderickvd added the enhancement label Jul 4, 2026

roderickvd force-pushed the feat/start-pause-stop branch 2 times, most recently from 0101f48 to f5cbdac Compare July 4, 2026 20:34

roderickvd requested a review from Copilot July 4, 2026 20:39

Copilot started reviewing on behalf of roderickvd July 4, 2026 20:39 View session

This was referenced Jul 4, 2026

Inconsistent stream auto-play behavior #603

Open

Pause semantics #284

Open

This comment was marked as resolved.

Sign in to view

This was referenced Jul 4, 2026

[Request] Sleep thread on pause #785

Open

PulseAudio backend: short / fixed-length playbacks truncated under pipewire-pulse #1190

Open

roderickvd force-pushed the feat/start-pause-stop branch from f5cbdac to a36d6d7 Compare July 4, 2026 20:57

roderickvd requested a review from Copilot July 4, 2026 20:58

Copilot started reviewing on behalf of roderickvd July 4, 2026 20:59 View session

This comment was marked as resolved.

Sign in to view

roderickvd force-pushed the feat/start-pause-stop branch from a36d6d7 to 9286187 Compare July 4, 2026 21:25

roderickvd requested a review from Copilot July 4, 2026 21:26

Copilot started reviewing on behalf of roderickvd July 4, 2026 21:26 View session

This comment was marked as resolved.

Sign in to view

roderickvd force-pushed the feat/start-pause-stop branch from 9286187 to a216772 Compare July 4, 2026 21:33

roderickvd requested a review from Copilot July 4, 2026 21:34

Copilot started reviewing on behalf of roderickvd July 4, 2026 21:35 View session

This comment was marked as resolved.

Sign in to view

roderickvd force-pushed the feat/start-pause-stop branch from a216772 to 6fd7141 Compare July 4, 2026 21:45

roderickvd requested a review from Copilot July 4, 2026 21:46

Copilot started reviewing on behalf of roderickvd July 4, 2026 21:46 View session

This comment was marked as resolved.

Sign in to view

roderickvd force-pushed the feat/start-pause-stop branch from 6fd7141 to aa9f4b3 Compare July 4, 2026 22:01

roderickvd requested a review from Copilot July 4, 2026 22:01

Copilot started reviewing on behalf of roderickvd July 4, 2026 22:02 View session

roderickvd requested a review from Copilot July 7, 2026 20:27

Copilot started reviewing on behalf of roderickvd July 7, 2026 20:28 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread src/host/alsa/mod.rs

roderickvd force-pushed the feat/start-pause-stop branch from 37cc6a5 to 06c6553 Compare July 7, 2026 20:40

roderickvd requested a review from Copilot July 7, 2026 20:40

Copilot started reviewing on behalf of roderickvd July 7, 2026 20:41 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread src/host/pulseaudio/stream.rs

roderickvd force-pushed the feat/start-pause-stop branch from 06c6553 to 86e2405 Compare July 8, 2026 18:24

roderickvd requested a review from Copilot July 8, 2026 18:25

Copilot started reviewing on behalf of roderickvd July 8, 2026 18:25 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread src/traits.rs Outdated

Comment thread UPGRADING.md Outdated

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

79d60bb

roderickvd force-pushed the feat/start-pause-stop branch from 86e2405 to 348e1b8 Compare July 8, 2026 18:54

roderickvd requested a review from Copilot July 8, 2026 18:54

Copilot started reviewing on behalf of roderickvd July 8, 2026 18:55 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread src/host/pipewire/stream.rs

Comment on lines +163 to +165

fn stop(&self, timeout: Option<std::time::Duration>) -> Result<(), Error> {

let do_drain = self.is_output && timeout != Some(std::time::Duration::ZERO);

if do_drain {

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread src/host/alsa/mod.rs

roderickvd added 4 commits July 8, 2026 22:13

feat(alsa): implement draining stop

5c53a48

feat(pulseaudio): implement draining stop

00c4e0e

feat(pipewire): implement draining stop

7e577be

feat(coreaudio): implement draining stop

030f562

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread src/host/wasapi/stream.rs Outdated

roderickvd added 6 commits July 8, 2026 22:32

feat(wasapi): implement draining stop

54b9863

feat(aaudio): implement draining stop

e1b2bba

refactor: make StreamTrait::start required

e19dcbd

docs: changelog and upgrade guide for v0.19 start/stop

aa6eb61

fix(pipewire): do not auto-start stream

e56bf78

fix(ci): lint aaudio with realtime feature on android

b279509

Copilot AI reviewed Jul 8, 2026

View reviewed changes

+                  fn stop(&self, timeout: Option<std::time::Duration>) -> Result<(), Error> {
+                      let do_drain = self.is_output && timeout != Some(std::time::Duration::ZERO);
+                      if do_drain {

Uh oh!

Conversation

roderickvd commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Playback

Capture

Behavior details

Backend support

Related

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

roderickvd commented Jul 4, 2026 •

edited

Loading