Skip to content

consider renaming .pause() / .stop() #1388

Open

Description

@LastExceed

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)

Activity

  1. roderickvd commented on Sep 27, 2026

    @roderickvd
    Member

    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.

  2. LastExceed commented on Sep 27, 2026

    @LastExceed
    CollaboratorAuthor

    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?

  3. roderickvd commented on Sep 27, 2026

    @roderickvd
    Member

    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.

  4. LastExceed commented on Sep 27, 2026

    @LastExceed
    CollaboratorAuthor

    How do you define stream position 0?

    ... right, there is no such thing. Didn't think this through😅

    The “cpal” Stream remains valid

    Then, from an outside perspective, draining is the only difference. Idk I just don't find this intuitive. But maybe I am overthinking this

  5. Marco-Farruggio commented on Oct 28, 2026

    @Marco-Farruggio
    Collaborator

    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?

  6. LastExceed commented on Oct 28, 2026

    @LastExceed
    CollaboratorAuthor

    Your summary looks correct. Monotonocity should apply for entire lifetime of the cpal stream

  7. Marco-Farruggio commented on Oct 28, 2026

    @Marco-Farruggio
    Collaborator

    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.

  8. LastExceed commented on Oct 28, 2026

    @LastExceed
    CollaboratorAuthor

    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

  9. Marco-Farruggio commented on Oct 28, 2026

    @Marco-Farruggio
    Collaborator

    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

  10. roderickvd commented on Nov 9, 2026

    @roderickvd
    Member
    • Calling stream.pause() stops calling the user supplied callback inside cpal's audio callback with the host.

    Additionally, on supported platforms it should:

    1. put the hardware in a power-conserving state
    2. “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

    I agree.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions