> For the complete documentation index, see [llms.txt](https://liquidated.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://liquidated.gitbook.io/docs/rings-wasm-port.md).

# Rings DSP Port

Technical notes for the browser-based physical-modelling audio engine.

Status: the original Rings DSP core now runs in the browser as WebAssembly, driven by the Liquidated/HL order gate and pitch model.

## Source Choice

Use the original Mutable Instruments Eurorack DSP source for the audio engine:

* Manual reference: <https://pichenettes.github.io/mutable-instruments-documentation/modules/rings/manual/>
* Source tree: <https://github.com/pichenettes/eurorack/tree/master/rings>
* DSP core: <https://github.com/pichenettes/eurorack/tree/master/rings/dsp>

Avoid branding the module as an official Mutable Instruments derivative. The repo README says the STM32F projects are MIT licensed, hardware is CC-BY-SA-3.0, and "Mutable Instruments" is a registered trademark.

VCVRack/AudibleInstruments is useful as a parameter/reference wrapper:

* Rack source: <https://github.com/VCVRack/AudibleInstruments/blob/v2/src/Rings.cpp>

But its `src/` code is GPL-3.0-or-later, so copying that wrapper into this MIT repo would change the licensing picture. For a clean browser port, use the MIT Rings DSP directly and write a small local browser wrapper.

## Parameter Mapping

The browser UI should stay simple and fader-based, but drive the same conceptual patch:

* `frequency` -> pitch / transpose
* `structure` -> model structure
* `brightness` -> exciter/resonator brightness
* `damping` -> decay / damping
* `position` -> pickup/excitation position
* `frequencyCv`, `structureCv`, `brightnessCv`, `dampingCv`, `positionCv` -> attenuverters
* `strum` -> generated by random order gate
* `v/oct` -> generated by order-size high/low pitch
* `in` -> generated by ADSR/noise exciter
* `odd` / `even` -> selectable outputs

## Required Native Files

Minimum Rings-side source set to vendor or fetch during build:

* `rings/dsp/part.cc`
* `rings/dsp/part.h`
* `rings/dsp/patch.h`
* `rings/dsp/performance_state.h`
* `rings/dsp/strummer.h`
* `rings/dsp/resonator.cc`
* `rings/dsp/resonator.h`
* `rings/dsp/string.cc`
* `rings/dsp/string.h`
* `rings/dsp/string_synth_part.cc`
* `rings/dsp/string_synth_part.h`
* `rings/dsp/string_synth_*.h`
* `rings/dsp/fm_voice.*`
* `rings/dsp/fx/*`
* matching `stmlib` DSP headers used by the above files

## Browser Shape

Compile a small C++ bridge with Emscripten:

* `rings_init(sampleRate)`
* `rings_set_patch(frequency, structure, brightness, damping, position)`
* `rings_set_mods(freqCv, structCv, brightCv, dampCv, posCv)`
* `rings_strum(vOct, velocity, trigger, exciter)`
* `rings_process(inputPtr, oddPtr, evenPtr, frames)`

Run that bridge inside an `AudioWorkletProcessor`. The React page sends fader/order events to the worklet; the worklet owns the DSP state so audio stays real-time and does not depend on React timing.

## Browser Integration

The generated loader and binary are shipped as:

* `public/rings/rings-dsp.js`
* `public/rings/rings-dsp.wasm`

`RingsWasmVoice` loads the module, owns the Web Audio context, exposes the patch controls, and renders each strum into a playable buffer. Audio is primed synchronously inside the user's entry or sound-button gesture so mobile Safari does not reject the later asynchronous WASM initialization.

To rebuild the artifacts after changing the native bridge, install Emscripten and run:

```sh
npm run build:rings-wasm
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://liquidated.gitbook.io/docs/rings-wasm-port.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.