ringbuf.js


A thread-safe wait-free single-consumer single-producer ring buffer for the web,
and some utilities.

The main files of this library:

- src/ringbuf.ts: base data structure, implementing the ring-buffer. This is
intentionally heavily commented.
- src/audioqueue.ts: wrapper for audio data streaming, without using
postMessage.
- src/param.ts: wrapper for parameter changes, allowing to send pairs of index
and value without using postMessage.

Examples and use-cases

is a deployment of the examples in this
repository with a web server that answers with the right headers for this
directory, and allows the example to work. More details available at Planned
changes to shared memory
.

Those examples work in browsers that support both the AudioWorklet, and
SharedArrayBuffer.

While most real-time audio work should happen on a real-time thread (which means
inside the AudioWorkletGlobaleScope on the Web), sending (resp. receiving) audio
to (from) a non-real-time thread is 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 with
AudioBufferSourceNode, etc.)
- Conversely, recording the output of an AudioContext using an
AudioWorkletNode with a very high degree of reliability and extreme
flexibility, possibly using Web Codecs or a WASM based solution for the
encoding, and then sending the result to the network or storing it locally.
- 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.
- 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)

Run locally

> cd public; node ../server.mjs

This is a simple web server that sets the right headers to use
SharedArrayBuffer (see Planned changes to shared memory

on MDN).

Contribute

Please do (just open an issue or send a PR).

> make build

allows running the build step and copying the file to allow the example to work.

> make doc

allows rebuilding the documentation.

Performance Benchmarks

As of version 0.4.0, the whole codebase has been ported to TypeScript, tooling
has been modernized and dependencies were updated. The package is now also
marked as side-effect free, which allows bundlers to tree-shake the code for
unused symbols when imported.

Alongside these updates, two performance optimizations were introduced:

- _copy has been optimized by a loop factor of 16.
bench
- deinterleave has been optimized by unrolling the loop with a factor of 4.
bench

Early, and limited test results have shown a substantial performance improvement
in buffer copying by ~325%. For ongoing monitoring in engine behaviour,
benchmarks have been added for independent verification of the results.

Compatibility

This needs the SharedArrayBuffer, so a couple of HTTP headers might need to be
set on the web server serving the page.

``
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
``

As of 2023-05-25, the following browsers are compatible:

- Firefox Desktop all current versions including current ESR
- Firefox for Android all current versions
- Chrome Desktop and Chromium-based browsers (for a long time)
- Chrome for Android
- Safari

License

Mozilla Public License 2.0