Python API

Decibri ships a native Python package with synchronous Microphone and Speaker classes plus matching AsyncMicrophone and AsyncSpeaker classes for asyncio. Written in Rust (via PyO3 / abi3) with pre-built wheels for Python 3.10 and newer. For installation and first capture, see Getting started.

Quickstart

Three ways to get audio into and out of Python, in order of increasing control.

Install

Recommended with uv:

Or with pip:

For NumPy ndarray support (see Audio format):

Record to a file in one line

import decibri

decibri.record_to_file("output.wav", duration_seconds=10)

Captures 10 seconds of microphone audio to a 16-bit PCM WAV file at 16 kHz mono. No async, no streaming, no setup.

Stream chunks with a with block

import decibri

with decibri.Microphone(sample_rate=16000) as mic:
    for chunk in mic:
        print(f"Got {len(chunk)} bytes")
        break

Open the system microphone, iterate raw 16-bit PCM chunks, break after the first. Replace break with your processing pipeline.

Async parallel

import asyncio
import decibri

async def main():
    async with await decibri.AsyncMicrophone.open(sample_rate=16000) as mic:
        async for chunk in mic:
            print(f"Got {len(chunk)} bytes")
            break

asyncio.run(main())

Same loop, but on the event loop. Use this in voice agents or websocket pipelines.

Compatibility

Pre-built wheels are published for every supported platform. pip install decibri fetches a binary wheel; no Rust toolchain, no C compiler, and no system audio headers are required at install time.

Wheels are built against the CPython stable ABI (abi3) with a 3.10 floor, so a single wheel per platform serves every supported interpreter version. New CPython releases work without a new Decibri release as long as the stable ABI is preserved. The Windows ARM64 wheel carries the same abi3 tag, but the oldest Python it supports is 3.11, the first CPython release published for that platform.

Microphone (sync)

Primary capture surface for synchronous code. Construct an instance, enter a with block (or call start() manually), then iterate or call read() for chunks.

Constructor

decibri.Microphone(
    sample_rate=16000,
    channels=1,
    frames_per_buffer=1600,
    dtype="int16",
    device=None,
    vad=False,
    model_path=None,
    as_ndarray=False,
    ort_library_path=None,
    denoise=None,
    highpass=None,
    agc=None,
    limiter=None,
    dc_removal=False,
    aec=None,
    channel_map=None,
)

The five conditioning options (dc_removal, denoise, highpass, agc, limiter) are off by default and run as a fixed chain before each chunk is delivered. They are documented in full on the Audio Capture Engine page. Above one delivered channel, DC removal, denoise and the high-pass run on each channel with its own state, while AGC and the limiter are linked: one detector measures across all the channels and one gain is applied to all of them, which keeps the balance between the channels.

Echo cancellation is a separate opt-in capture parameter, aec, documented in Acoustic Echo Cancellation (AEC) below. It is the one capture option that also needs a second audio stream from you at run time.

Channels

channels is a delivered count: the number of channels in every chunk you read, interleaved frame by frame, so a chunk holds frames_per_buffer * channels samples. It works the way sample_rate does. The device itself is always opened at its own native channel count, the figure MicrophoneInfo.max_input_channels reports, and Decibri derives the delivered channels from what the device gives it.

Without a channel_map, two counts can be derived:

• channels=1, the default, delivers the average of every device channel.
• A count equal to the device's own delivers every device channel, in device order.

Any other count above 1 without a map is refused by start(), because the device's channel count is only read when the stream opens. A count above the device's own raises MicrophoneChannelsUnsupported, because Decibri cannot deliver a channel the device does not have. A count above 1 but below the device's own raises ChannelSelectionAmbiguous, because it does not say which of the device's channels it means. A channel_map lifts both refusals, because it names every delivered channel.

channel_map names device channels. It is a list of 0-based device channel indices with one entry per delivered channel, so its length must equal channels: delivered channel j carries device channel channel_map[j]. Entries may repeat and their order is significant, so a map can select, reorder and duplicate device channels, and it can deliver more channels than the device has. channel_map=[1] with channels=1 delivers the device's second channel alone, and channel_map=[1, 0] with channels=2 swaps a stereo pair. Every entry must name a channel the device has.

Vad(source=...) names a delivered channel. It is a position in the chunk you read, counted after channel_map has been applied, and never a device index. None, the default, feeds the voice activity detector the frame average of every delivered channel; an integer feeds it that one delivered channel. It must be below channels, and it changes only what the detector reads, not the audio you receive.

import decibri

# Needs a device with at least three input channels.
# Deliver device channels 2 and 0, in that order. source=0 names
# delivered channel 0, which carries device channel 2.
with decibri.Microphone(
    channels=2,
    channel_map=[2, 0],
    vad=decibri.Vad(model="silero", source=0),
) as mic:
    for chunk in mic:
        process(chunk)  # interleaved frames: device channel 2, then device channel 0

The constructor checks everything that does not need the device. start() checks the rest against the resolved device, and a with block calls start() on entry, so the three device refusals surface there. AsyncMicrophone raises the same errors, from its constructor and from await mic.start().

The six named classes are DecibriError subclasses; TypeError and ValueError are Python built-ins. The type and range of source itself are checked when the Vad is built; see Voice activity detection. There is no MultichannelNotSupported class: nothing raises it, and importing it fails.

Context manager usage

The canonical Python pattern. Entering the with block opens the stream and starts capture; exiting stops the stream and resets VAD state, even if an exception propagates out.

import decibri

with decibri.Microphone(sample_rate=16000, channels=1, frames_per_buffer=1600) as mic:
    for chunk in mic:
        process(chunk)
        if done():
            break

Calling start() manually is also supported when the context manager does not fit. Pair it with stop() in a try / finally.

Methods

mic.start()

Open and start the capture stream. Calling start() after stop() or close() is supported and reconstructs the stream cleanly; VAD state resets on each new start(). Calling start() on an already-running instance raises AlreadyRunning. This is where channels and channel_map are checked against the resolved device; see Channels.

mic.stop()

Stop the capture stream and reset VAD state and the sequence counter. Idempotent; safe to call multiple times.

mic.close()

Alias for stop(). Provided for ergonomic parity with the asyncio / aiohttp / httpx convention. The two methods are currently equivalent and are intended to remain interchangeable.

mic.read(timeout_ms=None)

Read one chunk. Returns the chunk, or None if the stream closed. Return type is bytes by default, or numpy.ndarray when the Microphone was constructed with as_ndarray=True. Above one channel the chunk holds interleaved frames: bytes carry the channels frame by frame, and an ndarray is shaped (frames, channels). Advances VAD state as a side effect when VAD is enabled.

mic.read_with_metadata(timeout_ms=None)

Read one chunk and return it as a frozen Chunk with .data, .timestamp, .sequence, .is_speaking, and .vad_score attributes. Returns None on clean stream close. See Value types.

mic.iter_with_metadata()

Generator yielding Chunk objects until the stream closes cleanly. Use this in place of for chunk in mic when you want metadata alongside the audio data.

with decibri.Microphone(vad="silero") as mic:
    for chunk in mic.iter_with_metadata():
        if chunk.is_speaking:
            send_to_stt(chunk.data)

iter(mic) and next(mic)

The Microphone is itself an iterator. for chunk in mic: yields the raw data shape (bytes or numpy.ndarray) and raises StopIteration when the stream closes.

Properties

mic.is_open

bool (read-only). Returns True while the capture stream is currently running.

mic.is_speaking

bool (read-only). Returns True while VAD considers the user to be speaking, including the holdoff grace period. Always False when vad=False. Holdoff expiry is checked on every property access, so consumers who pause iteration still observe correct state when they next read.

mic.vad_score

float in [0, 1], mode-agnostic. In vad="silero" mode this is the raw Silero probability for the most recent chunk; in vad="energy" mode it is the normalised RMS energy. Above one delivered channel both modes score the frame average of the delivered channels, or the one channel Vad(source=...) names. Always 0.0 when vad=False.

mic.overrun_count

int (read-only). Number of capture buffers dropped because the consumer could not keep pace. 0 while the consumer keeps up, before capture starts, and after stop(), which releases the stream the counter lives on, so read it before stopping to see a session's total. A rising value means audio is being dropped to bound memory. The sync Microphone carries it; AsyncMicrophone does not.

Static methods

Microphone.devices()

Returns a list of MicrophoneInfo objects describing every input device recognised by the operating system.

for d in decibri.Microphone.devices():
    print(d.index, d.name, d.default_sample_rate)

Microphone.version()

Returns a VersionInfo object with the Rust core version, the audio backend version, and the binding wheel version.

All Microphone instances support repr() for debugging; the output includes sample rate, channels, dtype, frames per buffer, device, VAD mode, and open state.

Speaker (sync)

Audio output surface. Construct, enter a with block, write samples, and drain.

Constructor

decibri.Speaker(
    sample_rate=16000,
    channels=1,
    dtype="int16",
    device=None,
)

Context manager usage

import decibri

with decibri.Speaker(sample_rate=16000, channels=1) as spk:
    spk.write(audio_bytes)
    spk.drain()

Methods

spk.start()

Open and start the output stream. Re-entry after stop() or close() is supported.

spk.stop()

Stop the output stream.

spk.close()

Alias for stop(). See Microphone.close() for the equivalence note.

spk.write(samples)

Write a chunk to the output stream. Accepts bytes or a numpy.ndarray with dtype matching the configured dtype. Multi-channel ndarrays use shape (N, channels). Output streams duck-type the input on each call rather than committing at construction time; mixing bytes and ndarrays across calls is supported. Raises TypeError on dtype mismatch or unsupported input.

spk.drain()

Block until all queued samples have been played. Useful at the end of a playback sequence so the program does not exit before the speaker buffer empties.

Properties

spk.is_playing

bool (read-only). Returns True while the output stream is currently running.

spk.underrun_count

int (read-only). Number of samples played as silence because the playback queue ran dry. 0 while the producer keeps the queue fed, or before playback starts. A rising value means the output is filling gaps with silence. The sync Speaker carries it; AsyncSpeaker does not.

Static methods

Speaker.devices()

Returns a list of SpeakerInfo objects describing every output device recognised by the operating system.

File (sync)

Offline audio source. A File runs a recording, or samples you already hold, through the same conditioning chain as Microphone, and delivers the same chunk shape. Because a recording has an end, it can also score the whole thing for speech in one pass with analyze(). The feature page is Audio File Processor (AFP).

Constructor

decibri.File(
    path,
    sample_rate=16000,
    channels=1,
    channel_map=None,
    dtype="int16",
    vad=False,
    model_path=None,
    as_ndarray=False,
    ort_library_path=None,
    denoise=None,
    highpass=None,
    agc=None,
    limiter=None,
    dc_removal=False,
)

Every parameter after path is keyword-only. An unknown keyword raises TypeError.

The five conditioning options behave exactly as they do on Microphone, in the same fixed chain, and are documented in full on the Audio Capture Engine page.

channels, channel_map and Vad(source=...) follow the Microphone rules in Channels, with the source's own channel count standing where the device's stands: the file's header for a path, or input_channels for File.buffer. That count is known as soon as the source is opened, so every channel refusal is raised by the constructor, with its own class.

Context manager usage

File is a context manager. Entering the block hands back the same instance; exiting closes the source.

import decibri

with decibri.File("clip.wav", denoise="fastenhancer-t", agc=-18) as file:
    for chunk in file:
        handle(chunk)  # 3,200 bytes per full chunk at dtype="int16"

A full chunk is 1,600 frames at the target rate, each frame carrying one sample per delivered channel: at the default one channel that is 3,200 bytes as int16 and 6,400 bytes as float32, and it grows with channels. The final chunk is shorter whenever the total does not divide evenly.

Alternate constructors

File.open(path, **kwargs)

Classmethod, identical to File(path, **kwargs) and accepting the same keywords. It is an alternate spelling of the constructor, not an async variant; for asyncio use AsyncFile.

File.buffer(samples, *, input_rate, input_channels=1, **kwargs)

Wraps in-memory samples instead of reading a file. samples is a list of floats or a numpy.ndarray with a floating dtype, in the range -1.0 to 1.0, frame-interleaved at input_channels. Raw samples carry no header, so input_rate (their native rate, 1,000 to 384,000) is a mandatory keyword-only argument, and input_channels (default 1, mono) is its channel counterpart. At one input channel an ndarray must hold one channel: a redundant axis, (N, 1) or (1, N), is accepted, and an array with two axes longer than 1 raises ValueError. Above one input channel an ndarray is either 1-D and interleaved or 2-D (frames, input_channels), and the sample count must be a whole number of frames, or BlockSizeNotFrameAligned is raised. Every other keyword matches the constructor, so channels and channel_map choose what is delivered from those input channels.

file = decibri.File.buffer(samples, input_rate=48000, sample_rate=16000)

# pairs: a float32 ndarray shaped (frames, 2). Deliver both channels.
stereo = decibri.File.buffer(pairs, input_rate=48000, input_channels=2, channels=2)

This is also the route for any audio the reader rejects, an MP3 or an Opus file for example: decode it yourself, convert to floats in -1.0 to 1.0, and pass the source rate as input_rate and its channel count as input_channels. The conditioning chain then behaves identically to the path constructor. WAV, AIFF, AIFF-C and FLAC do not need it; the path constructor opens those directly.

Single-pass lifecycle

Iteration, analysis and saving are three alternatives, and each reads the source from beginning to end. Use one File per operation.

• analyze() after iteration has begun raises FileEngaged. Any call that advances the cursor marks the File engaged, including one that returns nothing: on an empty recording the first read() returns None and a later analyze() still raises.
• save() follows the same rule and checks it in the same order: after iteration has begun it raises FileEngaged, before any argument is interpreted, so a bad format on an engaged File reports the engagement rather than the argument.
• A second pass raises FileConsumed. That covers calling analyze() twice, saving twice, and iterating a File that has already been analysed or saved.
• Iterating a File that has been drained or closed yields nothing rather than raising. Only analysis and saving report the consumed state.
• A rejected analyze() that never touched the source leaves the File iterable: both VadNotConfigured and the energy-mode refusal return before the pass begins.
• close() is idempotent, and the four accessors keep returning their pre-close values afterwards.

Methods

file.read()

Read one conditioned chunk. Returns the chunk, or None at the end of the source. Return type is bytes by default, or numpy.ndarray when the File was constructed with as_ndarray=True. Advances VAD state as a side effect when VAD is enabled.

file.read_with_metadata()

Read one chunk and return it as a frozen Chunk, or None at the end. On a File, Chunk.timestamp is the chunk's position in seconds of file time from the start of the recording, not a time.monotonic() snapshot, and Chunk.is_speaking applies the holdoff in file time. See Value types.

file.iter_with_metadata()

Generator yielding Chunk objects until the end of the source.

with decibri.File("clip.wav", vad="silero") as file:
    for chunk in file.iter_with_metadata():
        if chunk.is_speaking:
            send_to_stt(chunk.data)

iter(file) and next(file)

The File is itself an iterator. for chunk in file: yields the raw data shape (bytes or numpy.ndarray) and raises StopIteration at the end of the source.

file.analyze() and file.analyse()

Score the whole recording for voice activity in one pass and return a VadReport. Requires vad="silero": a File built without a VAD configuration raises VadNotConfigured, and energy mode raises ValueError because it has no whole-recording analysis. Above one delivered channel it scores the frame average of the delivered channels, or the one channel Vad(source=...) names. On the sync class the two spellings are one object: File.analyse is File.analyze is True.

report = decibri.File("clip.wav", vad="silero").analyze()

report.scores    # list[VadWindow]: start, end, vad_score, is_speech
report.segments  # list[Segment]:   start, end

file.save(path, *, format=None, compression=None)

Run the recording once through the conditioning chain, whole, and write it to path. Returns a SaveReport. Both keyword arguments are keyword-only, and the pass consumes the source exactly as analyze() does.

Output is 16-bit PCM at sample_rate, in every one of the three containers, at the delivered channel count and interleaved: the same layout iteration delivers, so one channel unless channels asks for more. Each container's own channel ceiling applies, and a save above it raises AudioFormatUnsupported carrying the container layer's own text: FLAC carries at most 8 channels, and a 16-bit WAV at most 32767. Decibri adds no ceiling of its own. Decibri reads a file by its content and writes one by its name, which is why a save needs an extension or an explicit format and a read needs neither.

file = decibri.File("noisy.wav", denoise="fastenhancer-t", agc=-18, limiter=-1.0)
report = file.save("clean.flac", compression=8)

report.clipped_samples     # int
report.non_finite_samples  # int

file.close()

Release the source. Idempotent; a closed File reads as ended.

Properties

file.sample_rate

int (read-only). The target output rate every delivered chunk carries.

file.input_rate

int (read-only). The source's own rate, read from the file's header or taken from the input_rate passed to File.buffer. Differs from sample_rate whenever the recording is resampled.

file.is_speaking

bool (read-only). Whether per-chunk VAD currently considers speech present. The holdoff is measured in file time (sample positions), not wall-clock time, so processing speed never changes the reported state. Always False when vad=False.

file.vad_score

float in [0, 1] (read-only). The most recent per-chunk score, computed on the signal before conditioning. Always 0.0 when vad=False.

Errors

Every class below except the plain ValueError, TypeError, and ImportError rows is a DecibriError subclass, so a single except decibri.DecibriError catches the typed failures.

Vad(threshold=...), Vad(holdoff_ms=...), and the type and range of Vad(source=...) validate inside the Vad constructor, so those errors are raised before File is reached. Only the check of source against channels belongs to File, as DetectorSourceOutOfRange. See Voice activity detection.

AsyncMicrophone

When to use async

Reach for AsyncMicrophone when capture lives on an event loop: a voice agent that streams chunks to a websocket, a coroutine-based pipeline, or anywhere a sibling task may need to cancel the read in flight. The async classes serialise concurrent calls via a Rust-side Tokio mutex, so sibling-task cancellation is safe in a way that the sync Microphone does not provide.

Constructor

Parameters match Microphone exactly. See the Microphone section for the full parameter table.

mic = decibri.AsyncMicrophone(sample_rate=16000, vad="silero")

await AsyncMicrophone.open(...)

Async factory classmethod. The synchronous constructor blocks for roughly 100 to 500 milliseconds when vad="silero" because it loads the Silero ONNX model inline. open() dispatches that load to loop.run_in_executor(None, ...) so the event loop keeps spinning while ORT initialises.

mic = await decibri.AsyncMicrophone.open(vad="silero")
async with mic:
    async for chunk in mic:
        await process(chunk)

async with and async for

The async context manager opens the stream on entry and stops it on exit. Iteration via async for yields the same data shape as the sync Microphone (bytes by default, numpy.ndarray when as_ndarray=True).

async with await decibri.AsyncMicrophone.open(sample_rate=16000) as mic:
    async for chunk in mic:
        await websocket.send(chunk)

Methods

await mic.start()

Open and start the capture stream. Re-entry after stop() or close() is supported and resets VAD state.

await mic.stop()

Stop the capture stream and reset VAD state and the sequence counter.

await mic.close()

Alias for stop(). See Microphone.close() for the equivalence note.

await mic.read(timeout_ms=None)

Read one chunk. Returns the chunk, or None if the stream closed. Same return-type rules as the sync read().

await mic.read_with_metadata(timeout_ms=None)

Async parallel of Microphone.read_with_metadata(). Returns a frozen Chunk with metadata, or None on clean close.

mic.aiter_with_metadata()

Async-generator function yielding Chunk objects until the stream closes cleanly. Stops when the bridge returns None.

async with await decibri.AsyncMicrophone.open(vad="silero") as mic:
    async for chunk in mic.aiter_with_metadata():
        if chunk.is_speaking:
            await stt.send(chunk.data)

Properties

Properties on AsyncMicrophone are synchronous attribute access (no await). They are backed by lock-free atomic mirrors on the Rust bridge, so they report current truth even when the Rust side closes the stream itself (for example, device disconnect).

mic.is_open

bool (read-only). True while the capture stream is running.

mic.is_speaking

bool (read-only). Same semantics as the sync property: above-threshold detection plus holdoff. Always False when vad=False.

mic.vad_score

float in [0, 1]. Same semantics as the sync property.

Static methods

await AsyncMicrophone.devices()

Async parallel of Microphone.devices(). Returns a list of MicrophoneInfo.

AsyncMicrophone.version()

Synchronous (see the callout above). Returns a VersionInfo for the Rust core, the audio backend, and the binding wheel.

Cancellation semantics

Cancelling an awaited AsyncMicrophone call (via asyncio.CancelledError, asyncio.wait_for, or explicit task.cancel()) raises CancelledError immediately on the Python side. The Rust-side spawn_blocking thread completes on its own schedule and its result is dropped. The bridge state stays consistent for subsequent reads, so sibling-task cancellation while a read() is in flight is safe.

AsyncSpeaker

Asyncio mirror of Speaker. Same parameter set, same lifecycle, all methods coroutines.

Constructor

Parameters match Speaker exactly. See the Speaker section for the parameter table.

spk = decibri.AsyncSpeaker(sample_rate=24000, channels=1)

await AsyncSpeaker.open(...)

Async factory classmethod, symmetric with AsyncMicrophone.open. Speaker does not load ORT, so the event-loop blocking risk is smaller, but the factory is provided for API parity.

