You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The difference between them does not feel very intuitive to me. I'd suggest switching to something more explicit like .stop_immediate() / .stop_draining(), or just combining them and make draining a parameter. We should definitely make a decision on this before releasing 0.19 (the decision may of course be to stick with what we currently have)
I don’t see the problem. VCRs of old had different pause and stop buttons too. Pause temporarily interrupts, stop disengages. Pause keeps a steam live, stop tears it down.
VCRs of old had different pause and stop buttons too
Hmm, not super convinced by this argument, but it is a valid one. Should .stop() also reset the stream position to 0? (Do we even have a guarantee that streams start at 0 in the first place?)
stop tears it down
Oh, that is news to me. The doc comment states:
The stream remains valid after stop; calling start again resumes it, re-preparing the device if the backend requires it.
and so far I read the first part as directly stating the contrary. Am I to understand then that it specifically refers to the stream handle staying valid, and that the underlying stream (channel buffers etc) gets rebuild when .start() is called again?
Should .stop() also reset the stream position to 0? (Do we even have a guarantee that streams start at 0 in the first place?)
How do you define stream position 0?
stop tears it down
Oh, that is news to me. The doc comment states:
The stream remains valid after stop; calling start again resumes it, re-preparing the device if the backend requires it.
and so far I read the first part as directly stating the contrary. Am I to understand then that it specifically refers to the stream handle staying valid, and that the underlying stream (channel buffers etc) gets rebuild when .start() is called again?
You are right, my earlier reply was not consistent with that. The “cpal” Stream remains valid but the underlying system handle doesn’t need to, as long as cpal can rebuild or resume it - that’s backend-dependent and opaque to the cpal user.
I've been trying to wrap my head around this while writing #1404, and this is my current understanding:
Calling device.build_*_stream(...) constructs the stream with the host, not just at the cpal layer, but does not call the user-supplied callback yet.
Calling stream.start() starts calling the user supplied callback inside cpal's audio callback with the host.
Calling stream.pause() stops calling the user supplied callback inside cpal's audio callback with the host.
Calling stream.stop():
Stops calling the user's callback anymore.
Waits (up to a specific timeout) for all buffered audio to be played out (aka draining).
Deconstructs the stream with the host, but keeps the cpal-layer Stream valid (aka, doesn't consume self)
Dropping a Stream immediately deconstructs the stream with the host.
I want to make sure I get this right before I normalize the stream lifetime handling with the FreeBSD's OSS host incorrectly.
Also, not relevant to OSS, but how does the contract for monotonic stream callback timestamps work with this? Is the gaurentee per start() -> (pause) -> stop() lifecycle?
I've been thinking about writing up some of the cpal Wiki (as I don't want the README.md to grow too much) since the only thing in there is an outdated WASM guide, I've been putting some of it off mentally, thinking I'd have to most likely rewrite rather a lot due to the API changes discussed in #1334, but I may write one on 'Stream Lifecycles', just so this is formally documented.
I feel like there shouldn't be a need for a wiki, and that all relevant information should be expressed in doc comments and/or examples. I agree that our REAMDE is quite verbose at the moment, and feel like some of that (especially the ASIO and ALSA stuff) could be moved to doc-comments instead
Well eventually most of the ASIO stuff will be gone in the README, which will clear out lots of room including some of the cross compilation notes and whatnot, as for the wiki situation, I do feel that having a full blown wiki can be overkill, so maybe the docs for the stream lifecycle could go on StreamTrait/stream.rs, and/or each bullet point in my message above in the corresponding method of StreamTrait, clearly
Calling stream.pause() stops calling the user supplied callback inside cpal's audio callback with the host.
Additionally, on supported platforms it should:
put the hardware in a power-conserving state
“stop” immediately (mid-buffer) and retain its cursor for later resumption at that exact position
Point 1 holds for stop as well, point 2 does not.
I feel like there shouldn't be a need for a wiki, and that all relevant information should be expressed in doc comments and/or examples. I agree that our REAMDE is quite verbose at the moment, and feel like some of that (especially the ASIO and ALSA stuff) could be moved to doc-comments instead
Activity
roderickvd commentedon Sep 27, 2026
I don’t see the problem. VCRs of old had different pause and stop buttons too. Pause temporarily interrupts, stop disengages. Pause keeps a steam live, stop tears it down.
LastExceed commentedon Sep 27, 2026
Hmm, not super convinced by this argument, but it is a valid one. Should
.stop()also reset the stream position to 0? (Do we even have a guarantee that streams start at 0 in the first place?)Oh, that is news to me. The doc comment states:
and so far I read the first part as directly stating the contrary. Am I to understand then that it specifically refers to the stream handle staying valid, and that the underlying stream (channel buffers etc) gets rebuild when
.start()is called again?roderickvd commentedon Sep 27, 2026
How do you define stream position 0?
You are right, my earlier reply was not consistent with that. The “cpal”
Streamremains valid but the underlying system handle doesn’t need to, as long as cpal can rebuild or resume it - that’s backend-dependent and opaque to the cpal user.LastExceed commentedon Sep 27, 2026
... right, there is no such thing. Didn't think this through😅
Then, from an outside perspective, draining is the only difference. Idk I just don't find this intuitive. But maybe I am overthinking this
Marco-Farruggio commentedon Oct 28, 2026
I've been trying to wrap my head around this while writing #1404, and this is my current understanding:
device.build_*_stream(...)constructs the stream with the host, not just at the cpal layer, but does not call the user-supplied callback yet.stream.start()starts calling the user supplied callback inside cpal's audio callback with the host.stream.pause()stops calling the user supplied callback inside cpal's audio callback with the host.stream.stop():timeout) for all buffered audio to be played out (aka draining).Streamvalid (aka, doesn't consumeself)Streamimmediately deconstructs the stream with the host.I want to make sure I get this right before I normalize the stream lifetime handling with the FreeBSD's OSS host incorrectly.
Also, not relevant to OSS, but how does the contract for monotonic stream callback timestamps work with this? Is the gaurentee per start() -> (pause) -> stop() lifecycle?
LastExceed commentedon Oct 28, 2026
Your summary looks correct. Monotonocity should apply for entire lifetime of the cpal stream
Marco-Farruggio commentedon Oct 28, 2026
I've been thinking about writing up some of the cpal Wiki (as I don't want the
README.mdto grow too much) since the only thing in there is an outdated WASM guide, I've been putting some of it off mentally, thinking I'd have to most likely rewrite rather a lot due to the API changes discussed in #1334, but I may write one on 'Stream Lifecycles', just so this is formally documented.LastExceed commentedon Oct 28, 2026
I feel like there shouldn't be a need for a wiki, and that all relevant information should be expressed in doc comments and/or examples. I agree that our REAMDE is quite verbose at the moment, and feel like some of that (especially the ASIO and ALSA stuff) could be moved to doc-comments instead
Marco-Farruggio commentedon Oct 28, 2026
Well eventually most of the ASIO stuff will be gone in the README, which will clear out lots of room including some of the cross compilation notes and whatnot, as for the wiki situation, I do feel that having a full blown wiki can be overkill, so maybe the docs for the stream lifecycle could go on StreamTrait/stream.rs, and/or each bullet point in my message above in the corresponding method of StreamTrait, clearly
roderickvd commentedon Nov 9, 2026
Additionally, on supported platforms it should:
Point 1 holds for
stopas well, point 2 does not.I agree.