cyfaust

The cyfaust project provides a minimal, modular, self-contained, cross-platform cython wrapper of the Faust DSP language and the RtAudio cross-platform audio driver.

• Dual Backends: Interpreter (default, ~8MB) or LLVM JIT (~33MB, faster execution)
• Box API: Fully wrapped with both functional and object-oriented interfaces
• Signal API: Fully wrapped with both functional and object-oriented interfaces
• Platform Support: macOS, Linux, and Windows
• Build Variants: Dynamic (libfaust.so|dylib) and static (libfaust.a|lib)
• Faust Version: 2.85.9
• Documentation: cyfaust-docs

Installation

To install cyfaust with the faust interpreter backend (default):

pip install cyfaust

To install with the LLVM JIT backend:

pip install cyfaust-llvm

Features

• Python-oriented cross-platform implementation of the Faust DSP language

• Two backend options:

  • Interpreter (default): Compact ~8MB binary, good for development and most use cases
  • LLVM JIT: ~33MB binary with native code compilation for maximum performance

• Provides the following submodules (in the default build):

  • cyfaust.interp: wraps the faust interpreter and the rtaudio audio driver

  • cyfaust.box: wraps the faust box api

  • cyfaust.signal: wraps the faust signal api

  • cyfaust.common: common utilities and classes

• Self-contained, minimal, and modular design

• Can generate code using the following backends: c++, c, rust, codebox

• Can generate auxiliary files such as SVG block diagrams of DSP

• Dual functional/OO design for box and signal APIs with minimal code duplication

• Implements Memoryviews for read/write buffer using numpy or array.array

• Runtime UI parameter control: enumerate a DSP's controls and get/set their values by full path or label (params(), get_param(), set_param())

• Both dynamic and static build variants can be packaged as a self-contained python wheel

• Command-line interface for common operations

Quick Start

from cyfaust.interp import create_dsp_factory_from_string, RtAudioDriver
import time

# Define Faust DSP code
code = """
import("stdfaust.lib");
process = os.osc(440);
"""

# Create factory and DSP instance
factory = create_dsp_factory_from_string("osc", code)
dsp = factory.create_dsp_instance()
dsp.init(48000)

# Play through speakers
driver = RtAudioDriver(48000, 256)
driver.init(dsp)
driver.start()
time.sleep(2)
driver.stop()

Runtime parameters

A DSP's UI controls (sliders, buttons, checkboxes, nentries, bargraphs) can be enumerated and driven at runtime:

from cyfaust.interp import create_dsp_factory_from_string

factory = create_dsp_factory_from_string(
    "gain", 'process = _ * hslider("gain", 1, 0, 2, 0.01);'
)
dsp = factory.create_dsp_instance()
dsp.init(48000)

for p in dsp.params():
    print(p.path, p.kind, p.init, p.min, p.max)  # /gain/gain hslider 1.0 0.0 2.0

dsp.set_param("gain", 0.5)   # address by leaf label or full path; takes effect on the next compute
dsp.get_param("gain")        # 0.5

Buttons, checkboxes, sliders, and nentries are settable inputs; bargraphs are read-only outputs (set_param on one raises ValueError, as do unknown or ambiguous keys).

See the Getting Started guide and Examples for more usage patterns including the Box API, Signal API, buffer computation, and serialization.

Command-Line Interface

cyfaust provides a CLI accessible via the cyfaust command or python -m cyfaust:

cyfaust <command> [options]

Examples:

cyfaust play osc.dsp -d 5                     # play for 5 seconds
cyfaust compile synth.dsp -b cpp -o synth.cpp  # compile to C++
cyfaust params synth.dsp                       # list parameters (path, kind, range, value)
cyfaust params synth.dsp --get gain            # read a control value
cyfaust params synth.dsp --set gain 0.5        # set a control value
cyfaust json instrument.dsp --pretty           # export metadata
cyfaust validate filter.dsp --strict           # check for errors

See the full CLI Reference for all options.

Building from Source

git clone https://github.com/shakfu/cyfaust.git
cd cyfaust
make        # builds libfaust + installs for development
make test   # run tests

Common build targets:

make                   # dynamic interpreter build (default)
make STATIC=1 build    # static interpreter build
make build-llvm        # static LLVM build
make wheel             # build wheel
make wheel-llvm        # build LLVM wheel (cyfaust-llvm)
make wheel-windows     # Windows one-shot (deps + wheel + delvewheel)

Build options (set via make VAR=1):

Windows

On Windows, use the provided build script:

python scripts/build_windows.py              # static wheel (default)
python scripts/build_windows.py --dynamic    # dynamic wheel (bundles faust.dll)
python scripts/build_windows.py --clean      # clean first, then build
python scripts/build_windows.py --test       # build + install + run tests

If you have GNU Make installed, make wheel-windows also works for dynamic wheels.

Prerequisites: Visual Studio 2022 (or MSVC Build Tools), Python 3.10+, uv, and CMake.

See the full Building from Source guide for platform prerequisites, LLVM backend details, and wheel building instructions.

Platform Support

Interpreter backend (cyfaust):

LLVM backend (cyfaust-llvm):

Prior Art of Faust + Python

• DawDreamer by David Braun: Digital Audio Workstation with Python; VST instruments/effects, parameter automation, FAUST, JAX, Warp Markers, and JUCE processors. Full-featured and well-maintained. Use this for actual work! (pybind11)

• faust_python by Marc Joliet: A Python FAUST wrapper implemented using the CFFI (updated 2015). There's a more recent (updated in 2019) fork by Patrik Lechner. (cffi)

• pyfaust by Alexandru Stan: Embed Faust DSP Programs in Python. (cffi)

• faust-ctypes: a port of Marc Joliet's FaustPy from CFFI to Ctypes. (ctypes)

• faustpp: A post-processor for faust, which enables more flexible code generation.