Source code for audiodev.sample_out

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

"""CircuitPython-shaped sample playback, off the interpreter thread where it can.

This is the *public* ``audio_out`` contract (see ``docs/guides/audio.md``): a board's
``audio_out`` role returns an `AudioOut` wrapping a backend transport
(sdl2/win/wasm/i2s/emulated), and app code plays anything satisfying
CircuitPython's audiosample pull protocol -- a ``synthio.Synthesizer``, an
``audiomixer.Mixer``, an ``audiocore.RawSample``/``WaveFile``, or any effect
chained on top of one -- with the same ``play()``/``stop()``/``pause()``/
``resume()``/``playing`` shape CircuitPython's own ``AudioOut``/``I2SOut``
use, unchanged. Nothing below changes a line of that.

Where the pull happens is not part of that contract, and it has moved. When
the firmware carries ``audiopump`` this class hands the graph to the pump --
a C thread the interpreter is not on, a pinned FreeRTOS task on esp32 -- and
does no pulling at all; the interpreter is left shovelling bytes on the
desktop and doing nothing whatsoever on a board, where the pump writes each
block straight into I2S. No app asks for it and no board configures it: the
firmware either has the module or it has not. Where it has not -- stock
MicroPython, CircuitPython, CPython -- every word of the paragraph below is
still true and every byte is the same, because the old path is what runs.

The old path, and what it costs: every real output backend at the bottom is a
push+queued transport, and audio-thread callbacks into Python are unsafe
(documented in sdl2_audio.py). This class then pulls PCM from a sample via
``audiocore.get_buffer``/``reset_buffer`` on a lookahead schedule and pushes
it into the wrapped transport's ``write()``, all on the interpreter thread.
That used to be argued here as "the only sound architecture", on the grounds
that pulling a synthio graph allocates on the GC heap and so cannot be done
from a C callback. The premise was wrong: the pull is allocation-free under a
cold ``micropython.heap_lock()`` across 313 targets, byte-exact off the
interpreter thread, and safe under audiodsp's pump lock with no park. What
made the old path necessary was never the DSP -- it was that nobody had
written the thread.

Requires ``audiocore`` when `AudioOut` is constructed.  Importing
``audiodev`` and using a raw PCM transport remain independent of audiodsp.

No resampling: ``transport.format`` is the fixed playback rate/bit-depth/
channel-count (whatever the backend/device was opened with). A sample whose
own ``sample_rate`` differs plays at the wrong pitch rather than raising --
exactly like real DAC hardware and exactly like CircuitPython's own
``AudioOut``/``I2SOut``, which never resample either. ``bits_per_sample`` and
``channel_count`` *do* have to match: unlike a hardware clock mismatch, a
software queue interprets the raw bytes it's given, so a format mismatch
there would misread every sample rather than merely mis-pitch it.
"""

from audiodev import AudioLocked

try:
    from multimer import ticks_diff, ticks_ms
except ImportError:  # pragma: no cover - CPython fallback, no multimer
    import time

    def ticks_ms():
        return int(time.monotonic() * 1000)

    def ticks_diff(a, b):
        return a - b


#: One-shot latch for the "this board publishes no wire" note. A list rather
#: than a global so the check costs no `global` statement on the play path.
_WARNED = []

#: The fault sentence the "the pump is still down" note was last said about.
#: Once per fault rather than once per boot: a second, different fault later
#: in the same boot is news, and the same one said on every play() is not.
_SAID = []

#: `audiodev.pump`, imported once, lazily. Lazily because importing it from
#: module scope re-enters `audiodev/__init__` while THIS module is halfway
#: through being imported by it; once because the latch below is read on
#: every service tick.
_PUMP = []


def _pump_module():
    if not _PUMP:
        try:
            from audiodev import pump as mod
        except ImportError:                  # pragma: no cover - not shipped
            mod = None
        _PUMP.append(mod)
    return _PUMP[0]


class _Rearranging:
    """Hold the pump's "do not pull" latch across a whole method.

    A service tick arrives between bytecodes (`micropython.schedule`), so it
    lands wherever it lands. `AudioOut._pumping` stops it re-entering THIS
    player; the latch stops it pulling while ANY player, or a pushed stream,
    is rearranging who is sounding -- which is the case the P4 race was in
    and which one player's own flag cannot see. See
    `audiodev.pump.rearranging`.
    """

    __slots__ = ()

    def __enter__(self):
        mod = _pump_module()
        if mod is not None:
            mod._enter()

    def __exit__(self, exc_type, exc, tb):
        mod = _pump_module()
        if mod is not None:
            mod._leave()
        return False


_REARRANGING = _Rearranging()


