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:

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})

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)

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,
)

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

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

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.