sadda.live¶
Live audio recording with streaming pitch / formants / intensity / meter subscribers. PROVISIONAL tier — may change in minor versions after a deprecation cycle.
See the quickstart for a worked example. Design rationale lives in the 2026-05-22 DEVLOG entry "Live recording (E1)".
start_session
builtin
¶
start_session(project, *, device=Ellipsis, sample_rate=44100, channels=1, name=None, analysis_window_ms=30.0, analysis_hop_ms=10.0, num_formants=4, min_pitch_hz=75.0, max_pitch_hz=500.0)
Constructs a new live-recording session. device is a device name
from [list_input_devices] or "default". The cpal stream is
not built here — call session.start() to actually begin capture.
Source: crates/python/src/live.rs:372
list_input_devices
builtin
¶
Returns the names of available cpal input devices on the default
host. Names may not be unique across hosts; for stable identifiers
across reboots, hold onto the string returned by
[default_input_device] and pass it back to [start_session].
Source: crates/python/src/live.rs:436
default_input_device
builtin
¶
Returns the default input device's name, or None if there isn't
one.
Source: crates/python/src/live.rs:453
LiveSession ¶
Live recording session. Construct via [start_session]; register
callbacks via on_meter / on_pitch / on_intensity / on_formants;
then start() → stop() → commit() or discard().
Source: crates/python/src/live.rs:128
frames_written
property
¶
Number of samples (post-downmix mono frames) written to disk.
Source: crates/python/src/live.rs:284
dropped_samples
property
¶
Number of samples dropped due to consumer back-pressure. Non-zero means the recording is imperfect.
Source: crates/python/src/live.rs:291
duration_seconds
property
¶
Duration of the recording in seconds. 0.0 while still
capturing.
Source: crates/python/src/live.rs:301
in_progress_dir
property
¶
Path to the .in_progress/<uuid>/ directory as a string.
Source: crates/python/src/live.rs:310
start
method descriptor
¶
Begins capture. Builds the cpal input stream against the
requested device and starts the audio thread. Idempotent: a
second call returns Ok without rebuilding the stream.
Source: crates/python/src/live.rs:175
stop
method descriptor
¶
Stops the capture, joins the cpal-stream and dispatch threads,
and flushes the WAV writer. After stop() the session waits
for commit() or discard(). Idempotent.
Source: crates/python/src/live.rs:229
commit
method descriptor
¶
Atomically commits the recording into the parent project.
Returns the new bundle id. Errors if the session has not been
stopped, or if a bundle named name already exists.
Source: crates/python/src/live.rs:259
discard
method descriptor
¶
Discards the in-progress recording (deletes the directory). Errors if the session has not been stopped.
Source: crates/python/src/live.rs:274
on_meter
method descriptor
¶
Registers a callable invoked once per drained chunk with
(peak, rms, rms_db, time_seconds). Returns the callable
unchanged so the method can be used as a decorator.
Source: crates/python/src/live.rs:143
on_pitch
method descriptor
¶
Registers a callable invoked once per analysis hop with
(frequency_hz, voiced: bool, time_seconds). voiced is
voicing >= 0.45 (Boersma's recommended threshold).
Source: crates/python/src/live.rs:151
on_intensity
method descriptor
¶
Registers a callable invoked once per analysis hop with
(db_fs, time_seconds).
Source: crates/python/src/live.rs:158
on_formants
method descriptor
¶
Registers a callable invoked once per analysis hop with
(frequencies: list[float], bandwidths: list[float],
time_seconds). Both lists are co-indexed and the same length
(which varies per frame).
Source: crates/python/src/live.rs:167