Struct Playback 

pub struct Playback { /* private fields */ }

A playback in progress, or one that has already ended.

Returned by MediaSession::start_playback without waiting for the clip: the point of the handle is that the caller goes on to do something else — collect digits, watch for a hangup — while the audio plays, and can reach back to stop it.

Cloneable, and deliberately so: the handle is a control surface, not ownership of a resource. A call hands one clone to the application and keeps another to report the playback’s end on its event stream.

Implementations

impl Playback

pub const STOP_BOUND_PACKETS: u64 = 2

How many packets of a stopped playback may still reach the wire after it is cut.

Two, at 20 ms each by default — a number rather than “promptly”, because the whole difference between playback that can be controlled and playback that cannot is whether an application can say how long barge-in takes.

Where it comes from: MediaSession::start_playback runs ahead of the wire, so when a clip is stopped the send queue is generally holding its next few dozen packets. Those are not sent. The send loop tests each frame’s playback against this signal as it takes the frame off the queue and discards a stopped one without spending a packet interval on it, so the whole backlog drains inside one tick. What can still go out is the packet the send loop had already committed to the socket when the signal was set, and — allowing for the stop landing between taking a frame and sending it — the one after it.

The same bound covers Interrupt::OnDigit: an interruption sets the same signal, one task hop after the keypress is delivered.

pub const QUEUE_DEPTH: usize = 32

How many clips may be waiting behind the one playing before further ones are refused.

A bound rather than an unbounded queue because the caller of MediaSession::start_playback is not always a program somebody wrote by hand — under the application contract it is a remote app sending instructions, and a queue that grows without limit turns a buggy app into this process’s memory problem. Deep enough that no prompt sequence a call actually has time for will reach it.

pub fn id(&self) -> PlaybackId

Which playback this is.

pub fn stop(&self)

Cut this playback short.

Takes effect within Self::STOP_BOUND_PACKETS packets. Idempotent, and harmless on a playback that has already ended. Does not wait: Self::finished is how a caller learns it has landed.

pub fn is_stopped(&self) -> bool

Whether this playback has been asked to stop — by Self::stop or by a keypress.

pub fn end(&self) -> Option<PlaybackEnd>

How it ended, if it has, without waiting.

pub async fn play_out(&self) -> PlaybackEnd

Wait for it to end, and stop it if the wait itself is abandoned.

The difference from Self::finished is what happens when this future is dropped before the clip ends — a caller that wrapped the wait in a timeout, or lost a select!. It stops the playback, because that is what abandoning a play has always meant: the audio stops with the caller’s interest in it, rather than playing on out of a task the caller no longer holds a handle to.

MediaSession::play is this method, which is how it keeps that property now that the clip is fed by a task of its own rather than by the caller.

pub async fn finished(&self) -> PlaybackEnd

Wait for it to end, and say how. Observation only: dropping this wait does not touch the playback, which goes on to whatever end it was going to reach.

Resolves when the decision is made rather than when the last packet is on the wire — which is what a caller wants of an interruption, since the next thing it does is act on the keypress. The stopped clip’s remaining audio is already guaranteed not to be sent by then.

Takes &self, so several parties may await the same playback.

Trait Implementations

impl Clone for Playback

fn clone(&self) -> Playback

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Playback

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.