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:
RuntimeErrorThe 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, andAudioOutkeeps the sample and starts it on the first tick after the platform unlocks, so an app callsplay()once and needs no retry of its own. It is aRuntimeError, 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.
defaultis 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.minimumis 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:
objectDescription of raw, interleaved PCM frames.
- class audiodev.I2SWire(port, *, sck, ws, sd, mck=None, mck_fs=256, sd_in=None)[source]
Bases:
objectPhysical 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:
objectA 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’sBusioDriveropensaudioio.AudioOuton these pins, so a pin is anything that takes: aPinor its name, such as"PA4".rightis None on a board with one DAC channel.
- class audiodev.PDMWire(clock, data)[source]
Bases:
objectA board’s PDM microphone pins, published without opening them.
The microphone is clocked from
clockand sends its bit stream ondata; the board’s firmware turns that into PCM in hardware (DFSDM on an STM32H7, which the Arduino GIGA Display Shield’s microphone uses).pump.PumpPCMInputrecords from it. A pin is aPinor its name, such as"PD3".
- class audiodev.AnalogWire(pin)[source]
Bases:
objectAn 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 samplespinon a timer, andpump.PumpPCMInputrecords 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:
objectWhat 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 andnegotiateholds the policy.channelsis what the wire will open;native_channelsis 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 acceptschannels=(1, 2)withnative_channels=1and needs no mixdown for stereo content.rates=Nonemeans 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_formatis what the board opens its peripheral at;source_formatis what the returned device’swrite()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:
objectA board’s
audio_out/pcm_outcallable, with its capability attached.MicroPython function objects cannot hold attributes, so a board wraps its factory here rather than assigning
audio_out.capabilityonto a bare function. Call shape matchesaudiodev.auto:(format=None, **kwargs).capabilityis the only discovery surface – ask it what rates and channel counts the board takes, andcapability.wirefor 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:
objectCoordinate devices which share a codec or peripheral.
- class audiodev.PCMOutput(format, *, session=None, codec=None, amplifier=None, set_hardware_volume=None, set_hardware_mute=None, power=None)[source]
Bases:
_DeviceRaw 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 – andset_volume()andmute()were guarded onis_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 throughset_volume(20),set_volume(50),mute(True)andmute(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:
_DeviceRaw PCM capture with normalized gain and async support.
Subclasses implement
_readinto(and optionally_areadinto).
- class audiodev.ChannelAdapter(inner, source_format, remix=None)[source]
Bases:
PCMOutputAccept
source_formatonwrite(); 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).- 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.
- audiodev.adapt_channels(pcm, source_format, remix=None)[source]
Return pcm unchanged, or a wrapper that converts source_format to it.
pcm.formatis the wire.source_formatis whatwrite()accepts. Channel counts must be 1 or 2 and rates/widths must already match; this does not resample.remixis the conversion callable(src, src_ch, dst_ch, dest). Default is the pure-Python one in this module, which is correct everywhere and slow; passaudiodev.accel.best_remix()for the C implementation when audiodsp is present.
- class audiodev.InputChannelAdapter(inner, target_format, remix=None)[source]
Bases:
PCMInputHand
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.formatis the wire. Channel counts must be 1 or 2, and rates and widths must already match; this does not resample.remixis as foradapt_channels.
- class audiodev.PaceOutput(inner, queue_ms=80)[source]
Bases:
PCMOutputTake write() without blocking
machine.I2Suntil DMA is full.ESP32
I2S.writeholds 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_msonly 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, notwrite. The latter loops until every byte lands (or raises on a 0-byte I2S return).machine.I2Sin 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 mssleep_mswait held the GIL while DMA played out, which is the Connect skip (C ring full, I2S empty). Overflow abovequeue_msis dropped, oldest first, and counted inlost_bytes. The Connect pump must callspaceand 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.Intercomdoes) 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.