Overview

Python library for communicating with CamillaDSP.

The main component is the CamillaClient class. This class handles the communication over websocket with the CamillaDSP process.

The various commands are grouped on helper classes that are instantiated by the CamillaClient class. For example volume controls are handled by the Volume class. These methods are accessible via the volume property of the CamillaClient. Reading the main volume is then done by calling my_client.volume.main().

Methods for reading a value are named the same as the name of the value, while methods for writing have a set_ prefix. For example the method for reading the main volume is called main, and the method for changing the main volume is called set_main.

Example:

client = CamillaClient("localhost", 1234)
client.connect()

volume = client.volume.main()
mute = client.mute.main()
state = client.general.state()
capture_levels = client.levels.capture_rms()

Command group classes

Class	Via property	Description
General	`general`	Basics, for example starting and stopping processing
Status	`status`	Reading status parameters such as buffer levels
Config	`config`	Managing the configuration
Volume	`volume`	Volume controls
Mute	`mute`	Mute controls
Levels	`levels`	Reading signal levels
RateMonitor	`rate`	Reading the sample rate montitor
Settings	`settings`	Websocket server settings
Versions	`versions`	Read software versions

All commands

General

These commands are accessed via the general property of a CamillaClient instance.

Basic commands

`exit()`

Stop processing and exit.

`list_capture_devices(value)`

List the available capture devices for a given backend. Returns a list of tuples. Returns the system name and a descriptive name for each device. For some backends, those two names are identical.

`list_playback_devices(value)`

List the available playback devices for a given backend. Returns a list of tuples. Returns the system name and a descriptive name for each device. For some backends, those two names are identical.

`reload()`

Reload config from disk.

`state()`

Get current processing state.

`state_file_path()`

Get path to current state file.

`state_file_updated()`

Check if all changes have been saved to the state file.

`stop()`

Stop processing and wait for new config if wait mode is active, else exit.

`stop_reason()`

Get reason why processing stopped.

`supported_device_types()`

Read what device types the running CamillaDSP process supports. Returns a tuple with two lists of device types, the first for playback and the second for capture.

Status

These commands are accessed via the status property of a CamillaClient instance.

Collection of methods for reading status

`buffer_level()`

Get current buffer level of the playback device.

`clipped_samples()`

Get number of clipped samples since the config was loaded.

`processing_load()`

Get processing load in percent.

`rate_adjust()`

Get current value for rate adjust, 1.0 means 1:1 resampling.

Config

These commands are accessed via the config property of a CamillaClient instance.

Collection of methods for configuration management

`active()`

Get the active configuration as a Python object.

`active_raw()`

Get the active configuration in raw yaml format (as a string).

`description()`

Get the title of the active configuration.

`file_path()`

Get path to current config file.

`parse_yaml(config_string)`

Parse a config from yaml string and return the contents as a Python object, with defaults filled out with their default values.

`previous()`

Get the previously active configuration as a Python object.

`read_and_parse_file(filename)`

Read and parse a config file from disk and return the contents as a Python object.

`set_active(config_object)`

Upload and apply a new configuration from a Python object.

`set_active_raw(config_string)`

Upload and apply a new configuration in raw yaml format (as a string).

`set_file_path(value)`

Set path to config file, without loading it. Call reload() to apply the new config file.

`title()`

Get the title of the active configuration.

`validate(config_object)`

Validate a configuration object. Returns the validated config with all optional fields filled with defaults. Raises a CamillaError on errors.

Volume

These commands are accessed via the volume property of a CamillaClient instance.

Collection of methods for volume and mute control

`adjust_fader(fader, value)`

Adjust volume for the given fader in dB. Positive values increase the volume, negative decrease.

`fader(fader)`

Get current volume setting for the given fader in dB.

`main()`

Get current main volume setting in dB. Equivalent to calling get_fader_volume() with fader=0.

`set_fader(fader, vol)`

Set volume for the given fader in dB.

`set_fader_external(fader, vol)`

Special command for setting the volume when a "Loudness" filter is being combined with an external volume control (without a "Volume" filter). Set volume for the given fader in dB.

`set_main(value)`

Set main volume in dB. Equivalent to calling set_fader() with fader=0.

Mute

These commands are accessed via the mute property of a CamillaClient instance.

Collection of methods for mute control

`fader(fader)`

Get current mute setting for a fader.

`main()`

Get current main mute setting. Equivalent to calling get_fader() with fader=0.

`set_fader(fader, value)`

Set mute status for a fader, true or false.

`set_main(value)`

Set main mute, true or false. Equivalent to calling set_fader() with fader=0.

`toggle_fader(fader)`

Toggle mute status for a fader.

Levels

These commands are accessed via the levels property of a CamillaClient instance.

Collection of methods for level monitoring

`capture_peak()`

