CamillaDSP

CamillaDSP is a powerful and flexible audio processing tool, designed for applications like active crossovers, room correction, and advanced audio filtering.

The CamillaDSP project encompasses:

• CamillaDSP (the engine): The core DSP engine, written in Rust, responsible for real-time audio processing. It's a command-line application that runs on Linux, macOS, and Windows. It can be used stand-alone, or together with the GUI and other related projects. The CamillaDSP engine is the topic of this readme.
• CamillaDSP (the ecosystem): A broader family of related projects, including:
  • CamillaGUI: A user-friendly web-based interface for configuring and controlling the CamillaDSP engine.
  • camilladsp-setupscripts: Automated setup scripts.
  • pyCamillaDSP: A Python library for interacting with the CamillaDSP engine via its websocket interface.
  • pyCamillaDSP-plot: A Python library for visualizing CamillaDSP configurations and filter responses.
  • camilladsp-config: A repository of example configurations and scripts for common use cases.
  • camilladsp-controller: A controller for automatic sample rate switching.

CamillaDSP engine v4.1

The CamillaDSP engine is a command-line application that runs on Linux, macOS, and Windows.

Audio data is captured from a capture device and sent to a playback device. ALSA, PulseAudio, PipeWire, Jack, Wasapi, ASIO and CoreAudio are currently supported for both capture and playback.

The processing pipeline consists of any number of filters and mixers. Mixers are used to route audio between channels and to change the number of channels in the stream. Filters can be both IIR and FIR. IIR filters are implemented as biquads, while FIR use convolution via FFT/IFFT. A filter can be applied to any number of channels. All processing is done in chunks of a fixed number of samples. A small number of samples gives a small in-out latency while a larger number is more efficient. The full configuration is given in a YAML file.

License

CamillaDSP is free software; you can redistribute it and/or modify it under the terms of either of the following licenses:

1) the GNU General Public License version 3, available at www.gnu.org or LICENSE_GPLv3.txt. 2) the Mozilla Public License Version 2.0, available at www.mozilla.org, or LICENSE_MPL2.0.txt.

ASIO backend and license implications

The optional ASIO backend (asio-backend feature) depends on the ASIO SDK, which is licensed under the GNU General Public License version 3. When CamillaDSP is built with the asio-backend feature enabled, the resulting binary is subject to the GPLv3 license only. The MPL 2.0 option does not apply to binaries that include ASIO SDK code.

Disclaimer

The software is provided "as is" without any warranty. You use it entirely at your own risk, and the creators/distributors are not responsible for any damages that might result from its use or failure.

For more details, please see the GNU General Public License Version 3.0: - §15. Disclaimer of Warranty - §16. Limitation of Liability

and the Mozilla Public License Version 2.0: - §6. Disclaimer of Warranty - §7. Limitation of Liability

Table of Contents

Introduction - Background - How it works - System requirements - Usage example: crossover for 2-way speakers - Dependencies - Companion libraries and tools - GUI

Installing

Building - Build with standard features - Customized build - Optimize for your system - Building on Windows and macOS - Building with ASIO backend (Windows)

How to run - Command line options - Reloading the configuration - Controlling via websocket

Processing audio - Cross-platform - Jack - File or pipe - Windows - ASIO - macOS (CoreAudio) - Linux - ALSA - PulseAudio - PipeWire

Configuration - The YAML format - Title and description - Volume control - Devices - Resampling - Rate adjust: what problem it solves, and how it works - Mixers - Filters - Gain - Volume - Loudness - Delay - FIR - IIR - Dither - Limiter - Difference equation - Processors - Compressor - NoiseGate - Pipeline - Filter step - Mixer and Processor step - Tokens in names - Bypassing steps - Using filters from REW - Visualizing the config

Related projects

Getting help - FAQ - Troubleshooting

Introduction

Background

The purpose of CamillaDSP is to enable audio processing with combinations of FIR and IIR filters. This functionality is available in EqualizerAPO, but for Windows only. For Linux the best known FIR filter engine is probably BruteFIR, which works very well but doesn't support IIR filters. The goal of CamillaDSP is to provide both FIR and IIR filtering for Linux, Windows and macOS, to be stable, fast and flexible, and be easy to use and configure.

• BruteFIR: https://torger.se/anders/brutefir.html
• EqualizerAPO: https://sourceforge.net/projects/equalizerapo/
• The IIR filtering is heavily inspired by biquad-rs: https://github.com/korken89/biquad-rs

How it works

The audio pipeline in CamillaDSP runs in three separate threads. One thread handles capturing audio, one handles the playback, and one does the processing in between. The capture thread passes audio to the processing thread via a message queue. Each message consists of a chunk of audio with a configurable size. The processing queue waits for audio messages, processes them in the order they arrive, and passes the processed audio via another message queue to the playback thread. There is also a supervisor thread for control. This chart shows the most important parts:

