adac 0.1.0

automatic differentiable audio compilation: trained differentiable audio models to real-time FAUST DSP

ADAC

Automatic Differentiable Audio Compilation

from differentiable audio research to efficient real-time DSP

compile trained models to real-time DSP  ·  hear the optimisation as it trains  ·  stability-certified before every export

---

Paper (arXiv) · Documentation · Report a Bug

the problem

researchers design and optimise audio processors in differentiable frameworks such as FLAMO, but deploying them as efficient real-time DSP requires manual reimplementation. this is error-prone and creates a gap between research prototypes and usable tools. the worked example throughout is the feedback delay network (FDN), which exercises every part of the compiler.

how it works

the pipeline traverses the model graph, extracts all parameters (delays, gains, matrices, filters), serialises them to a JSON intermediate representation, and generates valid FAUST DSP code. extraction is map-aware: matrix types with non-identity maps (orthogonal, hadamard, householder) serialise the effective matrix the model applies, with the raw trainable weights preserved for round-tripping. json_to_flamo reconstructs the original model from the config.

on top of the codegen core:

HotReload	republishes the model to a running FAUST plugin during training, so you hear the optimisation while it runs
macro-controls	rt60, dry_wet, and pre_delay knobs layered onto the generated plugin without touching the trained parameters
certify	computes a stability certificate for every feedback loop, written as .cert.json next to the .dsp
export_juce	turns a config into an installed VST3/AU plugin in one call

installation

pip install -e .          #core compiler, numpy only
pip install -e ".[full]"  #full model support: flamo + pytorch

building plugins additionally requires the FAUST distribution and JUCE.

quick start

import adac

#given a trained model and sample rate
faust_code = adac.flamo_to_faust(model, fs=48000, name="MyReverb")

#write to file
with open("reverb.dsp", "w") as f:
    f.write(faust_code)

or use the two-step pipeline for inspection:

config = adac.flamo_to_json(model, fs=48000, name="MyReverb")
faust_code = adac.json_to_faust(config, controls={"rt60": True, "dry_wet": True})

hear it while it trains

live = adac.HotReload(fs=48000, name="MyReverb", controls={"rt60": True})
for step in range(n_steps):
    loss = criterion(model(x), target)
    loss.backward()
    optimiser.step()
    live.update(model)
live.update(model, force=True)

the hot-reload CLAP plugin (FAUST interpreter plus file watcher) lives in faust/architecture/clap/. reloads take about 100 ms and knob positions survive them. full script: examples/live_training.py.

ship it

adac.export_juce(
    adac.flamo_to_json(model, fs=48000, name="MyReverb"),
    "exported/", name="MyReverb",
    controls={"rt60": True, "dry_wet": True, "pre_delay": True},
    juce_modules="~/JUCE/modules",
    build=True,
)

one call: FAUST generation, stability certificate, JUCE project, release build, install into the user plugin folders (macOS). the export refuses to build a model whose certificate says unstable or not-certified; pass strict=False to override. full script: examples/export_plugin.py.

certify

cert = adac.certify(config)
print(cert["verdict"])

the criterion is small-gain: the product of per-element spectral norms around each feedback loop must stay below one at every frequency, evaluated on the parameter values as emitted (single precision). verdicts are certified-stable, marginally-stable, indeterminate, not-certified, unstable. a lossless prototype is marginally stable; with the rt60 control it is certified at any knob position.

equivalence

generated FAUST matches the source model sample-exactly, direct paths included. the energy decay of the compiled plugin follows the reference throughout, and the underlying impulse responses agree to within single-precision arithmetic noise. all four stereo paths match identically; the suite pins them.

the rt60 macro-control, measured by Schroeder integration, follows the ideal decay for the slider value:

cost stays well within real time as the network grows: a 32-line FDN, a large reverberator, runs at roughly ninety times real time on a single core, tracking the predicted Θ(N²) until the feedback matrix exceeds the cache.

regenerate the light figures with python examples/make_plots.py, then the dark variants with python examples/make_dark_plots.py.

supported modules

source module	FAUST output	description
parallelDelay	@(n) / de.fdelay	integer or fractional sample delays
Gain / Matrix	sum-of-products function	mixing matrices (hoisted, map-aware)
HouseholderMatrix	sum-of-products function	emitted as the effective matrix
parallelGain	*(g)	per-channel diagonal gains
parallelSOSFilter	fi.tf2(...)	cascaded biquad filters
Series	:	sequential composition
Parallel	, / :>	side-by-side or summing
Recursion	~	feedback loops (FDN core)
Biquad / SVF	fi.tf2 / fi.svf.*	single-channel filters
Shell	(unwrapped)	FFT wrapper skipped

testing

pytest                 #unit tests
pytest -m integration  #integration, needs faust + full install

201 unit tests validate the full pipeline: map-aware parameter extraction, delay quantisation, SOS normalisation, gain classification, graph traversal, code generation, macro-control wiring, multichannel arities, hot-reload publishing, certificate verdicts, and export orchestration.

integration tests compare impulse responses between the source model (frequency domain) and generated FAUST (time domain) sample-by-sample.

project structure

src/adac/
  codegen/
    flamo_to_json.py     parameter extraction and graph traversal
    json_to_faust.py     FAUST code generation and macro-controls
    json_to_flamo.py     model reconstruction from JSON config
    flamo_to_faust.py    convenience wrapper (both steps)
  hotreload.py           training-time live publishing
  certificate.py         small-gain stability certificate
  export.py              JUCE plugin export
examples/
    live_training.py
    export_plugin.py
    make_plots.py
    make_dark_plots.py
tests/
    test_flamo_to_json.py
    test_json_to_faust.py
    test_flamo_to_faust.py
    test_param_extraction.py
    test_hotreload.py
    test_certificate.py
    test_export.py
    integration/
        test_ir_comparison.py
        generate_flamo_ir.py

related projects

• FLAMO — differentiable audio processing framework
• pyFDN — python feedback delay networks
• FAUST — functional audio stream

license

MIT — see LICENSE for details.