def _load_audiocore():
    try:
        import audiocore

        return audiocore
    except ImportError as exc:
        import sys

        implementation = getattr(getattr(sys, "implementation", None), "name", "")
        if implementation == "micropython":
            message = (
                "AudioOut requires the audiocore module; rebuild the firmware "
                "with the audiodsp MicroPython usermod included"
            )
        else:
            message = (
                "AudioOut requires omnipython-audiodsp; install it with: "
                "python -m pip install omnipython-audiodsp"
            )
        raise ImportError(message) from exc


# audiocore.get_buffer()'s result codes (src/audiocore/__init__.h:
# GET_BUFFER_DONE, GET_BUFFER_MORE_DATA, GET_BUFFER_ERROR, in that order).
_GET_BUFFER_DONE = 0
_GET_BUFFER_MORE_DATA = 1
# Not one of audiocore's: "the pump has made nothing yet, come back". Only the
# pump path produces it, and the only thing it means is leave the loop.
_STARVED = -1


[docs] class AudioOut: """Pull-based sample player over a push transport. ``transport`` is any PCMOutput-shaped device (``format``, ``open``, ``close``, ``write``, ``service``, and the volume/mute/codec surface) -- typically what a board's ``audio_out`` role used to return directly, e.g. ``sdl2_audio.audio_out()`` or an ``I2SPCMOutput``. """ def __init__(self, transport, *, chunk_ms=40, lookahead_chunks=2, max_catchup_chunks=5, pump=True): self._audiocore = _load_audiocore() self.transport = transport self.chunk_ms = int(chunk_ms) self._lookahead_chunks = int(lookahead_chunks) self._max_catchup_chunks = int(max_catchup_chunks) self._sample = None self._loop = False # (sample, loop) of a play() the platform has not unlocked yet. self._waiting = None self._paused = False self._sched_start_ms = None self._played_frames = 0 self._pumping = False self._tick_sub = None # bytes-per-len(buf) unit for the current sample's get_buffer() # results; calibrated on the first pull (see _pump_locked). self._buf_len_scale = None #: How many consecutive backpressure skips with a queue that has not #: fallen before the cap stops being believed. See `_pump_locked`. #: #: Eight is a judgement about which way to be wrong, not a #: measurement. A false positive costs one chunk of extra latency; #: a false negative costs the whole stream, silently. It is set #: above the five ticks `test_backpressure_skips_pull_and_drains_ #: backlog` holds a queue saturated deliberately, so an ordinary #: full queue is never mistaken for a stall and nothing that #: worked before behaves differently -- a real backlogged transport #: drains, and this only fires for one that does not. self._stall_ticks = 8 #: The queued size at the last skip, how many skips have seen it not #: fall, and whether we are currently feeding past the cap. -1 means #: "not skipping". self._stall_queued = -1 self._stalled = 0 self._pushing = False #: How many times the pump started feeding past the cap because the #: transport had stopped consuming -- episodes, not ticks. A number #: above 0 means the sink was not draining: a wrapper that does not #: forward `prebuffer_bytes` (omnipython#54), or a device that died. self.stalls = 0 # --- the audio pump, if this firmware has one -------------------- # ``pump=False`` is for a caller that has a reason (a test proving # the two paths agree, a board whose peripheral someone else owns). # Nothing else ever asks: the firmware either carries the module or # it does not. self._want_pump = bool(pump) self._engine = None # audiodev.pump.Pump while this is on it self._pump_refused = None # why it is not, in one sentence self._prefetch = None # a file-backed source's producer, if any self._drain = None # where the ring's bytes land self._pumped = 0 # bytes a prefetcher's file has handed over self._sinking = False # esp32: the pump owns I2S, we write nothing self._on_speaker = False # Windows: the pump writes to WASAPI itself self._sink_driver = None # the pump writes to the transport's C sink self._engine_seen = False # sticky: this player has used the pump self._block = 0 # bytes in one pull of the graph self._drain_len = 0 self._drain_at = 0 # --- lifecycle ------------------------------------------------------- @property def format(self): return self.transport.format def open(self): self.transport.open() return self def close(self): # Under the latch as one action: between `stop()` and the transport's # own close a tick would find a player with no sample, call # `transport.service()` on a transport that is about to go, and on a # board reopen the very peripheral this is giving back. with _REARRANGING: self.stop() self.transport.close() deinit = close def __enter__(self): return self.open() def __exit__(self, exc_type, exc, tb): self.close() @property def pumped(self): """True while this player's audio is being pulled by the pump.""" return self._engine is not None @property def pump_refused(self): """Why the pump would not take this graph, or None. A console line is not enough. An app that keeps time off the audio clock when the pump takes it, and off a timer when it does not, is a DIFFERENT app either way -- and on a board the only thing that says which is one print nobody is watching. This is what a UI shows. """ return self._pump_refused # --- volume / codec passthrough -------------------------------------- # AudioOut adds no volume model of its own -- the transport already has # one (hardware or software), so this just forwards to it. @property def volume(self): return self.transport.volume def set_volume(self, percent): volume = self.transport.set_volume(percent) self._leave_speaker() return volume @property def muted(self): return self.transport.muted def mute(self, value=True): muted = self.transport.mute(value) self._leave_speaker() return muted @property def codec(self): return self.transport.codec # --- playback ----------------------------------------------------------
[docs] def play(self, sample, *, loop=False): """Start playing ``sample``. Replaces whatever was already playing.""" # `_pumping` is held across the whole rearrangement, and that is the # fix for the kit change. See stop() for what happens without it. # The latch beside it is the same fix for every OTHER player's tick. self._pumping = True self._waiting = None with _REARRANGING: try: self._detach_pump() self._check_format(sample) self._audiocore.reset_buffer(sample) self._sample = sample self._loop = bool(loop) self._paused = False self._sched_start_ms = None self._played_frames = 0 self._buf_len_scale = None # recalibrate per sample source # Before open(), on purpose. Where the pump drives I2S itself, # the transport must never open machine.I2S on the same port: # two owners of one peripheral is the failure that sounds like # silence. self._attach_pump(sample) if not self._sinking: try: self._open_unlocked() except AudioLocked: # A browser that wants a click first. Not a failure: # keep the sample, and service() starts it on the # first tick after the click. self._detach_pump() self._sample = None self._waiting = (sample, bool(loop)) return except Exception: # AND PUT THE PLAYER BACK, because `_sample` is # already set above and `service()` is already on # the app's shared timer. Before `open()` moved to # the end of this method it could not fail here at # all; now a transport that refuses -- a browser # AudioContext the visitor has not unlocked yet is # the ordinary case, not an edge -- leaves a player # that looks like it is playing, and every tick # raises the same error out of the app's timer # callback for as long as the page is open. Seen on # the gallery's piano: one traceback per tick until # the first click. self._detach_pump() self._sample = None raise finally: self._pumping = False self._pump() # kick an immediate chunk: lowest note-to-sound latency,
# same reason AudioEngine.note_on() does this def _open_unlocked(self): """Open the transport, raising `AudioLocked` while it is still locked. A transport says so by raising from ``open()``, or by answering true from an optional ``locked()`` once it is open (a browser context that opens suspended). """ self.transport.open() locked = getattr(self.transport, "locked", None) if locked is not None and locked(): raise AudioLocked("audio is locked until the page gets a click or key press") def _retry_waiting(self): """Start a play() that was waiting for the platform to unlock.""" try: self._open_unlocked() except AudioLocked: return except Exception: # Anything else is a real failure: say it once and stop waiting. self._waiting = None raise sample, loop = self._waiting self._waiting = None self.play(sample, loop=loop) # --- the pump -------------------------------------------------------- def _attach_pump(self, sample): """Hand *sample* to the pump, if there is one and it will take it. Every way this can fail leaves ``self._engine`` None, which is the old path exactly. A refusal is never an exception the caller sees: it did not ask for the pump, so it cannot be made to handle the pump's problems. """ self._release_prefetch() if not self._want_pump: return try: from audiodev import pump as _pump_mod except ImportError: return if not _pump_mod.available(): return engine = _pump_mod.owner() if engine.blocked(): # The pump is still holding whatever broke. Falling back is # right; falling back SILENTLY is what cost a board sitting an # hour -- the speaker works, `pumped` is False, the DMA counter # never moves and nothing anywhere says why (omnipython#45). Same # shape as the no-`wire=` note below, said once per fault. self._pump_refused = engine.fault() if not _SAID or _SAID[-1] != self._pump_refused: del _SAID[:] _SAID.append(self._pump_refused) print("audiodev: the audio pump is still down -", self._pump_refused, "- playing on the interpreter thread instead") return try: tail = sample if not _pump_mod.pumpable(sample): # A file-backed source reads through the VFS inside its own # get_buffer and the pump thread has no interpreter to do # that on. It becomes a producer into a ring instead, and # the ring is what the pump pulls. # # `audiobusio.I2SOut` has a feeder of its own and it is a # better one -- a static scheduler node, no allocation, a fill # on every read of `playing`. `audiodev` uses this one anyway, # on every backend, and the reason is not duplication: # # * `I2SOut` only ever feeds the TAIL. The moment a second # client arrives the tail is a root `audiomixer.Mixer` and # the file is one voice of it, where nothing feeds it and # the pump faults on the first block -- "a file-backed # source cannot be pulled by the pump". # * `playing` here is the PLAYER's, not the output's. With # two clients the output is still playing when this file # ends, so `audiodev` has to know the byte at which its own # sample ran out, which is what `Prefetch.fed()` is. # * `loop=` on a file is the file's lap, not the tail's. The # prefetcher rewinds the file; looping the tail would loop # whatever the mixer is, which is not the same sound. # # A lone file with nothing else sounding could go straight to # `I2SOut.play()` and be fed by it. It is not worth a second # shape: a second client can arrive on the next line. # How deep it has to be is not a taste. A pump the OUTPUT ring # paces runs on between this player's ticks, and every byte it # pulls comes out of THIS ring -- so it can be a whole output # ring ahead before it sleeps. A prefetcher shallower than that # is emptied between two ticks, and the push ring's underrun # rule then pastes a block of SILENCE into the middle of the # file and keeps the real frames for later. It did exactly # that: a 1 s WAV diverged at byte 30720, which was this ring's # own length to the byte. Prefetch doubles min_bytes into its # capacity, so asking for the output ring's length gives twice # it -- room for the run-ahead and for the drain that frees it. ahead = self._chunk_bytes() * 4 if (not _pump_mod.on_board() and _pump_mod.threaded() and _pump_mod.backpressure()): frame = (sample.channel_count * sample.bits_per_sample // 8) or 1 ahead = max(ahead, _pump_mod.ring_bytes( frame, self._chunk_bytes(), 256 * frame)) self._prefetch = _pump_mod.Prefetch( sample, loop=self._loop, min_bytes=ahead) self._prefetch.service() tail = self._prefetch.ring driver = self._driver_for(_pump_mod, tail) if driver is None: return # A Prefetch ring never ends, so the file's loop lives in the # Prefetch; a direct sample's loop is the pump's and has to be # handed over or `play(sample, loop=True)` sounds once. if not engine.play(self, tail, driver=driver, loop=bool(self._loop) and self._prefetch is None): # Pump.play() catches its own exception so that a refusal can # never reach an app that did not ask for the pump. Saying # nothing at all is the other failure: two play() calls in a # hundred went silently back to the old path and only a byte # count noticed. self._release_prefetch() self._pump_refused = str(engine.fault()) print("audiodev: the audio pump would not take this graph -", self._pump_refused, "- playing on the interpreter thread instead") return except Exception as exc: # noqa: BLE001 - reported, not raised self._release_prefetch() # A transient loss must not become permanent. Nothing clears # `_blocked` on this path -- `_play`'s own teardown is the repair # for everything that goes through `Pump.play`, and this except is # what catches the rest -- so recording a lost race as blocking # meant the process never reached for the pump again, on any # player, until it exited (omnipython#52). transient = isinstance(exc, _pump_mod.StartFailed) engine.note_fault(str(exc), blocking=not transient) # The sentence goes on the player too. A refusal that is only a # print looks, to an app, exactly like a firmware with no pump. self._pump_refused = str(exc) print("audiodev: the audio pump would not start -", exc, "- playing on the interpreter thread instead" + ("; the next play will try again" if transient else "")) return self._engine = engine self._engine_seen = True self._pump_refused = None self._pumped = 0 self._sinking = not driver.needs_service self._on_speaker = isinstance( getattr(driver, "wire", None), _pump_mod.SpeakerWire) self._sink_driver = driver if isinstance(driver, _pump_mod.SinkDriver) else None if driver.needs_service: # The block is the unit the OLD path hands the transport, because # that is what get_buffer() returns, and the schedule's "pull until # you have enough" overshoots to the end of one. Hand out anything # else and a note pressed on this tick lands at a different frame # -- measured as a divergence 23 ms in, with the totals identical. # So: drain a tick's worth in one go (one park), then give it back # a block at a time. block = _pump_mod.block_size(tail) want = max(self._chunk_bytes() * 2, block) if block: want = ((want + block - 1) // block) * block self._block = block self._drain_len = 0 self._drain_at = 0 if self._drain is None or len(self._drain) < want: self._drain = bytearray(want) def _chunk_bytes(self): fmt = self.transport.format return max(1, int(fmt.rate * self.chunk_ms / 1000)) * fmt.frame_size def _driver_for(self, pump_mod, tail): """The driver this transport wants, or None to stay on the old path.""" if pump_mod.c_sink(): # An output native code can write to, a USB speaker: the pump # writes the graph into it, at the transport's volume. inner = self.transport for _ in range(4): if hasattr(inner, "c_sink"): return pump_mod.SinkDriver(inner) inner = getattr(inner, "_inner", None) if inner is None: break if pump_mod.on_board(): # esp32: `audiobusio.I2SOut` owns the I2S peripheral outright. It # needs the board's pin map, which travels on the transport # because audiodev must not import board_peripherals. inner = self.transport for _ in range(4): wire = getattr(inner, "wire", None) if wire is not None: return pump_mod.BusioDriver( wire, inner.format, power=getattr(inner, "audio_power", None), volume=self.transport.volume, transport=inner) inner = getattr(inner, "_inner", None) if inner is None: break # No wire published: this board has not been taught the pump. # Play the old way rather than guessing at pins -- but say so # once. A firmware carrying the pump beside a board_peripherals # that predates `wire=` looks exactly like a working board: it # plays, on machine.I2S, and nothing anywhere says why the pump # is idle. That silence cost a board session an hour. self._pump_refused = ("this board's board_peripherals publishes " "no `wire=` on its audio transport") if not _WARNED: _WARNED.append(1) print("audiodev: this firmware has the audio pump but this " "board's board_peripherals publishes no `wire=` on its " "audio transport - playing on machine.I2S instead") return None if pump_mod.speaker(): driver = self._speaker_driver(pump_mod) if driver is not None: return driver if not pump_mod.threaded(): # WebAssembly and CPython: no pump thread, so the loop runs inside # this player's own service tick and the ring has to hold a tick's # worth of look-ahead rather than just absorb a racing thread. return pump_mod.ServiceDriver( self.transport.format.frame_size, chunk_bytes=self._chunk_bytes(), max_block=pump_mod.block_size(tail), ahead_ms=2 * self.chunk_ms) return pump_mod.RingDriver( self.transport.format.frame_size, chunk_bytes=self._chunk_bytes(), max_block=pump_mod.block_size(tail)) def _speaker_driver(self, pump_mod): """Windows: the pump plays to the speaker itself, or None. Only for a transport that names a speaker the firmware can open (``speaker_sink``, which `win_audio` sets for the default device), and only at full volume and unmuted: the speaker takes the graph's samples as they are, and a lower level is the transport's to apply in software, on the interpreter thread. """ if not self._full_level(): return None inner = self.transport for _ in range(4): sink = getattr(inner, "speaker_sink", None) if sink: return pump_mod.BusioDriver( pump_mod.SpeakerWire(sink), self.transport.format, volume=self.transport.volume, transport=inner) inner = getattr(inner, "_inner", None) if inner is None: break return None def _full_level(self): return self.transport.volume >= 100 and not self.transport.muted def _leave_speaker(self): """Carry on from the interpreter thread, where the volume applies. The speaker plays the graph's samples untouched, so a volume below full or a mute is a reason to stop writing to it directly. The sample continues from wherever the pump left it; the join is not sample-exact, which is the price of a level change while it plays. """ engine = self._engine if engine is not None and self._sink_driver is not None: # The pump applies this transport's level itself. self._sink_driver.level() return if (engine is None or not self._on_speaker or self._full_level()): return self._pumping = True try: with _REARRANGING: self._detach_pump() finally: self._pumping = False def _detach_pump(self): engine = self._engine self._engine = None self._sinking = False self._on_speaker = False self._sink_driver = None if engine is not None: engine.stop(self) self._release_prefetch() def _release_prefetch(self): prefetch = self._prefetch self._prefetch = None if prefetch is not None: prefetch.deinit() def _pump_died(self, why): """The pump stopped for a reason that is not the end of the sample.""" engine = self._engine self._detach_pump() if engine is not None: engine.note_fault(why) engine.shutdown() # `pumped` goes False here, so this is the only place an app can # learn why: without it the player reads as never having had a pump. self._pump_refused = why print("audiodev: the audio pump stopped -", why, "- playing on the interpreter thread instead") # Carry on from wherever the sample is. The pump consumed some of it # and there is no way to ask how much, so the join is not sample-exact; # it is a sentence and continued audio rather than a dead speaker. def _check_format(self, sample): fmt = self.transport.format bits = sample.bits_per_sample channels = sample.channel_count if bits != fmt.bits or channels != fmt.channels: raise ValueError( "sample format (bits_per_sample=%s channel_count=%s) does not " "match this AudioOut's fixed transport format (bits=%s " "channels=%s)" % (bits, channels, fmt.bits, fmt.channels) ) def stop(self): # THE TICK MUST NOT SEE THE MIDDLE OF THIS. `service()` is on the # app's shared timer, which arrives through `micropython.schedule` -- # between this method's own bytecodes. Between `_detach_pump()` and # `_sample = None` the player reads exactly like a healthy old-path # player: a sample, no engine, `_sinking` False. One tick landing # there pulls a block and writes it, and `PCMOutput.write()` opens # the transport, which on a board is `machine.I2S` on the port the # pump has just let go of. The next `play()` then asks the IDF for a # peripheral the interpreter is holding: # # ESP_ERR_NOT_FOUND -> RuntimeError("Peripheral in use") # # and `_attach_pump` reports "the audio pump would not take this # graph" and plays on the interpreter instead. That is the whole of # the shipped drum machine falling off the audio clock on every KIT # CHANGE (`CLK AUDIO` -> `CLK TIMER!`), and both halves of the race # were seen on a P4: the tick winning it leaves machine.I2S open and # the pump refused; the pump winning it leaves the tick's own open() # raising ESP_ERR_NOT_FOUND out of the app's timer callback. # # `_pumping` already means "the pull path is busy, do not re-enter", # and `_pump()` honours it on entry. Holding it across the two # methods that REARRANGE the player -- this one and play() -- is the # whole fix. It costs one attribute write on each. self._pumping = True self._waiting = None with _REARRANGING: try: self._detach_pump() self._sample = None self._paused = False self._sched_start_ms = None finally: self._pumping = False def pause(self): with _REARRANGING: self._pause() def _pause(self): if self._sample is not None: self._paused = True if self._engine is not None: # Park, not shutdown: the pump finishes the block it is in and # does not touch the graph again, so resume() carries on from # the same frame rather than the start of the buffer. self._engine.pause(self) def resume(self): with _REARRANGING: self._resume() def _resume(self): if self._sample is not None and self._paused: self._paused = False self._sched_start_ms = None # re-baseline the lookahead from now if self._engine is not None: self._engine.resume(self) @property def playing(self): return self._sample is not None or self._waiting is not None @property def paused(self): return self._paused
[docs] def service(self): """Call from the app tick. Required for continuous playback -- no different from the ``service()`` every other audiodev backend already requires; see docs/guides/audio.md.""" self._pump()
def _pump(self): if self._pumping: return if self._waiting is not None: self._retry_waiting() return mod = _pump_module() if mod is not None and mod.rearranging(): # Somebody is rearranging who is sounding. Doing nothing is never # a hole -- the buffer under this is hundreds of milliseconds deep # and the next tick tops it up -- whereas pulling here is the race # the P4 caught, with `machine.I2S` opened on the port the pump # had just let go of. mod._turned_away() return self._pumping = True try: if self._sample is None or self._paused: if not self._sinking: self.transport.service() return if self._sinking: # esp32: the pump pulls the graph and writes it into the I2S # DMA on its own task. There is nothing for this thread to do # except notice that it stopped. self._watch_sink() return self._pump_locked() finally: # Park on EVERY way out, not just the bottom of the pull loop. The # schedule's two early returns (nothing due yet, transport already # full) used to leave the pump free-running until the next tick, # and a desktop pump with nothing pacing it fills the ring in # milliseconds -- measured as 132 dropped blocks and a byte stream # that diverged 5.7 s in. if self._engine is not None and not self._sinking: self._engine.rest() self._pumping = False def _watch_sink(self): prefetch = self._prefetch if prefetch is not None: # THE FILE IS READ HERE, on the thread that is allowed to read it, # and until this line existed it was read nowhere at all on this # path. `_next_block` services the prefetcher, and `_next_block` # is only reached from `_pump_locked`, which a sinking player # never enters -- so a WaveFile on a board went into a ring that # was primed once at play() and never topped up again. The ring # never ends either, so `playing` stayed True for ever after the # first few blocks of silence. Nothing had run it: the esp32 half # has never played a file on a board. # `Prefetch` owns the loop for a file -- it rewinds inside its own # service() -- so `finished()` only ever comes True on a # non-looping one, and it means the last real frame has been # handed to the pump. prefetch.service() if prefetch.finished(): self._detach_pump() self._sample = None return why = self._engine.died() if self._engine is not None else None if why is None: return if "ran out" in why: if self._loop: self._audiocore.reset_buffer(self._sample) self._engine.shutdown() self._attach_pump(self._sample) return self._detach_pump() self._sample = None return sample = self._sample released = "released" in why self._pump_died(why) if released: # Do NOT carry on with this sample. The reason the pump stopped is # that the graph was freed under it, so falling back to pulling it # on the interpreter thread raises `Object has been deinitialized` # out of the next service() -- a sentence AND a traceback, which # is worse than either. Measured on the P4: releasing the Mixer # under a playing pump printed the sentence and then threw from # `_next_block`. The speaker goes quiet and `playing` goes False, # which is what an app can actually act on. self._sample = None return self._sample = sample # Where the bytes come from, on either path. Everything above and below # this -- the schedule, the backpressure, the loop, the end of the sample # -- is one implementation, so the two paths cannot drift apart. def _next_block(self, sample): if self._engine is None: return self._audiocore.get_buffer(sample) prefetch = self._prefetch if prefetch is not None: # The file is read here, on the thread that is allowed to read it. prefetch.service() if self._drain_at < self._drain_len: got = self._drain_len - self._drain_at else: self._drain_at = 0 self._drain_len = got = self._engine.produce(self._drain) if got and self._block and got > self._block: got = self._block if got: at = self._drain_at self._drain_at = at + got if prefetch is not None: # A starved ring emits a whole block of silence and keeps the # real frames, so bytes out can run past bytes in. What the # producer has actually handed over is the end of the file. left = prefetch.wrote - self._pumped if got > left: got = left self._drain_at = at + got self._pumped += got if got <= 0: return (_GET_BUFFER_DONE if prefetch.fed() else _STARVED), None return _GET_BUFFER_MORE_DATA, memoryview(self._drain)[at : at + got] if prefetch is not None: return (_GET_BUFFER_DONE if prefetch.fed() else _STARVED), None why = self._engine.died() if why is None: return _STARVED, None # running, just nothing ready yet if "ran out" in why: # ONE MORE DRAIN BEFORE THE VERDICT. `produce()` above can come # back empty because it gave up waiting for a pump that had not # been given the CPU yet -- and by the time `died()` is asked # here, that same pump has run, pulled the whole sample into the # ring and left. Calling the sample finished on that reading # strands every byte it made: measured under seven busy loops on # one core as a round that wrote nothing at all while the pump's # own counter said it had pulled 9600 of 9600 bytes # (omnipython#52). The pump has stopped, so this drain empties the # ring and cannot wait on anything. self._drain_at = 0 self._drain_len = got = self._engine.produce(self._drain) if got: if self._block and got > self._block: got = self._block self._drain_at = got return (_GET_BUFFER_MORE_DATA, memoryview(self._drain)[:got]) return _GET_BUFFER_DONE, None released = "released" in why self._pump_died(why) if released: # Same reason as in `_watch_sink`: the graph is gone, so there is # nothing to carry on with and pulling it would raise. self._sample = None return _GET_BUFFER_DONE, None return _STARVED, None def _pump_locked(self): sample = self._sample fmt = self.transport.format frame_size = fmt.frame_size rate = float(fmt.rate) chunk_frames = max(1, int(rate * self.chunk_ms / 1000)) # The catch-up allowance counts from the lookahead, not from zero: # the lookahead is part of what every tick asks for, so a limit # below it would cut the queue back to `max_catchup_chunks` on the # first stall (or the first pull) and it would never grow back. The # limit bounds only the burst on top of the lookahead. max_frames = chunk_frames * (self._lookahead_chunks + self._max_catchup_chunks) now = ticks_ms() if self._sched_start_ms is None: self._sched_start_ms = now self._played_frames = 0 elapsed_ms = ticks_diff(now, self._sched_start_ms) lookahead_ms = chunk_frames * self._lookahead_chunks * 1000.0 / rate target_frames = int((elapsed_ms + lookahead_ms) * rate / 1000.0) frames_needed = target_frames - self._played_frames if frames_needed > max_frames: frames_needed = max_frames self._played_frames = target_frames - max_frames if frames_needed <= 0: self.transport.service() return # Backpressure: when the transport already holds more than the # lookahead target plus one chunk of slack, pulling more only deepens # note-to-sound latency -- every queued byte plays before anything # pressed *now*. Without this, any backlog becomes permanent: the # steady-state pump produces exactly realtime, so it can never drain # what priming or stall catch-up piled up (measured: a small-chunk # profile carried the transport's whole prebuffer as extra latency for # the life of the stream). The schedule is marked consumed rather than # left to accumulate, so resuming pulls per-tick chunks instead of a # catch-up burst that would re-flood the queue. Transports without a # real queue report queued_size() == 0 (the PCMOutput default) and are # never skipped. # # The cap must clear the transport's priming threshold, or the two # mechanisms deadlock in silence: a freshly primed device stays paused # (consuming nothing) until _prebuffer_bytes are queued, while a cap # below that told the pump the queue was already "full enough" -- # each side waiting on the other, measured as exactly that. chunk_bytes = chunk_frames * frame_size cap = (self._lookahead_chunks + 1) * chunk_bytes # The PUBLIC name, because a wrapper can only forward what it can see. # `_prebuffer_bytes` stays as a fallback for a transport written # before `prebuffer_bytes` existed, but a wrapper that forwards the # documented interface now gets this right by doing nothing special. prebuffer = getattr(self.transport, "prebuffer_bytes", None) if prebuffer is None: prebuffer = getattr(self.transport, "_prebuffer_bytes", 0) if prebuffer and prebuffer + chunk_bytes > cap: cap = prebuffer + chunk_bytes queued = self.transport.queued_size() if queued > cap: # The cap is a latency guard, not a fact about the device, and # believing it forever is how the audio stops in silence. A # transport that cannot say what it needs to prime gets capped # below its own threshold, stays paused, and never consumes -- # so `queued` never falls and every later tick skips too. # # So the skip is only trusted while the queue is MOVING. When it # has not fallen for `_stall_ticks` consecutive skips, feed it on # the ordinary schedule instead: more bytes is exactly what a # device waiting to prime needs, and for a sink that has genuinely # stopped it is the one observable difference between "full" and # "dead". `stalls` counts the episodes, so an app can see it. # # A CHUNK a tick is not enough, and that was measured rather than # reasoned: SDL wants 96 000 B before it unpauses, which at one # 1 920 B chunk per eight ticks is sixteen seconds of trickle -- # long enough that the probe ran the SDL queue out of memory # before the device ever started. Feeding the normal schedule is # bounded by `max_catchup_chunks` and primes it in about ten # ticks. if queued < self._stall_queued or self._stall_queued < 0: self._stall_queued = queued self._stalled = 0 self._pushing = False else: self._stalled += 1 # One second of audio queued with nothing consumed is a dead sink, # not a priming one -- no device on this bench asks for more than # that -- so stop feeding rather than filling a board's memory. # Derived from the format rather than picked, and it sits above # every priming threshold this repository ships. if queued >= int(rate) * frame_size: self._pushing = False elif self._stalled >= self._stall_ticks and not self._pushing: self._pushing = True self.stalls += 1 if not self._pushing: self._played_frames = target_frames self.transport.service() return else: self._stall_queued = -1 self._stalled = 0 self._pushing = False bytes_needed = frames_needed * frame_size pulled = 0 scale = self._buf_len_scale while pulled < bytes_needed: result, buf = self._next_block(sample) if result == _STARVED: break if buf: if scale is None: # len(buf) must be counted in BYTES. Current audiodsp # returns byte views, but older frozen firmware returned # typed ('h') memoryviews whose len() is the SAMPLE # count -- trusting it made this pump under-count 16-bit # audio 2x and overproduce PCM at twice realtime, # saturating every non-blocking transport. One bytes() # copy on the first pull per play() calibrates the unit. scale = len(bytes(buf)) // len(buf) self._buf_len_scale = scale nbytes = len(buf) * scale self.transport.write(buf) pulled += nbytes self._played_frames += nbytes // frame_size elif result == _GET_BUFFER_MORE_DATA: # No bytes and no terminal result: defensive stop rather than # spin forever -- mirrors PCMOutput.write()'s own "made no # write progress" guard on the push side. self._sample = None break if result != _GET_BUFFER_MORE_DATA: # `self._sample` is the test for "is this graph still ours", # and on a looping player it is the whole of the difference # between a lap and a release. `_pump_block` drops the sample # when the pump died of a release and then has to answer # DONE, because there is no other terminal result -- and DONE # on a loop means rewind, so this rewound a Mixer that had # just been deinited and raised ValueError out of service(). # The sentence printed first, which made it look like the # release was handled. It was, on the esp32 sink path, where # `_watch_sink` returns before ever reaching here. if (self._loop and result == _GET_BUFFER_DONE and self._sample is not None): self._audiocore.reset_buffer(sample) if self._engine is not None: # The pump left its loop when the source ran out, and # the ring is drained -- so start it again on the # sample that has just been reset. No byte is lost at # the seam; the ring was empty before we got here. self._engine.shutdown() self._attach_pump(sample) if self._engine is None: self._buf_len_scale = None continue self._sample = None self._detach_pump() break self.transport.service() # --- app-tick integration, same shape as AudioEngine.attach/detach ---
[docs] def attach(self, app, period_ms=None): """Subscribe `service` to *app*'s shared timer; returns self.""" ms = self.chunk_ms if period_ms is None else int(period_ms) # App timer callbacks are always invoked with one positional arg # (the timer/tick object, see appdev.App._dispatch_tick) -- service() # itself stays a plain zero-arg method, matching every sibling # PCMOutput.service() elsewhere in audiodev, so adapt here instead. _tick = lambda _timer=None: self.service() # noqa: E731 if hasattr(app, "every"): self._tick_sub = app.every(ms, _tick) else: async_ = getattr(app, "timer_async", False) self._tick_sub = app.on_tick(_tick, period=ms, async_=async_) return self
def detach(self): sub = self._tick_sub self._tick_sub = None if sub is None: return if hasattr(sub, "cancel"): sub.cancel() else: deinit = getattr(sub, "deinit", None) if deinit is not None: try: deinit() except Exception: pass
[docs] def sample_out(transport_factory, format=None, **kwargs): """Wrap a backend's ``pcm_out(format, **kwargs)`` transport in `AudioOut`. ``transport_factory`` is a module (or any object) exposing ``pcm_out``, e.g. ``audiodev.sdl2_audio`` -- so ``sample_out(sdl2_audio)`` is the sdl2 equivalent of CircuitPython's ``audiobusio.I2SOut(...)``. """ return AudioOut(transport_factory.pcm_out(format, **kwargs))
__all__ = ("AudioOut", "sample_out")