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§
Implementations§
Source§impl AudioCapture
impl AudioCapture
pub(crate) fn inner(&self) -> &Arc<Inner> ⓘ
Sourcepub fn start(
&self,
settings: &AudioCaptureSettings,
sink: Option<Arc<dyn AudioSink>>,
) -> Result<(), Error>
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.
- 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_EXTERNALmeanwhile, the CAS fails and that stop stands (clearing it would strand its in-flight join forever). - Validate:
AudioCaptureSettings::validaterefuses withError::Settingswhat the worker could only fail on later, before any thread is touched. - Spawn:
spawn_workerstops/joins any prior thread and spawns the new one. The stop/clear ordering (the lost-stop invariant) lives inspawn_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). - Register the handle for
stop_all(best-effort), pruning dead weaks. - Startup handshake (
await_start): waits up to ~2 s for the thread to publishRUNNINGorFAILED, returningOkwhile it is stillSTARTING— the retry ladder can run longer than the window, so a later failure is observed throughstate/last_error. OnFAILED,join_failed_starttears down ONLY the thread this call spawned (identity-checked) — a concurrent start may already own the slot with a live run that must survive — andlast_erroris returned asError::Start.
Sourcepub fn stop(&self)
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).
Sourcepub fn update_audio_bitrate(&self, bps: i32)
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.
Sourcepub fn set_stereo_companion(&self, enabled: bool)
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.
Sourcepub fn is_capturing(&self) -> bool
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.
Sourcepub fn state(&self) -> State
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.
Sourcepub fn last_error(&self) -> Option<String>
pub fn last_error(&self) -> Option<String>
Why the last run failed, or None while no run has failed since the last start.