Get capture signal level peak in dB for the last processed chunk. Full scale is 0 dB. Returns a list with one element per channel.

`capture_peak_since(interval)`

Get capture signal level peak in dB for the last interval seconds. Full scale is 0 dB. Returns a list with one element per channel.

`capture_peak_since_last()`

Get capture signal level peak in dB since the last read by the same client. Full scale is 0 dB. Returns a list with one element per channel.

`capture_rms()`

Get capture signal level rms in dB for the last processed chunk. Full scale is 0 dB. Returns a list with one element per channel.

`capture_rms_since(interval)`

Get capture signal level rms in dB for the last interval seconds. Full scale is 0 dB. Returns a list with one element per channel.

`capture_rms_since_last()`

Get capture signal level rms in dB since the last read by the same client. Full scale is 0 dB. Returns a list with one element per channel.

`levels()`

Get all signal levels in dB for the last processed chunk. Full scale is 0 dB. The values are returned as a json object with keys playback_peak, playback_rms, capture_peak and capture_rms. Each dict item is a list with one element per channel.

`levels_since(interval)`

Get all signal levels in dB for the last interval seconds. Full scale is 0 dB. The values are returned as a json object with keys playback_peak, playback_rms, capture_peak and capture_rms. Each dict item is a list with one element per channel.

`levels_since_last()`

Get all signal levels in dB since the last read by the same client. Full scale is 0 dB. The values are returned as a json object with keys playback_peak, playback_rms, capture_peak and capture_rms. Each dict item is a list with one element per channel.

`peaks_since_start()`

Get the playback and capture peak level since processing started. The values are returned as a json object with keys playback and capture.

`playback_peak()`

Get playback signal level peak in dB for the last processed chunk. Full scale is 0 dB. Returns a list with one element per channel.

`playback_peak_since(interval)`

Get playback signal level peak in dB for the last interval seconds. Full scale is 0 dB. Returns a list with one element per channel.

`playback_peak_since_last()`

Get playback signal level peak in dB since the last read by the same client. Full scale is 0 dB. Returns a list with one element per channel.

`playback_rms()`

Get playback signal level rms in dB for the last processed chunk. Full scale is 0 dB. Returns a list with one element per channel.

`playback_rms_since(interval)`

Get playback signal level rms in dB for the last interval seconds. Full scale is 0 dB. Returns a list with one element per channel.

`playback_rms_since_last()`

Get playback signal level rms in dB since the last read by the same client. Full scale is 0 dB. Returns a list with one element per channel.

`range()`

Get signal range for the last processed chunk. Full scale is 2.0.

`range_decibel()`

Get current signal range in dB for the last processed chunk. Full scale is 0 dB.

`reset_peaks_since_start()`

Reset the peak level values.

RateMonitor

These commands are accessed via the rate property of a CamillaClient instance.

Methods for rate monitoring

`capture()`

Get current capture rate. Returns the nearest common rate, as long as it's within +-4% of the measured value.

`capture_raw()`

Get current capture rate, raw value.

Settings

These commands are accessed via the settings property of a CamillaClient instance.

Methods for various settings

`set_update_interval(value)`

Set current update interval in ms.

`update_interval()`

Get current update interval in ms.

Versions

These commands are accessed via the versions property of a CamillaClient instance.

Version info

Source code in camilladsp/camilladsp.py

class Versions(_CommandGroup):
    """
    Version info
    """

    def camilladsp(self) -> Optional[Tuple[str, str, str]]:
        """
        Read CamillaDSP version.

        Returns:
            Tuple[List[str], List[str]] | None: A tuple containing the CamillaDSP version,
                as (major, minor, patch).
        """
        return self.client.cdsp_version

    def library(self) -> Tuple[str, str, str]:
        """
        Read pyCamillaDSP library version.

        Returns:
            Tuple[List[str], List[str]] | None: A tuple containing the pyCamillaDSP version,
                as (major, minor, patch).
        """
        ver = VERSION.split(".")
        return (ver[0], ver[1], ver[2])

`camilladsp()`

Read CamillaDSP version.

Source code in camilladsp/camilladsp.py

def camilladsp(self) -> Optional[Tuple[str, str, str]]:
    """
    Read CamillaDSP version.

    Returns:
        Tuple[List[str], List[str]] | None: A tuple containing the CamillaDSP version,
            as (major, minor, patch).
    """
    return self.client.cdsp_version

`library()`

Read pyCamillaDSP library version.

Source code in camilladsp/camilladsp.py

def library(self) -> Tuple[str, str, str]:
    """
    Read pyCamillaDSP library version.

    Returns:
        Tuple[List[str], List[str]] | None: A tuple containing the pyCamillaDSP version,
            as (major, minor, patch).
    """
    ver = VERSION.split(".")
    return (ver[0], ver[1], ver[2])