audiodev.worklet_audio

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.

audiodev.worklet_audio.BLOCK_FRAMES = 256

Frames in one block of the wire protocol.

class audiodev.worklet_audio.WorkletOutput(port, channels=1, sample_rate=48000, *, listen=True)[source]

Bases: object

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.

offset

Latest offset from the worklet, or None before the first one: rendered frame k is heard at context frame k + offset.

underruns

Underruns the worklet has reported.

starved

Replies padded with silence because the source came up short.

frames

the rendered frame index of the next reply.

Type:

Frames sent so far

asked

asked of the latest request.

block_bytes(blocks=1)[source]

Bytes in blocks blocks at this channel count.

listen()[source]

Take port.onmessage. Called for you unless listen=False.

close()[source]

Stop answering: release port.onmessage and its proxy.

handle(data)[source]

Act on one message from the worklet. Returns True if it was ours.

class audiodev.worklet_audio.WorkletPCMOutput(fmt, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True, **kwargs)[source]

Bases: 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.

dropped

Bytes write() dropped because the queue was full.

handle(data)[source]

Pass one worklet message in, when you created this with listen=False.

space()[source]

Bytes the queue can take now, in whole frames.

queued_size()[source]

Bytes still waiting to play or capture. Default 0.

is_active()[source]

True while PCM remains queued. Default False.

clear()[source]

Drop queued PCM now. Default no-op.

try_write(buf)[source]

Push as many bytes as the backend will take without blocking.

Unlike write, a 0-byte or partial I2S return is not an error: the caller keeps the remainder. Volume scaling is applied to buf before the backend sees it; leftover bytes should be retried as the original unscaled prefix.

deinit()[source]

Close and stop answering the worklet.

audiodev.worklet_audio.pcm_out(format=None, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True)[source]

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.