CamillaDSP

CamillaDSP is a powerful audio processing tool used for applications like active crossovers, room correction, and advanced audio filtering. It consists of a core engine and a broader ecosystem of tools:

• CamillaDSP (the engine): A core DSP engine written in Rust. It is a command-line application for real-time audio processing on Linux, macOS, and Windows.
• CamillaGUI: A web-based interface for configuring and controlling the engine.
• pyCamillaDSP: A Python library for interacting with the engine via its websocket interface.
• pyCamillaDSP-plot: A Python library for visualizing configurations and filter responses.
• camilladsp-setupscripts: Automated setup scripts.
• camilladsp-config: A repository of example configurations.
• camilladsp-controller: A controller for automatic sample rate switching.

An asynchronous resampler is required when the ratio between the input and output sample rates cannot be expressed as a fixed ratio.

• Use Asynchronous Resampling: When adapting to match the rates of two devices with independent clocks (where the ratio drifts over time).
• Use Synchronous Resampling: When converting between fixed standard rates (e.g., 44.1 kHz $\leftrightarrow$ 48 kHz, 44.1 $\leftrightarrow$ 96 kHz, 88.2 $\leftrightarrow$ 192 kHz, etc.), as these have fixed mathematical ratios.

The AsyncPoly resampler performs polynomial interpolation between sample points without an anti-aliasing sinc filter. It is significantly faster than AsyncSinc and is suitable for saving CPU power with minimal perceived quality loss.

Available interpolation types:

resampler:
  type: AsyncPoly
  interpolation: Cubic

For ALSA capture devices like USB Gadgets or ALSA Loopback, CamillaDSP can subscribe to control events to detect when playback has stopped. Setting stop_on_inactive: true allows CamillaDSP to stop processing when these events occur:

• ALSA Loopback: Subscribes to PCM Slave Active. Stopping allows a player application to re-open the device at a different sample rate.
• USB Gadget: Subscribes to Capture Rate. If the sample rate changes, CamillaDSP will stop. You can use the GetStopReason websocket command to determine why it stopped.

capture:
  type: Alsa
  device: "hw:0,1"
  stop_on_inactive: true

CamillaDSP commands are sent as JSON objects. The format depends on whether the command requires arguments:

1. Commands without arguments: Send the command name as a string wrapped in quotes.

   • Example: "GetVersion"

2. Commands with arguments: Send a JSON object where the key is the command name and the value is the argument.

   • Example: {"SetUpdateInterval": 500}

All responses from the server are also JSON objects (sent as strings). Responses include a result field (either "Ok" or "Error"). Commands that return data will also include a "value" field.

/* Command without arguments */
"GetVersion"

/* Command with arguments */
{"SetUpdateInterval": 500}

/* Response for command without value */
{
  "SetUpdateInterval": {
    "result": "Ok"
  }
}

/* Response for command with value */
{
  "GetUpdateInterval": {
    "result": "Ok",
    "value": 500
  }
}

CamillaDSP is dual-licensed under GPLv3 and MPL 2.0.

Important Note on ASIO: If you build CamillaDSP 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 the ASIO SDK code.

CamillaDSP supports several exact binary sample formats, but most audio backends (APIs) use a simplified subset of these names.

API-level vs. Binary formats

When configuring a backend, you often use a simplified name like S24. CamillaDSP will then automatically query the audio API/device to determine which concrete binary format is supported and pick the best match. For example, S24 might map to:

• S24_3_LE (packed, 3 bytes per sample)
• S24_4_LJ_LE (padded to 4 bytes, left justified)
• S24_4_RJ_LE (padded to 4 bytes, right justified)

Auto-selection

If you leave the format parameter out or set it to null, CamillaDSP will automatically select a format based on the backend's specific quality priorities and the capabilities of the connected device.

24-bit devices have specific delivery requirements that affect which CamillaDSP format you should select:

• USB DACs: Typically use the packed S24_3_LE format.
• Integrated HD Audio Codecs: Often require padded samples. Since ALSA lacks a specific format for this, these devices use the S32_LE format and ignore the 8 least significant bits.
• Padded 24-bit (Right Justified): A rare format called S24_LE in ALSA is mapped to S24_4_LE in the CamillaDSP ALSA backend.

The --statefile <STATEFILE> option allows CamillaDSP to save and restore the configuration path, volume, and mute settings for the main fader and four Aux faders (Aux1 to Aux4).

Important Safety Note

The volume setting in the statefile is applied immediately upon startup. To prevent equipment damage, it is recommended to always use --gain or --gain1..4 to force a safe starting volume.

Statefile Format

The statefile is a YAML file structured as follows:

---
config_path: /path/to/config.yml
mute:
  - false
  - false
  - false
  - false
  - false
volume:
  - 0.0
  - 0.0
  - 0.0
  - 0.0
  - 0.0

Overriding State

• Providing a [CONFIGFILE] argument overrides the config_path in the statefile.
• Using --gain or --mute flags overrides the volume/mute values in the statefile.

CamillaDSP provides a volume control system that operates independently of the loaded configuration file. It uses five control "channels" known as "faders".

• Main Fader: The default channel that the standard volume control reacts to.
• Auxiliary Faders (Aux1 to Aux4): Additional channels that can be used for specialized tasks like separate headphone volume controls or crossfading between input channels.

When volume or mute settings change, the gain is smoothly ramped to prevent abrupt changes. You can customize this behavior in the devices section of your configuration.