FunDSP

Audio Processing and Synthesis Library for Rust

FunDSP is an audio DSP (digital signal processing) library for audio processing and synthesis.

FunDSP features a powerful inline graph notation for describing audio processing networks. The notation taps into composable, zero-cost abstractions that express the structure of audio networks as Rust types.

Another innovative feature of FunDSP is its signal flow system, which can determine analytic frequency responses for any linear network.

FunDSP comes with a combinator environment containing a suite of audio components, math and utility functions and procedural generation tools.

Uses

• Audio processing and synthesis for games and applications
• Education
• Music making
• Sound hacking and audio golfing
• Prototyping of DSP algorithms

Rust Audio Discord

To discuss FunDSP and other topics, come hang out with us at the Rust Audio Discord.

Related Projects

bevy_fundsp integrates FunDSP into the Bevy game engine.

bevy_procedural_audio is a fork of bevy_fundsp that is more up to date.

bgawk is a sandbox for playing with physics and sound.

lapis is an interpreter for FunDSP expressions.

midi_fundsp enables the easy creation of live synthesizer software using FunDSP for synthesis.

quartz is a visual programming and DSP playground with releases for Linux, Mac and Windows.

Installation

Add fundsp to your Cargo.toml as a dependency.

[dependencies]
fundsp = "0.23.0"

The files feature is enabled by default. It adds support for loading of audio files into Wave objects via the Symphonia crate.

The fft feature is also enabled by default. It adds support for efficient FFT convolutions via the fft_convolver crate.

no_std Support

FunDSP supports no_std environments. To enable no_std, disable the feature std, which is enabled by default. The alloc crate is still needed for components that allocate memory.

Audio file reading and writing is not available in no_std. The convolution engine is also missing in action, as it depends on rustfft.

[dependencies]
fundsp = { version = "0.23.0", default-features = false }

Graph Notation

FunDSP Composable Graph Notation expresses audio networks in algebraic form, using graph operators. It was developed together with the functional environment to minimize the number of typed characters needed to accomplish common audio tasks.

Many common algorithms can be expressed in a natural form conducive to understanding. For example, an FM oscillator can be written simply (for some f and m) as:

sine_hz(f) * f * m + f >> sine()

The above expression defines an audio graph that is compiled into a stack allocated, inlined form using the powerful generic abstractions built into Rust. Connectivity errors are detected during compilation, saving development time.

Audio DSP Becomes a First-Class Citizen

With no macros needed, the FunDSP graph notation integrates audio DSP tightly into the Rust programming language as a first-class citizen. Native Rust operator precedences work in harmony with the notation, minimizing the number of parentheses needed.

FunDSP graph expressions offer even more economy in being generic over channel arities, which are encoded at the type level. A mono network can be expressed as a stereo network simply by replacing its mono generators and filters with stereo ones, the graph notation remaining the same.

Basics

Component Systems

There are two parallel component systems: the static AudioNode and the dynamic AudioUnit.

---

| Trait | Dispatch | Allocation Strategy | Connectivity | | ------------- | -------------------- | ------------------- | ------------ | | AudioNode | static, inlined | stack | input and output arity fixed at compile time | | AudioUnit | dynamic, object safe | heap | input and output arity fixed after construction |

---

All AudioNode and AudioUnit components use 32-bit floating point samples (f32).

The main property of a component in either system is that it is a processing node in a graph with a specific number of input and output connections, called its arity. Audio and control signals flow through input and output connections.

Both systems operate on signals synchronously as an infinite stream. The stream can be rewound to the start at any time using the reset method.

AudioNodes can be stack allocated for the most part. Some nodes may use the heap for audio buffers and the like.

The allocate method preallocates all needed memory. It should be called last before sending something into a real-time context. This is done automatically in the Net and Sequencer frontends.

The purpose of the AudioUnit system is to grant more flexibility in dynamic situations: decisions about input and output arities and contents can be deferred to runtime.

Conversions

AudioNodes are converted to the AudioUnit system using the wrapper type An, which implements AudioUnit. Opcodes in the preludes return nodes already wrapped.

AudioUnits can in turn be converted to AudioNode with the wrapper unit. In this case, the input and output arities must be provided as type-level constants U0, U1, ..., for example:

use fundsp::prelude32::*;
// The number of inputs is zero and the number of outputs is one.
let type_erased: An<Unit<U0, U1>> = unit::<U0, U1>(Box::new(white() >> lowpass_hz(5000.0, 1.0) >> highpass_hz(1000.0, 1.0)));

Processing

Processing samples is easy in both AudioNode and AudioUnit systems. The tick method is for processing single sample frames, while the process method processes whole blocks.

If maximum speed is important, then it is a good idea to use block processing, as it reduces function calling, processing setup and dynamic network overhead, and enables explicit SIMD support.

Mono samples can be retrieved with get_mono and filter_mono methods. The get_mono method returns the next sample from a generator that has no inputs and one or two outputs, while the filter_mono method filters the next sample from a node that has one input and one output:

let out_sample = node.get_mono();
let out_sample = node.filter_mono(sample);

Stereo samples can be retrieved with get_stereo and filter_stereo methods. The get_stereo method returns the next stereo sample pair from a generator that has no inputs and one or two outputs, while the filter_stereo method filters the next sample from a node that has two inputs and two outputs.

let (out_left_sample, out_right_sample) = node.get_stereo();
let (out_left_sample, out_right_sample) = node.filter_stereo(left_sample, right_sample);

Block Processing

The buffer module contains buffers for block processing. The buffers contain 32-bit float samples. There are two types of owned buffers: the static BufferArray and the dynamic BufferVec.

Buffers are always 64 samples long (MAX_BUFFER_SIZE), have an arbitrary number of channels, and are explicitly SIMD accelerated with the type f32x8 from the wide crate. The samples are laid out noninterleaved in a flat array.

BufferArray is an audio buffer backed by an array. The number of channels is a generic parameter which must be known at compile time. Using this buffer type it is possible to do block processing without allocating heap memory.

BufferVec is an audio buffer backed by a dynamic vector. The buffer is heap allocated. The number of channels can be decided at runtime.

use fundsp::prelude64::*;
// Create a stereo buffer on the stack.
let mut buffer = BufferArray::<U2>::new();
// Declare stereo noise.
let mut node = noise() | noise();
// Process 50 samples into the buffer. There are no inputs, so we can borrow an empty buffer.
node.process(50, &BufferRef::empty(), &mut buffer.buffer_mut());
// Create another stereo buffer, this one on the heap.
let mut filtered = BufferVec::new(2);
// Declare stereo filter.
let mut filter = lowpole_hz(3000.0) | lowpole_hz(3000.0);
// Filter the 50 noise samples.
filter.process(50, &buffer.buffer_ref(), &mut filtered.buffer_mut());

To call process automatically behind the scenes, use the BlockRateAdapter adapter component. However, it works only with generators, which are components with no inputs.

To access f32 values in a buffer, use methods with the f32 suffix, for example, at_f32 or channel_f32.

Sample Rate Independence

Of the signals flowing in graphs, some contain audio while others are controls of different kinds.

With control signals and parameters in general, we prefer to use natur