audiodev

Portable PCM and tone device contracts for MicroPython and CPython.

Backends subclass PCMOutput, PCMInput, and ToneOutput. Optional host selection lives in audiodev.auto and is never imported from here.

exception audiodev.AudioLocked[source]

Bases: RuntimeError

The platform won’t start audio until the user acts.

A browser keeps its audio context suspended until a click or key press. A transport raises this from open() while that holds, and AudioOut keeps the sample and starts it on the first tick after the platform unlocks, so an app calls play() once and needs no retry of its own. It is a RuntimeError, so code that catches that keeps working.

audiodev.check_latency(latency)[source]

Validate a latency profile name, returning it unchanged.

Raises rather than falling back, so a typo is a visible error instead of silently buffered audio in an app that asked for low latency.

audiodev.queue_bytes(fmt, latency=None, queue_ms=None, default=None, minimum=0)[source]

Bytes of buffering for a latency profile, e.g. machine.I2S(ibuf=...).

MCU drivers size their ring buffer in bytes, which depends on the format, so the profile is expressed in milliseconds and converted here. default is returned untouched for the buffered profile: a board’s own value is usually tuned against its codec and should not be recomputed from a round number. minimum is the smallest size the driver can work with (for I2S, a few DMA buffers), so a caller asking for an unusable depth gets a working device.

class audiodev.AudioFormat(rate, channels, bits, signed=True, byteorder='little')[source]

Bases: object

Description of raw, interleaved PCM frames.

class audiodev.I2SWire(port, *, sck, ws, sd, mck=None, mck_fs=256, sd_in=None)[source]

Bases: object

Physical facts about a board’s I2S port, published without opening it.

A consumer that wants to drive the peripheral itself – audiodsp’s C pump, through pump.BusioDriver, is the live example – needs the port and pin numbers and no Python device at all. Publishing them on the capability is what lets such a consumer stop reaching into a board module’s private names.

class audiodev.DACWire(left, right=None)[source]

Bases: object

A board’s DAC output pins, published without opening them.

I2SWire’s counterpart for a board whose audio is a DAC, such as the Arduino GIGA R1’s headphone jack. The pump’s BusioDriver opens audioio.AudioOut on these pins, so a pin is anything that takes: a Pin or its name, such as "PA4". right is None on a board with one DAC channel.

class audiodev.PDMWire(clock, data)[source]

Bases: object

A board’s PDM microphone pins, published without opening them.

The microphone is clocked from clock and sends its bit stream on data; the board’s firmware turns that into PCM in hardware (DFSDM on an STM32H7, which the Arduino GIGA Display Shield’s microphone uses). pump.PumpPCMInput records from it. A pin is a Pin or its name, such as "PD3".

class audiodev.AnalogWire(pin)[source]

Bases: object

An analog microphone input, published without opening it.

A microphone whose signal reaches an ADC pin directly, such as the Arduino GIGA R1’s headphone jack’s microphone ring on "PA0". The firmware samples pin on a timer, and pump.PumpPCMInput records from it.

class audiodev.AudioCapability(default, *, kind='pcm', rates=None, channels=None, native_channels=None, bits=(16,), signed=True, byteorder='little', wire=None)[source]

Bases: object

What a board’s audio role can actually do. Boards declare; we decide.

Boards used to hand-write a _require_format() with their own raises, which meant every board reimplemented validation with different error text and each new question grew another ad-hoc attribute. Here a board states facts and negotiate holds the policy.

channels is what the wire will open; native_channels is how many signals actually reach a transducer. They are not the same thing and conflating them is a bug: the ESP32-P4’s ES8311 clocks two slots and feeds one speaker, so it accepts channels=(1, 2) with native_channels=1 and needs no mixdown for stereo content.

rates=None means continuous – an I2S PLL will take any rate asked. A board with a fixed crystal lists the rates it can actually clock.

New axes are added as keywords with defaults, so a board written today keeps working when one appears. That is the point of the class.

audiodev.negotiate(capability, requested=None)[source]

Resolve a requested format against a board capability.

Returns (wire_format, source_format). wire_format is what the board opens its peripheral at; source_format is what the returned device’s write() accepts. When they are the same object no conversion is needed – which is the common case, including stereo content on a mono-speaker board whose wire takes two slots.

Raises rather than substituting. A silently-different format is a class of bug that sounds like working audio at the wrong pitch, which is exactly what nobody notices until it ships.

class audiodev.AudioFactory(call, capability)[source]

Bases: object

A board’s audio_out/pcm_out callable, with its capability attached.

MicroPython function objects cannot hold attributes, so a board wraps its factory here rather than assigning audio_out.capability onto a bare function. Call shape matches audiodev.auto: (format=None, **kwargs).

capability is the only discovery surface – ask it what rates and channel counts the board takes, and capability.wire for the pins when you mean to open the peripheral yourself. There is deliberately no second way to ask the same question.

class audiodev.AudioSession(codec_factory=None, duplex=False)[source]

Bases: object

Coordinate devices which share a codec or peripheral.

get_codec()[source]

Return the shared codec, constructing it on first access.

class audiodev.PCMOutput(format, *, session=None, codec=None, amplifier=None, set_hardware_volume=None, set_hardware_mute=None, power=None)[source]

Bases: _Device

Raw PCM playback with normalized volume and async support.

Subclasses implement _write (and optionally _drain, _awrite, _adrain, service).

hardware_live(value=True)[source]

Say whether this transport’s codec is powered by someone else.

The esp32 audio pump owns the I2S peripheral outright, so nothing ever calls open() on this transport – and set_volume() and mute() were guarded on is_open, which meant that on a board playing through the pump the volume knob and the mute button stored a number and never reached the codec. Measured on the P4: the ES8311’s register 0x32 sat at 127 through set_volume(20), set_volume(50), mute(True) and mute(False).

Turning it on applies the volume and mute this transport is holding, which is the same thing open() does and for the same reason: the codec must not be left at whatever the last owner set.

try_write(buf)[source]

Push as many bytes as the backend will take without blocking.

Unlike write, a 0-byte or partial I2S return is not an error: the caller keeps the remainder. Volume scaling is applied to buf before the backend sees it; leftover bytes should be retried as the original unscaled prefix.

class audiodev.PCMInput(format, *, session=None, codec=None, set_hardware_gain=None, set_hardware_mute=None, power=None)[source]

Bases: _Device

Raw PCM capture with normalized gain and async support.

Subclasses implement _readinto (and optionally _areadinto).

class audiodev.ChannelAdapter(inner, source_format, remix=None)[source]

Bases: PCMOutput

Accept source_format on write(); emit the inner device’s format.

Native I2S / WASAPI / etc. stay at their wire format. This wrapper is the producer-facing PCMOutput (AudioOut.transport, Device.attach).

queued_size()[source]

Bytes still waiting to play or capture. Default 0.

property prebuffer_bytes

The inner device’s threshold, in this wrapper’s frames.

Scaled exactly like queued_size, and for the same reason: the producer compares the two, so they have to be counted in the same bytes. A mono graph on a stereo device writes half the bytes the wire does, and an unscaled threshold would be twice what the producer has to clear.

Not forwarding this at all is omnipython#54: the pump capped itself below the inner device’s priming threshold, the device stayed paused, and the audio stopped after about a tenth of a second with no exception and no message.

is_active()[source]

True while PCM remains queued. Default False.

clear()[source]

Drop queued PCM now. Default no-op.

service()[source]

Per-tick housekeeping. Queued hosts override; default is a no-op.

audiodev.adapt_channels(pcm, source_format, remix=None)[source]

Return pcm unchanged, or a wrapper that converts source_format to it.

