**Limitation:** AOT Faust-to-C++ fixes the patch set at build time. Player-authored or modded patches cannot run in a built player; live-edited patches run only in the editor (the developer-time lane of path (b)).
So Faust provides both bridge shapes the question names. The `FaustPlugin_template.cs`
path is the **OnAudioFilterRead bridge**: Unity calls `OnAudioFilterRead(float[] buffer, int
numchannels)` on its audio thread and C# P/Invokes the native `process`. `unity.cpp` is the
**native audio SDK** shape: Unity's mixer calls `ProcessCallback` directly with no managed
frame in the audio path.
`faust2unity` builds the native libraries and C# scripts and packs a `.unitypackage`;
platform scripts are `faust2winunity` (MinGW cross-compile: `-w32`/`-w64`) and
`faust2linuxunity` (`g++`, `-fPIC -shared`, `.so`) [V: scripts and README read; not run].
## Path (a): AOT Faust to C++ in a native plugin
### Per-platform outputs
| Platform | Output | Toolchain | Status |
|---|---|---|---|
| Windows x64 | `FaustPlugin_<name>.dll` | `faust2winunity -64` uses MinGW (`x86_64-w64-mingw32-gcc`) [V: script]. An MSVC build of the generated C++ is plausible but not in Faust's scripts. | [U] runs in a Unity Windows player |
| Linux x86_64 | `libFaustPlugin_<name>.so` | `g++ -fPIC -shared` (`faust2linuxunity`) [V: script] | [U] runs in a Unity Linux player |
| Inputs | `thruster.dsp` + `stdfaust.lib` tree | `faust` CLI with `-I` at faustlibraries | [V] |
Generating the thruster as C++ works [V]: `faust -I faustlibraries-20261031 -a minimal.cpp
-single -ftz 2 -vec -lv 1 thruster.dsp` gave 1,105 lines (40,045 bytes) with Faust 2.90.20.
Those are the same flags `AquaSynthNativeCompiler.CompileSource` passes to the JIT
(`src/AquaSynth.Faust/NativeFaustRuntime.cs:530`). The AOT lane should pick its flags
deliberately, not inherit them: `-vec` is a choice that the measurement plan below should
test against scalar output.
Windows and Linux builds need two different hosts or a cross-compiler. Starfire (Windows)
has Faust and a compiler only if someone installs them there [U].
### What is reusable from AquaSynth
| Part | Reusable for (a)? | Evidence |
|---|---|---|
| `patches/thruster/thruster.dsp` | Yes, as is. It is hand-written Faust, "not a `.aqua` script" (file header). | [V] |
| `FaustExport` / `FaustEmitter` (`src/AquaSynth.Core/FaustExport.cs`, 2,558 lines) | Only for `.aqua` patches. The thruster does not go through it. For an `.aqua` patch it yields the `.dsp` source to feed `faust -lang cpp`; `DspSourceDirectory` already writes it (`NativeFaustRuntime.cs:628`). | [V] |
| `FaustCompiler.CompileAsync` (`src/AquaSynth.Faust/FaustCompiler.cs:56`) | Yes. Runs the `faust` CLI with `-lang Cpp`; `FaustTargetLanguage.Cpp` exists. This is the AOT generator step. | [V] |
| `NativeFaustRuntime.cs` (1,132 lines: `AquaSynthPatchCompiler`, `AquaSynthStreamingPatch`, `FaustNativeToolchain`) | **Not in the shipped player.** It is the libfaust loader and the managed host. Under (a) it stays on the build/authoring side: it renders reference audio and the manifest that the plugin's output is checked against. | [V] |
| `tools/FaustRender` + `docs/renders/thruster-v5-manifest.json` | Yes, as the golden reference: hashes, peak, RMS, `nonFinite` per rpm case, 48 kHz / 512-frame blocks. The native plugin should be diffed against this. The manifest hashes predate the 2026-11-05 edit to `thruster.dsp` (`docs/faust-toolchain-boundary.md`, "Linux Native Toolchain"), so re-render first. | [V] |
| `AquaSynthNativeManifest` (id, compile key, sample rate, I/O counts, Faust version) | Yes as the artifact provenance record. It has **no parameter table** (no min, max, default). That is a gap for crossing params (below). | [V] |
Missing for (a), not in AquaSynth today: a build step that runs `faust2unity`-style
generation per patch and records the result as artifacts. That should be a script in
`tools/`, not a new library. Per the boundary doc, AquaSynth owns "generated
source/native artifact layout" and "parameter and bus manifests", and Aquarium/Unity owns
"artifact loading policy for its platform".
### Hot-path hazards in the managed bridge (if OnAudioFilterRead + managed host)
If the player used `AquaSynthStreamingPatch` directly (managed host, native `libfaust`
instance), these are in the audio callback [V: `NativeFaustRuntime.cs`]:
-`ProcessBlock(float[][] ...)` (line 251) allocates `IntPtr[]` arrays and pins six
`GCHandle`s per call. Use the pointer overload (line 235) with preallocated pinned buffers
| Where it runs | Mixer effect, native audio thread, no managed code | Managed callback on the audio thread, then P/Invoke |
| Source/generator | Effect slot on a mixer group; `ProcessCallback` returns `ERR_UNSUPPORTED` if `inchannels != outchannels` (`unity.cpp:179`) [V] | Component on a GameObject with `AudioSource` |
| Params | `SetFloatParameterCallback`, set from mixer exposed params or `AudioMixer.SetFloat` [U] | `setParameter(int, float)` per patch component |
| Risk | Mixer setup per patch; 15-char parameter names (below) | GC pauses or managed allocation can overrun the callback if the managed side allocates [U] |
| Fit for thruster | Better on determinism; whether a generator-only (0-input) effect behaves well in a mixer slot is [U] | Matches Faust's template; many instances are easy (one component each) |
The thruster has 0 inputs and 1 output. In both shapes a 1-channel Faust output goes to
the first interleaved channel only and zero-fills the rest (`interleavedWrite`,
`architecture/faust/dsp/dsp-tools.h:216-223`) [V]. A stereo player would hear left only
unless the patch is made to output two channels or the plugin is edited.
## Path (b): runtime `libfaust`/LLVM in the player
`AquaSynthPatchCompiler` already is this, host-side: `createCDSPFactoryFromString` via
`NativeLibrary.Load` (`NativeFaustRuntime.cs:793`), the C API delegates (727-737), instances
created and computed through `computeCDSPInstance`.
| Windows x64 | `libfaust.dll` plus `share/faust` | [U] no Windows libfaust built or run by this run. `AquaSynthFaustToolchain.LibraryFileNames` looks for `libfaust.dll`/`faust.dll` (`NativeFaustRuntime.cs:654-657`); the doc says `C:\Program Files\Faust` is the default home. |
Costs specific to AquaSynth's own history, from `docs/faust-toolchain-boundary.md`:
the Linux link first failed (`cannot find -lPolly -lPollyISL -lzstd`), and the prefix
`share/faust` lacked `stdfaust.lib` until the faustlibraries tree was added. The library
tree has to travel with the player (`AquaSynthFaustToolchain.Find` probes
`<AppContext.BaseDirectory>/Tools/Faust`, line 666).
Beyond size:
- A JIT needs executable memory. Desktop Windows/Linux allow it; iOS and consoles do not
[U]. A player that needs those later cannot have (b) as its only path.
- The compile step is multi-hundred-millisecond to seconds and must run on a worker thread
with a finished-DSP handoff (boundary doc, "Runtime Rule"). `AquaSynthNativeManifest.CompileMilliseconds`
records it [V: field exists; no number measured here].
- Output from a JIT with `-vec` at optLevel `-1` is whatever LLVM emits on that machine.
It is not bit-identical across hosts [U], so the reproducibility invariant in the
boundary doc ("artifacts are reproducible from script, version, target, options") weakens.
## Licensing if shipped
Read from files in the tree this run built [V] unless marked.
| Component | Licence | Ship implication |
|---|---|---|
| Faust compiler / `libfaust` 2.90.20 | LGPL-2.1-or-later (header of `COPYING.txt`: "GNU Lesser General Public License ... version 2.1") | Dynamic loading of an unmodified `libfaust.so/.dll` satisfies LGPL if the user can replace it. Ship licence text and source offer. [U] legal review. |
| Faust architecture files (`unity.cpp`) | LGPL-3.0-or-later **with exception**: you may create a larger work with the architecture section and distribute it under terms of your choice, **so long as the architecture section is not modified** | Use `unity.cpp` / `unityplugin.cpp` unmodified and the rest of the plugin has no copyleft. Editing them (e.g. to add param clamping) drops the exception for that file. Prefer clamping elsewhere (below). |
| Generated C++ from `faust` (the DSP section of the output) | Not governed by the compiler licence per Faust's licence note [U: from Faust FAQ, not checked here] | Verify before shipping. |
| `faustlibraries` (`stdfaust.lib`, used by the thruster via `os`, `fi`, `no`, `si`, `ba`, `ma`) | Per-function: `oscillators.lib`, `noises.lib`, `signals.lib`, `basics.lib`, `maths.lib` headers say LGPL (GRAME); `filters.lib` says "Each function in this library has its own license" (e.g. Julius O. Smith III) | Compiled into the generated code. Need a per-function licence inventory of the functions the thruster calls before shipping. Not done. |
| LLVM (path (b) only) | Apache-2.0 with LLVM exceptions [U: from memory, not in tree] | Permissive; ship notice. Also notices for z3 (MIT), libffi (MIT), libedit (BSD) [U]. |
Net: (a) puts only unmodified-architecture-file and faustlibraries notices in the player. (b)
adds LGPL relinking obligations for `libfaust` and a third-party LLVM stack.
`UnityAudioParameterDefinition` with `min`, `max`, `defaultval` from the Faust UI
(`unity.cpp:116-118`) [V]. Unity then knows the range and the default; the inspector and
mixer use it. **Names are cut to 15 characters** (`strncpy(pdef[i].name, ..., 15)`,
`unity.cpp:112`) [V]. `rpm` fits; Aqua-style paths such as `/curves/<name>/depth` do not.
The AquaSynth path lengths need a unique-prefix rule or the control must be
addressed by index.
- **Runtime `libfaust` (b)**: `AquaSynthStreamingPatch.SetControls` writes the float's
bits to the zone pointer with `Marshal.WriteInt32` (`NativeFaustRuntime.cs:868`). No
range or default crosses; `FaustUiGlue.AddControl` discards `init, min, max, step`
(line 1028) [V].
Float writes are the only thing crossing. A single aligned 32-bit store is atomic on x86-64,
so no lock is needed for one scalar control [U: assumes the compiler does not tear; the
generated code reads each zone once per block, `float fSlow0 = static_cast<float>(fHslider0)`,
`compute` line 430 in the generated file] [V for the read]. A control that moves within a
block takes effect at the next block, smoothed by `si.smooth` (rpm uses a 0.2 s time
constant).
### Needed for several bounded params
1. A parameter table per patch alongside the existing `AquaSynthNativeManifest`:
`{path, index, default, min, max}`. (b) can get it from `FaustUiGlue` if
`AddControl` stops discarding `init/min/max`; (a) can get it from the same
`faust -json` output or from the C++ UI callbacks at build time.
2. One clamp site (below), driven from that table, owned by AquaSynth, not by
Unity code.
3. A normalized-to-range mapping owned by AquaSynth for load/velocity/quality when the game
supplies 0..1, if that is the game's contract. `ControlSurfaceCatalog` already holds
normalized surfaces for `.aqua` (`hslider(path, DefaultNormalized, 0, 1, 0.001)`,
`FaustExport.cs:157`) [V]; the thruster has none.
## Are param inputs clamped today?
No, for the thruster path. Layer by layer [V]:
| Layer | Clamp? |
|---|---|
| `thruster.dsp` | No. Slider min/max are UI metadata. The generated `compute` reads the zone raw (`fSlow0 = fHslider0`). An rpm of 20000 or -5 reaches `si.smooth` and every formula (`shaft = 28 + rpm*0.025`, `load = (rpm-300)/5700`, band centres, drive). |
| `FaustNativeToolchain.WriteControl` (`NativeFaustRuntime.cs:860-869`) | No. Only unknown-path rejection, and `NaN`/infinity written as-is. |
| `tools/FaustRender/Program.cs:51` | No; it only sweeps within its CLI arguments. |
| `NativeFaustRuntimeTests.cs` | No test for out-of-range, NaN, or infinity control values found (grep for clamp/throws/range: no hit). |
| `ControlSplineTimeline` (`src/AquaSynth.Core/ControlSplineTimeline.cs:167-231`) | Yes, but only normalized `[0,1]` for `.aqua` control splines. It is not in the thruster path. |
| Unity side | The mixer/inspector clamp to the declared `min/max` in the native SDK path [U]. A script calling `setParameter` or `SetFloat` directly is not clamped by Faust's glue [V]. |
The final `tanh` and the 0.425 trim (`thruster.dsp` last line) bound the output. Peak at
rpm 4800 is 0.36 (`docs/renders/thruster-v5-manifest.json`) [V]. Whether out-of-range rpm stays
finite and bounded is **not measured**: the manifest covers 300..6000 only. Hence
`nonFinite` coverage in the plan below includes out-of-range and non-finite inputs.
Recommended clamp site: in the AquaSynth-owned manifest/host layer (for (a), a small
wrapper in the managed script that Faust's unmodified architecture files sit under; for (b),
`WriteControl`), clamping to the declared min/max and rejecting NaN. Do not edit
`unity.cpp`/`APIUI.h` (loses the architecture exception). The DSP itself can also carry the
bound: `hslider(...) : max(300) : min(6000)` in the `.dsp` is the one place both
lanes would share. That is a patch edit and a design choice for the thruster's owner, not
decided here.
## Callback-deadline measurement plan (rerunnable)
Goal: show, per path and platform, that `compute` fits the audio callback with margin,
including at the worst rpm sweep, under CPU load. Nothing here has been run.
**Deadline.** `D = frames / sampleRate`. Unity's block comes from `AudioSettings.GetDSPBufferSize`
(`FaustPlugin_template.cs``getBufferSize`). Test 256, 512, 1024 frames at 44.1 k and
48 k (the render manifest uses 48 k / 512, i.e. D = 10.67 ms). Proposed pass line: