A thread-safe wait-free single-consumer single-producer ring buffer for the web, and some utilities.
The main files of this library:
js/ringbuf.js
: base data structure, implementing the ring-buffer. This is intentionally heavily commented.js/audioqueue.js
: wrapper for audio data streaming, without usingpostMessage
.js/param.js
: wrapper for parameter changes, allowing to send pairs of index and value without usingpostMessage
.
This library contains an example, explained below, with the following files:
example/app.js
: example usage, main thread side (send audio and param changes to the real-time thread)example/processor.js
: example usage, real-time thread side (receive audio and parameter changes from the main thread)example/utils.js
: helper to load multiple files in anAudioWorkletGlobalScope
example/index.js
: vendored and built version of the library to have the example easily online.
- https://padenot.github.io/ringbuf.js/example/ (this will not work when Chrome will implement COOP and COEP).
- https://paul.cx/ringbuf.js/ (this has the right headers)
A sine wave is generated on the main thread, sent to the audio thread, played out. The frequency of this sine wave is controllable from the main thread. The amplitude of this sine wave is also controllable: the amplitude parameter is communicated lock-free to the real-time thread.
Yes this is a contrived example, people should not use the main thread or any other non-real-time thread this if they can. However sending audio from a non-real-time thread to a real-time thread is sometimes useful:
- Decoding a audio codecs that browsers don't support natively in a web worker,
sending the PCM to an
AudioWorklet
(no need to fiddle withAudioBufferSourceNode
, etc.) - Implementing emulators for (e.g.) old consoles that only had one execution thread and did everything on the same CPU
- Porting code that is using a push-style audio API (
SDL_QueueAudio
) without having to refactor everything.
The opposite (recording the input of an AudioWorklet
) is very useful:
- Implement off-main-thread off-real-time-thread audio analysis (streaming the
real-time audio data to a web worker, visualizing it using an
OffscreenCanvas
, shielding the audio processing and visualization from main thread load) - Implement off-main-thread off-real-time thread encoding of audio data in a
codec not supported by
MediaRecorder
, or maybe with more flexibility.
cd example; node server.js
This is a simple web server that sets the right headers to use
SharedArrayBuffer
(see Planned changes to shared memory
on MDN), and uses https
(however this requires a bit of manual setup,
mkcert can be useful, read the source,
it's not particularly complicated).
Please do (just open an issue or send a PR).
npm run-script build
allows running the build step and copying the file to allow the example to work.
Mozilla Public License 2.0