Skip to main content

AudioCapture

Struct AudioCapture 

Source
pub struct AudioCapture {
    pub(crate) shared: Arc<Shared>,
}
Expand description

A capture: one PulseAudio record stream encoded to Opus and delivered to an AudioSink. Owns the Shared lifecycle state; start / stop / update_audio_bitrate / set_stereo_companion drive it, and is_capturing / state / last_error report it. Dropping the handle stops the capture.

Fields§

§shared: Arc<Shared>

Implementations§

Source§

impl AudioCapture

Source

pub fn new() -> Self

An idle capture; nothing runs until start.

Source

pub(crate) fn inner(&self) -> &Arc<Inner> ⓘ

Source

pub fn start( &self, settings: &AudioCaptureSettings, sink: Option<Arc<dyn AudioSink>>, ) -> Result<(), Error>

Start (or restart) audio capture, delivering encoded frames to sink; with no sink the run serves only its output_socket and no frame is delivered.

  1. Re-entrancy guard: if called on one of the run’s own threads — the delivery thread (where the sink executes) or the capture thread — it cannot join/recreate the run it is part of (the capture thread joins the delivery thread on teardown, so a join from either closes a cycle), so it just undoes a nested SELF-stop and returns. That undo is a compare-exchange that clears the stop ONLY if this thread still owns it — if an external stop stored STOP_EXTERNAL meanwhile, the CAS fails and that stop stands (clearing it would strand its in-flight join forever).
  2. Validate: AudioCaptureSettings::validate refuses with Error::Settings what the worker could only fail on later, before any thread is touched.
  3. Spawn: spawn_worker stops/joins any prior thread and spawns the new one. The stop/clear ordering (the lost-stop invariant) lives in spawn_worker; a join here waits for the sink’s in-flight call, so a caller holding a lock that call needs releases it first (the Python bridge releases the GIL).
  4. Register the handle for stop_all (best-effort), pruning dead weaks.
  5. Startup handshake (await_start): waits up to ~2 s for the thread to publish RUNNING or FAILED, returning Ok while it is still STARTING — the retry ladder can run longer than the window, so a later failure is observed through state / last_error. On FAILED, join_failed_start tears down ONLY the thread this call spawned (identity-checked) — a concurrent start may already own the slot with a live run that must survive — and last_error is returned as Error::Start.
Source

pub fn stop(&self)

Stop audio capture, joining the capture thread.

A re-entrant stop from one of the run’s own threads — the delivery thread (where the sink executes) or the capture thread — only records a self-stop: a join from inside the run would cycle (the capture thread joins the delivery thread on teardown). It must not clobber an external stop already in effect, which has to win the join. Otherwise it takes the lifecycle lock and joins; the authoritative external stop is set INSIDE the lock immediately before the join, so it wins over any concurrent self-stop. The join waits for the sink’s in-flight call, so a caller holding a lock that call needs releases it first (the Python bridge releases the GIL).

Source

pub fn update_audio_bitrate(&self, bps: i32)

Set the live Opus target bitrate (bits/s) via the atomic mirror; the capture loop applies it on the next frame, without a restart. Values are clamped to the valid Opus range so an out-of-range request can never wedge the encoder. The value does not persist into the next start, which re-seeds it from its settings.

Source

pub fn set_stereo_companion(&self, enabled: bool)

Have a surround capture also deliver every frame downmixed to stereo, live: each surround frame is followed by its companion, the same pts and channels == 2, encoded by a stereo encoder of its own at the capture’s bitrate, for consumers that decode no multistream Opus. Off by default, it keeps its setting across restarts, and a mono or stereo capture ignores it.

Source

pub fn is_capturing(&self) -> bool

True while a capture worker is connected and running with no stop pending; false while still starting and after a failure — see state to tell those apart.

Source

pub fn state(&self) -> State

Lifecycle phase. A run that fails after start returned (its retry ladder gave up, or a mid-run reconnect budget was spent) reads Failed with the reason in last_error.

Source

pub fn last_error(&self) -> Option<String>

Why the last run failed, or None while no run has failed since the last start.

Trait Implementations§

Source§

impl Default for AudioCapture

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Drop for AudioCapture

Source§

fn drop(&mut self)

Best-effort stop: the re-entrant case (running on the run’s own delivery or capture thread) records a self-stop only (never clobbering a pending external stop); otherwise it takes the lifecycle lock and joins the capture thread, as stop.

Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.