async with usage

async with decibri.AsyncSpeaker(sample_rate=24000) as spk:
    await spk.write(audio_bytes)
    await spk.drain()

Methods

await spk.start()

Open and start the output stream.

await spk.stop()

Stop the output stream.

await spk.close()

Alias for stop(). See Microphone.close() for the equivalence note.

await spk.write(samples)

Async parallel of Speaker.write. Accepts bytes or a numpy.ndarray with matching dtype.

await spk.drain()

Block until all queued samples have been played. Cancelling this await raises CancelledError immediately, but the audio continues to play until the output buffer empties on the callback's own schedule. For production code, complete drains before initiating new writes.

Properties

spk.is_playing

bool (read-only). Synchronous property backed by a lock-free atomic mirror on the bridge.

Static methods

await AsyncSpeaker.devices()

Async parallel of Speaker.devices().

AsyncFile

Asyncio mirror of File. Same parameters, same single-pass lifecycle, same errors; the file read, the conditioning pass, and detection each run in the default ThreadPoolExecutor so the event loop keeps spinning.

Constructors

AsyncFile(path, **kwargs) takes exactly the parameters File takes, and reads the file inline. Prefer the factory inside a running event loop:

• await AsyncFile.open(path, **kwargs): the async factory. Identical result to the bare constructor, with the read dispatched off the event loop.
• await AsyncFile.buffer(samples, *, input_rate, **kwargs): the async parallel of File.buffer. Unlike the sync class, this one is a coroutine.

import asyncio
import decibri

async def main():
    file = await decibri.AsyncFile.open("clip.wav", denoise="fastenhancer-t")
    async with file:
        async for chunk in file:
            await handle(chunk)

asyncio.run(main())

Methods

await file.read()

Read one chunk. Returns the chunk, or None at the end of the source. Same return-type rules as the sync read().

await file.read_with_metadata()

Async parallel of File.read_with_metadata(). Returns a frozen Chunk whose timestamp is file time in seconds, or None at the end.

file.aiter_with_metadata()

Async-generator function yielding Chunk objects until the end of the source. Iterate it with async for chunk in file.aiter_with_metadata():; do not await the call itself.

await file.analyze() and await file.analyse()

Score the whole recording and return a VadReport, with the single pass running off the event loop. The same requirements as the sync method: vad="silero", and a source that iteration has not yet touched. Unlike the sync class, the two spellings are two callables here (AsyncFile.analyse is AsyncFile.analyze is False); they return equal reports.

file = await decibri.AsyncFile.open("clip.wav", vad="silero")
report = await file.analyze()

for segment in report.segments:
    print(segment.start, segment.end)

await file.save(path, *, format=None, compression=None)

Async parallel of File.save(), with the single conditioning and encode pass running off the event loop. Same signature, same keyword-only arguments, same SaveReport, and the same contract: the container comes from the extension or from format, compression sets the FLAC level, output is 16-bit PCM at sample_rate and at the delivered channel count, each container's own channel ceiling applies, and the source is consumed. Requires an AsyncFile whose iteration has not begun; after that it raises FileEngaged.

file = await decibri.AsyncFile.open("noisy.wav", denoise="fastenhancer-t")
report = await file.save("clean.wav")

print(report.clipped_samples, report.non_finite_samples)

await file.close()

Release the source. Idempotent. AsyncFile is an async context manager, so async with file: closes it on exit.

Properties

The four accessors are synchronous attribute access, with the same semantics as the sync class: sample_rate, input_rate, is_speaking, and vad_score.

Module-level helpers

Convenience entry points exposed directly on the decibri module.

decibri.input_devices()

Module-level shortcut for Microphone.devices(). Returns a list of MicrophoneInfo.

for d in decibri.input_devices():
    print(d.index, d.name)

decibri.output_devices()

Module-level shortcut for Speaker.devices(). Returns a list of SpeakerInfo.

decibri.version()

Returns a VersionInfo for the Rust core, the audio backend, and the binding wheel.

v = decibri.version()
print(v.decibri, v.audio_backend, v.binding)

decibri.record_to_file(path, duration_seconds, sample_rate=16000, channels=1, device=None)

Synchronous one-shot recorder. Captures duration_seconds of microphone audio to a 16-bit PCM WAV file. Wraps Microphone plus the standard library wave module. Frame-count termination guarantees an accurate duration even on platforms where the buffer hint is ignored by the OS audio subsystem.

channels=1 writes the average of every device channel, and a count equal to the device's own writes every device channel, interleaved. The helper takes no channel_map, so a strict subset of the device's channels needs a Microphone with a channel_map; any other count above 1 is refused exactly as Microphone.start() refuses it. See Channels.

decibri.record_to_file("clip.wav", duration_seconds=5.0)

await decibri.async_record_to_file(path, duration_seconds, sample_rate=16000, channels=1, device=None)

Async parallel of record_to_file. Same parameters, same semantics; await it from an asyncio context.

await decibri.async_record_to_file("clip.wav", duration_seconds=5.0)

Value types

Small typed return shapes used across the API.

Chunk

Frozen dataclass returned by read_with_metadata() and iter_with_metadata() on Microphone, AsyncMicrophone, File, and AsyncFile.

VadReport

Frozen dataclass returned by File.analyze() and await AsyncFile.analyze(). It has exactly two attributes.

SaveReport

Frozen dataclass returned by File.save() and await AsyncFile.save(). It records what the write did to the samples on their way into the file.

VadWindow

One scored analysis window, carried in VadReport.scores. Windows tile the recording from zero, contiguous and non-overlapping, 0.032 seconds each; a trailing remainder shorter than one window is left unscored.

Segment

One merged speech region, carried in VadReport.segments. Consecutive speech windows whose silence gaps fall within the configured holdoff collapse into one segment, and a segment ends at its last speech window rather than at the holdoff expiry.

MicrophoneInfo

Returned by Microphone.devices(), decibri.input_devices(), and await AsyncMicrophone.devices().

SpeakerInfo

Returned by Speaker.devices(), decibri.output_devices(), and await AsyncSpeaker.devices().

VersionInfo

Returned by Microphone.version(), AsyncMicrophone.version(), and decibri.version().

Voice activity detection

Decibri ships two VAD modes plus a disabled default. All three are selected with the vad constructor parameter on Microphone and AsyncMicrophone.

Both detectors read one mono signal. Above one delivered channel that signal is the frame average of every delivered channel, unless Vad(source=...) names one delivered channel for the detector to read instead. vad_score and is_speaking describe that signal; the audio you receive is not changed by it.

Tuning with the decibri.Vad object

To tune the threshold or holdoff, or to choose the delivered channel the detector reads, pass a decibri.Vad object as the vad argument instead of a bare mode string. Vad is a frozen dataclass, so vad="silero" is shorthand for vad=decibri.Vad(model="silero") with default tuning.

mic = decibri.Microphone(vad=decibri.Vad(model="silero", threshold=0.6, holdoff_ms=200))

Holdoff and the is_speaking state machine

Decibri runs a pure-Python state machine on top of the raw VAD probability. Above-threshold chunks set the speaking state and cancel any pending silence timer. Below-threshold chunks while already speaking start a silence timer; the timer expires after the Vad object's holdoff_ms (default 300) of elapsed real time, at which point is_speaking flips back to False. Timer expiry is checked on every property access via time.monotonic(), so consumers who pause iteration still observe correct state on the next read.

is_speaking vs vad_score

is_speaking is the debounced state machine output: above the threshold plus the holdoff grace. vad_score is the raw per-chunk view, identical to the Silero probability in Silero mode and the normalised RMS in energy mode. Use is_speaking for gating downstream work; use vad_score when you need the underlying signal (for example, to threshold differently per chunk or to log probability distributions).

Custom Silero model with model_path

The bundled Silero model is the published Silero v6.2 checkpoint. To use a different Silero ONNX variant, pass an absolute path on the model_path constructor parameter. The path is only consulted when vad="silero"; energy mode and vad=False ignore it.

mic = decibri.Microphone(vad="silero", model_path="/opt/models/silero_vad_v4.onnx")

Acoustic Echo Cancellation (AEC)

Echo cancellation removes the sound of your own loudspeaker from the microphone capture. It is opt-in through the aec parameter on Microphone and AsyncMicrophone. Unlike every other capture option, it also needs a second audio stream at run time: the audio you are playing, pushed block by block for as long as you are playing it.

The plumbing, the diagnostics procedure, and the limits of the technique are on the Acoustic Echo Cancellation (AEC) feature page. This section is the Python surface.

The aec parameter

Signature: aec: str | Aec | None = None.

from decibri import Aec, Microphone

# Short form: the model with its defaults.
a = Microphone(sample_rate=16000, aec="tau")

# Object form: the same model, every option set to its default.
b = Microphone(
    sample_rate=16000,
    aec=Aec(
        model="tau",
        tail_ms=200,
        suppression="conservative",
        reference_sample_rate=16000,
        reference_channels=1,
    ),
)

Echo cancellation requires sample_rate between 8000 and 48000, narrower than the range sample_rate otherwise accepts. It runs on every delivered channel: one canceller per delivered channel, each fed the same pushed reference and each finding its own channel's echo delay, so its processing cost grows with channels. It is available on native capture only and is not a File parameter. The browser build does not carry it. See the Browser API.

decibri.Aec

Frozen dataclass carrying the tuning. Assigning to a field after construction raises dataclasses.FrozenInstanceError. Build a new instance instead.

@dataclass(frozen=True, slots=True)
class Aec:
    model: str = "tau"
    tail_ms: int | None = None                 # 16 to 500, None takes 200
    suppression: str | None = None             # "conservative" or "off", None takes "conservative"
    reference_sample_rate: int | None = None   # 1000 to 384000, None takes the capture rate
    reference_channels: int = 1                # at least 1, the interleave of what you push

The declared reference_channels must match what you push. A mismatch is not detected and raises no error: the frames are misread, nothing is cancelled, and aec_metrics().delay_samples stays None. The canceller reads one mono reference, so with playback through more than one loudspeaker whose echo paths differ, some echo remains that adaptation does not remove.

Methods

mic.push_aec_reference(samples)

Signature push_aec_reference(samples: SampleData) -> None, identical on Microphone and AsyncMicrophone. Push the audio you played, as you played it, in the order it was played, in the same dtype the microphone was constructed with, interleaved at reference_channels (mono by default). bytes and 1-D or 2-D ndarrays are accepted, the input shapes Speaker.write accepts. One push serves every delivered channel.

The push method never blocks and never raises on a full queue. Samples that do not fit are discarded and counted in reference_dropped. A push while capture is not running, or with the option unset, does nothing and is not counted in reference_dropped. A bad input type raises regardless of capture state.

