A flexible tool for processing audio

# CamillaDSP v2.0 

A tool to create audio processing pipelines for applications such as active crossovers or room correction. It is written in Rust to benefit from the safety and elegant handling of threading that this language provides.

Supported platforms: Linux, macOS, Windows.

Audio data is captured from a capture device and sent to a playback device. Alsa, PulseAudio, Jack, Wasapi 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 required for long FIR filters. The full configuration is given in a YAML file.

# Disclaimer

CamillaDSP is distributed under the [GNU GENERAL PUBLIC LICENSE Version 3](LICENSE.txt).

This includes the following disclaimer: > 15. Disclaimer of Warranty. > > THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY >APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT >HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY >OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, >THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR >PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM >IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF >ALL NECESSARY SERVICING, REPAIR OR CORRECTION. > > 16. Limitation of Liability. > > IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING >WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS >THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY >GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE >USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF >DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD >PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), >EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF >SUCH DAMAGES.

In short this means that the user is responsible for any damage resulting from using this program. It does not matter if the damage is caused by incorrect usage or a bug in the software.

# Table of Contents **[Introduction](#introduction)** - **[Background](#background)** - **[How it works](#how-it-works)** - **[System requirements](#system-requirements)** - **[Usage example: crossover for 2-way speakers](#usage-example-crossover-for-2-way-speakers)** - **[Dependencies](#dependencies)** - **[Companion libraries and tools](#companion-libraries-and-tools)** - **[GUI](#gui)**

**[Installing](#installing)**

**[Building](#building)** - **[Build with standard features](#building-in-linux-with-standard-features)** - **[Customized build](#customized-build)** - **[Optimize for your system](#optimize-for-your-system)** - **[Building on Windows and macOS](#building-on-windows-and-macos)**

**[How to run](#how-to-run)** - **[Command line options](#command-line-options)** - **[Reloading the configuration](#reloading-the-configuration)** - **[Controlling via websocket](#controlling-via-websocket)**

**[Processing audio](#processing-audio)** - **[Cross-platform](#cross-platform)** - **[Jack](#jack)** - **[File or pipe](#file-or-pipe)** - **[Windows](#windows)** - **[MacOS (CoreAudio)](#macos-coreaudio)** - **[Linux](#linux)** - **[Alsa](#alsa)** - **[PulseAudio](#pulseaudio)** - **[Pipewire](#pipewire)**

**[Configuration](#configuration)** - **[The YAML format](#the-yaml-format)** - **[Title and description](#title-and-description)** - **[Volume control](#volume-control)** - **[Devices](#devices)** - **[Resampling](#resampling)** - **[Mixers](#mixers)** - **[Filters](#filters)** - **[Gain](#gain)** - **[Volume](#volume)** - **[Loudness](#loudness)** - **[Delay](#delay)** - **[FIR](#fir)** - **[IIR](#iir)** - **[Dither](#dither)** - **[Limiter](#limiter)** - **[Difference equation](#difference-equation)** - **[Processors](#processors)** - **[Compressor](#compressor)** - **[Pipeline](#pipeline)** - **[Filter step](#filter-step)** - **[Mixer and Processor step](#mixer-and-processor-step)** - **[Tokens in names](#tokens-in-names)** - **[Bypassing steps](#bypassing-steps)** - **[Export filters from REW](#export-filters-from-rew)** - **[Visualizing the config](#visualizing-the-config)**

**[Related projects](#related-projects)**

**[Getting help](#getting-help)** - **[FAQ](#faq)** - **[Troubleshooting](#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 with both PulseAudio and Alsa by setting up a loopback device (Alsa) or null sink (Pulse) and setting this device as the default output device. 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.](./stepbystep.md)

## Dependencies These are the key dependencies for CamillaDSP. * https://crates.io/crates/alsa - Alsa audio backend * https://crates.io/crates/clap - Command line argument parsing * https://crates.io/crates/cpal - Jack audio backend * https://crates.io/crates/libpulse-simple-binding - PulseAudio audio backend * 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/serde_yaml - 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](https://github.com/HEnquist/camillagui-backend) 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"](https://github.com/HEnquist/camilladsp/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:

| Filename | Description | Backends | |----------|-------------|----------| | `camilladsp-linux-amd64.tar.gz` | Linux on 64-bit Intel or AMD CPU | Alsa, Pulseaudio | | `camilladsp-linux-armv6.tar.gz` | Linux on Armv6 (32-bit), intended for Raspberry Pi 1 and Pi Zero but should also work on others | Alsa | | `camilladsp-linux-armv7.tar.gz` | Linux on Armv7 with Neon (32-bit), intended for Raspberry Pi 2 and up but should also work on others | Alsa | | `camilladsp-linux-aarch64.tar.gz` | Linux on Armv8 (64-bit), intended for Raspberry Pi 3 and up, but should also work on others | Alsa | | `camilladsp-macos-amd64.tar.gz` | macOS on 64-bit Intel CPU | CoreAudio | | `camilladsp-macos-aarch64.tar.gz` | macOS on Apple silicon | CoreAudio | | `camilladsp-windows-amd64.zip` | Windows on 64-bit Intel or AMD CPU | Wasapi |

All buil