Source code for audiodev

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""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.
"""

try:
    import asyncio
except ImportError:  # pragma: no cover - uasyncio name on older firmware
    try:
        import uasyncio as asyncio
    except ImportError:
        asyncio = None

# PaceOutput waits this many 1 ms ticks for DMA to drain before dropping
# stash. CPython tests leave it None so write() stays instantaneous.
try:
    from time import sleep_ms as _pace_sleep_ms
except ImportError:  # pragma: no cover - CPython host
    _pace_sleep_ms = None

# Latency profiles, shared vocabulary for every backend's ``audio_out`` /
# ``audio_in``. Backends translate a profile into their own block and queue
# sizes -- the names live here so all of them spell it the same way, and so a
# caller can ask for a profile without knowing which backend it will get.
#
# ``None``      backend default: buffered for throughput, which is what a
#               producer that can write faster than realtime wants (a TTS pump
#               with whole utterances ready, file playback).
# ``"low"``     interactive: shortest block and queue the backend supports, for
#               a producer that writes at realtime with a small look-ahead (a
#               synth responding to key presses). A buffered profile turns
#               directly into note-to-sound delay for those callers.
# ``"buffered"``the default, named explicitly.
LATENCIES = (None, "low", "buffered")


[docs] class AudioLocked(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. """
[docs] def check_latency(latency): """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. """ if latency not in LATENCIES: raise ValueError( "unknown latency profile {!r}; expected one of {}".format(latency, LATENCIES) ) return latency
# Queue depth for the "low" profile, in milliseconds of audio. LOW_LATENCY_QUEUE_MS = 100
[docs] def queue_bytes(fmt, latency=None, queue_ms=None, default=None, minimum=0): """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. """ check_latency(latency) if queue_ms is None: if latency != "low": return default queue_ms = LOW_LATENCY_QUEUE_MS wanted = fmt.rate * fmt.frame_size * int(queue_ms) // 1000 return max(minimum, fmt.frame_size, wanted)
async def _asleep(seconds=0): if seconds and hasattr(asyncio, "sleep_ms"): await asyncio.sleep_ms(int(seconds * 1000) if seconds >= 0.001 else 0) return if hasattr(asyncio, "sleep_ms") and not seconds: await asyncio.sleep_ms(0) return await asyncio.sleep(seconds)
[docs] class AudioFormat: # noqa: PLW1641 - mutable value object is intentionally unhashable """Description of raw, interleaved PCM frames.""" def __init__(self, rate, channels, bits, signed=True, byteorder="little"): if rate <= 0: raise ValueError("rate must be positive") if channels <= 0: raise ValueError("channels must be positive") if bits not in (8, 16, 32): raise ValueError("bits must be 8, 16, or 32") if byteorder not in ("little", "big"): raise ValueError("byteorder must be 'little' or 'big'") self.rate = int(rate) self.channels = int(channels) self.bits = int(bits) self.signed = bool(signed) self.byteorder = byteorder self.frame_size = self.channels * self.bits // 8 def __repr__(self): return "AudioFormat(rate=%d, channels=%d, bits=%d, signed=%r, byteorder=%r)" % ( self.rate, self.channels, self.bits, self.signed, self.byteorder, ) def __eq__(self, other): return isinstance(other, AudioFormat) and ( self.rate, self.channels, self.bits, self.signed, self.byteorder, ) == ( other.rate, other.channels, other.bits, other.signed, other.byteorder, )
[docs] class I2SWire: """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. """ def __init__(self, port, *, sck, ws, sd, mck=None, mck_fs=256, sd_in=None): self.port = int(port) self.sck = int(sck) self.ws = int(ws) self.sd = int(sd) self.mck = None if mck is None else int(mck) self.mck_fs = int(mck_fs) # The microphone's data pin, when the microphone shares this wire's # clocks. A board that publishes it can record while it plays: the # output opens the port as a TX/RX pair and the input reads the RX # half (``audiodev.pump.PumpPCMInput``). self.sd_in = None if sd_in is None else int(sd_in) def __repr__(self): return ( "I2SWire(port=%d, sck=%d, ws=%d, sd=%d, mck=%r, mck_fs=%d, sd_in=%r)" % (self.port, self.sck, self.ws, self.sd, self.mck, self.mck_fs, self.sd_in) )
[docs] class DACWire: """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 <audiodev.pump.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. """ def __init__(self, left, right=None): self.left = left self.right = right def __repr__(self): return "DACWire(left=%r, right=%r)" % (self.left, self.right)
[docs] class PDMWire: """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 <audiodev.pump.PumpPCMInput>` records from it. A pin is a ``Pin`` or its name, such as ``"PD3"``. """ def __init__(self, clock, data): self.clock = clock self.data = data def __repr__(self): return "PDMWire(clock=%r, data=%r)" % (self.clock, self.data)
[docs] class AnalogWire: """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 <audiodev.pump.PumpPCMInput>` records from it. """ def __init__(self, pin): self.pin = pin def __repr__(self): return "AnalogWire(pin=%r)" % (self.pin,)
[docs] class AudioCapability: """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. """ def __init__( self, default, *, kind="pcm", rates=None, channels=None, native_channels=None, bits=(16,), signed=True, byteorder="little", wire=None, ): if kind not in ("pcm", "tone"): raise ValueError("kind must be 'pcm' or 'tone'") if kind == "pcm" and not isinstance(default, AudioFormat): raise TypeError("default must be an AudioFormat for kind='pcm'") self.kind = kind self.default = default self.rates = None if rates is None else tuple(int(r) for r in rates) if channels is not None: self.channels = tuple(int(c) for c in channels) elif default is not None: self.channels = (default.channels,) else: self.channels = () if native_channels is not None: self.native_channels = int(native_channels) else: self.native_channels = min(self.channels) if self.channels else 0 self.bits = tuple(int(b) for b in bits) self.signed = bool(signed) self.byteorder = byteorder self.wire = wire if kind == "pcm": # A board that cannot open its own default is a board that will # fail on audio_out() with no argument. Catch it at import. negotiate(self, default) def __repr__(self): return ( "AudioCapability(kind=%r, default=%r, rates=%r, channels=%r, " "native_channels=%d, bits=%r)" % ( self.kind, self.default, self.rates, self.channels, self.native_channels, self.bits, ) )
def _describe(values): return ", ".join(str(v) for v in values)
[docs] def negotiate(capability, requested=None): """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. """ if capability.kind != "pcm": if requested is not None: raise ValueError( "this audio role is %r, not PCM; it takes no format" % capability.kind ) return None, None if requested is None: requested = capability.default if not isinstance(requested, AudioFormat): raise TypeError("format must be an AudioFormat or None") if requested.bits not in capability.bits: raise ValueError( "this board takes %s-bit audio; asked for %d" % (_describe(capability.bits), requested.bits) ) if requested.signed != capability.signed: raise ValueError( "this board takes %s samples" % ("signed" if capability.signed else "unsigned") ) if requested.byteorder != capability.byteorder: raise ValueError( "this board takes %s-endian samples" % capability.byteorder ) if capability.rates is not None and requested.rate not in capability.rates: raise ValueError( "this board can clock %s Hz; asked for %d (audiodev does not " "resample)" % (_describe(capability.rates), requested.rate) ) if requested.channels in capability.channels: return requested, requested # The wire cannot take that channel count. Remix bridges 1<->2 only. if requested.channels not in (1, 2): raise ValueError( "channel count must be 1 or 2; asked for %d" % requested.channels ) bridge = 2 if requested.channels == 1 else 1 if bridge not in capability.channels: raise ValueError( "this board opens %s channel(s); asked for %d and cannot bridge it" % (_describe(capability.channels), requested.channels) ) wire = AudioFormat( requested.rate, bridge, requested.bits, signed=requested.signed, byteorder=requested.byteorder, ) return wire, requested
[docs] class AudioFactory: """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. """ def __init__(self, call, capability): if not isinstance(capability, AudioCapability): raise TypeError("capability must be an AudioCapability") self.capability = capability self._call = call def __call__(self, format=None, **kwargs): return self._call(format, **kwargs) def __repr__(self): return "AudioFactory(%r)" % (self.capability,)
def _remix_s16_py(source, src_channels, dst_channels, dest=None): """Portable channel remix. Matches ``audiodsp_remix_s16`` exactly. Indexes the bytes directly rather than calling ``struct`` per sample, and allocates nothing when ``dest`` is supplied. Both matter on an MCU: measured on a QT Py ESP32 Pico at 240 MHz, a 10 ms chunk of 44.1 kHz stereo cost 50.5 ms with ``struct`` and 17.3 ms this way, with zero heap growth across repeated calls. Per-chunk allocation on an audio path is what produced the multi-hundred-millisecond GC pauses recorded in `PaceOutput`. It is still not fast enough to feed a live 44.1 kHz stereo stream on that chip (1.73x realtime); 16 kHz is comfortable at 0.63x and 24 kHz marginal at 0.94x. A board that must remix at a high rate needs the C implementation -- see `audiodev.accel.best_remix`. """ src_channels = int(src_channels) dst_channels = int(dst_channels) if src_channels not in (1, 2) or dst_channels not in (1, 2): raise ValueError("channel_count must be 1 or 2") src = memoryview(source) frame = src_channels * 2 if frame == 0 or len(src) % frame: raise ValueError("source must be a whole number of frames") frames = len(src) // frame need = frames * dst_channels * 2 if dest is None: dest = bytearray(need) elif len(dest) < need: raise ValueError("dest is too small") if src_channels == dst_channels: dest[:need] = src[:need] return dest if src_channels == 2: o = 0 for i in range(0, frames * 4, 4): a = src[i] | (src[i + 1] << 8) if a > 32767: a -= 65536 b = src[i + 2] | (src[i + 3] << 8) if b > 32767: b -= 65536 total = a + b # Truncate toward zero, which is what the C does. A plain # ``total >> 1`` floors instead, differing by one on every ODD # NEGATIVE sum -- a discrepancy invisible to any test whose # sample pairs happen to sum to even numbers. total = (total + (total < 0)) >> 1 dest[o] = total & 255 dest[o + 1] = (total >> 8) & 255 o += 2 return dest # Expansion runs backwards so dest may alias src: it cannot overwrite a # sample it has yet to read. o = frames * 4 - 4 for i in range(frames * 2 - 2, -2, -2): lo = src[i] hi = src[i + 1] dest[o] = lo dest[o + 1] = hi dest[o + 2] = lo dest[o + 3] = hi o -= 4 return dest # NOTE: no audiodsp import here, deliberately. audiodev/__init__.py and every # transport backend are importable with no audiodsp present -- that is the # layering rule the README's table states, and the reason a headless PCM # consumer (a Connect speaker, a USB audio pump) needs no DSP package in # firmware. The pure-Python remix below is correct but slow; a caller that # wants the C one passes it in. ``audiodev.accel.best_remix()`` is the seam, # and it lives in its own module precisely so importing it is a choice.
[docs] class AudioSession: """Coordinate devices which share a codec or peripheral.""" def __init__(self, codec_factory=None, duplex=False): self.codec_factory = codec_factory self.duplex = bool(duplex) self.codec = None self._owners = []
[docs] def get_codec(self): """Return the shared codec, constructing it on first access.""" if self.codec is None and self.codec_factory is not None: self.codec = self.codec_factory() return self.codec
def acquire(self, owner, direction): if owner in self._owners: return self.codec if self._owners and not self.duplex: raise OSError("audio session is already active") self.get_codec() self._owners.append(owner) return self.codec def release(self, owner): if owner in self._owners: self._owners.remove(owner)
def _clamp_percent(value): value = int(value) if value < 0: return 0 if value > 100: return 100 return value def _scale_pcm(source, target, fmt, percent): """Scale PCM into target without allocating per sample.""" src = memoryview(source) dst = memoryview(target) length = len(src) if len(dst) < length: raise ValueError("target is too small") if percent == 100: dst[:length] = src return length if percent == 0: dst[:length] = bytes(length) return length width = fmt.bits // 8 order = fmt.byteorder signed = fmt.signed midpoint = 0 if signed else 1 << (fmt.bits - 1) sign_bit = 1 << (fmt.bits - 1) modulus = 1 << fmt.bits for offset in range(0, length, width): sample = int.from_bytes(src[offset : offset + width], order) if signed and sample & sign_bit: sample -= modulus if signed: sample = sample * percent // 100 else: sample = midpoint + (sample - midpoint) * percent // 100 dst[offset : offset + width] = (sample % modulus).to_bytes(width, order) return length class _Device: """Shared open/close, session, and no-op queue housekeeping.""" direction = None def __init__(self, *, session=None): self.session = session self.is_open = False self._codec = None @property def codec(self): if self._codec is None and self.session is not None: return self.session.get_codec() return self._codec @codec.setter def codec(self, value): self._codec = value def _open(self): """Open the transport. Subclasses override.""" pass def _close(self): """Close the transport. Subclasses override.""" pass def open(self): if self.is_open: return self if self.session is not None: self.session.acquire(self, self.direction) try: self._open() self.is_open = True except Exception: if self.session is not None: self.session.release(self) raise return self def close(self): if not self.is_open: return try: self._close() finally: self.is_open = False if self.session is not None: self.session.release(self) deinit = close def service(self): """Per-tick housekeeping. Queued hosts override; default is a no-op.""" return None def queued_size(self): """Bytes still waiting to play or capture. Default 0.""" return 0 @property def prebuffer_bytes(self): """Bytes that must be queued before this device starts consuming. Part of the interface, not an implementation detail, because a producer has to clear it or the two mechanisms deadlock: a freshly primed device stays paused until this many bytes are queued, while a producer that caps itself lower has already decided the queue is full enough. Each waits on the other and the audio stops without an exception (omnipython#54). It used to be readable only as ``_prebuffer_bytes``, by ``getattr`` with a default of 0 -- so a wrapper that forwarded every *documented* part of this interface still missed it, and 0 is the value that wedges. A wrapper forwards this the way it forwards `queued_size`. 0 means the device starts on the first byte, which is the honest answer for a device with no queue at all. """ return getattr(self, "_prebuffer_bytes", 0) def is_active(self): """True while PCM remains queued. Default False.""" return False def clear(self): """Drop queued PCM now. Default no-op.""" return None def __enter__(self): return self.open() def __exit__(self, exc_type, exc, traceback): self.close()
[docs] class PCMOutput(_Device): """Raw PCM playback with normalized volume and async support. Subclasses implement `_write` (and optionally `_drain`, `_awrite`, `_adrain`, `service`). """ kind = "pcm" direction = "out" def __init__( self, format, *, session=None, codec=None, amplifier=None, set_hardware_volume=None, set_hardware_mute=None, power=None, ): super().__init__(session=session) self.format = format self.codec = codec self.amplifier = amplifier self._set_hardware_volume = set_hardware_volume self._set_hardware_mute = set_hardware_mute self._power = power self._volume = 100 self._muted = False # True when somebody else has the codec powered -- the esp32 pump owns # the I2S peripheral and brings the codec up itself, so this transport # is never open()ed and `is_open` is not the question to ask before # writing a codec register. See `hardware_live`. self._hw_live = False self._scratch = bytearray() capabilities = {"pcm", "playback", "volume", "mute"} capabilities.add("hardware-volume" if set_hardware_volume else "software-volume") self.capabilities = frozenset(capabilities) @property def volume(self): return self._volume @property def muted(self): return self._muted def open(self): if self.is_open: return self super().open() if self.session is not None and self.codec is None: self.codec = self.session.codec if self._power is not None: self._power(True) if self._set_hardware_volume is not None: self._set_hardware_volume(self._volume) if self._set_hardware_mute is not None: self._set_hardware_mute(self._muted) return self
[docs] def hardware_live(self, value=True): """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. """ self._hw_live = bool(value) if not self._hw_live: return if self._set_hardware_volume is not None: self._set_hardware_volume(self._volume) if self._set_hardware_mute is not None: self._set_hardware_mute(self._muted)
def _hw_reachable(self): return self.is_open or self._hw_live def set_volume(self, percent): self._volume = _clamp_percent(percent) if self._hw_reachable() and self._set_hardware_volume is not None: self._set_hardware_volume(self._volume) return self._volume def mute(self, value=True): self._muted = bool(value) if self._hw_reachable() and self._set_hardware_mute is not None: self._set_hardware_mute(self._muted) return self._muted def _prepare(self, buf): view = memoryview(buf) if len(view) % self.format.frame_size: raise ValueError("PCM buffer must contain complete frames") if self._set_hardware_volume is not None and not ( self._muted and self._set_hardware_mute is None ): return view percent = 0 if self._muted else self._volume if percent == 100: return view if len(self._scratch) < len(view): self._scratch = bytearray(len(view)) target = memoryview(self._scratch)[: len(view)] _scale_pcm(view, target, self.format, percent) return target def _write(self, buf): raise NotImplementedError("PCMOutput subclasses must implement _write") def _drain(self): return None async def _awrite(self, buf): count = self._write(buf) await _asleep(0) return count async def _adrain(self): result = self._drain() await _asleep(0) return result def write(self, buf): self.open() source = self._prepare(buf) written = 0 while written < len(source): count = self._write(source[written:]) if count is None: count = len(source) - written if count <= 0: raise OSError("audio stream made no write progress") written += count return len(buf)
[docs] def try_write(self, buf): """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. """ self.open() source = self._prepare(buf) count = self._write(source) if count is None: return 0 count = int(count) if count < 0: return 0 if count > len(source): return len(source) return count
def drain(self): self.open() return self._drain() async def awrite(self, buf): self.open() source = self._prepare(buf) written = 0 while written < len(source): count = await self._awrite(source[written:]) if count is None: count = len(source) - written if count <= 0: raise OSError("audio stream made no write progress") written += count return len(buf) async def adrain(self): self.open() return await self._adrain() def close(self): if not self.is_open: return try: if self._set_hardware_mute is not None: self._set_hardware_mute(True) if self._power is not None: self._power(False) finally: super().close()
[docs] class PCMInput(_Device): """Raw PCM capture with normalized gain and async support. Subclasses implement `_readinto` (and optionally `_areadinto`). """ kind = "pcm" direction = "in" def __init__( self, format, *, session=None, codec=None, set_hardware_gain=None, set_hardware_mute=None, power=None, ): super().__init__(session=session) self.format = format self.codec = codec self._set_hardware_gain = set_hardware_gain self._set_hardware_mute = set_hardware_mute self._power = power self._gain = 100 self._muted = False capabilities = {"pcm", "capture", "gain", "mute"} capabilities.add("hardware-gain" if set_hardware_gain else "software-gain") self.capabilities = frozenset(capabilities) @property def gain(self): return self._gain @property def muted(self): return self._muted def open(self): if self.is_open: return self super().open() if self.session is not None and self.codec is None: self.codec = self.session.codec if self._power is not None: self._power(True) if self._set_hardware_gain is not None: self._set_hardware_gain(self._gain) if self._set_hardware_mute is not None: self._set_hardware_mute(self._muted) return self def set_gain(self, percent): self._gain = _clamp_percent(percent) if self.is_open and self._set_hardware_gain is not None: self._set_hardware_gain(self._gain) return self._gain def mute(self, value=True): self._muted = bool(value) if self.is_open and self._set_hardware_mute is not None: self._set_hardware_mute(self._muted) return self._muted def _finish_read(self, buf, count): count -= count % self.format.frame_size view = memoryview(buf)[:count] if self._muted: view[:] = bytes(count) elif self._set_hardware_gain is None and self._gain != 100: _scale_pcm(view, view, self.format, self._gain) return count def _readinto(self, buf): raise NotImplementedError("PCMInput subclasses must implement _readinto") async def _areadinto(self, buf): count = self._readinto(buf) await _asleep(0) return count def readinto(self, buf): self.open() if len(buf) % self.format.frame_size: raise ValueError("PCM buffer must hold complete frames") return self._finish_read(buf, self._readinto(buf)) async def areadinto(self, buf): self.open() if len(buf) % self.format.frame_size: raise ValueError("PCM buffer must hold complete frames") return self._finish_read(buf, await self._areadinto(buf)) def close(self): if not self.is_open: return try: if self._set_hardware_mute is not None: self._set_hardware_mute(True) if self._power is not None: self._power(False) finally: super().close()
[docs] class ChannelAdapter(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``). """ def __init__(self, inner, source_format, remix=None): super().__init__( source_format, session=None, set_hardware_volume=getattr(inner, "_set_hardware_volume", None), set_hardware_mute=getattr(inner, "_set_hardware_mute", None), ) self._inner = inner self._mix = bytearray() self.remix = remix or _remix_s16_py self.codec = getattr(inner, "codec", None) @property def i2s(self): return getattr(self._inner, "i2s", None) @property def volume(self): return self._inner.volume @property def muted(self): return self._inner.muted def set_volume(self, percent): return self._inner.set_volume(percent) def mute(self, value=True): return self._inner.mute(value) def open(self): self._inner.open() self.is_open = True self.codec = getattr(self._inner, "codec", None) return self def close(self): if not self.is_open: return try: self._inner.close() finally: self.is_open = False
[docs] def queued_size(self): inner_q = self._inner.queued_size() inner_frame = self._inner.format.frame_size if inner_frame <= 0: return 0 return inner_q * self.format.frame_size // inner_frame
@property def prebuffer_bytes(self): """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. """ inner_frame = self._inner.format.frame_size if inner_frame <= 0: return 0 return self._inner.prebuffer_bytes * self.format.frame_size // inner_frame
[docs] def is_active(self): return self._inner.is_active()
[docs] def clear(self): return self._inner.clear()
[docs] def service(self): return self._inner.service()
def space(self): fn = getattr(self._inner, "space", None) if fn is None: return 0 inner_space = int(fn()) inner_frame = self._inner.format.frame_size if inner_frame <= 0: return 0 return inner_space * self.format.frame_size // inner_frame def _write(self, buf): src = memoryview(buf) src_ch = self.format.channels dst_ch = self._inner.format.channels need = len(src) * dst_ch // src_ch if len(self._mix) < need: self._mix = bytearray(need) self.remix(src, src_ch, dst_ch, self._mix) taken = self._inner.try_write(memoryview(self._mix)[:need]) if taken <= 0: return 0 src_taken = taken * src_ch // dst_ch src_taken -= src_taken % self.format.frame_size return src_taken
[docs] def adapt_channels(pcm, source_format, remix=None): """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. """ if not isinstance(source_format, AudioFormat): raise TypeError("source_format must be AudioFormat") if source_format.channels == pcm.format.channels: return pcm if source_format.rate != pcm.format.rate: raise ValueError("adapt_channels does not resample") if ( source_format.bits != pcm.format.bits or source_format.signed != pcm.format.signed or source_format.byteorder != pcm.format.byteorder ): raise ValueError("adapt_channels converts channels only") if source_format.channels not in (1, 2) or pcm.format.channels not in (1, 2): raise ValueError("channel_count must be 1 or 2") return ChannelAdapter(pcm, source_format, remix=remix)
[docs] class InputChannelAdapter(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. """ def __init__(self, inner, target_format, remix=None): super().__init__(target_format, session=None) self._inner = inner self._wire = bytearray() self.remix = remix or _remix_s16_py self.codec = getattr(inner, "codec", None) @property def gain(self): return self._inner.gain @property def muted(self): return self._inner.muted def set_gain(self, percent): return self._inner.set_gain(percent) def mute(self, value=True): return self._inner.mute(value) def open(self): self._inner.open() self.is_open = True self.codec = getattr(self._inner, "codec", None) return self def close(self): if not self.is_open: return try: self._inner.close() finally: self.is_open = False def _wire_view(self, buf): if len(buf) % self.format.frame_size: raise ValueError("PCM buffer must hold complete frames") need = len(buf) // self.format.frame_size * self._inner.format.frame_size if len(self._wire) < need: self._wire = bytearray(need) return memoryview(self._wire)[:need] def _converted(self, buf, got): inner_frame = self._inner.format.frame_size got -= got % inner_frame if got <= 0: return 0 self.remix(memoryview(self._wire)[:got], self._inner.format.channels, self.format.channels, buf) return got // inner_frame * self.format.frame_size def readinto(self, buf): self.open() wire = self._wire_view(buf) return self._converted(buf, self._inner.readinto(wire)) async def areadinto(self, buf): self.open() wire = self._wire_view(buf) return self._converted(buf, await self._inner.areadinto(wire))
[docs] def adapt_input_channels(pcm, target_format, remix=None): """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`. """ if not isinstance(target_format, AudioFormat): raise TypeError("target_format must be AudioFormat") if target_format.channels == pcm.format.channels: return pcm if target_format.rate != pcm.format.rate: raise ValueError("adapt_input_channels does not resample") if ( target_format.bits != pcm.format.bits or target_format.signed != pcm.format.signed or target_format.byteorder != pcm.format.byteorder ): raise ValueError("adapt_input_channels converts channels only") if target_format.channels not in (1, 2) or pcm.format.channels not in (1, 2): raise ValueError("channel_count must be 1 or 2") return InputChannelAdapter(pcm, target_format, remix=remix)
[docs] class PaceOutput(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. """ def __init__(self, inner, queue_ms=80): super().__init__( inner.format, session=None, set_hardware_volume=getattr(inner, "_set_hardware_volume", None), set_hardware_mute=getattr(inner, "_set_hardware_mute", None), ) self._inner = inner frame = inner.format.frame_size self._cap = int(queue_ms) * inner.format.rate * frame // 1000 if self._cap < frame: self._cap = frame # One inner.write of a 40 ms Connect pump still blocks I2S with the # GIL held if DMA only has a few milliseconds of room. Slice to 10 ms. self._slice = 10 * inner.format.rate * frame // 1000 if self._slice < frame: self._slice = frame size = self._cap + self._slice rem = size % frame if rem: size += frame - rem self._store = bytearray(size) self._store_mv = memoryview(self._store) self._r = 0 self._held = 0 # Bytes write() had to drop because the stash was at its cap. self.lost_bytes = 0 self.codec = getattr(inner, "codec", None) def _reset_stash(self): self._r = 0 self._held = 0 def _compact(self): if self._r == 0 or self._held <= 0: return n = len(self._store) first = n - self._r if first > self._held: first = self._held linear = bytearray(self._held) linear[:first] = self._store_mv[self._r : self._r + first] rest = self._held - first if rest: linear[first:] = self._store_mv[:rest] self._store_mv[: self._held] = linear self._r = 0 @property def i2s(self): return getattr(self._inner, "i2s", None) @property def volume(self): return self._inner.volume @property def muted(self): return self._inner.muted def set_volume(self, percent): return self._inner.set_volume(percent) def mute(self, value=True): return self._inner.mute(value) def open(self): self._inner.open() self.is_open = True self.codec = getattr(self._inner, "codec", None) return self def close(self): if not self.is_open: return try: self._inner.close() finally: self._reset_stash() self.is_open = False
[docs] def queued_size(self): """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. """ self._flush() return self._inner.queued_size() + self._held
@property def prebuffer_bytes(self): """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. """ return self._inner.prebuffer_bytes
[docs] def is_active(self): return self._held > 0 or self._inner.is_active()
[docs] def clear(self): self._reset_stash() return self._inner.clear()
[docs] def service(self): self._flush() return self._inner.service()
[docs] def space(self): """Bytes the stash can take without dropping. Flushes first.""" self._flush() frame = self._inner.format.frame_size room = self._cap - self._held if room < frame: return 0 return room - (room % frame)
def _ensure(self, extra): need = self._held + extra n = len(self._store) if need <= n: return new = bytearray(need + self._slice) if self._held: first = n - self._r if first > self._held: first = self._held new[:first] = self._store_mv[self._r : self._r + first] rest = self._held - first if rest: new[first : first + rest] = self._store_mv[:rest] self._store = new self._store_mv = memoryview(new) self._r = 0 def _append(self, buf): src = memoryview(buf) extra = len(src) if extra <= 0: return self._ensure(extra) n = len(self._store) off = (self._r + self._held) % n i = 0 while i < extra: room = n - off chunk = extra - i if chunk > room: chunk = room self._store[off : off + chunk] = src[i : i + chunk] off = (off + chunk) % n i += chunk self._held += extra def _flush(self): frame = self._inner.format.frame_size if frame <= 0: return n = len(self._store) while self._held >= frame: contig = n - self._r if contig > self._held: contig = self._held take = contig if contig < self._slice else self._slice take -= take % frame if take < frame: if contig < self._held: self._compact() n = len(self._store) continue return written = self._inner.try_write(self._store_mv[self._r : self._r + take]) if written < 0: written = 0 if written > take: written = take written -= written % frame if written <= 0: return self._r = (self._r + written) % n self._held -= written if written < take: # The device is full: it took only the room that freed up # while it was called. Asking again would chase the DAC a # few samples at a time until the stash ran out, so write() # waited out the whole queue and space() never fell. return def _drop_to_cap(self): if self._held <= self._cap: return drop = self._held - self._cap n = len(self._store) if n: self._r = (self._r + drop) % n self._held = self._cap self.lost_bytes += drop def _write(self, buf): self._append(buf) self._flush() self._drop_to_cap() return len(buf)
[docs] def try_write(self, buf): """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. """ self.open() source = self._prepare(buf) frame = self._inner.format.frame_size total = len(source) taken = 0 while taken < total: self._flush() room = self._cap - self._held chunk = total - taken if chunk > room: chunk = room chunk -= chunk % frame if chunk <= 0: break self._append(source[taken : taken + chunk]) taken += chunk self._flush() return taken
[docs] def pace_output(pcm, queue_ms=80): """Return *pcm* wrapped so ``write()`` will not block a full I2S DMA.""" if isinstance(pcm, PaceOutput): return pcm return PaceOutput(pcm, queue_ms=queue_ms)
[docs] class ToneOutput(_Device): """Frequency/duty output for PWM speakers and buzzers. Subclasses implement `_play` and `_stop`. """ kind = "tone" direction = "out" def __init__(self, *, session=None, power=None): super().__init__(session=session) self._power = power self.capabilities = frozenset({"tone", "playback", "volume", "mute"}) self._volume = 100 self._muted = False def open(self): if self.is_open: return self super().open() if self._power is not None: self._power(True) return self @property def volume(self): return self._volume @property def muted(self): return self._muted def set_volume(self, percent): self._volume = _clamp_percent(percent) return self._volume def mute(self, value=True): self._muted = bool(value) if self._muted and self.is_open: self.stop() return self._muted def _play(self, frequency, level): raise NotImplementedError("ToneOutput subclasses must implement _play") def _stop(self): raise NotImplementedError("ToneOutput subclasses must implement _stop") def play(self, frequency, *, volume=None): self.open() level = self._volume if volume is None else _clamp_percent(volume) if self._muted: level = 0 self._play(frequency, level) def stop(self): if not self.is_open: return self._stop() async def aplay(self, frequency, duration_ms): self.play(frequency) try: if hasattr(asyncio, "sleep_ms"): await asyncio.sleep_ms(duration_ms) else: await asyncio.sleep(duration_ms / 1000) finally: self.stop() def close(self): if self.is_open: self.stop() if self._power is not None: self._power(False) super().close()
__all__ = ( "LATENCIES", "LOW_LATENCY_QUEUE_MS", "AudioFormat", "AudioFactory", "AudioCapability", "AudioLocked", "I2SWire", "DACWire", "PDMWire", "AnalogWire", "negotiate", "AudioSession", "ChannelAdapter", "adapt_channels", "InputChannelAdapter", "adapt_input_channels", "PaceOutput", "pace_output", "PCMInput", "PCMOutput", "ToneOutput", "check_latency", "queue_bytes", )