pcm.format is the wire. source_format is what write() accepts. Channel counts must be 1 or 2 and rates/widths must already match; this does not resample.

remix is the conversion callable (src, src_ch, dst_ch, dest). Default is the pure-Python one in this module, which is correct everywhere and slow; pass audiodev.accel.best_remix() for the C implementation when audiodsp is present.

class audiodev.InputChannelAdapter(inner, target_format, remix=None)[source]

Bases: PCMInput

Hand readinto() the channel count asked for; read the inner device’s.

A board whose capture wire is stereo can give a caller mono, and the other way round: two channels mix down to their mean, one channel is copied to both. Gain, mute and power stay the inner device’s, so nothing is scaled twice.

audiodev.adapt_input_channels(pcm, target_format, remix=None)[source]

Return pcm unchanged, or a wrapper whose readinto() gives target_format’s channel count from pcm’s.

pcm.format is the wire. Channel counts must be 1 or 2, and rates and widths must already match; this does not resample. remix is as for adapt_channels.

class audiodev.PaceOutput(inner, queue_ms=80)[source]

Bases: PCMOutput

Take write() without blocking machine.I2S until DMA is full.

ESP32 I2S.write holds the GIL until the DMA has room. Filling the ring then blocking was measured at 88-160 ms on the P4 and starves the C6 SDIO Wi-Fi path (Connect underruns, audible skips). Overflow is copied into a preallocated bytearray ring and flushed until the inner device returns 0 (DMA full). bytes(buf) / leftover slices on that path allocated a 7 kB object per Connect pump and GC-paused the P4 for 200 ms–1.8 s. A software byte-clock must not gate the flush: I2S MCLK on this board runs ~1.6% fast, so the clock reports the ring still full after DMA has already gone empty, and audio sits in Python while the speaker underruns. queue_ms only caps how much we keep in the stash (OOM), not how much we are willing to push into I2S.

Inner writes use PCMOutput.try_write, not write. The latter loops until every byte lands (or raises on a 0-byte I2S return). machine.I2S in asyncio mode returns partial/zero when DMA is full; that is the stop signal, not an error.

write() always copies what it is given, then flushes. It does not sleep for I2S room: a 250 ms sleep_ms wait held the GIL while DMA played out, which is the Connect skip (C ring full, I2S empty). Overflow above queue_ms is dropped, oldest first, and counted in lost_bytes. The Connect pump must call space and leave PCM in the C ring when the stash is at cap.

try_write() never drops: it takes only what the I2S ring and the stash have room for and returns that count, so a caller that keeps the remainder (medialink.Intercom does) loses nothing here.

queued_size()[source]

Bytes queued for the DAC, the stash included. Flushes first.

A caller that writes only while this is under a threshold would otherwise never write again once the stash alone reached it: the stash drains only on a write, and the DAC ran dry behind it.

property prebuffer_bytes

The inner device’s threshold, unscaled: same format either side.

Forwarded rather than inherited, for omnipython#54’s reason – a wrapper that answers 0 here caps the producer below what the device needs to start, and both sides wait.

is_active()[source]

True while PCM remains queued. Default False.

clear()[source]

Drop queued PCM now. Default no-op.

service()[source]

Per-tick housekeeping. Queued hosts override; default is a no-op.

space()[source]

Bytes the stash can take without dropping. Flushes first.

try_write(buf)[source]

Take what fits in the I2S ring and the stash, drop nothing.

Returns the bytes taken, whole frames only. PCMOutput.try_write promises the caller keeps the rest; going through _write instead reported every byte taken and dropped what was over the stash’s cap.

audiodev.pace_output(pcm, queue_ms=80)[source]

Return pcm wrapped so write() will not block a full I2S DMA.

class audiodev.ToneOutput(*, session=None, power=None)[source]

Bases: _Device

Frequency/duty output for PWM speakers and buzzers.

Subclasses implement _play and _stop.