# 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 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 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 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",
)