mic.aec_metrics()

Signature aec_metrics() -> AecMetrics | None. Returns None when the aec option is unset or capture is not running, and an AecMetrics otherwise. Read it while capture is still running; after stop() it returns None.

AecMetrics

Frozen dataclass returned by aec_metrics().

@dataclass(frozen=True, slots=True)
class AecMetrics:
    delay_samples: int | None
    erle_db: float
    double_talk: bool
    reference_starved: int
    acquisition_parked: int
    reference_reanchors: int
    reference_dropped: int
    reference_silence: int
    channels: tuple[AecChannelMetrics, ...]

The first six fields report the canceller on the first delivered channel. reference_dropped and reference_silence describe the one reference queue that every channel's canceller shares. On a one-channel capture, channels holds a single entry that agrees with the top-level fields.

The diagnostics section of the feature page reads these fields as a procedure rather than a field list.

AecChannelMetrics

Frozen dataclass, one entry of AecMetrics.channels: the report of the canceller on one delivered channel. It carries the six canceller fields and not the two queue counters, which stay on AecMetrics. Importable from decibri.

@dataclass(frozen=True, slots=True)
class AecChannelMetrics:
    delay_samples: int | None
    erle_db: float
    double_talk: bool
    reference_starved: int
    acquisition_parked: int
    reference_reanchors: int

Each channel's canceller finds its own echo delay, so the entries differ where the channels' acoustic paths differ. erle_db is not a ranking across channels: it rises with echo distance, because a weaker echo is easier to reduce in ratio terms, so a far microphone can report a higher figure than a near one while removing less echo in absolute terms. Compare a channel with its own history, not with its neighbours.

The async surface

On AsyncMicrophone, the two members do not match, and the difference is deliberate.

push_aec_reference is a plain method. You call it, you do not await it. The push never blocks, so making it a coroutine would add an await to a call that has nothing to wait for, and would stop you calling it from a synchronous render callback. It has the same signature on Microphone and AsyncMicrophone.

aec_metrics is a coroutine and must be awaited. Reading the metrics serialises against block processing on the capture chain, so it can wait; awaiting keeps that wait off the event loop.

mic.push_aec_reference(block)      # no await
metrics = await mic.aec_metrics()  # await

import asyncio

from decibri import AsyncFile, AsyncMicrophone, AsyncSpeaker

RATE = 16000


async def main():
    async with AsyncFile("speech.wav", sample_rate=RATE) as f:
        audio = b"".join([chunk async for chunk in f])

    block_bytes = RATE // 10 * 2

    async with (
        AsyncMicrophone(sample_rate=RATE, aec="tau") as mic,
        AsyncSpeaker(sample_rate=RATE) as speaker,
    ):
        for i in range(0, len(audio), block_bytes):
            block = audio[i : i + block_bytes]
            await speaker.write(block)
            mic.push_aec_reference(block)     # not awaited
            near = await mic.read(timeout_ms=100)

        metrics = await mic.aec_metrics()     # awaited


asyncio.run(main())

Errors

Python has typed exceptions for its own failure modes and uses them. Catch them in the idiom of the language you are in, not in a shape shared across both bindings; the Node.js API raises different classes on purpose.

Where the check happens differs. Aec(...) validates tail_ms, suppression, reference_sample_rate and reference_channels at construction, before any microphone exists, so those raise from the config object. The model name is not checked there; an unknown name raises from the Microphone constructor, as does the capture rate constraint.

AecConfigInvalid, AecSampleRateUnsupported and SampleRateOutOfRange all subclass DecibriError, so except DecibriError catches all three. They are importable from decibri and from decibri.exceptions.

from decibri import Aec, Microphone
from decibri.exceptions import AecConfigInvalid, AecSampleRateUnsupported

try:
    mic = Microphone(sample_rate=64000, aec="tau")
except AecSampleRateUnsupported:
    mic = Microphone(sample_rate=48000, aec="tau")

Audio format

Decibri supports two on-the-wire sample formats, selected with the dtype constructor parameter. Both apply to Microphone, Speaker, and their async variants.

int16 (default)

Each two bytes represents one 16-bit signed integer sample, little-endian. Range: -32,768 to 32,767. Two bytes per sample. This is the format expected by most cloud STT providers and the wire format used by the record_to_file helpers.

with decibri.Microphone(dtype="int16") as mic:
    chunk = mic.read()  # bytes; len(chunk) == frames * channels * 2

float32

Each four bytes represents one 32-bit IEEE 754 float sample, little-endian. Range: approximately -1.0 to 1.0. Four bytes per sample. Use this when your downstream pipeline expects normalised floats and you would otherwise convert from int16.

with decibri.Microphone(dtype="float32") as mic:
    chunk = mic.read()  # bytes; len(chunk) == frames * channels * 4

NumPy integration

Set as_ndarray=True on the Microphone constructor to receive numpy.ndarray instead of bytes from read(). The array's dtype matches the configured dtype (np.int16 or np.float32). Its shape follows channels: 1-D (frames,) at one channel, and 2-D (frames, channels) above one, one row per frame.

import decibri
import numpy as np

with decibri.Microphone(sample_rate=16000, dtype="float32", as_ndarray=True) as mic:
    chunk = mic.read()
    assert isinstance(chunk, np.ndarray)
    assert chunk.dtype == np.float32

Speaker.write() duck-types on each call: pass bytes or pass an ndarray with matching dtype. Mixing both within a single output session is supported.

The NumPy extra is opt-in to keep the default install lightweight:

Type hints and py.typed

The decibri wheel ships a py.typed marker file per PEP 561, with hand-written .pyi stubs covering the internal Rust extension module and the full exception hierarchy. The package is mypy strict-clean. IDEs and type checkers will autocomplete every public name and narrow return types correctly.

import decibri
import numpy as np

mic = decibri.Microphone(as_ndarray=True)
chunk = mic.read()
# Type checker narrows `chunk` to numpy.ndarray | None when as_ndarray=True
# and to bytes | None otherwise.

The package depends on typing-extensions at runtime to support the 3.10 abi3 floor (typing.Self is only available in 3.11 and newer).

Exception handling

Decibri raises typed exceptions instead of generic RuntimeError or Exception. The root of the hierarchy is DecibriError. Three intermediate parents (DeviceError, OrtError, OrtPathError) group related instance classes so callers can catch by category instead of by individual class. Every exception remains catchable as DecibriError.

Hierarchy

Exceptions with extra attributes

Four classes carry additional attributes beyond the standard exception message:

• VadModelLoadFailed.path: the model path that failed to load.
• ModelLoadFailed.path: the capture model path (the denoise stage) that failed to load.
• OrtLoadFailed.path: the ORT dylib path that failed to load.
• OrtPathInvalid.path, OrtPathInvalid.reason: the rejected path and a short reason string.

Catch patterns

Catch any decibri error:

try:
    with decibri.Microphone(sample_rate=16000) as mic:
        chunk = mic.read()
except decibri.DecibriError as e:
    print(f"Decibri error: {e}")

Catch device-selection failures specifically, then fall back to the system default:

try:
    mic = decibri.Microphone(device="USB Audio")
except decibri.DeviceError as e:
    print(f"Device problem: {e}")
    mic = decibri.Microphone()

Multiprocessing and asyncio caveats

Linux fork-safety with Silero

Python's default fork start method on Linux duplicates the parent's memory into the child, but ONNX Runtime's internal state is not safe to share across forked processes. A Silero-enabled Microphone initialised in the parent and then used in a forked child either produces incorrect inference results or segfaults; decibri detects the PID mismatch at the start of every Silero inference call and raises ForkAfterOrtInit instead.

The fix is to either set the spawn start method before constructing any worker, or to construct the Microphone inside each child process after the fork.

import multiprocessing

if __name__ == "__main__":
    multiprocessing.set_start_method("spawn")
    # ... rest of program

Async event-loop blocking on ORT init

The synchronous AsyncMicrophone(...) constructor blocks for roughly 100 to 500 milliseconds when vad="silero" because it loads the Silero ONNX model inline. In an async context this blocks the event loop for the duration of the load, which can cause dropped websocket frames, late timer callbacks, and UI jitter in voice agents. Use await AsyncMicrophone.open(...) instead; the factory dispatches the synchronous construction to loop.run_in_executor(None, ...) so the event loop keeps running.

For more multiprocessing recipes, see the Python multiprocessing guide in the repository.

ONNX Runtime resolution

Two stages run on ONNX Runtime: the Silero detector, vad="silero", and the denoise conditioning stage. When either is enabled, Decibri needs to load the ONNX Runtime dynamic library. The path is resolved in this order, first match wins:

1. The ort_library_path constructor argument, if supplied.
2. The DECIBRI_ORT_DYLIB_PATH environment variable, for per-deployment overrides without code changes.
3. The ORT_DYLIB_PATH environment variable, the upstream ort crate's standard convention, respected so existing bare-ort deployments keep working.
4. The dylib bundled inside the wheel under decibri/_ort/. This is the default pip install decibri experience.

If none of the above resolve to a real file, ORT's default loader runs. That loader itself respects ORT_DYLIB_PATH if set after decibri import, so a late environment change still works as a last-resort fallback.

When ORT is loaded

When vad="silero" or denoise is set, on Microphone, AsyncMicrophone, File and AsyncFile alike. Energy mode and vad=False, with denoise unset, never touch ORT, so the resolver and bundled-dylib lookup are skipped entirely. On a Microphone, the Silero model loads in the constructor and the denoise model when capture starts. On a File, the denoise model loads in the constructor and the Silero model at the first read, or when analyze() runs.

First-load cost

The first Microphone constructed with vad="silero" incurs roughly 100 to 500 milliseconds of cold load on most platforms. The cost is amortised across the rest of the process: later loads, by either stage and from any class, reuse the same loaded ORT.

Process-global initialisation

The first load of ORT in a process, by either stage and from any class, determines the dylib for the whole process. Later loads inherit that initialisation regardless of their own ort_library_path argument. To switch dylibs, restart the process.

Telemetry

ONNX Runtime carries its own telemetry, separate from anything Decibri does. Decibri disables it when it initialises the runtime. Set DECIBRI_ORT_TELEMETRY=1 in the environment before the first load to leave it enabled; any other value, an empty value, and an absent variable leave it disabled.

Two limits apply on Windows, and Decibri can close neither, so it does not claim that no telemetry is emitted. ONNX Runtime logs one process-information event while its environment is being created, before the setting is applied, once per process, so that event is emitted whichever way the setting is left. The runtime also takes its telemetry state from the Windows tracing session through an ETW callback, so the platform can re-enable telemetry after Decibri has disabled it. On other platforms ONNX Runtime's telemetry provider does nothing.