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 forblocksblocks. The worker replies exactly once per request.worker to worklet:
{pcm: Int16Array, asked: frame}, where theInt16Arrayholdsblocks * 256 * channelssamples andaskedechoes the request. Its buffer goes in the transfer list, so nothing is copied on the way.worklet to worker:
{offset: n}says rendered framekis heard atAudioContextframek + n.WorkletOutput.offsetholds the latest value, so you can schedule an event at an exact sample.worklet to worker:
{underrun: n}reportsnunderruns since its last report;WorkletOutput.underrunsadds 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:
objectThe worker’s end of an AudioWorklet port.
portis theMessagePortthe page transferred to this worker.channelsis 1 or 2. Setsourceto a callable taking a block count and returningblocks * 256 * channelsint16 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, passlisten=Falseand callhandlewith each message’sdatayourself.- offset
Latest
offsetfrom the worklet, or None before the first one: rendered framekis heard at context framek + 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
askedof the latest request.
- class audiodev.worklet_audio.WorkletPCMOutput(fmt, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True, **kwargs)[source]
Bases:
PCMOutputaudiodev.PCMOutputover an AudioWorklet port.write()fills a queue and each request from the worklet drains it, padding with silence when the queue runs short (counted instarved). 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 indropped.try_write()takes only what fits and leaves you the rest.awrite()andadrain()wait properly, yielding to the event loop so requests keep being answered.
- dropped
Bytes
write()dropped because the queue was full.
- 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.
- audiodev.worklet_audio.pcm_out(format=None, *, port, latency=None, queue_ms=None, poll_ms=4, listen=True)[source]
Create a
WorkletPCMOutputonport(a Pyodide worker’s MessagePort).latencysizes the queue: the default holds 500 ms,"low"holds 100 ms.queue_mssets it directly. Either way it is at least eight blocks.formatdefaults to 48 kHz mono and must be 16-bit signed little-endian with one or two channels, at theAudioContext’s rate.