Source code for audiodev.worklet_audio

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

"""AudioWorklet output for Python running in a Pyodide Web Worker.

Web Audio lives on the page, but your Python can run in a Web Worker so audio
work never waits on the UI. The page creates an ``AudioContext`` and an
``AudioWorkletProcessor``, connects the worklet to your worker with a
``MessageChannel``, and hands the worker one end of it. This module is the
worker's side of that port. It answers the worklet's requests for audio with
PCM, either rendered on demand or drained from a queue you write into.

Two ways to use it:

Pull, for an engine that renders on demand::

    from audiodev import worklet_audio

    out = worklet_audio.WorkletOutput(port, channels=2, sample_rate=48000)
    out.source = render          # render(blocks) -> int16 bytes

Push, for code written against `audiodev.PCMOutput` (an
``AudioOut`` pump, a TTS writer)::

    pcm = worklet_audio.pcm_out(AudioFormat(48000, 2, 16), port=port)
    pcm.write(chunk)

The wire protocol, all messages plain objects over the ``MessagePort``:

- Audio moves in blocks of 256 frames. Samples are signed 16-bit,
  interleaved when there are two channels.
- worklet to worker: ``{need: blocks, asked: frame}`` asks for ``blocks``
  blocks. The worker replies exactly once per request.
- worker to worklet: ``{pcm: Int16Array, asked: frame}``, where the
  ``Int16Array`` holds ``blocks * 256 * channels`` samples and ``asked``
  echoes the request. Its buffer goes in the transfer list, so nothing is
  copied on the way.
- worklet to worker: ``{offset: n}`` says rendered frame ``k`` is heard at
  ``AudioContext`` frame ``k + n``. `WorkletOutput.offset` holds the
  latest value, so you can schedule an event at an exact sample.
- worklet to worker: ``{underrun: n}`` reports ``n`` underruns since its
  last report; `WorkletOutput.underruns` adds them up.

The format's rate must match the page's ``AudioContext`` rate: the worklet
plays samples as they come and does not resample.
"""

try:
    import asyncio
except ImportError:  # pragma: no cover
    try:
        import uasyncio as asyncio
    except ImportError:
        asyncio = None

import time

from audiodev import AudioFormat, PCMOutput, check_latency, queue_bytes
from audiodev.bytequeue import ByteQueue

try:
    from js import Array, Int16Array, Object
except ImportError:  # pragma: no cover - non-browser import for tooling
    Array = None
    Int16Array = None
    Object = None

try:
    from pyodide.ffi import create_proxy, to_js
except ImportError:  # pragma: no cover - non-browser import for tooling
    try:
        from pyscript.ffi import create_proxy, to_js
    except ImportError:
        create_proxy = None
        to_js = None

#: Frames in one block of the wire protocol.
BLOCK_FRAMES = 256

DEFAULT_FORMAT = AudioFormat(48000, 1, 16)

# Buffered profile depth for pcm_out's queue, in milliseconds.
_BUFFERED_QUEUE_MS = 500
# Never smaller than this many blocks: a queue shorter than one request
# starves on every request.
_MIN_QUEUE_BLOCKS = 8


def _field(data, name):
    """Read ``name`` from a message: a JS object, or a dict in tests."""
    if isinstance(data, dict):
        return data.get(name)
    try:
        return getattr(data, name, None)
    except Exception:
        return None


def _as_bytes(data):
    view = memoryview(data)
    if getattr(view, "format", "B") not in ("B", "b", "c"):
        view = view.cast("B")
    return view


[docs] class WorkletOutput: """The worker's end of an AudioWorklet port. ``port`` is the ``MessagePort`` the page transferred to this worker. ``channels`` is 1 or 2. Set `source` to a callable taking a block count and returning ``blocks * 256 * channels`` int16 samples as any bytes-like object; until you do, the worklet gets silence. By default this sets ``port.onmessage``. If your worker shares the port with other messages, pass ``listen=False`` and call `handle` with each message's ``data`` yourself. """ def __init__(self, port, channels=1, sample_rate=48000, *, listen=True): if channels not in (1, 2): raise ValueError("worklet_audio supports 1 or 2 channels") self.port = port self.channels = int(channels) self.sample_rate = int(sample_rate) self.source = None #: Latest ``offset`` from the worklet, or None before the first one: #: rendered frame ``k`` is heard at context frame ``k + offset``. self.offset = None #: Underruns the worklet has reported. self.underruns = 0 #: Replies padded with silence because the source came up short. self.starved = 0 #: Frames sent so far: the rendered frame index of the next reply. self.frames = 0 #: ``asked`` of the latest request. self.asked = None self._proxy = None if listen: self.listen()
[docs] def block_bytes(self, blocks=1): """Bytes in ``blocks`` blocks at this channel count.""" return int(blocks) * BLOCK_FRAMES * self.channels * 2
[docs] def listen(self): """Take ``port.onmessage``. Called for you unless ``listen=False``.""" if self._proxy is not None: return handler = self._on_message self._proxy = create_proxy(handler) if create_proxy is not None else handler self.port.onmessage = self._proxy
[docs] def close(self): """Stop answering: release ``port.onmessage`` and its proxy.""" if self._proxy is None: return try: self.port.onmessage = None except Exception: pass destroy = getattr(self._proxy, "destroy", None) if destroy is not None: try: destroy() except Exception: pass self._proxy = None
def _on_message(self, event): self.handle(event.data)
[docs] def handle(self, data): """Act on one message from the worklet. Returns True if it was ours.""" need = _field(data, "need") if need is not None: self._answer(int(need), _field(data, "asked")) return True offset = _field(data, "offset") if offset is not None: self.offset = int(offset) return True underrun = _field(data, "underrun") if underrun is not None: self.underruns += int(underrun) return True return False
def _render(self, blocks): """PCM for ``blocks`` blocks, exactly ``block_bytes(blocks)`` long.""" size = self.block_bytes(blocks) source = self.source if source is None: return bytearray(size) data = source(blocks) if data is None: self.starved += 1 return bytearray(size) view = _as_bytes(data) if len(view) == size: return view if len(view) > size: return view[:size] self.starved += 1 out = bytearray(size) out[: len(view)] = view return out def _answer(self, blocks, asked): self.asked = asked if blocks <= 0: pcm = bytearray(0) else: try: pcm = self._render(blocks) except Exception: # Reply anyway: an unanswered request stalls the worklet. self._post(bytearray(self.block_bytes(blocks)), asked) self.frames += blocks * BLOCK_FRAMES raise self._post(pcm, asked) self.frames += max(0, blocks) * BLOCK_FRAMES def _post(self, pcm, asked): # One bulk copy into JS, then a view of that fresh buffer as int16. u8 = to_js(_as_bytes(pcm)) samples = Int16Array.new(u8.buffer, u8.byteOffset, u8.byteLength // 2) message = Object.new() message.pcm = samples message.asked = asked transfer = Array.new() transfer.push(samples.buffer) self.port.postMessage(message, transfer)
[docs] class WorkletPCMOutput(PCMOutput): """`audiodev.PCMOutput` over an AudioWorklet port. ``write()`` fills a queue and each request from the worklet drains it, padding with silence when the queue runs short (counted in `starved`). The worker can't block while it waits for the worklet, since the worklet's requests arrive on the same thread, so: - ``write()`` never waits. When the queue is full it drops the oldest audio to make room and counts the bytes in `dropped`. - ``try_write()`` takes only what fits and leaves you the rest. - ``awrite()`` and ``adrain()`` wait properly, yielding to the event loop so requests keep being answered. """ def __init__(self, fmt, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True, **kwargs): if fmt.bits != 16 or not fmt.signed or fmt.byteorder != "little": raise ValueError("worklet_audio requires signed 16-bit little-endian PCM") if fmt.channels not in (1, 2): raise ValueError("worklet_audio supports 1 or 2 channels") check_latency(latency) super().__init__(fmt, **kwargs) self.latency = latency self.poll_ms = int(poll_ms) minimum = _MIN_QUEUE_BLOCKS * BLOCK_FRAMES * fmt.frame_size limit = queue_bytes(fmt, latency, queue_ms, minimum=minimum) if limit is None: limit = max(minimum, fmt.rate * fmt.frame_size * _BUFFERED_QUEUE_MS // 1000) limit -= limit % fmt.frame_size self._queue = ByteQueue(limit) #: Bytes ``write()`` dropped because the queue was full. self.dropped = 0 self.worklet = WorkletOutput(port, fmt.channels, fmt.rate, listen=listen) self.worklet.source = self._drain_blocks # The worklet's numbers, here so you needn't reach through ``worklet``. @property def offset(self): return self.worklet.offset @property def underruns(self): return self.worklet.underruns @property def starved(self): return self.worklet.starved @property def frames(self): return self.worklet.frames
[docs] def handle(self, data): """Pass one worklet message in, when you created this with ``listen=False``.""" return self.worklet.handle(data)
def _drain_blocks(self, blocks): size = self.worklet.block_bytes(blocks) out = bytearray(size) got = self._queue.readinto(out) if got < size and not self.is_open: # Nothing has been written yet: silence, not starvation. return out return memoryview(out)[:got] if got < size else out
[docs] def space(self): """Bytes the queue can take now, in whole frames.""" free = self._queue.free() return max(0, free - free % self.format.frame_size)
[docs] def queued_size(self): return len(self._queue)
[docs] def is_active(self): return len(self._queue) > 0
[docs] def clear(self): self._queue.clear()
def _write(self, buf): view = memoryview(buf) over = len(view) - self._queue.free() if over > 0: self.dropped += over self._queue.push(view) return len(view)
[docs] def try_write(self, buf): self.open() source = self._prepare(buf) count = min(len(source), self.space()) if count <= 0: return 0 return self._queue.write(source[:count])
async def _awrite(self, buf): view = memoryview(buf) while True: count = min(len(view), self.space()) if count > 0: return self._queue.write(view[:count]) await _asleep_ms(self.poll_ms) def _drain(self): # Waiting here would block the very requests that drain the queue. return None async def _adrain(self): frames = len(self._queue) // self.format.frame_size deadline = time.time() + frames / float(self.format.rate) + 1.0 while len(self._queue) and time.time() < deadline: await _asleep_ms(self.poll_ms) def _close(self): self._queue.clear()
[docs] def deinit(self): """Close and stop answering the worklet.""" self.close() self.worklet.close()
async def _asleep_ms(milliseconds): if hasattr(asyncio, "sleep_ms"): await asyncio.sleep_ms(milliseconds) else: await asyncio.sleep(milliseconds / 1000)
[docs] def pcm_out(format=None, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True): """Create a `WorkletPCMOutput` on ``port`` (a Pyodide worker's MessagePort). ``latency`` sizes the queue: the default holds 500 ms, ``"low"`` holds 100 ms. ``queue_ms`` sets it directly. Either way it is at least eight blocks. ``format`` defaults to 48 kHz mono and must be 16-bit signed little-endian with one or two channels, at the ``AudioContext``'s rate. """ fmt = format or DEFAULT_FORMAT return WorkletPCMOutput( fmt, port=port, latency=latency, queue_ms=queue_ms, poll_ms=poll_ms, listen=listen, )