Capture

The capture thread reads a chunk samples from the audio device in the selected format. It then converts the samples to 64-bit floats (or optionally 32-bit). If resampling is enabled, the audio data is sent to the resampler. At the end, the chunk of samples is packed as a message that is then posted to the input queue of the processing thread. After this the capture thread returns to reading the next chunk of samples from the device.

Processing

The processing thread waits for audio chunk messages to arrive in the input queue. Once a message arrives, it's passed through all the defined filters and mixers of the pipeline. Once all processing is done, the audio data is posted to the input queue of the playback device.

Playback

The playback thread simply waits for audio messages to appear in the queue. Once a message arrives, the audio data is converted to the right sample format for the device, and written to the playback device. The ALSA playback device supports monitoring the buffer level of the playback device. This is used to send requests for adjusting the capture speed to the supervisor thread, on a separate message channel.

Supervisor

The supervisor monitors all threads by listening to their status messages. The requests for capture rate adjust are passed on to the capture thread. It's also responsible for updating the configuration when requested to do so via the websocket server or a SIGHUP signal.

Websocket server

The websocket server launches a separate thread to handle each connected client. All commands to change the config are sent to the supervisor thread.

System requirements

CamillaDSP runs on Linux, macOS and Windows. The exact system requirements are determined by the amount of processing the application requires, but even relatively weak CPUs like Intel Atom have much more processing power than most will need.

In general, a 64-bit CPU and OS will perform better.

A few examples, done with CamillaDSP v0.5.0:

• A Raspberry Pi 4 doing FIR filtering of 8 channels, with 262k taps per channel, at 192 kHz. CPU usage about 55%.

• An AMD Ryzen 7 2700u (laptop) doing FIR filtering of 96 channels, with 262k taps per channel, at 192 kHz. CPU usage just under 100%.

Linux requirements

Both 64 and 32 bit architectures are supported. All platforms supported by the Rustc compiler should work.

Pre-built binaries are provided for: - x86_64 (almost all PCs) - armv6 (32-bit arm, for example a Raspberry Pi 1 and Zero) - armv7 (32-bit arm, for example a Raspberry Pi 2,3,4 with a 32-bit OS) - aarch64 (64-bit arm, for example Raspberry Pis running a 64 bit OS)

Windows requirements

An x86_64 CPU and the 64-bit version of Windows is recommended. Any x86_64 CPU will likely be sufficient.

Pre-built binaries are provided for 64-bit systems.

macOS requirements

CamillaDSP can run on both Intel and Apple Silicon macs. Any reasonably recent version of macOS should work.

Pre-built binaries are provided for both Intel and Apple Silicon

Usage example: crossover for 2-way speakers

A crossover must filter all sound being played on the system. This is possible by setting up a virtual loopback device and setting this device as the default output device. Virtual loopback devices are available for most audio APIs, either as built-in features or via third-party solutions. CamillaDSP is then configured to capture from the output of this device and play the processed audio on the real sound card.

See the tutorial for a step-by-step guide.

Dependencies

These are the key dependencies for CamillaDSP. * https://crates.io/crates/alsa - ALSA bindings * https://crates.io/crates/coreaudio-rs - CoreAudio bindings * https://crates.io/crates/pipewire - PipeWire bindings * https://crates.io/crates/asio-sys * https://crates.io/crates/wasapi * https://crates.io/crates/cpal - Cross platform audio library used to provide Jack support * https://crates.io/crates/libpulse-simple-binding - PulseAudio audio backend * https://crates.io/crates/clap - Command line argument parsing * https://crates.io/crates/realfft - Wrapper for RustFFT that speeds up FFTs of real-valued data * https://crates.io/crates/rustfft - FFT used for FIR filters * https://crates.io/crates/rubato - Sample rate conversion * https://crates.io/crates/yaml_serde - Config file reading * https://crates.io/crates/tungstenite - Websocket server

Companion libraries and tools

These projects are part of the CamillaDSP family: * https://github.com/HEnquist/pycamilladsp - Library for communicating with CamillaDSP over websocket. * https://github.com/HEnquist/pycamilladsp-plot - Plotting and visualization of configurations. * https://github.com/HEnquist/camilladsp-config - Example configurations for things like running CamillaDSP as a systemd service.

GUI

CamillaGUI is a user interface for CamillaDSP that is accessed via a web browser.

Installing

The easiest way to install CamillaDSP is to download a pre-built binary. Binaries for each release are available for the most common systems. See the "Releases" page. To see the files click "Assets".

These are compressed files containing a single executable file that is ready to run.

The following configurations are provided: