Lib Audio DSP£££doc/lib_audio_dsp.html#lib-audio-dsp

Introduction

lib_audio_dsp is a DSP library for the XMOS xcore architecture. It facilitates the creation of multithreaded audio DSP pipelines that efficiently utilise the xcore architecture.

The library is built around a set of DSP function blocks, referred to in the documentation as “Stages” , which have a consistent API and can be combined to create many different designs.

A tool for easily combining stages into a custom DSP pipeline is provided. DSP pipeline parameters can be adjusted and tuned on the fly via a PC based tuning interface, and utilities for hardware controls are also provided.

lib_audio_dsp includes common signal processing functions optimised for the xcore, such as:

biquads and FIR filters.
compressors, limiters, noise gates and envelope detectors.
adders, subtractors, gains, volume controls and mixers.
delays and reverb.

These can be combined together to make complex audio pipelines for many different applications, such as home audio, music production, voice processing, and AI feature extraction.

This document covers the following topics:

Tool User Guide: A Beginner’s Guide to installing and using the DSP design and generation Python library.
Design Guide: Advanced guidance on designing and debugging generated DSP pipelines.
DSP Components: Details all DSP components provided by this library.
Run-Time Control User Guide: How to add run time control to a DSP application.

The subsequent sections provide comprehensive insights into the functionalities and applications of lib_audio_dsp, detailing how to leverage its features for efficient audio signal processing.

Lib Audio DSP$$$Tool User Guide£££doc/01_tool_user_guide/index.html#tool-user-guide

This guide introduces the audio_dsp Python library, and how to use it to generate multithreaded DSP pipelines for the xcore.

The following sections provide guidance on preparing the environment for the library, building a pipeline, and exploring the API documentation.

Lib Audio DSP$$$Tool User Guide$$$Setup£££doc/01_tool_user_guide/setup.html#setup

This section describes the requirements and the steps to run a basic pipeline. This document lists the necessary steps for both Windows and Linux/macOS. This section uses the app_simple_audio_dsp_integration example found within this repository. The steps will be broadly similar for any user-created project.

Note

Copying multiple lines into the console may not work as expected on Windows. To avoid issues, copy and execute each line individually.

Lib Audio DSP$$$Tool User Guide$$$Setup$$$Hardware Requirements£££doc/01_tool_user_guide/setup.html#hardware-requirements

xcore.ai evaluation board (XK-EVK-XU316 or XK-316-AUDIO-MC-AB)
xTag debugger and cable
2x Micro USB cable (one for power supply and one for the xTag)

Lib Audio DSP$$$Tool User Guide$$$Setup$$$Software Requirements£££doc/01_tool_user_guide/setup.html#software-requirements

Graphviz: this software must installed and the dot executable must be on the system path.
XTC 15.3.0
Python 3.10
Jupyter 7.2.1
CMake 3.21

Additionally, on Windows the following is required:

ninja-build

Lib Audio DSP$$$Tool User Guide$$$Setup$$$Setup Steps£££doc/01_tool_user_guide/setup.html#setup-steps

Note

All the steps below are executed from the sandbox folder created in the second step.

Prepare the development environment
Windows
On Windows:
1. Open the Command Prompt or other terminal application of choice
2. Activate the XTC environment:
  call "C:\Program Files\XMOS\XTC\15.3.0\SetEnv.bat"
Linux and macOS:
On Linux and macOS:
1. Open a terminal
2. Activate the XTC environment using SetEnv
Create a sandbox folder with the command below:
```
mkdir lib_audio_dsp_sandbox
```

Clone the library inside lib_audio_dsp_sandbox:

git clone git@github.com:xmos/lib_audio_dsp.git

Get the sandbox inside lib_audio_dsp_sandbox. This step can take several minutes.

Windows

On Windows:

cd lib_audio_dsp/examples/app_simple_audio_dsp_integration
cmake -B build -G Ninja
cd ../../..

Linux and macOS

On Linux and macOS:

cd lib_audio_dsp/examples/app_simple_audio_dsp_integration
cmake -B build
cd ../../..

Create a requirements file inside lib_audio_dsp_sandbox.

Windows

On Windows:

echo -e lib_audio_dsp/python > requirements.txt
echo notebook >> requirements.txt

Linux and macOS

On Linux or macOS:

echo "-e lib_audio_dsp/python" > requirements.txt
echo notebook >> requirements.txt
chmod 644 requirements.txt

Create a Python virtualenv inside lib_audio_dsp_sandbox.

Windows

On Windows:

python -m venv .venv
call .venv/Scripts/activate.bat
pip install -Ur requirements.txt
cd ..

Linux and macOS

On Linux or macOS:

python -m venv .venv
source .venv/bin/activate
pip install -Ur requirements.txt
cd ..

Connect an XCORE-AI-EXPLORER using both USB ports
Open the notebook by running from lib_audio_dsp_sandbox the following command:
```
jupyter notebook lib_audio_dsp/examples/app_simple_audio_dsp_integration/dsp_design.ipynb
```
If a blank screen appears or nothing opens, then copy the link starting with “http://127.0.0.1/” from the terminal into the browser. The following page should open:

Top-level page of the Jupyter Notebook
Run all the cells from the browser. From the menu at the top of the page click Run -> Run all cells:

Run menu of the Jupyter Notebook

This creates the pipeline and builds the app. Wait for all the cells to finish

Any configuration or compilation errors will be displayed in the notebook in the Build and run cell, as in the example below:

Run error of the Jupyter Notebook
Update and run Pipeline design stage to add the desired audio processing blocks. A diagram will be generated showing the pipeline IO mapping.

A simple pipeline example is shown in Fig. 4:

Diagram of a simple audio pipeline

See the top of the notebook for more information about this stage.
Update and run the Tuning Stage cell to change the parameters before building. See the top of the notebook for more information about this stage.

Lib Audio DSP$$$Tool User Guide$$$Setup$$$Running a notebook after the first installation£££doc/01_tool_user_guide/setup.html#running-a-notebook-after-the-first-installation

If running the notebook after the initial configuration, the following steps are required:

Configure the settings below, using the instructions in the Setup Steps section:
- Enable the XTC tools: the installation can be tested by running the command xrun --version from the terminal. If the command is not found, the XTC tools are not installed correctly.
- Enable the Python Virtual Environment: this is checked by running the command echo %VIRTUAL_ENV% on Windows, or echo $VIRTUAL_ENV on Linux or macOS. The path should have been set.
Open the notebook by running jupyter notebook lib_audio_dsp/examples/app_simple_audio_dsp_integration/dsp_design.ipynb from lib_audio_dsp_sandbox, as described in the Setup Steps section.

Lib Audio DSP$$$Tool User Guide$$$Using the Tool£££doc/01_tool_user_guide/using_the_tool.html#using-the-tool

In this section the basic operation of the tools provided by lib_audio_dsp is described.

This document takes the user through three scenarios, illustrated by way of the included example app_simple_audio_dsp_integration, which may be found in the examples directory in lib_audio_dsp.

These scenarios are:

Creating a pipeline
Tuning and simulating a pipeline
Deploying pipeline code onto the xcore.

The steps in this guide should be executed in a Jupyter Notebook.

Lib Audio DSP$$$Tool User Guide$$$Using the Tool$$$Creating a Pipeline£££doc/01_tool_user_guide/using_the_tool.html#creating-a-pipeline

A simple yet useful DSP pipeline that could be made is a bass and treble control with output limiter. In this design the product will stream real time audio boosting or suppressing the treble and bass and then limiting the output amplitude to protect the output device.

The DSP pipeline will perform the following processes:

../_images/bass_treble_limit.drawio.png — The target pipeline

The first step is to create an instance of the Pipeline class. This is the top level class which will be used to create and tune the pipeline. On creation the number of inputs and sample rate must be specified.

from audio_dsp.design.pipeline import Pipeline

pipeline, inputs = Pipeline.begin(
    1,          # Number of pipeline inputs.
    fs=48000    # Sample rate.
)

The pipeline object can now be used to add DSP stages. For high shelf and low shelf use Biquad and for the limiter use LimiterPeak.

from audio_dsp.design.pipeline import Pipeline
from audio_dsp.stages import *

p, inputs = Pipeline.begin(1, fs=48000)

# i is a list of pipeline inputs. "lowshelf" is a label for this instance of Biquad.
# The new variable x is the output of the lowshelf Biquad
x = p.stage(Biquad, inputs, "lowshelf")

# The output of lowshelf "x" is passed as the input to the
# highshelf. The variable x is reassigned to the outputs of the new Biquad.
x = p.stage(Biquad, x, "highshelf")

# Connect highshelf to the limiter. Labels are optional, however they are required
# if the stage will be tuned later.
x = p.stage(LimiterPeak, x)

# Finally connect to the output of the pipeline.
p.set_outputs(x)

p.draw()

When running the above snippet in a Jupyter Notebook it will output the following image which illustrates the pipeline which has been designed:

../_images/pipeline_diagram.png — Generated pipeline diagram

Lib Audio DSP$$$Tool User Guide$$$Using the Tool$$$Tuning and simulating a pipeline£££doc/01_tool_user_guide/using_the_tool.html#tuning-and-simulating-a-pipeline

Each stage contains a number of designer methods which can be identified as they have the make_ prefix. These can be used to configure the stages. The stages also provide a plot_frequency_response() method which shows the magnitude and phase response of the stage with its current configuration. The two biquads created above will have a flat frequency response until they are tuned. The code below shows how to use the designer methods to convert them into the low shelf and high shelf that is desired. The individual stages are accessed using the labels that were assigned to them when the stage was added to the pipeline.

# Make a low shelf with a centre frequency of 200 Hz, q of 0.7 and gain of +6 dB
p["lowshelf"].make_lowshelf(200, 0.7, 6)
p["lowshelf"].plot_frequency_response()

# Make a high shelf with a centre frequency of 4000 Hz, q of 0.7 and gain of +6 dB
p["highshelf"].make_highshelf(4000, 0.7, 6)
p["highshelf"].plot_frequency_response()

../_images/frequency_response.png — Frequency response of the biquads (low shelf left, high shelf right)

For this tutorial the default settings for the limiter will provide adequate performance.

Lib Audio DSP$$$Tool User Guide$$$Using the Tool$$$Code Generation£££doc/01_tool_user_guide/using_the_tool.html#code-generation

With an initial pipeline complete, it is time to generate the xcore source code and run it on a device. The code can be generated using the generate_dsp_main() function.

from audio_dsp.design.pipeline import generate_dsp_main
generate_dsp_main(p)

The reference application should then provide instructions for compiling the application and running it on the target device.

With that the tuned DSP pipeline will be running on the xcore device and can be used to stream audio. The next step is to iterate on the design and tune it to perfection. One option is to repeat the steps described above, regenerating the code with new tuning values until the performance requirements are satisfied.

Lib Audio DSP$$$Tool User Guide$$$Using the Tool$$$Designing Complex Pipelines£££doc/01_tool_user_guide/using_the_tool.html#designing-complex-pipelines

The audio dsp library is not limited to the simple linear pipelines shown above. Stages can scale to take an arbitrary number of inputs, and the outputs of each stage can be split and joined arbitrarily.

When created, every stage’s initialiser returns an instance of StageOutputList, a container of StageOutput. The stage’s outputs can be selected from the StageOutputList by indexing into it, creating a new StageOutputList, which can be concatenated with other StageOutputList instances using the + operator. When creating a stage, it will require a StageOutputList as its inputs.

The below shows an example of how this could work with a pipeline with 7 inputs.

# split the pipeline inputs
i0 = p.stage(Biquad, i[0:2])      # use the first 2 inputs
i1 = p.stage(Biquad, i[2])        # use the third input (index 2)
i2 = p.stage(Biquad, i[3, 5, 6])  # use the inputs at index 3, 5, and 6
# join biquad outputs
i3 = p.stage(Biquad, i0 + i1 + i2[0]) # pass all of i0 and i1, as well as the first channel in i2

p.set_outputs(i3 + i2[1:]) # The pipeline output will be all i3 channels and the 2nd and 3rd channel from i2.

As the pipeline grows it may end up consuming more MIPS than are available on a single xcore thread. The pipeline design interface allows adding additional threads using the next_thread() method of the Pipeline instance. Each thread in the pipeline represents an xcore hardware thread. Do not add more threads than are available in your application. The maximum number of threads that should be used, if available, is five. This limitation is due to the architecture of the xcore processor.

# thread 0
i = p.stage(Biquad, i)

# thread 1
p.next_thread()
i = p.stage(Biquad, i)

# thread 2
p.next_thread()
i = p.stage(Biquad, i)

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API£££doc/01_tool_user_guide/pipeline_design.html#pipeline-design-api

This page describes the C and Python APIs that will be needed when using the pipeline design utility.

When designing a pipeline first create an instance of Pipeline, add threads to it with Pipeline.add_thread(). Then add DSP stages such as Biquad using CompositeStage.stage(). The pipeline can be visualised in a Jupyter Notebook using Pipeline.draw() and the xcore source code for the pipeline can be generated using generate_dsp_main().

Once the code is generated use the functions defined in stages/adsp_pipeline.h to read and write samples to the pipeline and update configuration fields.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$C Design API£££doc/01_tool_user_guide/pipeline_design.html#c-design-api

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$C Design API$$$stages/adsp_control.h£££doc/01_tool_user_guide/pipeline_design.html#stages-adsp-control-h

The control API for the generated DSP.

These functions can be executed on any thread which is on the same tile as the generated DSP threads.

Enums

enum adsp_control_status_t

Control status.

Values:

enumerator ADSP_CONTROL_SUCCESS: Command succesfully executed.

enumerator ADSP_CONTROL_BUSY: Stage has not yet processed the command, call again.

Functions

void adsp_controller_init(adsp_controller_t *ctrl, adsp_pipeline_t *pipeline)

Create a DSP controller instance for a particular pipeline.

Parameters:

ctrl – The controller instance to initialise.
pipeline – The DSP pipeline that will be controlled with this controller.

adsp_control_status_t adsp_read_module_config(adsp_controller_t *ctrl, adsp_stage_control_cmd_t *cmd)

Initiate a read command by passing in an intialised adsp_stage_control_cmd_t.

Must be called repeatedly with the same cmd until ADSP_CONTROL_SUCCESS is returned. If the caller abandons the attempt to read before SUCCESS is returned then this will leave the stage in a state where it can never be read from again.

Parameters:

ctrl – An instance of adsp_controller_t which has been initialised to control the DSP pipeline.
cmd – An initialised adsp_stage_control_cmd_t.

Returns:

adsp_control_status_t

adsp_control_status_t adsp_write_module_config(adsp_controller_t *ctrl, adsp_stage_control_cmd_t *cmd)

Initiate a write command by passing in an initialised adsp_stage_control_cmd_t.

Must be called repeatedly with the same cmd until ADSP_CONTROL_SUCCESS is returned.

Parameters:

ctrl – An instance of adsp_controller_t which has been initialised to control the DSP pipeline.
cmd – An initialised adsp_stage_control_cmd_t.

Returns:

adsp_control_status_t

void adsp_control_xscope_register_probe()

Default xscope setup function.

Sets up a single xscope probe with name ADSP, type XSCOPE_CONTINUOUS, and datatype XSCOPE_UINT. Should be called within xscope_user_init().

chanend_t adsp_control_xscope_init()

Creates an xscope chanend and connects it to the host. Must be called on the same tile as the DSP pipeline.

Returns:: chanend_t

adsp_control_status_t adsp_control_xscope_process(chanend_t c_xscope, adsp_controller_t *ctrl)

Process an xscope chanend containing a control command from the host.

Parameters:

c_xscope – A chanend which has been connected to the host.
ctrl – An instance of adsp_controller_t which has been initialised to control the DSP pipeline.

Returns:

adsp_control_status_t

void adsp_control_xscope(adsp_pipeline_t *adsp)

Creates an xscope handler thread for ADSP control.

Handles all xscope traffic and calls to adsp_read_module_config and adsp_write_module_config. If the application already uses xscope, do not call this function; instead, identify host-to-device packets by the ADSP header and pass them to adsp_control_xscope_process manually.

Parameters:

adsp – The DSP pipeline that will be controlled with this xscope thread.

struct adsp_stage_control_cmd_t

#include <adsp_control.h>

The command to execute. Specifies which stage, what command and contains the buffer to read from or write to.

Public Members

uint8_t instance_id: The ID of the stage to target. Consider setting the label parameter in the pipeline definition to ensure that a usable identifier gets generated for using with control.

uint8_t cmd_id: “See the generated cmds.h for the available commands. Make sure to use a command which is supported for the target stage.

uint16_t payload_len: Length of the command in bytes.

void *payload: The buffer. Must be set to a valid array of size payload_len before calling the read or write functions.

struct adsp_controller_t

#include <adsp_control.h>

Object used to control a DSP pipeline.

As there may be multiple threads attempting to interact with the DSP pipeline at the same time, a separate instance of adsp_controller_t must be used by each to ensure that control can proceed safely.

Initialise each instance of adsp_controller_t with adsp_controller_init.

Private Members

module_instance_t *modules

size_t num_modules

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$C Design API$$$stages/adsp_module.h£££doc/01_tool_user_guide/pipeline_design.html#stages-adsp-module-h

Defines the generic structs that will hold the state and control configuration for each stage.

Enums

enum config_rw_state_t

Control states, used to communicate between DSP and control threads to notify when control needs processing.

Values:

enumerator config_read_pending: Control waiting to read the updated config from DSP.

enumerator config_write_pending: Config written by control and waiting for DSP to update.

enumerator config_read_updated: Stage has succesfully consumed a read command.

enumerator config_none_pending: All done. Control and DSP not waiting on anything.

struct module_control_t

#include <adsp_module.h>

Control related information shared between control thread and DSP.

Public Members

void *config: Pointer to a stage-specific config struct which is used by the control thread.

uint32_t id: Unique module identifier assigned by the host.

uint32_t num_control_commands: The number of control commands for this stage.

uint8_t module_type: Identifies the stage type. Each type of stage has a unique identifier.

uint8_t cmd_id: Is set to the current command being processed.

config_rw_state_t config_rw_state

intptr_t current_controller: id of the current control object that requested a read, do not modify.

swlock_t lock: lock used by controlling threads to manage access

struct module_instance_t

#include <adsp_module.h>

The entire state of a stage in the pipeline.

Public Members

void *state: Pointer to the module’s state memory.

module_control_t control: Module’s control state.

void *constants

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$C Design API$$$stages/adsp_pipeline.h£££doc/01_tool_user_guide/pipeline_design.html#stages-adsp-pipeline-h

Generated pipeline interface. Use the source and sink functions defined here to send samples to the generated DSP and receive processed samples back.

Functions

static inline void adsp_pipeline_source(adsp_pipeline_t *adsp, int32_t **data)

Pass samples into the DSP pipeline.

These samples are sent by value to the other thread, therefore the data buffer can be reused immediately after this function returns.

Parameters:

adsp – The initialised pipeline.
data – An array of arrays of samples. The length of the array shall be the number of pipeline input channels. Each array contained within shall be contain a frame of samples large enough to pass to the stage that it is connected to.

static inline void adsp_pipeline_sink(adsp_pipeline_t *adsp, int32_t **data)

Receive samples from the DSP pipeline.

Parameters:

adsp – The initialised pipeline.
data – An array of arrays that will be filled with processed samples from the pipeline. The length of the array shall be the number of pipeline input channels. Each array contained within shall be contain a frame of samples large enough to pass to the stage that it is connected to.

static inline bool adsp_pipeline_sink_nowait(adsp_pipeline_t *adsp, int32_t **data)

Non-blocking receive from the pipeline. It is risky to use this API in an isochronous application as the sink thread can lose synchronisation with the source thread which can cause the source thread to block.

Parameters:

adsp – The initialised pipeline.
data – See adsp_pipeline_sink for details of same named param.

Return values:

true – The data buffer has been filled with new values from the pipeline.
false – The pipeline has not produced any more data. The data buffer was untouched.

struct adsp_pipeline_t

#include <adsp_pipeline.h>

The DSP pipeline.

The generated pipeline will contain an init function that returns a pointer to one of these. It can be used to send data in and out of the pipeline, and also execute control commands.

Public Members

module_instance_t *modules: Array of DSP stage states, must be used when calling one of the control functions.

size_t n_modules: Number of modules in the adsp_pipeline_t::modules array.

Private Members

channel_t *p_in

size_t n_in

channel_t *p_out

size_t n_out

channel_t *p_link

size_t n_link

adsp_mux_t input_mux

adsp_mux_t output_mux

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API£££doc/01_tool_user_guide/pipeline_design.html#python-design-api

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.build_utils£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-build-utils

Utility functions for building and running the application within the Jupyter notebook.

class audio_dsp.design.build_utils.XCommonCMakeHelper(source_dir: Optional[Union[str, Path]] = None, build_dir: Optional[Union[str, Path]] = None, bin_dir: Optional[Union[str, Path]] = None, project_name: Optional[str] = None, config_name: Optional[str] = None)

This class packages a set of helper utilities for configuring, building, and running xcore applications using xcommon-cmake within Python.

Parameters:

source_dirstr | pathlib.Path | None: Specify a source directory for this build, passed as the -S parameter to CMake. If None passed or unspecified, defaults to the current working directory.
build_dirstr | pathlib.Path | None: Specify a build directory for this build, passed as the -B parameter to CMake. If None passed or unspecified, defaults to “build” within the current working directory.
bin_dirstr | pathlib.Path | None: Specify a binary output directory for this build. This should match what is configured to be the output directory from “cmake –build” within the application. If None passed or unspecified, defaults to “bin” within the current working directory.
project_namestr | None: The name of the project() specified in the project’s CMakeLists.txt. If None or unspecified, defaults to the name of the current working directory (so if in /app_example_name/, the project name is assumed to be app_example_name).
config_namestr | None: The name of the configuration to use from the project’s CMakeLists.txt. If None or unspecified, defaults to nothing - therefore the –target option to CMake will be just the project name, and the output binary will be assumed to be “<current working directory>/<bin_dir>/<project_name>.xe”. If specified, the –target option to CMake will be “<project name>_<config name>”, and the output binary will be assumed to be “<current working directory>/<bin_dir>/<config_name>/<project name>_<config name>.xe”.

build() → int

Invoke CMake’s build with the options specified in this class instance. Invokation will be of the form “cmake –build <build_dir> –target <target_name>”, where the target name is constructed as per this class’ docstring.

Returns:

returncode: Return code from the invokation of CMake. 0 if success.

configure() → int | None

Invoke CMake with the options specified in this class instance. Invokation will be of the form “cmake -S <source_dir> -B <build_dir>”. On first run, the invokation will also contain “-G <generator>”, where “generator” will be either “Ninja” if Ninja is present on the current system or “Unix Makefiles” if it is not.

Returns:

returncode: Return code from the invokation of CMake. 0 if success.

configure_build_run(xscope: bool = True) → None

Run, in order, this class’ .configure(), .build(), and .run() methods. If any return code from any of the three is nonzero, returns early. Otherwise, sleeps for 5 seconds after the .run() stage and prints “Done!”.

Parameters:

xscopebool: Passed directly to the call to .run(); determines whether to start an xscope server or not.

run(xscope: bool = True, hostname: str = 'localhost', port: str = '12345') → int

Invoke xrun with the options specified in this class instance. Invokation will be of the form “xrun <binary>”, where the path to the binary is constructed as per this class’ docstring.

Parameters:

xscopebool: Specify whether to also pass “–xscope-port {hostname}:{port} as an option to the call to xrun.
hostnamestr: Hostname to pass to xrun for the xscope server, if xscope is True
portstr: Port to pass to xrun for the xscope server, if xscope is True

Returns:

returncode: Return code from the invokation of xrun. 0 if success.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.composite_stage£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-composite-stage

Contains the higher order stage class CompositeStage.

class audio_dsp.design.composite_stage.CompositeStage(graph: Graph, name: str = '')

This is a higher order stage.

Contains stages as well as other composite stages. A thread will be a composite stage. Composite stages allow:

drawing the detail with graphviz
process
frequency response

TODO: - Process method on the composite stage will need to know its inputs and the order of the inputs (which input index corresponds to each input edge). However a CompositeStage doesn’t know all of its inputs when it is created.

Parameters:

graphaudio_dsp.graph.Graph: instance of graph that all stages in this composite will be added to.
namestr: Name of this instance to use when drawing the pipeline, defaults to class name.

add_to_dot(dot)

Recursively adds composite stages to a dot diagram which is being constructed. Does not add the edges.

Parameters:

dotgraphviz.Diagraph: dot instance to add edges to.

composite_stage(name: str = '') → CompositeStage: Create a new composite stage that will be a included in the current composite. The new stage can have stages added to it dynamically.

contains_stage(stage: Stage) → bool

Recursively search self for the stage.

Returns:

bool: True if this composite contains the stage else False

draw(): Draws the stages and edges present in this instance of a composite stage.

get_all_stages() → list[audio_dsp.design.stage.Stage]

Get a flat list of all stages contained within this composite stage and the composite stages within.

Returns:

list of stages.

property o: StageOutputList

Outputs of this composite.

Dynamically computed by searching the graph for edges which originate in this composite and whose destination is outside this composite. Order not currently specified.

process(data): Execute the stages in this composite on the host.

Warning

Not implemented.

stage(stage_type: Type[_StageOrComposite], inputs: StageOutputList, label: Optional[str] = None, **kwargs) → _StageOrComposite

Create a new stage or composite stage and register it with this composite stage.

Parameters:

stage_type: Must be a subclass of Stage or CompositeStage
inputs: Edges of the pipeline that will be connected to the newly created stage.
kwargsdict: Additional args are forwarded to the stages constructors (__init__)

Returns:

stage_type: Newly created stage or composite stage.

stages(stage_types: list[Type[_StageOrComposite]], inputs: StageOutputList) → list[_StageOrComposite]

Iterate through the provided stages and connect them linearly.

Returns a list of the created instances.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.graph£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-graph

Basic data structures for managing the pipeline graph.

class audio_dsp.design.graph.Edge

Graph node.

Attributes:

iduuid.UUID4: A unique identifier for this node.
sourceNode | None
destNode | None: source and dest are the graph nodes that this edge connects between.

set_dest(node: Node)

Set the dest node of this edge.

Parameters:

node: The instance to set as the dest.

set_source(node: Node)

Set the source node of this edge.

Parameters:

node: The instance to set as the source.

class audio_dsp.design.graph.Graph

A container of nodes and edges.

Attributes:

nodes: A list of the nodes in this graph.
edges: A list of the edges in this graph.

add_edge(edge) → None: Append an edge to this graph.

add_node(node: NodeSubClass) → None

Append a node to this graph.

The node’s index attribute is set here and therefore the node may not coexist in multiple graphs.

get_dependency_dict() → dict[NodeSubClass, set[NodeSubClass]]: Return a mapping of nodes to their dependencies ready for use with the graphlib utilities.

get_view(nodes: list[NodeSubClass]) → Graph[NodeSubClass]: Get a filtered view of the graph, including only the provided nodes and the edges which connect to them.

lock(): Lock the graph. Adding nodes or edges to a locked graph will cause a runtime exception. The graph is locked once the pipeline checksum is computed.

sort() → tuple[NodeSubClass, ...]

Sort the nodes in the graph based on the order they should be executed. This is determined by looking at the edges in the graph and resolving the order.

Returns:

tuple[Node]: Ordered list of nodes

class audio_dsp.design.graph.Node

Graph node.

Attributes:

iduuid.UUID4: A unique identifier for this node.
indexNone | int: node index in the graph. This is set by Graph when it is added to the graph.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.parse_config£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-parse-config

Script for use at build time to generate header files.

Use as:

python -m audio_dsp.design.parse_config -c CONFIG_DIR -o OUTPUT_DIR

audio_dsp.design.parse_config.main(args): Use the mako templates to build the autogenerated files.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.pipeline£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-pipeline

Top level pipeline design class and code generation functions.

class audio_dsp.design.pipeline.Pipeline(n_in, identifier='auto', frame_size=1, fs=48000, generate_xscope_task=False)

Top level class which is a container for a list of threads that are connected in series.

Parameters:

n_inint: Number of input channels into the pipeline
identifier: string: Unique identifier for this pipeline. This identifier will be included in the generated header file name (as “adsp_generated_<identifier>.h”), the generated source file name (as “adsp_generated_<identifier>.c”), and the pipeline’s generated initialisation and main functions (as “adsp_<identifier>_pipeline_init” and “adsp_<identifier>_pipeline_main”)
frame_sizeint: Size of the input frame of all input channels
fsint: Sample rate of the input channels
generate_xscope_taskbool: Determines whether the generated pipeline automatically instantiates a task to handle tuning over xscope. False by default. If False, the application code will need to explicitly call the “adsp_control_xscope_*” functions defined in adsp_control.h in order to handle tuning over xscope, such as that undertaken by the XScopeTransport() class.

Attributes:

ilist(StageOutput): The inputs to the pipeline should be passed as the inputs to the first stages in the pipeline
threadslist(Thread): List of all the threads in the pipeline
pipeline_stagePipelineStage | None: Stage corresponding to the pipeline. Needed for handling pipeline level control commands

add_pipeline_stage(thread): Add a PipelineStage stage for the pipeline.

static begin(n_in, identifier='auto', frame_size=1, fs=48000)

Create a new Pipeline and get the attributes required for design.

Returns:

Pipeline, Thread, StageOutputList: The pipeline instance, the initial thread and the pipeline input edges.

draw(path: Optional[Path] = None)

Render a dot diagram of this pipeline.

If path is not none then the image will be saved to the named file instead of drawing to the jupyter notebook.

executor() → PipelineExecutor: Create an executor instance which can be used to simulate the pipeline.

generate_pipeline_hash(threads: list, edges: list)

Generate a hash unique to the pipeline and save it in the ‘checksum’ control field of the pipeline stage.

Parameters:

“threads”: list of [[(stage index, stage type name), …], …] for all threads in the pipeline
“edges”: list of [[[source stage, source index], [dest stage, dest index]], …] for all edges in the pipeline

next_thread() → None

Update the thread which stages will be added to.

This will always create a new thread.

resolve_pipeline()

Generate a dictionary with all of the information about the thread. Actual stage instances not included.

Returns:

dict: ‘identifier’: string identifier for the pipeline “threads”: list of [[(stage index, stage type name, stage memory use), …], …] for all threads “edges”: list of [[[source stage, source index], [dest stage, dest index]], …] for all edges “configs”: list of dicts containing stage config for each stage. “modules”: list of stage yaml configs for all types of stage that are present “labels”: dictionary {label: instance_id} defining mapping between the user defined stage labels and the index of the stage “xscope”: bool indicating whether or not to create an xscope task for control

set_outputs(output_edges: StageOutputList)

Set the pipeline outputs, configures the output channel index.

Parameters:

output_edgesIterable(None | StageOutput): configure the output channels and their indices. Outputs of the pipeline will be in the same indices as the input to this function. To have an empty output index, pass in None.

stage(stage_type: Type[audio_dsp.design.stage.Stage | audio_dsp.design.composite_stage.CompositeStage], inputs: StageOutputList, label: Optional[str] = None, **kwargs) → StageOutputList

Add a new stage to the pipeline.

Parameters:

stage_type: The type of stage to add.
inputs: A StageOutputList containing edges in this pipeline.
label: An optional label that can be used for tuning and will also be converted into a macro in the generated pipeline. Label must be set if tuning or run time control is required for this stage.

property stages: Flattened list of all the stages in the pipeline.

validate()

TODO validate pipeline assumptions.

Thread connections must not lead to a scenario where the pipeline hangs
Stages must fit on thread
feedback must be within a thread (future)
All edges have the same fs and frame_size (until future enhancements)

class audio_dsp.design.pipeline.PipelineStage(**kwargs)

Stage for the pipelne. Does not support processing of data through it. Only used for pipeline level control commands, for example, querying the pipeline checksum.

add_to_dot(dot)

Override the CompositeStage.add_to_dot() function to ensure PipelineStage type stages are not added to the dot diagram.

Parameters:

dotgraphviz.Diagraph
dot instance to add edges to.

audio_dsp.design.pipeline.callonce(f): Decorate functions to ensure they only execute once despite being called multiple times.

audio_dsp.design.pipeline.generate_dsp_main(pipeline: Pipeline, out_dir='build/dsp_pipeline')

Generate the source code for adsp_generated_<x>.c.

Parameters:

pipelinePipeline: The pipeline to generate code for.
out_dirstr: Directory to store generated code in.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.pipeline_executor£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-pipeline-executor

Utilities for processing the pipeline on the host machine.

class audio_dsp.design.pipeline_executor.ExecutionResult(result: ndarray, fs: float)

The result of processing samples through the pipeline.

Parameters:

result: The data produced by the pipeline.
fs: sample rate

Attributes:

data: ndarray containing the results of the pipeline.
fs: Sample rate.

play(channel: int)

Create a widget in the jupyter notebook to listen to the audio.

Warning

This will not work outside of a jupyter notebook.

Parameters:

channel: The channel to listen to.

plot(path: Optional[Union[Path, str]] = None)

Display a time domain plot of the result. Save to file if path is not None.

Parameters:

path: If path is not none then the plot will be saved to a file and not shown.

plot_magnitude_spectrum(path: Optional[Union[Path, str]] = None)

Display a spectrum plot of the result. Save to file if path is not None.

Parameters:

path: If path is not none then the plot will be saved to a file and not shown.

plot_spectrogram(path: Optional[Union[Path, str]] = None)

Display a spectrogram plot of the result. Save to file if path is not None.

Parameters:

path: If path is not none then the plot will be saved to a file and not shown.

to_wav(path: str | pathlib.Path): Save output to a wav file.

class audio_dsp.design.pipeline_executor.PipelineExecutor(graph: Graph[Stage], view_getter: Callable[[], PipelineView])

Utility for simulating the pipeline.

Parameters:

graph: The pipeline graph to simulate

log_chirp(length_s: float = 0.5, amplitude: float = 1, start: float = 20, stop: Optional[float] = None) → ExecutionResult

Generate a logarithmic chirp of constant amplitude and play through the simulated pipeline.

Parameters:

length_s: Length of generated chirp in seconds.
amplitude: Amplitude of the generated chirp, between 0 and 1.
start: Start frequency.
stop: Stop frequency. Nyquist if not set

Returns:

ExecutionResult: The output wrapped in a helpful container for viewing, saving, processing, etc.

process(data: ndarray) → ExecutionResult

Process the DSP pipeline on the host.

Parameters:

data: Pipeline input to process through the pipeline. The shape must match the number of channels that the pipeline expects as an input; if this is 1 then it may be a 1 dimensional array. Otherwise, it must have shape (num_samples, num_channels).

Returns:

ExecutionResult: A result object that can be used to visualise or save the output.

class audio_dsp.design.pipeline_executor.PipelineView(stages: Optional[list[audio_dsp.design.stage.Stage]], inputs: list[audio_dsp.design.stage.StageOutput], outputs: list[audio_dsp.design.stage.StageOutput])

A view of the DSP pipeline that is used by PipelineExecutor.

inputs: list[audio_dsp.design.stage.StageOutput]: Alias for field number 1

outputs: list[audio_dsp.design.stage.StageOutput]: Alias for field number 2

stages: Optional[list[audio_dsp.design.stage.Stage]]: Alias for field number 0

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.plot£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-plot

Helper functions for displaying plots in the jupyter notebook pipeline design.

audio_dsp.design.plot.plot_frequency_response(f, h, name='', range=50)

Plot the frequency response.

Parameters:

fnumpy.ndarray: Frequencies (The X axis)
hnumpy.ndarray: Frequency response at the corresponding frequencies in f
namestr: String to include in the plot title, if not set there will be no title.
rangeint | float: Set the Y axis lower limit in dB, upper limit will be the maximum magnitude.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.stage£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-stage

The edges and nodes for a DSP pipeline.

class audio_dsp.design.stage.PropertyControlField(get, set=None)

For stages which have internal state they can register callbacks for getting and setting control fields.

property value

The current value of this control field.

Determined by executing the getter method.

class audio_dsp.design.stage.Stage(inputs: StageOutputList, config: Optional[Union[Path, str]] = None, name: Optional[str] = None, label: Optional[str] = None)

Base class for stages in the DSP pipeline. Each subclass should have a corresponding C implementation. Enables code generation, tuning and simulation of a stage.

The stages config can be written and read using square brackets as with a dictionary. This is shown in the below example, note that the config field must have been declared in the stages yaml file.

self[“config_field”] = 2 assert self[“config_field”] == 2

Parameters:

configstr | Path: Path to yaml file containing the stage definition for this stage. Config parameters are derived from this config file.
inputsIterable[StageOutput]: Pipeline edges to connect to self
namestr: Name of the stage. Passed instead of config when the stage does not have an associated config yaml file
labelstr: User defined label for the stage. Used for autogenerating a define for accessing the stage’s index in the device code

Attributes:

ilist[StageOutput]: This stages inputs.
fsint | None: Sample rate.
frame_sizeint | None: Samples in frame.
namestr: Stage name determined from config file
yaml_dictdict: config parsed from the config file
labelstr: User specified label for the stage
n_inint: number of inputs
n_outint: number of outputs
detailsdict: Dictionary of descriptive details which can be displayed to describe current tuning of this stage
dsp_blockNone | audio_dsp.dsp.generic.dsp_block: This will point to a dsp block class (e.g. biquad etc), to be set by the child class

add_to_dot(dot)

Add this stage to a diagram that is being constructed. Does not add the edges.

Parameters:

dotgraphviz.Diagraph: dot instance to add edges to.

property constants: Get a copy of the constants for this stage.

create_outputs(n_out)

Create this stages outputs.

Parameters:

n_outint: number of outputs to create.

get_config()

Get a dictionary containing the current value of the control fields which have been set.

Returns:

dict: current control fields

get_frequency_response(nfft=512) → tuple[numpy.ndarray, numpy.ndarray]

Return the frequency response of this instance’s dsp_block attribute.

Parameters:

nfft: The length of the FFT

Returns:

ndarray, ndarray: Frequency values, Frequency response for this stage.

get_required_allocator_size()

Calculate the required statically-allocated memory in bytes for this stage. Formats this into a compile-time determinable expression.

Returns:

compile-time determinable expression of required allocator size.

property o: StageOutputList: This stage’s outputs. Use this object to connect this stage to the next stage in the pipeline. Subclass must call self.create_outputs() for this to exist.

plot_frequency_response(nfft=512)

Plot magnitude and phase response of this stage using matplotlib. Will be displayed inline in a jupyter notebook.

Parameters:

nfftint: Number of frequency bins to calculate in the fft.

process(in_channels)

Run dsp object on the input channels and return the output.

Args:: in_channels: list of numpy arrays

Returns:

list of numpy arrays.

set_constant(field, value, value_type)

Define constant values in the stage. These will be hard coded in the autogenerated code and cannot be changed at runtime.

Parameters:

fieldstr: name of the field
valuendarray or int or float or list: value of the constant. This can be an array or scalar

set_control_field_cb(field, getter, setter=None)

Parameters:

fieldstr: name of the field
getterfunction: A function which returns the current value
setterfunction: A function which accepts 1 argument that will be used as the new value

class audio_dsp.design.stage.StageOutput(fs=48000, frame_size=1)

The Edge of a dsp pipeline.

Parameters:

fsint: Edge sample rate Hz
frame_sizeint: Number of samples per frame

Attributes:

sourceaudio_dsp.design.graph.Node: Inherited from Edge
destaudio_dsp.design.graph.Node: Inherited from Edge
source_indexint | None: The index of the edge connection to source.
fsint: see fs parameter
frame_sizeint: see frame_size parameter

property dest_index: int | None: The index of the edge connection to the dest.

class audio_dsp.design.stage.StageOutputList(edges: Optional[list[audio_dsp.design.stage.StageOutput | None]] = None)

A container of StageOutput.

A stage output list will be created whenever a stage is added to the pipeline. It is unlikely that a StageOutputList will have to be explicitly created during pipeline design. However the indexing and combining methods shown in the example will be used to create new StageOutputList instances.

Parameters:

edges: list of StageOutput to create this list from.

Examples

This example shows how to combine StageOutputList in various ways:

# a and b are StageOutputList
a = some_stage.o
b = other_stage.o

# concatenate them
a + b

# Choose a single channel from 'a'
a[0]

# Choose channels 0 and 3 from 'a'
a[0, 3]

# Choose a slice of channels from 'a', start:stop:step
a[0:10:2]

# Combine channels 0 and 3 from 'a', and 2 from 'b'
a[0, 3] + b[2]

# Join 'a' and 'b', with a placeholder "None" in between
a + None + b

Attributes:

edgeslist[StageOutput]: To access the actual edges contained within this list then read from the edges attribute. All methods in this class return new StageOutputList instances (even when the length is 1).

class audio_dsp.design.stage.ValueControlField(value=None): Simple field which can be updated directly.

audio_dsp.design.stage.all_stages() → dict[str, Type[audio_dsp.design.stage.Stage]]: Get a dict containing all stages in scope.

audio_dsp.design.stage.find_config(name)

Find the config yaml file for a stage by looking for it in the default directory for built in stages.

Parameters:

namestr: Name of stage, e.g. a stage whose config is saved in “biquad.yaml” should pass in “biquad”.

Returns:

Path: Path to the config file.

Lib Audio DSP$$$Tool User Guide$$$Pipeline Design API$$$Python Design API$$$audio_dsp.design.thread£££doc/01_tool_user_guide/pipeline_design.html#audio-dsp-design-thread

Contains classes for adding a thread to the DSP pipeline.

class audio_dsp.design.thread.DSPThreadStage(**kwargs)

Stage for the DSP thread. Does not support processing of data through it. Only used for DSP thread level control commands, for example, querying the max cycles consumed by the thread.

add_to_dot(dot)

Exclude this stage from the dot diagram.

Parameters:

dotgraphviz.Diagraph: dot instance to add edges to.

class audio_dsp.design.thread.Thread(id: int, **kwargs)

A composite stage used to represent a thread in the pipeline. Create using Pipeline.thread rather than instantiating directly.

Parameters:

idint: Thread index
kwargsdict: forwarded to __init__ of CompositeStage

Attributes:

idint: Thread index
thread_stageStage: DSPThreadStage stage

add_thread_stage(): Add to this thread the stage which manages thread level commands.

Lib Audio DSP$$$Design Guide£££doc/02_design_guide/index.html#design-guide

This guide will cover the details of how the xcore DSP pipeline is generated from the Python description. This should enable the reader to debug their pipeline when issues arise and understand the resource usage of a generated DSP pipeline. This is an advanced guide intended for users who wish for a deeper understanding of the generated DSP pipeline that they have created. The accompanying tool and component guides should be consulted for the basic process of using this tool.

Lib Audio DSP$$$Design Guide$$$Summary of the xcore.ai architecture£££doc/02_design_guide/design_guide.html#summary-of-the-xcore-ai-architecture

A basic understanding of the xcore architecture is required in order to understand the consequences of various design choices that can be made in the DSP pipeline.

An xcore application will consist of 1 or more xcore.ai chips connected together via a communication fabric (the XLink). Each xcore.ai contains 2 or more tiles; a tile is an independent processor with its own memory. A tile cannot read or write the memory of another tile. Each tile contains 8 logical cores; a logical core is an independent thread of execution that will run some application code. Each tile also has 32 chanends available for allocation; connecting 2 chanends forms a channel, which allows for synchronous communication between any 2 logical cores in the system (even between tiles or packages).

In its default configuration, an xcore.ai chip will operate at 600MHz; this means that each tile executes instructions at a rate of 600MIPS. This is shared between the 8 logical cores by multiplexing the execution across 5 time slots. Each thread can consume at most 1 time slot per scheduler cycle. The consequence of this is that for applications with up to 5 threads, each thread operates at 120MIPS (600/5). If there are over 5 threads then this number can be reduced down to 75MIPS (600/8). If any of the threads modify their priority mode then this can reduce the available MIPS even further; high-priority threads are always guaranteed a slot in the scheduler on each cycle.

Term	Definition
xcore.ai	A chip containing 2 or more tiles.
Tile	A single processor with some memory.
Logical Core	1 of the 8 threads available in each tile.
Chanend	The physical hardware used by a logical core to create a channel. There are 32 available per tile.
Channel	The bidirectional communication pathway that is created when 2 chanends are connected.

For more information about the xcore architecture, consult The XMOS XS3 Architecture and the data sheet for your package.

Lib Audio DSP$$$Design Guide$$$The Architecture of the Generated Pipeline£££doc/02_design_guide/design_guide.html#the-architecture-of-the-generated-pipeline

Fig. 8 shows the relationship between the classes in an application with a generated DSP pipeline. A class in this context refers to a C struct and the functions that operate on it.

../_images/dsp_class.drawio.png — Class diagram of a lib_audio_dsp application

The application package contains Audio Source, Audio Sink and Control classes. The Audio Source and Sink are responsible for producing and consuming audio at the rate required by the DSP pipeline. The Control is responsible for implementing any application specific dynamic control of the DSP pipeline; this is optional and will only be present where run time control is used. These are in the Application package as they will be unique for each application. Audio Source, Audio Sink, and Control make use of the classes in lib_audio_dsp; all make use of a pointer to a shared adsp_pipeline_t (as shown by the aggregation relationships (hollow diamond) in Fig. 8). lib_audio_dsp presents a thread safe API, allowing Audio Source, Audio Sink and Control to exist on separate threads if desired. However, they must all exist on the same tile in order to access the shared adsp_pipeline_t.

The “lib_audio_dsp” repository represents the classes from this library. These APIs are documented fully in the Tool User Guide.

The “Generated Pipeline” package represents the classes and objects which will be generated from the user’s specified DSP pipeline design. Fig. 8 shows that adsp_generated_auto is composed of (filled diamond) the adsp_pipeline_t and multiple module_instance_t. Therefore, the generated pipeline is responsible for allocating the memory for all the stages in the pipeline and also initialising each stage. The generated pipeline also creates multiple threads (labelled dsp_threadX in Fig. 8), each of which will have been uniquely generated for the DSP pipeline that has been designed. The generated pipeline will always require at least 1 thread to run the DSP on; it is not possible to generate a DSP pipeline that can be executed inline on an existing thread. It is also not possible to split the DSP threads across more than 1 tile, because all threads access a shared adsp_pipeline_t object.

To summarise, the generated DSP pipeline will consume the number of threads specified in the design (at least 1). At least one other thread on the same tile must be available to exchange audio with the DSP pipeline.

Lib Audio DSP$$$Design Guide$$$Resource usage of the Generated Pipeline£££doc/02_design_guide/design_guide.html#resource-usage-of-the-generated-pipeline

The resources that are consumed by the generated DSP pipeline are threads, chanends, and memory. Each DSP thread also has a finite number of instructions per sample that are available for DSP. It is the responsibility of the DSP designer to ensure that this limit is not exceeded on any of the threads.

Lib Audio DSP$$$Design Guide$$$Resource usage of the Generated Pipeline$$$Chanend Usage£££doc/02_design_guide/design_guide.html#chanend-usage

The following snippet of Python shows a DSP design; the pipeline diagram for the snippet is shown in Fig. 9. This design splits 4 DSP stages amongst 3 threads. Threads 0 and 1 operate on the pipeline inputs in parallel. Thread 2 receives its inputs from threads 0 and 1. The pipeline output comes from thread 1.

The generated DSP threads and the APIs for exchanging inputs with the pipeline all use channels to communicate audio.

from audio_dsp.design.pipeline import Pipeline
from audio_dsp.stages import *

p, edge = Pipeline.begin(4)

# thread 0
e0 = p.stage(Bypass, edge[0], "a")

# thread 1
p.next_thread()
e1 = p.stage(Bypass, edge[1:], "b")
e1 = p.stage(Bypass, e1, "c")

# thread 2
p.next_thread()
e = p.stage(Bypass, e0 + e1, "d")

p.set_outputs(e)

../_images/design_guide_resources.gv.png — Output of Pipeline.draw() for the example pipeline

Fig. 10 shows how the chanends are allocated for this design. A channel (2 chanends) is allocated for every connection from one thread to another. Thread 2 receives data from thread 0 and 1, therefore it has 2 input channels. It only outputs to 1 thread (end) so has 1 output channel.

If multiple data channels are passed from 1 thread to another (e.g. 3 channels from thread 1 to 2) this still only consumes a single xcore channel (2 chanends) as all the data channels are sent over the same xcore channel.

For a simple linear pipeline, the chanend usage will be $2 * num_dsp_threads + 2$. For pipelines with parallel threads the usage will be higher, as shown in Fig. 10 where 10 chanends (5 channels) are used for 3 DSP threads.

../_images/chanends.drawio.png — Chanend usage for the example pipeline

Lib Audio DSP$$$Design Guide$$$Resource usage of the Generated Pipeline$$$Thread Usage£££doc/02_design_guide/design_guide.html#thread-usage

Thread usage of the DSP pipeline is discussed in the sections above. Understanding the thread usage of your application is a manual process. The application designer must have an understanding of how many threads are in use in their application as well as in the DSP pipeline to ensure that the limit of 8 is not exceeded. If this limit is exceeded the xcore will trap when the application attempts to fork a ninth thread.

Lib Audio DSP$$$Design Guide$$$Resource usage of the Generated Pipeline$$$Memory Usage£££doc/02_design_guide/design_guide.html#memory-usage

All memory used in the generated DSP pipeline is statically allocated and therefore known at compile time. The Python design API cannot assist in understanding the memory usage of your application. The memory report which is displayed when compiling the application must be consulted to see the memory used. This value will include the generated DSP pipeline as well as any other application code that is running on the tile.

Lib Audio DSP$$$Design Guide$$$Resource usage of the Generated Pipeline$$$MIPS Usage£££doc/02_design_guide/design_guide.html#mips-usage

In order to operate in a real time audio system it is critical that each thread in the DSP pipeline can complete execution in less time than the sample period (or frame period if the frame size is greater than 1). It is this constraint that requires the DSP to be split into pipelined threads. If a thread is overloaded, the DSP pipeline will consume and produce samples at a slower rate than expected. This could cause the source and sink threads to block and miss timing. The current version of lib_audio_dsp provides only limited support for measuring the MIPS usage of each thread.

Each thread measures the total number of system ticks (periods of the system clock, by default a 100MHz clock) that pass while it is doing work and stores the maximum value that has occured since boot. This measurement can be used to get an estimate of the threads’ MIPS utilisations. To access this value, the function adsp_auto_print_thread_max_ticks() (“auto” may be replaced with a custom pipeline identifier if specified) is generated along with the other generated pipeline functions. Calling this function on the same tile as the pipeline will print the measured value. Printing is implemented with printf, so the output will only be visible when connected to the device with xrun or xgdb.

The number of available ticks on each thread depends on the frame size and sample rate of the data. For example, given that the system clock runs by default at 100MHz, if the sample rate is 48000 Hz and frame size is 1 then the available ticks will be $1 * 100e6/48000 = 2083 ticks$. Below is an example output from adsp_auto_print_thread_max_ticks() for a pipeline with 4 threads:

DSP Thread Ticks:
    1800
    181
    67
    93

The number that is displayed is the worst case that has happened since boot. This is not necessarily the absolute worst case as some stages have data dependent execution time. Therefore, it is recommended to play an audio signal through the pipeline with varying amplitude and frequencies before measuring the thread MIPS.

Lib Audio DSP$$$Design Guide$$$Troubleshooting resource issues£££doc/02_design_guide/design_guide.html#troubleshooting-resource-issues

Lib Audio DSP$$$Design Guide$$$Troubleshooting resource issues$$$Tile exceeds memory limit£££doc/02_design_guide/design_guide.html#tile-exceeds-memory-limit

Memory available check will report “FAILED” during linking. The Memory Usage section describes how memory is allocated in the DSP pipeline. Recommended steps:

Remove all stages from the pipeline.
Add them back one at a time and take note of the memory usage of each stage.
Consult the documentation for the problematic stages and see if its memory usage is configuration dependent.

Moving stages between threads will not impact the memory usage as all threads are on the same tile.

Lib Audio DSP$$$Design Guide$$$Troubleshooting resource issues$$$Tile exceeds available chanends£££doc/02_design_guide/design_guide.html#tile-exceeds-available-chanends

If a tile attempts to allocate too many chanends it will raise an illegal resource exception and cease execution. This can be detected easily with xgdb or xrun as it will print the following message:

Unhandled exception: ILLEGAL_RESOURCE

The Chanend Usage section describes how chanends are used within the DSP pipeline. Resolving this problem will require either redesigning the DSP or the application that runs on the same tile to use fewer chanends.

Lib Audio DSP$$$Design Guide$$$Exchanging audio with the DSP pipeline blocks for too long£££doc/02_design_guide/design_guide.html#exchanging-audio-with-the-dsp-pipeline-blocks-for-too-long

adsp_pipeline_sink or adsp_pipeline_source will block until data is available. The MIPS Usage section describes how to ensure the DSP pipeline meets timing. Identifying this particular issue will depend on the rest of the application. The result could be either dropped samples that are audible in the output or a complete application crash.

Lib Audio DSP$$$Design Guide$$$Exchanging audio with the DSP pipeline blocks for too long$$$Tile exceeds available threads£££doc/02_design_guide/design_guide.html#tile-exceeds-available-threads

If a tile attempts to fork too many threads it will raise an illegal resource exception and cease execution. This can be detected easily with xgdb or xrun as it will print the following message:

Unhandled exception: ILLEGAL_RESOURCE

The Thread Usage section describes how threads are used within the DSP pipeline. Resolving this problem will require either redesigning the DSP or the application that runs on the same tile to use fewer threads.

Lib Audio DSP$$$DSP Components£££doc/03_dsp_components/index.html#dsp-components

lib_audio_dsp provides many common signal processing functions optimised for xcore. These can be combined together to make complex audio pipelines for many different applications, such as home audio, music production, voice processing, and AI feature extraction.

The library is split into 2 levels of API: DSP stages and DSP modules. Both APIs provide similar DSP functionality, but are suited to different use cases.

The higher-level APIs are called DSP Stages. These stages are designed to work with the Python DSP pipeline tool. This tool allows developers to quickly and easily create, test, and deploy DSP pipelines without needing to write a lot of code. By using DSP stages, the user can build complex audio processing workflows in a short amount of time, making it ideal for rapid prototyping and development.

The lower-level APIs are called DSP Modules. They are meant to be used as an API directly in cases where the Python DSP pipeline tool is not used. These modules can be useful when integrating DSP functionality into an existing system, or as a starting point for creating bespoke DSP functions.

Lib Audio DSP$$$DSP Components$$$DSP Stages£££doc/03_dsp_components/stages/index.html#dsp-stages

DSP stages are high level blocks for use in the Python DSP pipeline tool. Each Stage has a Python and C implementation, allowing pipelines to be rapidly prototyped in Python before being easily deployed to hardware in C. The audio performance of both implementations is equivalent.

Most stages have parameters that can be changed at runtime, and the available parameters are outlined in the documentation.

All the DSP stages can be imported into a Python file using:

from audio_dsp.stages import *

The following DSP stages are available for use in the Python DSP pipeline design.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Biquad Stages£££doc/03_dsp_components/stages/gen/biquad.html#biquad-stages

Biquad Stages can be used for basic audio filters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Biquad Stages$$$Biquad£££doc/03_dsp_components/stages/gen/biquad.html#biquad

class audio_dsp.stages.biquad.Biquad(**kwargs)

A second order biquadratic filter, which can be used to make many common second order filters. The filter is initialised in a bypass state, and the make_* methods can be used to calculate the coefficients.

This Stage implements a direct form 1 biquad filter: a0*y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]

For efficiency the biquad coefficients are normalised by a0 and the output a coefficients multiplied by -1.

Attributes:

dsp_blockaudio_dsp.dsp.biquad.biquad: The DSP block class; see Single Biquad for implementation details.

make_allpass(f: float, q: float) → Biquad

Make this biquad an all pass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_bandpass(f: float, bw: float) → Biquad

Make this biquad a second order bandpass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bandstop(f: float, bw: float) → Biquad

Make this biquad a second order bandstop filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bypass() → Biquad: Make this biquad a bypass by setting the b0 coefficient to 1.

make_constant_q(f: float, q: float, boost_db: float) → Biquad

Make this biquad a peaking filter with constant Q.

Constant Q means that the bandwidth of the filter remains constant as the gain varies. It is commonly used for graphic equalisers.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_highpass(f: float, q: float) → Biquad

Make this biquad a second order high pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_highshelf(f: float, q: float, boost_db: float) → Biquad

Make this biquad a second order high shelf filter.

The Q factor is defined in a similar way to standard high pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_linkwitz(f0: float, q0: float, fp: float, qp: float) → Biquad

Make this biquad a Linkwitz Transform biquad filter.

The Linkwitz Transform changes the low frequency cutoff of a filter, and is commonly used to change the low frequency roll off slope of a loudspeaker. When applied to a loudspeaker, it will change the cutoff frequency from f0 to fp, and the Q factor from q0 to qp.

Parameters:

f0float: The original cutoff frequency of the filter in Hz.
q0float: The original quality factor of the filter at f0.
fpfloat: The target cutoff frequency for the filter in Hz.
qpfloat: The target quality factor for the filter.

make_lowpass(f: float, q: float) → Biquad

Make this biquad a second order low pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_lowshelf(f: float, q: float, boost_db: float) → Biquad

Make this biquad a second order low shelf filter.

The Q factor is defined in a similar way to standard low pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_notch(f: float, q: float) → Biquad

Make this biquad a notch filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_peaking(f: float, q: float, boost_db: float) → Biquad

Make this biquad a peaking filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Biquad Stages$$$Biquad$$$Biquad Control£££doc/03_dsp_components/stages/gen/biquad.html#biquad-control

The following runtime command ids are available for the Biquad Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_BIQUAD_LEFT_SHIFT	`sizeof(int)`
The number of bits to shift the output left by, in order to compensate for any right shift applied to the biquad b coefficients.

CMD_BIQUAD_FILTER_COEFFS	`sizeof(int32_t)*[5]`
The normalised biquad filter coefficients, in the order [b0, b1, b2, -a1, -a2]/a0. The coefficients should be in Q1.30 format. If the maximum b coefficient magnitude is greater than 2.0, the b coefficients should be right shifted to fit in Q1.30 format, and the shift value passed as left_shift to correct the gain after filtering. Biquad coefficients can be generated using the helper functions in `control/biquad.h`.

CMD_BIQUAD_RESERVED	`sizeof(int32_t)*[3]`
Reserved memory to ensure the VPU receives 8 DWORD_ALIGNED coefficients. This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Cascaded Biquads Stages£££doc/03_dsp_components/stages/gen/cascaded_biquads.html#cascaded-biquads-stages

Cascaded biquad Stages consist of several biquad filters connected together in series.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Cascaded Biquads Stages$$$CascadedBiquads£££doc/03_dsp_components/stages/gen/cascaded_biquads.html#cascadedbiquads

class audio_dsp.stages.cascaded_biquads.CascadedBiquads(**kwargs)

8 cascaded biquad filters. This allows up to 8 second order biquad filters to be run in series.

This can be used for either:

an Nth order filter built out of cascaded second order sections
a parametric EQ, where several biquad filters are used at once.

For documentation on the individual biquad filters, see audio_dsp.stages.biquad.Biquad and audio_dsp.dsp.biquad.biquad

Attributes:

dsp_blockaudio_dsp.dsp.cascaded_biquad.cascaded_biquad: The DSP block class; see Cascaded Biquads for implementation details.

make_butterworth_highpass(N: int, fc: float) → CascadedBiquads

Configure this instance as an Nth order Butterworth highpass filter using N/2 cascaded biquads.

For details on the implementation, see audio_dsp.dsp.cascaded_biquads.make_butterworth_highpass

Parameters:

Nint: Filter order, must be even
fcfloat: -3 dB frequency in Hz.

make_butterworth_lowpass(N: int, fc: float) → CascadedBiquads

Configure this instance as an Nth order Butterworth lowpass filter using N/2 cascaded biquads.

For details on the implementation, see audio_dsp.dsp.cascaded_biquads.make_butterworth_lowpass

Parameters:

Nint: Filter order, must be even
fcfloat: -3 dB frequency in Hz.

make_parametric_eq(filter_spec: list[list[Any]]) → CascadedBiquads

Configure this instance as a Parametric Equaliser.

This allows each of the 8 biquads to be individually designed using the designer methods for the biquad. This expects to receive a list of up to 8 biquad design descriptions where a biquad design description is of the form:

["type", args...]

where “type” is a string defining how the biquad should be designed e.g. “lowpass”, and args… is all the parameters to design that type of filter. All options and arguments are listed below:

["biquad_allpass", filter_freq, q_factor, Q_sig]
["biquad_bandpass", filter_freq, bw, Q_sig]
["biquad_bandstop", filter_freq, bw, Q_sig]
["biquad_bypass", Q_sig]
["biquad_constant_q", filter_freq, q_factor, boost_db, Q_sig]
["biquad_gain", gain_db, Q_sig]
["biquad_highpass", filter_freq, q_factor, Q_sig]
["biquad_highshelf", filter_freq, q_factor, boost_db, Q_sig]
["biquad_linkwitz", f0, q0, fp, qp, Q_sig]
["biquad_lowpass", filter_freq, q_factor, Q_sig]
["biquad_lowshelf", filter_freq, q_factor, boost_db, Q_sig]
["biquad_notch", filter_freq, q_factor, Q_sig]
["biquad_peaking", filter_freq, q_factor, boost_db, Q_sig]

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Cascaded Biquads Stages$$$CascadedBiquads$$$CascadedBiquads Control£££doc/03_dsp_components/stages/gen/cascaded_biquads.html#cascadedbiquads-control

The following runtime command ids are available for the CascadedBiquads Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_CASCADED_BIQUADS_LEFT_SHIFT	`sizeof(int)*[8]`
The coefficient shift applied to the output of each biquad in the cascade. The shifts should be in the same format as specified in the individual biquad.

CMD_CASCADED_BIQUADS_FILTER_COEFFS	`sizeof(int32_t)*[40]`
The normalised biquad filter coefficients for each biquad in the cascade as an array of [5][8], with 5 coefficients for up to 8 biquads. The coefficients should be in the same format as specified in the individual biquad.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Stages£££doc/03_dsp_components/stages/gen/compressor.html#compressor-stages

Compressor stages allow for control of the dynamic range of the signal, such as reducing the level of loud sounds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Stages$$$CompressorRMS£££doc/03_dsp_components/stages/gen/compressor.html#compressorrms

class audio_dsp.stages.compressor.CompressorRMS(**kwargs)

A compressor based on the RMS envelope of the input signal.

When the RMS envelope of the signal exceeds the threshold, the signal amplitude is reduced by the compression ratio.

The threshold sets the value above which compression occurs. The ratio sets how much the signal is compressed. A ratio of 1 results in no compression, while a ratio of infinity results in the same behaviour as a limiter. The attack time sets how fast the compressor starts compressing. The release time sets how long the signal takes to ramp up to its original level after the envelope is below the threshold.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.compressor_rms: The DSB block class; see RMS Compressor for implementation details.

make_compressor_rms(ratio, threshold_db, attack_t, release_t, Q_sig=27)

Update compressor configuration based on new parameters.

Parameters:

ratiofloat: Compression gain ratio applied when the signal is above the threshold.
threshold_dbfloat: Threshold in decibels above which compression occurs.
attack_tfloat: Attack time of the compressor in seconds.
release_tfloat: Release time of the compressor in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Stages$$$CompressorRMS$$$CompressorRMS Control£££doc/03_dsp_components/stages/gen/compressor.html#compressorrms-control

The following runtime command ids are available for the CompressorRMS Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_COMPRESSOR_RMS_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_COMPRESSOR_RMS_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_COMPRESSOR_RMS_ENVELOPE	`sizeof(int32_t)`
The current RMS² envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db_pow(envelope, Q_SIG)` in `control/helpers.h`. This command is read only. When sending a write control command, it will be ignored.

CMD_COMPRESSOR_RMS_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which compression will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_rms_threshold(x)` in `control/helpers.h`.

CMD_COMPRESSOR_RMS_GAIN	`sizeof(int32_t)`
The current gain applied by the compressor in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_COMPRESSOR_RMS_SLOPE	`sizeof(float)`
The compression slope of the compressor. This is calculated as `(1 - 1 / ratio) / 2.0`. To convert a ratio to a slope, use the function `rms_compressor_slope_from_ratio(ratio)` in `control/helpers.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Sidechain Stages£££doc/03_dsp_components/stages/gen/compressor_sidechain.html#compressor-sidechain-stages

Sidechain compressor Stages use the envelope of one input to control the level of a different input.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Sidechain Stages$$$CompressorSidechain£££doc/03_dsp_components/stages/gen/compressor_sidechain.html#compressorsidechain

class audio_dsp.stages.compressor_sidechain.CompressorSidechain(**kwargs)

An sidechain compressor based on the RMS envelope of the detect signal.

This stage is limited to accepting 2 channels. The first is the channel that will be compressed. The second is the detect channel. The level of compression depends on the envelope of the second channel.

When the RMS envelope of the detect signal exceeds the threshold, the processed signal amplitude is reduced by the compression ratio.

Attributes:

dsp_blockaudio_dsp.dsp.drc.sidechain.compressor_rms_sidechain_mono: The DSP block class; see Sidechain RMS Compressor for implementation details.

make_compressor_sidechain(ratio, threshold_db, attack_t, release_t, Q_sig=27)

Update compressor configuration based on new parameters.

Parameters:

ratiofloat: Compression gain ratio applied when the signal is above the threshold.
threshold_dbfloat: Threshold in decibels above which compression occurs.
attack_tfloat: Attack time of the compressor in seconds.
release_tfloat: Release time of the compressor in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Compressor Sidechain Stages$$$CompressorSidechain$$$CompressorSidechain Control£££doc/03_dsp_components/stages/gen/compressor_sidechain.html#compressorsidechain-control

The following runtime command ids are available for the CompressorSidechain Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_COMPRESSOR_SIDECHAIN_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_COMPRESSOR_SIDECHAIN_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_COMPRESSOR_SIDECHAIN_ENVELOPE	`sizeof(int32_t)`
The current RMS² envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db_pow(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_COMPRESSOR_SIDECHAIN_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which compression will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_rms_threshold(x)` in `control/helpers.h`.

CMD_COMPRESSOR_SIDECHAIN_GAIN	`sizeof(int32_t)`
The current gain applied by the compressor in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_COMPRESSOR_SIDECHAIN_SLOPE	`sizeof(float)`
The compression slope of the compressor. This is calculated as (1 - 1 / ratio) / 2.0. To convert a ratio to a slope, use the function `rms_compressor_slope_from_ratio(ratio)` in `control/helpers.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Envelope Detector Stages£££doc/03_dsp_components/stages/gen/envelope_detector.html#envelope-detector-stages

Envelope detector Stages measure how the average or peak amplitude of a signal varies over time.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Envelope Detector Stages$$$EnvelopeDetectorPeak£££doc/03_dsp_components/stages/gen/envelope_detector.html#envelopedetectorpeak

class audio_dsp.stages.envelope_detector.EnvelopeDetectorPeak(**kwargs)

A stage with no outputs that measures the signal peak envelope.

The current envelope of the signal can be read out using this stage’s envelope control.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.envelope_detector_peak: The DSP block class; see Peak Envelope Detector for implementation details.

make_env_det_peak(attack_t, release_t, Q_sig=27)

Update envelope detector configuration based on new parameters.

Parameters:

attack_tfloat: Attack time of the envelope detector in seconds.
release_tfloat: Release time of the envelope detector in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Envelope Detector Stages$$$EnvelopeDetectorPeak$$$EnvelopeDetectorPeak Control£££doc/03_dsp_components/stages/gen/envelope_detector.html#envelopedetectorpeak-control

The following runtime command ids are available for the EnvelopeDetectorPeak Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_ENVELOPE_DETECTOR_PEAK_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_ENVELOPE_DETECTOR_PEAK_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_ENVELOPE_DETECTOR_PEAK_ENVELOPE	`sizeof(int32_t)`
The current peak envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Envelope Detector Stages$$$EnvelopeDetectorRMS£££doc/03_dsp_components/stages/gen/envelope_detector.html#envelopedetectorrms

class audio_dsp.stages.envelope_detector.EnvelopeDetectorRMS(**kwargs)

A stage with no outputs that measures the signal RMS envelope.

The current envelope of the signal can be read out using this stage’s envelope control.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.envelope_detector_rms: The DSP block class; see RMS Envelope Detector for implementation details.

make_env_det_rms(attack_t, release_t, Q_sig=27)

Update envelope detector configuration based on new parameters.

Parameters:

attack_tfloat: Attack time of the envelope detector in seconds.
release_tfloat: Release time of the envelope detector in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Envelope Detector Stages$$$EnvelopeDetectorRMS$$$EnvelopeDetectorRMS Control£££doc/03_dsp_components/stages/gen/envelope_detector.html#envelopedetectorrms-control

The following runtime command ids are available for the EnvelopeDetectorRMS Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_ENVELOPE_DETECTOR_RMS_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_ENVELOPE_DETECTOR_RMS_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_ENVELOPE_DETECTOR_RMS_ENVELOPE	`sizeof(int32_t)`
The current RMS² envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db_pow(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$FIR Stages£££doc/03_dsp_components/stages/gen/fir.html#fir-stages

Finite impulse response (FIR) filter Stages allow the use of arbitrary filters with a finite number of taps.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$FIR Stages$$$FirDirect£££doc/03_dsp_components/stages/gen/fir.html#firdirect

class audio_dsp.stages.fir.FirDirect(coeffs_path, **kwargs)

A FIR filter implemented in the time domain. The input signal is convolved with the filter coefficients. The filter coefficients can only be set at compile time.

Parameters:

coeffs_pathPath: Path to a file containing the coefficients, in a format supported by np.loadtxt.

Attributes:

dsp_blockaudio_dsp.dsp.fir.fir_direct: The DSP block class; see FIR Direct for implementation details.

make_fir_direct(coeffs_path, Q_sig=27)

Update FIR configuration based on new parameters.

Parameters:

coeffs_pathPath: Path to a file containing the coefficients, in a format supported by np.loadtxt.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$FIR Stages$$$FirDirect$$$FirDirect Control£££doc/03_dsp_components/stages/gen/fir.html#firdirect-control

The FirDirect Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages£££doc/03_dsp_components/stages/gen/limiter.html#limiter-stages

Limiter Stages allow the amplitude of the signal to be restricted based on its envelope.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$LimiterRMS£££doc/03_dsp_components/stages/gen/limiter.html#limiterrms

class audio_dsp.stages.limiter.LimiterRMS(**kwargs)

A limiter based on the RMS value of the signal. When the RMS envelope of the signal exceeds the threshold, the signal amplitude is reduced.

The threshold sets the value above which limiting occurs. The attack time sets how fast the limiter starts limiting. The release time sets how long the signal takes to ramp up to its original level after the envelope is below the threshold.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.limiter_rms: The DSP block class; see RMS Limiter for implementation details.

make_limiter_rms(threshold_db, attack_t, release_t, Q_sig=27)

Update limiter configuration based on new parameters.

Parameters:

threshold_dbfloat: Threshold in decibels above which limiting occurs.
attack_tfloat: Attack time of the limiter in seconds.
release_tfloat: Release time of the limiter in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$LimiterRMS$$$LimiterRMS Control£££doc/03_dsp_components/stages/gen/limiter.html#limiterrms-control

The following runtime command ids are available for the LimiterRMS Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_LIMITER_RMS_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_LIMITER_RMS_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_LIMITER_RMS_ENVELOPE	`sizeof(int32_t)`
The current RMS² envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db_pow(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_LIMITER_RMS_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which limiting will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_rms_threshold(x)` in `control/helpers.h`.

CMD_LIMITER_RMS_GAIN	`sizeof(int32_t)`
The current gain applied by the limiter in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$LimiterPeak£££doc/03_dsp_components/stages/gen/limiter.html#limiterpeak

class audio_dsp.stages.limiter.LimiterPeak(**kwargs)

A limiter based on the peak value of the signal. When the peak envelope of the signal exceeds the threshold, the signal amplitude is reduced.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.limiter_peak: The DSP block class; see Peak Limiter for implementation details.

make_limiter_peak(threshold_db, attack_t, release_t, Q_sig=27)

Update limiter configuration based on new parameters.

Parameters:

threshold_dbfloat: Threshold in decibels above which limiting occurs.
attack_tfloat: Attack time of the limiter in seconds.
release_tfloat: Release time of the limiter in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$LimiterPeak$$$LimiterPeak Control£££doc/03_dsp_components/stages/gen/limiter.html#limiterpeak-control

The following runtime command ids are available for the LimiterPeak Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_LIMITER_PEAK_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_LIMITER_PEAK_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_LIMITER_PEAK_ENVELOPE	`sizeof(int32_t)`
The current peak envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_LIMITER_PEAK_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which limiting will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_peak_threshold(x)` in `control/helpers.h`.

CMD_LIMITER_PEAK_GAIN	`sizeof(int32_t)`
The current gain applied by the limiter in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$HardLimiterPeak£££doc/03_dsp_components/stages/gen/limiter.html#hardlimiterpeak

class audio_dsp.stages.limiter.HardLimiterPeak(**kwargs)

A limiter based on the peak value of the signal. The peak envelope of the signal may never exceed the threshold.

When the peak envelope of the signal exceeds the threshold, the signal amplitude is reduced. If the signal still exceeds the threshold, it is clipped.

The threshold sets the value above which limiting/clipping occurs. The attack time sets how fast the limiter starts limiting. The release time sets how long the signal takes to ramp up to its original level after the envelope is below the threshold.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.hard_limiter_peak: The DSP block class; see Hard Peak Limiter for implementation details.

make_hard_limiter_peak(threshold_db, attack_t, release_t, Q_sig=27)

Update limiter configuration based on new parameters.

Parameters:

threshold_dbfloat: Threshold in decibels above which limiting occurs.
attack_tfloat: Attack time of the limiter in seconds.
release_tfloat: Release time of the limiter in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$HardLimiterPeak$$$HardLimiterPeak Control£££doc/03_dsp_components/stages/gen/limiter.html#hardlimiterpeak-control

The following runtime command ids are available for the HardLimiterPeak Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_HARD_LIMITER_PEAK_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_HARD_LIMITER_PEAK_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_HARD_LIMITER_PEAK_ENVELOPE	`sizeof(int32_t)`
The current peak envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_HARD_LIMITER_PEAK_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which limiting will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_peak_threshold(x)` in `control/helpers.h`.

CMD_HARD_LIMITER_PEAK_GAIN	`sizeof(int32_t)`
The current gain applied by the limiter in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$Clipper£££doc/03_dsp_components/stages/gen/limiter.html#clipper

class audio_dsp.stages.limiter.Clipper(**kwargs)

A simple clipper that limits the signal to a specified threshold.

If the signal is greater than the threshold level, it is set to the threshold value.

Attributes:

dsp_blockaudio_dsp.dsp.drc.drc.clipper: The DSP block class; see Clipper for implementation details.

make_clipper(threshold_db, Q_sig=27)

Update clipper configuration based on new parameters.

Parameters:

threshold_dbfloat: Threshold in decibels above which clipping occurs.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Limiter Stages$$$Clipper$$$Clipper Control£££doc/03_dsp_components/stages/gen/limiter.html#clipper-control

The following runtime command ids are available for the Clipper Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_CLIPPER_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format above which clipping will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_peak_threshold(x)` in `control/helpers.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Gate Stages£££doc/03_dsp_components/stages/gen/noise_gate.html#noise-gate-stages

Noise gate Stages remove quiet signals from the audio output.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Gate Stages$$$NoiseGate£££doc/03_dsp_components/stages/gen/noise_gate.html#noisegate

class audio_dsp.stages.noise_gate.NoiseGate(**kwargs)

A noise gate that reduces the level of an audio signal when it falls below a threshold.

When the signal envelope falls below the threshold, the gain applied to the signal is reduced to 0 over the release time. When the envelope returns above the threshold, the gain applied to the signal is increased to 1 over the attack time.

The initial state of the noise gate is with the gate open (no attenuation); this models a full scale signal having been present before t = 0.

Attributes:

dsp_blockaudio_dsp.dsp.drc.expander.noise_gate: The DSP block class; see Noise Gate for implementation details.

make_noise_gate(threshold_db, attack_t, release_t, Q_sig=27)

Update noise gate configuration based on new parameters.

Parameters:

threshold_dbfloat: The threshold level in decibels below which the audio signal is attenuated.
attack_tfloat: Attack time of the noise gate in seconds.
release_tfloat: Release time of the noise gate in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Gate Stages$$$NoiseGate$$$NoiseGate Control£££doc/03_dsp_components/stages/gen/noise_gate.html#noisegate-control

The following runtime command ids are available for the NoiseGate Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_NOISE_GATE_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_NOISE_GATE_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_NOISE_GATE_ENVELOPE	`sizeof(int32_t)`
The current peak envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_NOISE_GATE_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format below which gating will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_peak_threshold(x)` in `control/helpers.h`.

CMD_NOISE_GATE_GAIN	`sizeof(int32_t)`
The current gain applied by the noise gate in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Suppressor Expander Stages£££doc/03_dsp_components/stages/gen/noise_suppressor_expander.html#noise-suppressor-expander-stages

Noise suppressor and expander Stages control the behaviour of quiet signals, typically by tring to reduce the audibility of noise in the signal.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Suppressor Expander Stages$$$NoiseSuppressorExpander£££doc/03_dsp_components/stages/gen/noise_suppressor_expander.html#noisesuppressorexpander

class audio_dsp.stages.noise_suppressor_expander.NoiseSuppressorExpander(**kwargs)

The Noise Suppressor (Expander) stage. A noise suppressor that reduces the level of an audio signal when it falls below a threshold. This is also known as an expander.

When the signal envelope falls below the threshold, the gain applied to the signal is reduced relative to the expansion ratio over the release time. When the envelope returns above the threshold, the gain applied to the signal is increased to 1 over the attack time.

The initial state of the noise suppressor is with the suppression off; this models a full scale signal having been present before t = 0.

Attributes:

dsp_blockaudio_dsp.dsp.drc.expander.noise_suppressor_expander: The DSP block class; see Noise Suppressor/Expander for implementation details.

make_noise_suppressor_expander(ratio, threshold_db, attack_t, release_t, Q_sig=27)

Update noise suppressor (expander) configuration based on new parameters.

All parameters are passed to the constructor of audio_dsp.dsp.drc.noise_suppressor_expander.

Parameters:

ratiofloat: The expansion ratio applied to the signal when the envelope falls below the threshold.
threshold_dbfloat: The threshold level in decibels below which the audio signal is attenuated.
attack_tfloat: Attack time of the noise suppressor in seconds.
release_tfloat: Release time of the noise suppressor in seconds.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Noise Suppressor Expander Stages$$$NoiseSuppressorExpander$$$NoiseSuppressorExpander Control£££doc/03_dsp_components/stages/gen/noise_suppressor_expander.html#noisesuppressorexpander-control

The following runtime command ids are available for the NoiseSuppressorExpander Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_NOISE_SUPPRESSOR_EXPANDER_ATTACK_ALPHA	`sizeof(int32_t)`
The attack alpha in Q0.31 format. To convert an attack time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, attack_time)` in `control/helpers.h`.

CMD_NOISE_SUPPRESSOR_EXPANDER_RELEASE_ALPHA	`sizeof(int32_t)`
The release alpha in Q0.31 format. To convert a release time in seconds to an `int32_t` control value, use the function `calc_alpha(fs, release_time)` in `control/helpers.h`.

CMD_NOISE_SUPPRESSOR_EXPANDER_ENVELOPE	`sizeof(int32_t)`
The current peak envelope of the signal in Q_SIG format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, Q_SIG)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_NOISE_SUPPRESSOR_EXPANDER_THRESHOLD	`sizeof(int32_t)`
The threshold in Q_SIG format below which suppression will occur. To convert a threshold in dB to the `int32_t` control value, use the function `calculate_peak_threshold(x)` in `control/helpers.h`.

CMD_NOISE_SUPPRESSOR_EXPANDER_GAIN	`sizeof(int32_t)`
The current gain applied by the noise suppressor in Q0.31 format. To read the `int32_t` control value, use the function `qxx_to_db(envelope, 31)` in `control/helpers.h` This command is read only. When sending a write control command, it will be ignored.

CMD_NOISE_SUPPRESSOR_EXPANDER_SLOPE	`sizeof(float)`
The expansion slope of the noise suppressor. This is calculated as (1 - ratio).To convert a ratio to a slope, use the function `peak_expander_slope_from_ratio(ratio)` in `control/helpers.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages£££doc/03_dsp_components/stages/gen/reverb.html#reverb-stages

Reverb Stages emulate the natural reverberance of rooms.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbBase£££doc/03_dsp_components/stages/gen/reverb.html#reverbbase

class audio_dsp.stages.reverb.ReverbBase(inputs: StageOutputList, config: Optional[Union[Path, str]] = None, name: Optional[str] = None, label: Optional[str] = None)

The base class for reverb stages, containing pre delays, and wet/dry mixes and pregain.

set_dry_gain(gain_dB)

Set the dry gain of the reverb room stage. This sets the level of the unprocessed signal.

Parameters:

gain_dbfloat: Dry gain in dB, less than 0 dB.

set_pre_gain(pre_gain)

Set the pre gain of the reverb room stage.

Parameters:

pre_gainfloat: Pre gain value. Must be less than 1.

set_predelay(predelay)

Set the predelay of the wet channel.

Parameters:

predelayfloat: Predelay in ms, less than max_predelay.

set_wet_dry_mix(mix)

Set the wet/dry gains so that the mix of 0 results in a fully dry output, the mix of 1 results in a fully wet output.

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

set_wet_gain(gain_dB)

Set the wet gain of the reverb room stage. This sets the level of the reverberated signal.

Parameters:

gain_dbfloat: Wet gain in dB, less than 0 dB.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbBase$$$ReverbBase Control£££doc/03_dsp_components/stages/gen/reverb.html#reverbbase-control

The ReverbBase Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbRoom£££doc/03_dsp_components/stages/gen/reverb.html#reverbroom

class audio_dsp.stages.reverb.ReverbRoom(max_room_size=1, predelay=10, max_predelay=None, **kwargs)

The room reverb stage. This is based on Freeverb by Jezar at Dreampoint, and consists of 8 parallel comb filters fed into 4 series all-pass filters.

Parameters:

max_room_size: Sets the maximum room size for this reverb. The room_size parameter sets the fraction of this value actually used at any given time. For optimal memory usage, max_room_size should be set so that the longest reverb tail occurs when room_size=1.0.
predelayfloat, optional: The delay applied to the wet channel in ms.
max_predelayfloat, optional: The maximum predelay in ms.

Attributes:

dsp_blockaudio_dsp.dsp.reverb.reverb_room: The DSP block class; see Reverb Room for implementation details.

set_damping(damping)

Set the damping of the reverb room stage. This controls how much high frequency attenuation is in the room. Higher values yield shorter reverberation times at high frequencies.

Parameters:

dampingfloat: How much high frequency attenuation in the room, between 0 and 1.

set_decay(decay)

Set the decay of the reverb room stage. This sets how reverberant the room is. Higher values will give a longer reverberation time for a given room size.

Parameters:

decayfloat: How long the reverberation of the room is, between 0 and 1.

set_dry_gain(gain_dB)

Set the dry gain of the reverb room stage. This sets the level of the unprocessed signal.

Parameters:

gain_dbfloat: Dry gain in dB, less than 0 dB.

set_pre_gain(pre_gain)

Set the pre gain of the reverb room stage.

Parameters:

pre_gainfloat: Pre gain value. Must be less than 1.

set_predelay(predelay)

Set the predelay of the wet channel.

Parameters:

predelayfloat: Predelay in ms, less than max_predelay.

set_room_size(new_room_size)

Set the room size, will adjust the delay line lengths.

The room size is proportional to max_room_size, and must be between 0 and 1. To increase the room_size above 1.0, max_room_size must instead be increased. Optimal memory usage occurs when room_size is set to 1.0.

Parameters:

new_room_sizefloat: How big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.

set_wet_dry_mix(mix)

Set the wet/dry gains so that the mix of 0 results in a fully dry output, the mix of 1 results in a fully wet output.

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

set_wet_gain(gain_dB)

Set the wet gain of the reverb room stage. This sets the level of the reverberated signal.

Parameters:

gain_dbfloat: Wet gain in dB, less than 0 dB.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbRoom$$$ReverbRoom Control£££doc/03_dsp_components/stages/gen/reverb.html#reverbroom-control

The following runtime command ids are available for the ReverbRoom Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_REVERB_ROOM_ROOM_SIZE	`sizeof(float)`
How big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.

CMD_REVERB_ROOM_FEEDBACK	`sizeof(int32_t)`
feedback gain in Q0.31 format. Feedback can be calculated from decay as (0.28 decay) + 0.7. Use the function `adsp_reverb_calculate_feedback` in `control/reverb.h`.

CMD_REVERB_ROOM_DAMPING	`sizeof(int32_t)`
High frequency attenuation in Q0.31 format. Use the function `adsp_reverb_calculate_damping` in `control/reverb.h`.

CMD_REVERB_ROOM_WET_GAIN	`sizeof(int32_t)`
Gain applied to the wet signal in Q0.31 format. Use the function `adsp_reverb_db2int` in `control/reverb.h`. Alternatively, both wet and dry gains can be obtained from `adsp_reverb_wet_dry_mix`.

CMD_REVERB_ROOM_DRY_GAIN	`sizeof(int32_t)`
Dry signal gain in Q0.31 format. Use the function `adsp_reverb_db2int` in `control/reverb.h`. Alternatively, both wet and dry gains can be obtained from `adsp_reverb_wet_dry_mix`.

CMD_REVERB_ROOM_PREGAIN	`sizeof(int32_t)`
The pregain applied to the signal before the reverb. Changing this value is not recommended. Use the function `adsp_reverb_float2int` in `control/reverb.h`.

CMD_REVERB_ROOM_PREDELAY	`sizeof(uint32_t)`
Predelay applied to the wet channel in samples. To convert a value in other units of time to samples, use `time_to_samples` in `control/signal_chain.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbRoomStereo£££doc/03_dsp_components/stages/gen/reverb.html#reverbroomstereo

class audio_dsp.stages.reverb.ReverbRoomStereo(max_room_size=1, predelay=10, max_predelay=None, **kwargs)

The stereo room reverb stage. This is based on Freeverb by Jezar at Dreampoint. Each channel consists of 8 parallel comb filters fed into 4 series all-pass filters, and the reverberator outputs are mixed according to the width parameter.

Parameters:

max_room_size: Sets the maximum room size for this reverb. The room_size parameter sets the fraction of this value actually used at any given time. For optimal memory usage, max_room_size should be set so that the longest reverb tail occurs when room_size=1.0.
predelayfloat, optional: The delay applied to the wet channel in ms.
max_predelayfloat, optional: The maximum predelay in ms.

Attributes:

dsp_blockaudio_dsp.dsp.reverb_stereo.reverb_room_stereo: The DSP block class; see Reverb Room Stereo for implementation details.

set_damping(damping)

Set the damping of the reverb room stage. This controls how much high frequency attenuation is in the room. Higher values yield shorter reverberation times at high frequencies.

Parameters:

dampingfloat: How much high frequency attenuation in the room, between 0 and 1.

set_decay(decay)

Set the decay of the reverb room stage. This sets how reverberant the room is. Higher values will give a longer reverberation time for a given room size.

Parameters:

decayfloat: How long the reverberation of the room is, between 0 and 1.

set_dry_gain(gain_dB)

Set the dry gain of the reverb room stage. This sets the level of the unprocessed signal.

Parameters:

gain_dbfloat: Dry gain in dB, less than 0 dB.

set_pre_gain(pre_gain)

Set the pre gain of the reverb room stage.

Parameters:

pre_gainfloat: Pre gain value. Must be less than 1.

set_predelay(predelay)

Set the predelay of the wet channel.

Parameters:

predelayfloat: Predelay in ms, less than max_predelay.

set_room_size(new_room_size)

Set the room size, will adjust the delay line lengths.

Parameters:

new_room_sizefloat: How big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.

set_wet_dry_mix(mix)

Set the wet/dry gains so that the mix of 0 results in a fully dry output, the mix of 1 results in a fully wet output.

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

set_wet_gain(gain_dB)

Set the wet gain of the reverb room stage. This sets the level of the reverberated signal.

Parameters:

gain_dbfloat: Wet gain in dB, less than 0 dB.

set_width(width)

Set the decay of the reverb room stage. This sets how reverberant the room is. Higher values will give a longer reverberation time for a given room size.

Parameters:

widthfloat: How much stereo separation between the channels. A width of 0 indicates no stereo separation (i.e. mono). A width of 1 indicates maximum stereo separation.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbRoomStereo$$$ReverbRoomStereo Control£££doc/03_dsp_components/stages/gen/reverb.html#reverbroomstereo-control

The following runtime command ids are available for the ReverbRoomStereo Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_REVERB_ROOM_STEREO_ROOM_SIZE	`sizeof(float)`
How big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.

CMD_REVERB_ROOM_STEREO_FEEDBACK	`sizeof(int32_t)`
feedback gain in Q0.31 format. Feedback can be calculated from decay as (0.28 decay) + 0.7. Use the function `adsp_reverb_calculate_feedback` in `control/reverb.h`.

CMD_REVERB_ROOM_STEREO_DAMPING	`sizeof(int32_t)`
High frequency attenuation in Q0.31 format. Use the function `adsp_reverb_calculate_damping` in `control/reverb.h`.

CMD_REVERB_ROOM_STEREO_WET_GAIN1	`sizeof(int32_t)`
Gain applied to obtain the wet signal in Q0.31 format. Use function `adsp_reverb_room_st_calc_wet_gains` in `control/reverb.h`. Alternatively, all gains can be obtained from `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_ROOM_STEREO_WET_GAIN2	`sizeof(int32_t)`
Gain applied to obtain the wet signal in Q0.31 format. Use function `adsp_reverb_room_st_calc_wet_gains` in `control/reverb.h`. Alternatively, all gains can be obtained from `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_ROOM_STEREO_DRY_GAIN	`sizeof(int32_t)`
Dry signal gain in Q0.31 format. Use the function `adsp_reverb_db2int` in `control/reverb.h`. Alternatively, all gains can be obtained from `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_ROOM_STEREO_PREGAIN	`sizeof(int32_t)`
The pregain applied to the signal before the reverb. Changing this value is not recommended. Use the function `adsp_reverb_float2int` in `control/reverb.h`.

CMD_REVERB_ROOM_STEREO_PREDELAY	`sizeof(uint32_t)`
Predelay applied to the wet channel in samples. To convert a value in other units of time to samples, use `time_to_samples` in `control/signal_chain.h`.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbPlateStereo£££doc/03_dsp_components/stages/gen/reverb.html#reverbplatestereo

class audio_dsp.stages.reverb.ReverbPlateStereo(predelay=10, max_predelay=None, **kwargs)

The stereo room plate stage. This is based on Dattorro’s 1997 paper. This reverb consists of 4 allpass filters for input diffusion, followed by a figure of 8 reverb tank of allpasses, low-pass filters, and delays. The output is taken from multiple taps in the delay lines to get a desirable echo density.

Parameters:

predelayfloat, optional: The delay applied to the wet channel in ms.
max_predelayfloat, optional: The maximum predelay in ms.

Attributes:

dsp_blockaudio_dsp.dsp.reverb.reverb_plate_stereo: The DSP block class; see Reverb Plate Stereo for implementation details.

set_bandwidth(bandwidth)

Set the bandwidth of the plate reverb stage. This sets the low pass cutoff frequency of the reverb input. Higher values will give a higher cutoff frequency.

Parameters:

bandwidthfloat: The bandwidth of the plate input signal, between 0 and 1.

set_damping(damping)

Set the damping of the plate reverb stage. This controls how much high frequency attenuation is in the plate. Higher values yield shorter reverberation times at high frequencies.

Parameters:

dampingfloat: How much high frequency attenuation in the plate, between 0 and 1.

set_decay(decay)

Set the decay of the plate reverb stage. This sets how reverberant the plate is. Higher values will give a longer reverberation time.

Parameters:

decayfloat: How long the reverberation of the plate is, between 0 and 1.

set_dry_gain(gain_dB)

Set the dry gain of the reverb room stage. This sets the level of the unprocessed signal.

Parameters:

gain_dbfloat: Dry gain in dB, less than 0 dB.

set_early_diffusion(diffusion)

Set the early diffusion of the plate reverb stage. This sets how much diffusion is present in the first part of the reverberation. Higher values will give more diffusion.

Parameters:

diffusionfloat: How diffuse the plate is, between 0 and 1.

set_late_diffusion(diffusion)

Set the late diffusion of the plate reverb stage. This sets how much diffusion is present in the latter part of the reverberation. Higher values will give more diffusion.

Parameters:

diffusionfloat: How diffuse the plate is, between 0 and 1.

set_pre_gain(pre_gain)

Set the pre gain of the reverb room stage.

Parameters:

pre_gainfloat: Pre gain value. Must be less than 1.

set_predelay(predelay)

Set the predelay of the wet channel.

Parameters:

predelayfloat: Predelay in ms, less than max_predelay.

set_wet_dry_mix(mix)

Set the wet/dry gains so that the mix of 0 results in a fully dry output, the mix of 1 results in a fully wet output.

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

set_wet_gain(gain_dB)

Set the wet gain of the reverb room stage. This sets the level of the reverberated signal.

Parameters:

gain_dbfloat: Wet gain in dB, less than 0 dB.

set_width(width)

Set the decay of the reverb room stage. This sets how reverberant the room is. Higher values will give a longer reverberation time for a given room size.

Parameters:

widthfloat: How much stereo separation between the channels. A width of 0 indicates no stereo separation (i.e. mono). A width of 1 indicates maximum stereo separation.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Reverb Stages$$$ReverbPlateStereo$$$ReverbPlateStereo Control£££doc/03_dsp_components/stages/gen/reverb.html#reverbplatestereo-control

The following runtime command ids are available for the ReverbPlateStereo Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_REVERB_PLATE_STEREO_DECAY	`sizeof(int32_t)`
The amount of decay in the plate in Q0.31 format. To convert a decay value between 0 and 1 to an `int32_t` control value, use the function adsp_reverb_float2int` in `control/reverb.h`.

CMD_REVERB_PLATE_STEREO_DAMPING	`sizeof(int32_t)`
The amount of high frequency attenuation in Q0.31 format. To convert a damping value between 0 and 1 to an `int32_t` control value, use the function `adsp_reverb_plate_calculate_damping` in `control/reverb.h`.

CMD_REVERB_PLATE_STEREO_EARLY_DIFFUSION	`sizeof(int32_t)`
The amount of diffusion in the early part of the reverb. To convert a diffusion value between 0 and 1 to an `int32_t` control value, use the function adsp_reverb_float2int` in `control/reverb.h`.

CMD_REVERB_PLATE_STEREO_LATE_DIFFUSION	`sizeof(int32_t)`
The amount of diffusion in the late part of the reverb. To convert a diffusion value between 0 and 1 to an `int32_t` control value, use the function adsp_reverb_plate_calc_late_diffusion` in `control/reverb.h`.

CMD_REVERB_PLATE_STEREO_BANDWIDTH	`sizeof(int32_t)`
The input low pass coefficient in Q0.31 format. A bandwidth in Hertz can be converted to an `int32_t` control value using the function xxxxx. Alternatively, a bandwidth between 0 and 1 can be converted using the function adsp_reverb_plate_calc_bandwidth`.

CMD_REVERB_PLATE_STEREO_WET_GAIN1	`sizeof(int32_t)`
Gain applied to the wet signal in Q0.31 format. To calculate the wet gains based on a level in dB and a stereo width, use the function `adsp_reverb_room_st_calc_wet_gains` in `control/reverb.h`. Alternatively, wet and dry gains can be calculated using a wet/dry ratio with the function `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_PLATE_STEREO_WET_GAIN2	`sizeof(int32_t)`
Gain applied to the wet signal in Q0.31 format. To calculate the wet gains based on a level in dB and a stereo width, use the function `adsp_reverb_room_st_calc_wet_gains` in `control/reverb.h`. Alternatively, wet and dry gains can be calculated using a wet/dry ratio with the function `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_PLATE_STEREO_DRY_GAIN	`sizeof(int32_t)`
Gain applied to the dry signal in Q0.31 format. To calculate the dry gain based on a level in dB, use the function `adsp_reverb_db2int` in `control/reverb.h`. Alternatively, wet and dry gains can be calculated using a wet/dry ratio with the function `adsp_reverb_st_wet_dry_mix`.

CMD_REVERB_PLATE_STEREO_PREGAIN	`sizeof(int32_t)`
The pregain applied to the signal before the reverb. Changing this value is only required if saturation occurs in the reverb tank. To convert a linear gain value to an `int32_t` control value, use the function `adsp_reverb_float2int` in `control/reverb.h`.

CMD_REVERB_PLATE_STEREO_PREDELAY	`sizeof(uint32_t)`
The wet channel predelay value in samples. To convert a value in other units of time to samples, use `time_to_samples` in `control/signal_chain.h`. Note the minimum delay provided by this stage is 1 sample. Setting the delay to 0 will still yield a 1 sample delay.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages£££doc/03_dsp_components/stages/gen/signal_chain.html#signal-chain-stages

Signal chain stages allow for the control of signal flow through the pipeline. This includes stages for combining and splitting signals, basic gain components, and delays.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Bypass£££doc/03_dsp_components/stages/gen/signal_chain.html#bypass

class audio_dsp.stages.signal_chain.Bypass(**kwargs)

Stage which does not modify its inputs. Useful if data needs to flow through a thread which is not being processed on to keep pipeline lengths aligned.

process(in_channels): Return a copy of the inputs.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Bypass$$$Bypass Control£££doc/03_dsp_components/stages/gen/signal_chain.html#bypass-control

The Bypass Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Fork£££doc/03_dsp_components/stages/gen/signal_chain.html#fork

class audio_dsp.stages.signal_chain.Fork(count=2, **kwargs)

Fork the signal.

Use if the same data needs to be sent to multiple data paths:

a = t.stage(Example, ...)
f = t.stage(Fork, a, count=2)  # count optional, default is 2
b = t.stage(Example, f.forks[0])
c = t.stage(Example, f.forks[1])

Attributes:

forkslist[list[StageOutput]]: For convenience, each forked output will be available in this list each entry contains a set of outputs which will contain the same data as the input.

class ForkOutputList(edges: Optional[list[audio_dsp.design.stage.StageOutput | None]] = None)

Custom StageOutputList that is created by Fork.

This allows convenient access to each fork output.

Attributes:

forks: list[StageOutputList]: Fork duplicates its inputs, each entry in the forks list is a single copy of the input edges.

get_frequency_response(nfft=512): Fork has no sensible frequency response, not implemented.

process(in_channels): Duplicate the inputs to the outputs based on this fork’s configuration.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Fork$$$Fork Control£££doc/03_dsp_components/stages/gen/signal_chain.html#fork-control

The Fork Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Mixer£££doc/03_dsp_components/stages/gen/signal_chain.html#mixer

class audio_dsp.stages.signal_chain.Mixer(**kwargs)

Mixes the input signals together. The mixer can be used to add signals together, or to attenuate the input signals.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.mixer: The DSP block class; see Mixer for implementation details

set_gain(gain_db)

Set the gain of the mixer in dB.

Parameters:

gain_dbfloat: The gain of the mixer in dB.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Mixer$$$Mixer Control£££doc/03_dsp_components/stages/gen/signal_chain.html#mixer-control

The following runtime command ids are available for the Mixer Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_MIXER_GAIN	`sizeof(int32_t)`
The current gain in Q_GAIN format. To convert a value in decibels to this format, the function `adsp_dB_to_gain` in `control/signal_chain.h` can be used.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Adder£££doc/03_dsp_components/stages/gen/signal_chain.html#adder

class audio_dsp.stages.signal_chain.Adder(**kwargs)

Add the input signals together. The adder can be used to add signals together.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.adder: The DSP block class; see Adder for implementation details.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Adder$$$Adder Control£££doc/03_dsp_components/stages/gen/signal_chain.html#adder-control

The Adder Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Subtractor£££doc/03_dsp_components/stages/gen/signal_chain.html#subtractor

class audio_dsp.stages.signal_chain.Subtractor(**kwargs)

Subtract the second input from the first. The subtractor can be used to subtract signals from each other. It must only have 2 inputs.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.subtractor: The DSP block class; see Subtractor for implementation details.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Subtractor$$$Subtractor Control£££doc/03_dsp_components/stages/gen/signal_chain.html#subtractor-control

The Subtractor Stage has no runtime controllable parameters.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$FixedGain£££doc/03_dsp_components/stages/gen/signal_chain.html#fixedgain

class audio_dsp.stages.signal_chain.FixedGain(gain_db=0, **kwargs)

This stage implements a fixed gain. The input signal is multiplied by a gain. If the gain is changed at runtime, pops and clicks may occur.

If the gain needs to be changed at runtime, use a VolumeControl stage instead.

Parameters:

gain_dbfloat, optional: The gain of the mixer in dB.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.fixed_gain: The DSP block class; see Fixed Gain for implementation details.

set_gain(gain_db)

Set the gain of the fixed gain in dB.

Parameters:

gain_dbfloat: The gain of the fixed gain in dB.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$FixedGain$$$FixedGain Control£££doc/03_dsp_components/stages/gen/signal_chain.html#fixedgain-control

The following runtime command ids are available for the FixedGain Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_FIXED_GAIN_GAIN	`sizeof(int32_t)`
The gain value in Q_GAIN format. To convert a value in decibels to this format, the function `adsp_dB_to_gain` in `control/signal_chain.h` can be used.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$VolumeControl£££doc/03_dsp_components/stages/gen/signal_chain.html#volumecontrol

class audio_dsp.stages.signal_chain.VolumeControl(gain_dB=0, mute_state=0, **kwargs)

This stage implements a volume control. The input signal is multiplied by a gain. The gain can be changed at runtime. To avoid pops and clicks during gain changes, a slew is applied to the gain update. The stage can be muted and unmuted at runtime.

Parameters:

gain_dbfloat, optional: The gain of the mixer in dB.
mute_stateint, optional: The mute state of the Volume Control: 0: unmuted, 1: muted.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.volume_control: The DSP block class; see Volume Control for implementation details.

make_volume_control(gain_dB, slew_shift, mute_state, Q_sig=27)

Update the settings of this volume control.

Parameters:

gain_dB: Target gain of this volume control.
slew_shift: The shift value used in the exponential slew.
mute_state: The mute state of the Volume Control: 0: unmuted, 1: muted.

set_gain(gain_dB)

Set the gain of the volume control in dB.

Parameters:

gain_dbfloat: The gain of the volume control in dB.

set_mute_state(mute_state)

Set the mute state of the volume control.

Parameters:

mute_statebool: The mute state of the volume control.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$VolumeControl$$$VolumeControl Control£££doc/03_dsp_components/stages/gen/signal_chain.html#volumecontrol-control

The following runtime command ids are available for the VolumeControl Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_VOLUME_CONTROL_TARGET_GAIN	`sizeof(int32_t)`
The target gain of the volume control in Q_GAIN format. To convert a value in decibels to this format, the function `adsp_dB_to_gain` in `control/signal_chain.h` can be used.

CMD_VOLUME_CONTROL_GAIN	`sizeof(int32_t)`
The current applied gain of the volume control in Q_GAIN format. The volume control will slew the applied gain towards the target gain. This command is read only. When sending a write control command, it will be ignored.

CMD_VOLUME_CONTROL_SLEW_SHIFT	`sizeof(int32_t)`
The shift value used to set the slew rate. See the volume control documentation for conversions between slew_shift and time constant.

CMD_VOLUME_CONTROL_MUTE_STATE	`sizeof(uint8_t)`
Sets the mute state. 1 is muted and 0 is unmuted.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Switch£££doc/03_dsp_components/stages/gen/signal_chain.html#switch

class audio_dsp.stages.signal_chain.Switch(index=0, **kwargs)

Switch the input to one of the outputs. The switch can be used to select between different signals.

move_switch(position)

Move the switch to the specified position.

Parameters:

positionint: The position to which to move the switch. This changes the output signal to the input[position]

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Switch$$$Switch Control£££doc/03_dsp_components/stages/gen/signal_chain.html#switch-control

The following runtime command ids are available for the Switch Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_SWITCH_POSITION	`sizeof(int32_t)`
The current switch position.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Delay£££doc/03_dsp_components/stages/gen/signal_chain.html#delay

class audio_dsp.stages.signal_chain.Delay(max_delay, starting_delay, units='samples', **kwargs)

Delay the input signal by a specified amount.

The maximum delay is set at compile time, and the runtime delay can be set between 0 and max_delay.

Parameters:

max_delayfloat: The maximum delay in specified units. This can only be set at compile time.
starting_delayfloat: The starting delay in specified units.
unitsstr, optional: The units of the delay, can be ‘samples’, ‘ms’ or ‘s’. Default is ‘samples’.

Attributes:

dsp_blockaudio_dsp.dsp.signal_chain.delay: The DSP block class; see Delay for implementation details.

set_delay(delay, units='samples')

Set the length of the delay line, will saturate at max_delay.

Parameters:

delayfloat: The delay in specified units.
unitsstr: The units of the delay, can be ‘samples’, ‘ms’ or ‘s’. Default is ‘samples’.

Lib Audio DSP$$$DSP Components$$$DSP Stages$$$Signal Chain Stages$$$Delay$$$Delay Control£££doc/03_dsp_components/stages/gen/signal_chain.html#delay-control

The following runtime command ids are available for the Delay Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_DELAY_MAX_DELAY	`sizeof(uint32_t)`
The maximum delay value in samples. This is only configurable at compile time. This command is read only. When sending a write control command, it will be ignored.

CMD_DELAY_DELAY	`sizeof(uint32_t)`
The current delay value in samples. To convert a value in other units of time to samples, use `time_to_samples` in `control/signal_chain.h`. Note the minimum delay provided by this stage is 1 sample. Setting the delay to 0 will still yield a 1 sample delay.

Lib Audio DSP$$$DSP Components$$$DSP Modules£££doc/03_dsp_components/modules/index.html#dsp-modules

In lib_audio_dsp, DSP modules are the lower level functions and APIs. These can be used directly without the pipeline building tool. The documentation also includes more implementation details about the DSP algorithms. It includes topics such as Q formats, C and Python APIs, providing more detailed view of the DSP modules.

Each DSP module has been implemented in floating point Python, fixed point int32 Python and fixed point int32 C, with optimisations for xcore. The Python and C fixed point implementations aim to be bit exact with each other, allowing for Python prototyping of DSP pipelines.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Library Q Format£££doc/03_dsp_components/modules/q_format.html#library-q-format

Note

For fixed point Q formats this document uses the format QM.N, where M is the number of bits before the decimal point (excluding the sign bit), and N is the number of bits after the decimal point. For an int32 number, M+N=31.

Most modules in this library assume that the signal is in a specific global Q format. This format is defined by the Q_SIG macro. An additional macro for the signal exponent, SIG_EXP is defined, where SIG_EXP = - Q_SIG.

Q_SIG: Default Q format

SIG_EXP: Default signal exponent

To ensure optimal headroom and noise floor, the user should ensure that signals are in the correct Q format before processing. Either the input Q format can be converted to Q_SIG, or Q_SIG can be changed to the desired value.

Note

Not using the DSP pipeline tool means that Q formats will not automatically be managed, and the user should take care to ensure they have the correct values for optimum performance and signal level.

For example, for more precision, the pipeline can be configured to run with no headroom in Q0.31 format, but this would require manual headroom management (e.g. reducing the signal level before a boost to avoid clipping).

To convert between Q_SIG and Q0.31 in a safe and optimised way, the APIs below are provided.

int32_t adsp_from_q31(int32_t input)

Convert from Q0.31 to Q_SIG.

Parameters:

input – Input in Q0.31 format

Returns:

int32_t Output in Q_SIG format

int32_t adsp_to_q31(int32_t input)

Convert from Q_SIG to Q0.31.

Parameters:

input – Input in Q_SIG format

Returns:

int32_t Output in Q0.31 format

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Biquad Filters£££doc/03_dsp_components/modules/biquads.html#biquad-filters

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Biquad Filters$$$Single Biquad£££doc/03_dsp_components/modules/biquads.html#single-biquad

A second order biquadratic filter, which can be used to implement many common second order filters. The filter had been implemented in the direct form 1, and uses the xcore.ai vector unit to calculate the 5 filter taps in a single instruction.

Coefficients are stored in Q1.30 format to benefit from the vector unit, allowing for a filter coefficient range of [-2, 1.999]. For some high gain biquads (e.g. high shelf filters), the numerator coefficients may exceed this range. If this is the case, the numerator coefficients only should be right-shifted until they fit within the range (the denominator coefficients cannot become larger than 2.0 without the poles exceeding the unit circle). The shift should be passed into the API, and the output signal from the biquad will then have a left-shift applied. This is equivalent to reducing the overall signal level in the biquad, then returning to unity gain afterwards.

The state should be initialised to 0. The state and coeffs must be word-aligned.

C API

int32_t adsp_biquad(int32_t new_sample, q2_30 coeffs[5], int32_t state[8], left_shift_t lsh)

Biquad filter. This function implements a biquad filter. The filter is implemented as a direct form 1.

Parameters:

new_sample – New sample to be filtered
coeffs – Filter coefficients
state – Filter state
lsh – Left shift compensation value

Returns:

int32_t Filtered sample

Python API

class audio_dsp.dsp.biquad.biquad(coeffs: list[float], fs: int, n_chans: int = 1, b_shift: int = 0, Q_sig: int = 27)

A second order biquadratic filter instance.

This implements a direct form 1 biquad filter, using the coefficients provided at initialisation: a0*y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]

For efficiency the biquad coefficients are normalised by a0 and the output a coefficients multiplied by -1.

Parameters:

coeffslist[float]: List of normalised biquad coefficients in the form in the form [b0, b1, b2, -a1, -a2]/a0
fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
b_shiftint: The number of right shift bits applied to the b coefficients. The default coefficient scaling allows for a maximum coefficient value of 2, but high gain shelf and peaking filters can have coefficients above this value. Shifting the b coefficients down allows coefficients greater than 2, with the cost of b_shift bits of precision.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
coeffslist[float]: List of normalised float biquad coefficients in the form in the form [b0, b1, b2, -a1, -a2]/a0, rounded to int32 precision.
int_coeffslist[int]: List of normalised int biquad coefficients in the form in the form [b0, b1, b2, -a1, -a2]/a0, scaled and rounded to int32.

process(sample: float, channel: int = 0) → float

Filter a single sample using direct form 1 biquad using floating point maths.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed sample.

update_coeffs(new_coeffs: list[float])

Update the saved coefficients to the input values.

Parameters:

new_coeffslist[float]: The new coefficients to be updated.

reset_state(): Reset the biquad saved states to zero.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Biquad Filters$$$Cascaded Biquads£££doc/03_dsp_components/modules/biquads.html#cascaded-biquads

The cascaded biquad module is equivalent to 8 individual biquad filters connected in series. It can be used to implement a simple parametric equaliser or high-order Butterworth filters, implemented as cascaded second order sections.

C API

int32_t adsp_cascaded_biquads_8b(int32_t new_sample, q2_30 coeffs[40], int32_t state[64], left_shift_t lsh[8])

8-band cascaded biquad filter This function implements an 8-band cascaded biquad filter. The filter is implemented as a direct form 1 filter.

Note

The filter coefficients must be in [5][8]

Parameters:

new_sample – New sample to be filtered
coeffs – Filter coefficients
state – Filter state
lsh – Left shift compensation value

Returns:

int32_t Filtered sample

Python API

class audio_dsp.dsp.cascaded_biquads.cascaded_biquads_8(coeffs_list, fs, n_chans, Q_sig=27)

A class representing a cascaded biquad filter with up to 8 biquads.

This can be used to either implement a parametric equaliser or a higher order filter built out of second order sections.

8 biquad objects are always created, if there are less than 8 biquads in the cascade, the remaining biquads are set to bypass (b0 = 1).

For documentation on individual biquads, see audio_dsp.dsp.biquad.biquad.

Parameters:

coeffs_listlist: List of coefficients for each biquad in the cascade.
fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
biquadslist: List of biquad objects representing each biquad in the cascade.

process(sample, channel=0)

Process the input sample through the cascaded biquads using floating point maths.

Parameters:

samplefloat: The input sample to be processed.
channelint: The channel index to process the sample on.

Returns:

float: The processed output sample.

reset_state(): Reset the biquad saved states to zero.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Finite Impulse Response Filters£££doc/03_dsp_components/modules/fir.html#finite-impulse-response-filters

Finite impulse response (FIR) filters allow the use of arbitrary filters with a finite number of taps. This library does not provide FIR filter design tools, but allows for coefficients to be imported from other design tools, such as SciPy/filter_design.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Finite Impulse Response Filters$$$FIR Direct£££doc/03_dsp_components/modules/fir.html#fir-direct

The direct FIR implements the filter as a convolution in the time domain. This library uses FIR filter_fir_s32 implementation from lib_xcore_math to run on xcore. More information on implementation can be found in XCORE Math Library documentation.

class audio_dsp.dsp.fir.fir_direct(fs: float, n_chans: int, coeffs_path: Path, Q_sig: int = 27)

An FIR filter, implemented in direct form in the time domain.

When the filter coefficients are converted to fixed point, if there will be leading zeros, a left shift is applied to the coefficients in order to use the full dynamic range of the VPU. A subsequent right shift is applied to the accumulator after the convolution to return to the same gain.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
coeffs_pathPath: Path to a file containing the coefficients, in a format supported by np.loadtxt.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
coeffsnp.ndarray: Array of the FIR coefficients in floating point format.
coeffs_intlist: Array of the FIR coefficients in fixed point int32 format.
shiftint: Right shift to be applied to the fixed point convolution result. This compensates for any left shift applied to the coefficients.
n_tapsint: Number of taps in the filter.
buffernp.ndarray: Buffer of previous inputs for the convlution in floating point format.
buffer_intlist: Buffer of previous inputs for the convlution in fixed point format.
buffer_idxlist: List of the floating point buffer head for each channel.
buffer_idx_intlist: List of the fixed point point buffer head for each channel.

process(sample: float, channel: int = 0) → float

Update the buffer with the current sample and convolve with the filter coefficients, using floating point math.

Parameters:

samplefloat: The input sample to be processed.
channelint: The channel index to process the sample on.

Returns:

float: The processed output sample.

reset_state() → None: Reset all the delay line values to zero.

check_coeff_scaling()

Check the coefficient scaling is optimal.

If there will be leading zeros, calculate a shift to use the full dynamic range of the VPU

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Reverb£££doc/03_dsp_components/modules/reverb.html#reverb

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Reverb$$$Reverb Room£££doc/03_dsp_components/modules/reverb.html#reverb-room

The room reverb module imitates the reflections of a room. The algorithm is a Schroeder style reverberation, based on Freeverb by Jezar at Dreampoint. It consists of the wet predelay, 8 parallel comb filters fed into 4 series all-pass filters, with a wet and dry microphone control to set the effect level.

For more details on the algorithm, see Physical Audio Signal Processing by Julius Smith.

struct reverb_room_t

A room reverb filter structure.

Public Members

uint32_t total_buffer_length: Total buffer length

float room_size: Room size

int32_t wet_gain: Wet linear gain

int32_t dry_gain: Dry linear gain

int32_t pre_gain: Linear pre-gain

comb_fv_t combs[ADSP_RVR_N_COMBS]: Comb filters

allpass_fv_t allpasses[ADSP_RVR_N_APS]: Allpass filters

delay_t predelay: Predelay applied to the wet channel

C API

int32_t adsp_reverb_room(reverb_room_t *rv, int32_t new_samp)

Process a sample through a reverb room object.

Parameters:

rv – Reverb room object
new_samp – New sample to process

Returns:

int32_t Processed sample

Python API

class audio_dsp.dsp.reverb.reverb_room(fs, n_chans, max_room_size=1, room_size=1, decay=0.5, damping=0.4, wet_gain_db=-1, dry_gain_db=-1, pregain=0.015, predelay=10, max_predelay=None, Q_sig=27)

Generate a room reverb effect. This is based on Freeverb by Jezar at Dreampoint, and consists of 8 parallel comb filters fed into 4 series all-pass filters.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
max_room_sizefloat, optional: sets the maximum size of the delay buffers, can only be set at initialisation.
room_sizefloat, optional: how big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.
decayint, optional: The length of the reverberation of the room, between 0 and 1.
dampingfloat, optional: how much high frequency attenuation in the room, between 0 and 1
wet_gain_dbint, optional: wet signal gain, less than 0 dB.
dry_gain_dbint, optional: dry signal gain, less than 0 dB.
pregainfloat, optional: the amount of gain applied to the signal before being passed into the reverb, less than 1. If the reverb raises an OverflowWarning, this value should be reduced until it does not. The default value of 0.015 should be sufficient for most Q27 signals.
predelayfloat, optional: the delay applied to the wet channel in ms.
max_predelayfloat, optional: the maximum predelay in ms.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
pregainfloat: The pregain applied before the reverb as a floating point number.
pregain_intint: The pregain applied before the reverb as a fixed point number.
wet_dbfloat: The gain applied to the wet signal in dB.
wetfloat: The linear gain applied to the wet signal.
wet_intint: The linear gain applied to the wet signal as a fixed point number.
dryfloat: The linear gain applied to the dry signal.
dry_dbfloat: The gain applied to the dry signal in dB.
dry_intint: The linear gain applied to the dry signal as a fixed point number.
predelayfloat
comb_lengthsnp.ndarray: An array of the comb filter delay line lengths, scaled by max_room_size.
ap_lengthnp.ndarray: An array of the all pass filter delay line lengths, scaled by max_room_size.
combslist: A list of comb_fv objects containing the comb filters for the reverb.
allpasseslist: A list of allpass_fv objects containing the all pass filters for the reverb.
room_sizefloat: The room size as a proportion of the max_room_size.
decayfloat: The length of the reverberation of the room, between 0 and 1.
feedbackfloat: Gain of the feedback line in the reverb filters.
feedback_intint: feedback as a fixed point integer.
dampingfloat: How much high frequency attenuation in the room, between 0 and 1.
damping_intint: damping as a fixed point integer.

process(sample, channel=0)

Add reverberation to a signal, using floating point maths.

Take one new sample and return the sample with reverb. Input should be scaled with 0 dB = 1.0.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed sample.

reset_state(): Reset all the delay line values to zero.

set_wet_dry_mix(mix)

Will mix wet and dry signal by adjusting wet and dry gains. So that when the mix is 0, the output signal is fully dry, when 1, the output signal is fully wet. Tries to maintain a stable signal level using -4.5 dB Pan Law.

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

set_pre_gain(pre_gain)

Deprecated since version 1.0.0: set_pre_gain will be removed in 2.0.0. Replace reverb_room.set_pre_gain(x) with reverb_room.pregain = x

Set the pre gain.

Parameters:

pre_gainfloat: pre gain value, less than 1.

set_wet_gain(wet_gain_db)

Deprecated since version 1.0.0: set_wet_gain will be removed in 2.0.0. Replace reverb_room.set_wet_gain(x) with reverb_room.wet_db = x

Set the wet gain.

Parameters:

wet_gain_dbfloat: Wet gain in dB, less than 0 dB.

set_dry_gain(dry_gain_db)

Deprecated since version 1.0.0: set_dry_gain will be removed in 2.0.0. Replace reverb_room.set_dry_gain(x) with reverb_room.dry_db = x

Set the dry gain.

Parameters:

dry_gain_dbfloat: Dry gain in dB, lees than 0 dB.

set_decay(decay)

Deprecated since version 1.0.0: set_decay will be removed in 2.0.0. Replace reverb_room.set_decay(x) with reverb_room.decay = x

Set the decay of the reverb.

Parameters:

decayfloat: How long the reverberation of the room is, between 0 and 1.

set_damping(damping)

Deprecated since version 1.0.0: set_damping will be removed in 2.0.0. Replace reverb_room.set_damping(x) with reverb_room.damping = x

Set the damping of the reverb.

Parameters:

dampingfloat: How much high frequency attenuation in the room, between 0 and 1.

set_room_size(room_size)

Deprecated since version 1.0.0: set_room_size will be removed in 2.0.0. Replace reverb_room.set_room_size(x) with reverb_room.room_size = x

Set the current room size; will adjust the delay line lengths accordingly.

Parameters:

room_sizefloat: How big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Reverb$$$Reverb Room Stereo£££doc/03_dsp_components/modules/reverb.html#reverb-room-stereo

The stereo room reverb module extends the mono Reverb Room by adding a second set of comb and all-pass filters in parallel, and mixing the output of the two networks. Varying the mix of the networks changes the stereo width of the effect.

For more details on the algorithm, see Physical Audio Signal Processing by Julius Smith.

struct reverb_room_st_t

A stereo room reverb filter structure.

Public Members

uint32_t total_buffer_length: Total buffer length

uint32_t spread_length: Spread length

float room_size: Room size

int32_t wet_gain1: Wet 1 linear gain

int32_t wet_gain2: Wet 2 linear gain

int32_t dry_gain: Dry linear gain

int32_t pre_gain: Linear pre-gain

comb_fv_t combs[2][ADSP_RVR_N_COMBS]: Comb filters, 0:left, 1:right

allpass_fv_t allpasses[2][ADSP_RVR_N_APS]: Allpass filters, 0:left, 1:right

delay_t predelay: Predelay applied to the wet channel

C API

void adsp_reverb_room_st(reverb_room_st_t *rv, int32_t outputs_lr[2], int32_t in_left, int32_t in_right)

Process samples through a stereo reverb room object.

Parameters:

rv – Stereo reverb room object
outputs_lr – Pointer to the outputs 0:left, 1:right
in_left – New left sample to process
in_right – New right sample to process

Python API

class audio_dsp.dsp.reverb_stereo.reverb_room_stereo(fs, n_chans, max_room_size=1, room_size=1, decay=0.5, damping=0.4, width=1.0, wet_gain_db=-1, dry_gain_db=-1, pregain=0.0075, predelay=10, max_predelay=None, Q_sig=27)

Generate a stereo room reverb effect. This is based on Freeverb by Jezar at Dreampoint. Each channel consists of 8 parallel comb filters fed into 4 series all-pass filters, and the reverberator outputs are mixed according to the width parameter.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
max_room_sizefloat, optional: sets the maximum size of the delay buffers, can only be set at initialisation.
room_sizefloat, optional: how big the room is as a proportion of max_room_size. This sets delay line lengths and must be between 0 and 1.
decayint, optional: The length of the reverberation of the room, between 0 and 1.
dampingfloat, optional: how much high frequency attenuation in the room, between 0 and 1
widthfloat, optional: how much stereo separation there is between the left and right channels. Setting width to 0 will yield a mono signal, whilst setting width to 1 will yield the most stereo separation.
wet_gain_dbint, optional: wet signal gain, less than 0 dB.
dry_gain_dbint, optional: dry signal gain, less than 0 dB.
pregainfloat, optional: the amount of gain applied to the signal before being passed into the reverb, less than 1. If the reverb raises an OverflowWarning, this value should be reduced until it does not. The default value of 0.015 should be sufficient for most Q27 signals.
predelayfloat, optional: the delay applied to the wet channel in ms.
max_predelayfloat, optional: the maximum predelay in ms.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
pregainfloat: The pregain applied before the reverb as a floating point number.
pregain_intint: The pregain applied before the reverb as a fixed point number.
wet_dbfloat: The gain applied to the wet signal in dB.
wetfloat: The linear gain applied to the wet signal.
wet_intint: The linear gain applied to the wet signal as a fixed point number.
dryfloat: The linear gain applied to the dry signal.
dry_dbfloat: The gain applied to the dry signal in dB.
dry_intint: The linear gain applied to the dry signal as a fixed point number.
predelayfloat
widthfloat: Stereo separation of the reverberated signal.
comb_lengthsnp.ndarray: An array of the comb filter delay line lengths, scaled by max_room_size.
ap_lengthnp.ndarray: An array of the all pass filter delay line lengths, scaled by max_room_size.
combslist: A list of comb_fv objects containing the comb filters for the reverb.
allpasseslist: A list of allpass_fv objects containing the all pass filters for the reverb.
room_sizefloat: The room size as a proportion of the max_room_size.
decayfloat: The length of the reverberation of the room, between 0 and 1.
feedbackfloat: Gain of the feedback line in the reverb filters.
feedback_intint: feedback as a fixed point integer.
dampingfloat: How much high frequency attenuation in the room, between 0 and 1.
damping_intint: damping as a fixed point integer.

process(sample, channel=0)

Process is not implemented for the stereo reverb, as it needs 2 channels at once.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed sample.

reset_state(): Reset all the delay line values to zero.

set_wet_dry_mix(mix)

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

property wet_db: The gain applied to the wet signal in dB.

property dry_db: The gain applied to the dry signal in dB.

property decay: The length of the reverberation of the room, between 0 and 1.

property damping: How much high frequency attenuation in the room, between 0 and 1.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Reverb$$$Reverb Plate Stereo£££doc/03_dsp_components/modules/reverb.html#reverb-plate-stereo

The plate reverb module imitates the reflections of a plate reverb, which has more early reflections than the room reverb. The algorithm is based on Dattorro’s 1997 paper. This reverb consists of 4 allpass filters for input diffusion, followed by a figure of 8 reverb tank of allpasses, low-pass filters, and delays. The output is taken from multiple taps in the delay lines to get a desirable echo density. The left and right output can be mixed with various widths.

For more details on the algorithm, see Effect Design, Part 1: Reverberator and Other Filters by Jon Dattorro.

struct reverb_plate_t

A plate reverb structure.

Public Members

int32_t decay: Reverb decay

int32_t wet_gain1: Wet 1 linear gain

int32_t wet_gain2: Wet 2 linear gain

int32_t dry_gain: Dry linear gain

int32_t pre_gain: Linear pre-gain

int32_t paths[ADSP_RVP_N_PATHS]: Saved output paths

int32_t taps_l[ADSP_RVP_N_OUT_TAPS]: Indexes for the left channel calculation

int32_t taps_len_l[ADSP_RVP_N_OUT_TAPS]: Max lenghts of buffers use for the left channel calculation

int32_t taps_r[ADSP_RVP_N_OUT_TAPS]: Indexes for the right channel calculation

int32_t taps_len_r[ADSP_RVP_N_OUT_TAPS]: Max lenghts of buffers use for the right channel calculation

lowpass_1ord_t lowpasses[ADSP_RVP_N_LPS]: FIrst order lowpass filters

allpass_fv_t mod_allpasses[ADSP_RVP_N_PATHS]: Modulated allpass filters

allpass_fv_t allpasses[ADSP_RVP_N_APS]: Allpass filters

delay_t delays[ADSP_RVP_N_DELAYS]: Delay lines

delay_t predelay: Predelay applied to the wet channel

C API

void adsp_reverb_plate(reverb_plate_t *rv, int32_t outputs_lr[2], int32_t in_left, int32_t in_right)

Process samples through a reverb plate object.

Parameters:

rv – Reverb plate object
outputs_lr – Pointer to the outputs 0:left, 1:right
in_left – New left sample to process
in_right – New right sample to process

Python API

class audio_dsp.dsp.reverb_plate.reverb_plate_stereo(fs, n_chans, decay=0.4, damping=0.75, bandwidth=8000, early_diffusion=0.75, late_diffusion=0.7, width=1.0, wet_gain_db=-3, dry_gain_db=-3, pregain=0.5, predelay=10, max_predelay=None, Q_sig=27)

Generate a stereo plate reverb effect, based on Dattorro’s 1997 paper. This reverb consists of 4 allpass filters for input diffusion, followed by a figure of 8 reverb tank of allpasses, low-pass filters, and delays. The output is taken from multiple taps in the delay lines to get a desirable echo density.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
decayint, optional: The length of the reverberation of the room, between 0 and 1.
dampingfloat, optional: How much high frequency attenuation in the room, between 0 and 1
bandwidthfloat, optional: Controls the low pass filter cutoff frequency at the start of the reverb, in Hz.
early_diffusionfloat, optional: Controls how much diffusion the early echoes have.
late_diffusionfloat, optional: Controls how much diffusion the late echoes have.
widthfloat, optional: how much stereo separation there is between the left and right channels. Setting width to 0 will yield a mono signal, whilst setting width to 1 will yield the most stereo separation.
wet_gain_dbint, optional: wet signal gain, less than 0 dB.
dry_gain_dbint, optional: dry signal gain, less than 0 dB.
pregainfloat, optional: the amount of gain applied to the signal before being passed into the reverb, less than 1. If the reverb raises an OverflowWarning, this value should be reduced until it does not. The default value of 0.5 should be sufficient for most Q27 signals, and should be reduced by 1 bit per increase in Q format, e.g. 0.25 for Q28, 0.125 for Q29 etc.
predelayfloat, optional: the delay applied to the wet channel in ms.
max_predelayfloat, optional: the maximum predelay in ms.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
pregainfloat: The pregain applied before the reverb as a floating point number.
pregain_intint: The pregain applied before the reverb as a fixed point number.
wet_dbfloat: The gain applied to the wet signal in dB.
wetfloat: The linear gain applied to the wet signal.
wet_intint: The linear gain applied to the wet signal as a fixed point number.
dryfloat: The linear gain applied to the dry signal.
dry_dbfloat: The gain applied to the dry signal in dB.
dry_intint: The linear gain applied to the dry signal as a fixed point number.
predelayfloat
widthfloat: Stereo separation of the reverberated signal.
allpasseslist: A list of allpass objects containing the all pass filters for the reverb.
lowpasseslist: A list of lowpass objects containing the low pass filters for the reverb.
delayslist: A list of delay objects containing the delay lines for the reverb.
mod_allpasseslist: A list of allpass objects containing the modulated all pass objects for the reverb.
taps_llist: A list of the current output tap locations for the left output.
taps_rlist: A list of the current output tap locations for the right output.
tap_lens_llist: A list of the buffer lengths used by taps_l, to aid wrapping the read head at the end of the buffer
tap_lens_rlist: As tap lens_l, but for the right output channel.
decayfloat: The length of the reverberation of the room, between 0 and 1.
decay_intint: decay as a fixed point integer.
dampingfloat: How much high frequency attenuation in the room, between 0 and 1.
damping_intint: damping as a fixed point integer.
bandwidthfloat: The bandwidth of the reverb input signal, in Hertz.
early_diffusionfloat: How much early diffusion in the reverb, between 0 and 1.
late_diffusionfloat: How much late diffusion in the reverb, between 0 and 1.

process(sample, channel=0)

Process is not implemented for the stereo reverb, as it needs 2 channels at once.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed sample.

reset_state(): Reset all the delay line values to zero.

set_wet_dry_mix(mix)

Parameters:

mixfloat: The wet/dry mix, must be [0, 1].

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components£££doc/03_dsp_components/modules/signal_chain.html#signal-chain-components

Signal chain components includes DSP modules for: * combining signals, such as subtracting, adding, and mixing * forks for splitting signals * basic gain components, such as fixed gain, volume control, and mute * basic delay buffers.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Adder£££doc/03_dsp_components/modules/signal_chain.html#adder

The adder will add samples from N inputs together. It will round and saturate the result to the Q0.31 range.

C API

int32_t adsp_adder(int32_t *input, unsigned n_ch)

Saturating addition of an array of samples.

Note

Will work for any q format

Parameters:

input – Array of samples
n_ch – Number of channels

Returns:

int32_t Sum of samples

Python API

class audio_dsp.dsp.signal_chain.adder(fs: float, n_chans: int, Q_sig: int = 27)

A class representing an adder in a signal chain.

This class inherits from the mixer class and provides an adder with no attenuation.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
gain_dbfloat: The mixer gain in decibels.
gainfloat: Gain as a linear value.
gain_intint: Gain as an integer value.

process_channels(sample_list: list[float]) → float

Process a single sample. Apply the gain to all the input samples then sum them using floating point maths.

Parameters:

sample_listlist: List of input samples

Returns:

float: Output sample.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Subtractor£££doc/03_dsp_components/modules/signal_chain.html#subtractor

The subtractor will subtract one sample from another, then round and saturate the difference to Q0.31 range.

C API

int32_t adsp_subtractor(int32_t x, int32_t y)

Saturating subtraction of two samples, this returns x - y.

Note

Will work for any q format

Parameters:

x – Minuend
y – Subtrahend

Returns:

int32_t Difference

Python API

class audio_dsp.dsp.signal_chain.subtractor(fs: float, Q_sig: int = 27)

Subtractor class for subtracting two signals.

Parameters:

fsint: Sampling frequency in Hz.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.

process_channels(sample_list: list[float]) → float

Subtract the second input sample from the first using floating point maths.

Parameters:

sample_listlist[float]: List of input samples.

Returns:

float: Result of the subtraction.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Fixed Gain£££doc/03_dsp_components/modules/signal_chain.html#fixed-gain

This module applies a fixed gain to a sample, with rounding and saturation to Q0.31 range. The gain must be in Q_GAIN format.

Q_GAIN: Gain format to be used in the gain APIs

C API

int32_t adsp_fixed_gain(int32_t input, int32_t gain)

Fixed-point gain.

Note

One of the inputs has to be in Q_GAIN format

Parameters:

input – Input sample
gain – Gain

Returns:

int32_t Output sample

Python API

class audio_dsp.dsp.signal_chain.fixed_gain(fs: float, n_chans: int, gain_db: float, Q_sig: int = 27)

Multiply every sample by a fixed gain value.

In the current implementation, the maximum boost is +24 dB.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
gain_dbfloat: The gain in decibels. Maximum fixed gain is +24 dB.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
gain_dbfloat: The mixer gain in decibels.
gainfloat: Gain as a linear value.
gain_intint: Gain as an integer value.

process(sample: float, channel: int = 0) → float

Multiply the input sample by the gain, using floating point maths.

Parameters:

samplefloat: The input sample to be processed.
channelint: The channel index to process the sample on, not used by this module.

Returns:

float: The processed output sample.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Mixer£££doc/03_dsp_components/modules/signal_chain.html#mixer

The mixer applies a gain to all N channels of input samples and adds them together. The sum is rounded and saturated to Q0.31 range. The gain must be in Q_GAIN format.

C API

int32_t adsp_mixer(int32_t *input, unsigned n_ch, int32_t gain)

Mixer. Will add signals with gain applied to each signal before mixing.

Note

Inputs or gain have to be in Q_GAIN format

Parameters:

input – Array of samples
n_ch – Number of channels
gain – Gain

Returns:

int32_t Mixed sample

An alternative way to implement a mixer is to multiply-accumulate the input samples into a 64-bit word, then saturate it to a 32-bit word using:

int32_t adsp_saturate_32b(int64_t acc)

Saturating 64-bit accumulator. Will saturate to 32-bit, so that the output value is in the range of int32_t.

Parameters:

acc – Accumulator

Returns:

int32_t Saturated value

Python API

class audio_dsp.dsp.signal_chain.mixer(fs: float, n_chans: int, gain_db: float = -6, Q_sig: int = 27)

Mixer class for adding signals with attenuation to maintain headroom.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
gain_dbfloat: Gain in decibels (default is -6 dB).
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
gain_dbfloat: The mixer gain in decibels.
gainfloat: Gain as a linear value.
gain_intint: Gain as an integer value.

process_channels(sample_list: list[float]) → float

Process a single sample. Apply the gain to all the input samples then sum them using floating point maths.

Parameters:

sample_listlist: List of input samples

Returns:

float: Output sample.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Volume Control£££doc/03_dsp_components/modules/signal_chain.html#volume-control

The volume control allows safe real-time gain adjustments with minimal artifacts. When the target gain is changed, a slew is used to move from the current gain to the target gain. This allows smooth gain change and no clicks in the output signal.

The mute API allows the user to safely mute the signal by setting the target gain to 0, with the slew ensuring no pops or clicks. Unmuting will restore the pre-mute target gain. The new gain can be set while muted, but will not take effect until unmute is called. There are separate APIs for process, setting the gain, muting and unmuting so that volume control can easily be implemented into the control system.

The slew is applied as an exponential of the difference between the target and current gain. For run-time efficiency, instead of an EMA-style alpha, the difference is right shifted by the slew_shift parameter. The relation between slew_shift and time is further discussed in the Python class documentation.

struct volume_control_t

Volume control state structure.

Public Members

int32_t target_gain: Target linear gain

int32_t gain: Current linear gain

int32_t slew_shift: Slew shift

int32_t saved_gain: Saved linear gain

uint8_t mute_state: Mute state: 0: unmuted, 1 muted

C API

int32_t adsp_volume_control(volume_control_t *vol_ctl, int32_t samp)

Process a new sample with a volume control.

Parameters:

vol_ctl – Volume control object
samp – New sample

Returns:

int32_t Processed sample

void adsp_volume_control_set_gain(volume_control_t *vol_ctl, int32_t new_gain)

Set the target gain of a volume control.

Parameters:

vol_ctl – Volume control object
new_gain – New target linear gain

void adsp_volume_control_mute(volume_control_t *vol_ctl)

Mute a volume control. Will save the current target gain and set the target gain to 0.

Parameters:

vol_ctl – Volume control object

void adsp_volume_control_unmute(volume_control_t *vol_ctl)

Unmute a volume control. Will restore the saved target gain.

Parameters:

vol_ctl – Volume control object

Python API

class audio_dsp.dsp.signal_chain.volume_control(fs: float, n_chans: int, gain_db: float = -6, slew_shift: int = 7, mute_state: int = 0, Q_sig: int = 27)

A volume control class that allows setting the gain in decibels. When the gain is updated, an exponential slew is applied to reduce artifacts.

The slew is implemented as a shift operation. The slew rate can be converted to a time constant using the formula: time_constant = -1/ln(1 - 2^-slew_shift) * (1/fs)

A table of the first 10 slew shifts is shown below:

slew_shift	Time constant (ms)
1	0.03
2	0.07
3	0.16
4	0.32
5	0.66
6	1.32
7	2.66
8	5.32
9	10.66
10	21.32

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
gain_dbfloat, optional: The initial gain in decibels
slew_shiftint, optional: The shift value used in the exponential slew.
mute_stateint, optional: The mute state of the Volume Control: 0: unmuted, 1: muted.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Raises:

ValueError: If the gain_db parameter is greater than 24 dB.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
target_gain_dbfloat: The target gain in decibels.
target_gainfloat: The target gain as a linear value.
target_gain_intint: The target gain as a fixed-point integer value.
gain_dbfloat: The current gain in decibels.
gainfloat: The current gain as a linear value.
gain_intint: The current gain as a fixed-point integer value.
slew_shiftint: The shift value used in the exponential slew.
mute_stateint: The mute state of the Volume Control: 0: unmuted, 1: muted

process(sample: float, channel: int = 0) → float

Update the current gain, then multiply the input sample by it, using floating point maths.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Not used by this module.

Returns:

float: The processed output sample.

set_gain(gain_db: float) → None

Deprecated since version 1.0.0: set_gain will be removed in 2.0.0. Replace volume_control.set_gain(x) with volume_control.target_gain_db = x

Set the gain of the volume control.

Parameters:

gain_dbfloat: The gain in decibels. Must be less than or equal to 24 dB.

Raises:

ValueError: If the gain_db parameter is greater than 24 dB.

mute() → None: Mute the volume control.

unmute() → None: Unmute the volume control.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Signal Chain Components$$$Delay£££doc/03_dsp_components/modules/signal_chain.html#delay

The delay module uses a memory buffer to return a sample after a specified time period. The returned samples will be delayed by a specified value. The max_delay is set at initialisation, and sets the amount of memory used by the buffers. It cannot be changed at runtime. The current delay value can be changed at runtime within the range [0, max_delay]

struct delay_t

Delay state structure.

Public Members

float fs: Sampling frequency

uint32_t delay: Current delay in samples

uint32_t max_delay: Maximum delay in samples

uint32_t buffer_idx: Current buffer index

int32_t *buffer: Buffer

C API

int32_t adsp_delay(delay_t *delay, int32_t samp)

Process a new sample through a delay object.

Note

The minimum delay provided by this block is 1 sample. Setting the delay to 0 will still yield a 1 sample delay.

Parameters:

delay – Delay object
samp – New sample

Returns:

int32_t Oldest sample

Python API

class audio_dsp.dsp.signal_chain.delay(fs, n_chans, max_delay: float, starting_delay: float, units: str = 'samples')

A simple delay line class.

Note the minimum delay provided by this block is 1 sample. Setting the delay to 0 will still yield a 1 sample delay.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
max_delayfloat: The maximum delay in specified units.
starting_delayfloat: The starting delay in specified units.
unitsstr, optional: The units of the delay, can be ‘samples’, ‘ms’ or ‘s’. Default is ‘samples’.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.
max_delayint: The maximum delay in samples.
delayint: The delay in samples.
buffernp.ndarray: The delay line buffer.
buffer_idxint: The current index of the buffer.

process_channels(sample: list[float]) → list[float]

Put the new sample in the buffer and return the oldest sample.

Parameters:

samplelist: List of input samples

Returns:

float: List of delayed samples.

reset_state() → None: Reset all the delay line values to zero.

set_delay(delay: float, units: str = 'samples') → None

Set the length of the delay line, will saturate at max_delay.

Parameters:

delayfloat: The delay length in specified units.
unitsstr, optional: The units of the delay, can be ‘samples’, ‘ms’ or ‘s’. Default is ‘samples’.

Lib Audio DSP$$$DSP Components$$$DSP Modules$$$Python module base class£££doc/03_dsp_components/modules/more_python.html#python-module-base-class

All the Python DSP modules are based on a common base class. In order to keep the documentation short, all Python classes in the previous sections only had the process method described, and control methods where necessary. This section provides the user with a more in-depth information of the Python API, which may be useful when adding custom DSP modules.

Some classes overload the base class APIs where they require different input data types or dimensions. However, they will all have the attributes and methods described below.

The process methods can be split into 2 groups:

process is a 64b floating point implementation
process_xcore is a 32b fixed-point implementation, with the aim of being bit exact with the C/assembly implementation.

The process_xcore methods can be used to simulate the xcore implementation precision and the noise floor. The Python process_xcore implementations have very similar accuracy to the xcore C adsp_* implementations (subject to the module and implementation). Python simulation methods tend to be slower as Python has a limited support for the fixed point processing. Bit exactness is not always possible for modules that use 32b float operations, as the rounding of these can differ between C libraries.

class audio_dsp.dsp.generic.dsp_block(fs, n_chans, Q_sig=27)

Generic DSP block, all blocks should inherit from this class and implement it’s methods.

By using the metaclass NumpyDocstringInheritanceInitMeta, parameter and attribute documentation can be inherited by the child classes.

Parameters:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int, optional: Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

Attributes:

fsint: Sampling frequency in Hz.
n_chansint: Number of channels the block runs on.
Q_sig: int: Q format of the signal, number of bits after the decimal point.

freq_response(nfft=512)

Calculate the frequency response of the module for a nominal input.

The generic module has a flat frequency response.

Parameters:

nfftint, optional: The number of points to use for the FFT, by default 512

Returns:

tuple: A tuple containing the frequency values and the corresponding complex response.

process(sample: float, channel=0)

Take one new sample and give it back. Do no processing for the generic block.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed sample.

process_frame(frame: list)

Take a list frames of samples and return the processed frames.

A frame is defined as a list of 1-D numpy arrays, where the number of arrays is equal to the number of channels, and the length of the arrays is equal to the frame size.

For the generic implementation, just call process for each sample for each channel.

Parameters:

framelist: List of frames, where each frame is a 1-D numpy array.

Returns:

list: List of processed frames, with the same structure as the input frame.

process_frame_xcore(frame: list)

Take a list frames of samples and return the processed frames, using an xcore-like implementation.

A frame is defined as a list of 1-D numpy arrays, where the number of arrays is equal to the number of channels, and the length of the arrays is equal to the frame size.

For the generic implementation, just call process for each sample for each channel.

Parameters:

framelist: List of frames, where each frame is a 1-D numpy array.

Returns:

list: List of processed frames, with the same structure as the input frame.

process_xcore(sample: float, channel=0)

Take one new sample and return 1 processed sample.

For the generic implementation, scale and quantize the input, call the xcore-like implementation, then scale back to 1.0 = 0 dB.

Parameters:

samplefloat: The input sample to be processed.
channelint, optional: The channel index to process the sample on. Default is 0.

Returns:

float: The processed output sample.

Lib Audio DSP$$$DSP Components$$$Precision£££doc/03_dsp_components/precision.html#precision

Note

By default, the signal processing in the audio pipeline is carried out at 32 bit fixed point precision in Q4.27 format. Assuming a 24 bit input signal in Q0.24 format, this gives 4 bits of internal headroom in the audio pipeline, which is equivalent to 24 dB. The output of the audio pipeline will be clipped back to Q0.24 before returning. For more precision, the pipeline can be configured to run with no headroom in Q0.31 format, but this requires manual headroom management. More information on setting the Q format can be found in the Library Q Format section.

DSP algorithms are implemented either on the XS3 CPU or VPU (vector processing unit).

CPU algorithms are typically implemented as 32-bit x 32-bit operations into 64-bit results and accumulators, before rounding back to 32-bit outputs.

The VPU allows for 8 simultaneous operations, with a small cost in precision. VPU algorithms are typically implemented as 32-bit x 32-bit operations into 34-bit results and 40-bit accumulators, before rounding back to 32-bit outputs.

Lib Audio DSP$$$DSP Components$$$Latency£££doc/03_dsp_components/latency.html#latency

The latency of the DSP pipeline is dependent on the number of threads. By default, the DSP pipeline is configured for one sample of latency per thread. All current DSP modules have zero inbuilt latency (except where specified e.g. delay stages). For pipelines that fit on a single thread, this means the total pipeline latency is 1 sample.

The pipeline can also be configured to use a higher frame size. This increases latency, but can reduce compute for simple functions. For a pipeline consisting of just biquads:

Frame size = 1, latency = 1 sample, compute = 25 biquads per thread @ 48kHz.
Frame size = 8, latency = 8 samples, compute = 60 biquads per thread @ 48kHz.

Lib Audio DSP$$$Run-Time Control User Guide£££doc/04_run_time_control_guide/index.html#run-time-control-user-guide

For many applications, the ability to update the DSP configuration at run time will be required. A simple example would be a volume control where the end product will update the volume setting based on user input. This DSP library has been designed with use cases like this in mind and the generated DSP pipeline provides an interface for writing and reading the configuration of each stage.

This document details how to use this interface to extend a DSP application with run-time control of the audio processing. For a complete example of an application that updates the DSP configuration based on user input refer to application note AN02015.

Lib Audio DSP$$$Run-Time Control User Guide$$$Control Interface Walkthrough£££doc/04_run_time_control_guide/control_interface_walkthrough.html#control-interface-walkthrough

Lib Audio DSP$$$Run-Time Control User Guide$$$Control Interface Walkthrough$$$Defining a Controllable Pipeline£££doc/04_run_time_control_guide/control_interface_walkthrough.html#defining-a-controllable-pipeline

This section will walk through adding control to a basic DSP pipeline. The following code snippet describes a simple DSP process with a volume control and a limiter. In the end application the volume can be set by the application.

from audio_dsp.design.pipeline import Pipeline
from audio_dsp.stages import *

p, edge = Pipeline.begin(4)
edge = p.stage(VolumeControl, edge, "volume")
edge = p.stage(LimiterRMS, edge)
p.set_outputs(edge)

This code snippet will generate the pipeline diagram shown in Fig. 11.

../_images/run_time_control.gv.png — The example pipeline diagram

In this example the tuning methods on the stages in the pipeline are not called which means the code that is generated will intialise the stages with their default configuration values.

A point of interest in this example is that the label argument to the pipeline stage method is set, but only for the volume control stage. The label for the volume control in this example is “volume”. After generating the source code for this pipeline, a file will be created in the specified directory named “adsp_instance_id_auto.h” (assuming that the pipeline identifier has been left as its default value of “auto”). The contents of the generated file are shown below:

#pragma once

#define thread0_stage_index		(1)
#define volume_stage_index		(2)
#define auto_thread_stage_indices  { thread0_stage_index }

In this file the macro volume_stage_index is defined. The value of this macro can be used by the control interface to find the volume control stage and process control commands. The benefit of this to an application author is that this header file can be included in the application and the value of volume_stage_index will always be correct, even when the pipeline is redesigned.

Lib Audio DSP$$$Run-Time Control User Guide$$$Control Interface Walkthrough$$$Writing the Configuration of a Stage£££doc/04_run_time_control_guide/control_interface_walkthrough.html#writing-the-configuration-of-a-stage

Each stage type has a set of controllable parameters that can be read or written. A description of each parameter along with its type and name can be found in the DSP Stages section in the DSP components document. For volume control, there is a command named CMD_VOLUME_CONTROL_TARGET_GAIN that can be updated at run time to set the volume. This command is defined in the generated header file “cmds.h” which will be placed into the build directory at “src.autogen/common/cmds.h”. “cmds.h” contains all the command IDs for all the stage types that CMake found.

It is also possible to see the available control parameters, along with the values they will be set to, while designing the pipeline in Python. This can be done using the get_config method of the stage as shown below.

config = p["volume"].get_config()
print(config)

This will print this dictionary of parameters:

{'target_gain': 134217728, 'slew_shift': 7, 'mute_state': 0}

This dictionary does not contain CMD_VOLUME_CONTROL_TARGET_GAIN, but is does contain “target_gain”. The final command name is constructed as “CMD_{STAGE_TYPE}_{PARAMETER}” where stage type and parameter should be replaced with the correct values for each, capitalised. All stages of the same type (e.g. VolumeControl) will have the same set of parameters.

The format and type of the control parameters for each stage are chosen to optimise processing time on the DSP thread. For example, CMD_VOLUME_CONTROL_TARGET_GAIN is not a floating point value in decibels, but rather a linear fixed point value. For this example we can use the convenience function adsp_dB_to_gain() which is defined in dsp/signal_chain.h.

In order to send a control command, the API defined in stages/adsp_control.h is used. This API is documented in the Tool User Guide, in the Pipeline Design API section. Complete the following steps:

Create a thread that will be updating the DSP configuration. This thread must be on the same tile as the DSP.
Create a new adsp_controller_t from the adsp_pipeline_t that was initialised for the generated pipeline. If multiple threads will be attempting control, each thread must have a unique instance of adsp_controller_t to ensure thread safety.
Initialise a new adsp_stage_control_cmd_t, specifying the instance ID (volume_stage_index), the command ID (CMD_VOLUME_CONTROL_TARGET_GAIN), and payload length (sizeof(int32_t)).
Create the command payload; this will be an int32_t containing the computed gain. Update the command payload pointer to reference the payload.
Call adsp_write_module_config until it returns ADSP_CONTROL_SUCCESS. There may be in-progress write or read commands which have been issued but not completed when starting the new command. In this scenario the adsp_write_module_config will return ADSP_CONTROL_BUSY which means that the attempt to write had no effect and should be attempted again.

A full example of a control thread that does this is shown below.

#include <xcore/parallel.h>
#include "cmds.h"
#include "adsp_generated_auto.h"
#include "adsp_instance_id_auto.h"
#include "dsp/signal_chain.h"
#include "control/signal_chain.h"
#include "stages/adsp_control.h"
#include "stages/adsp_pipeline.h"

void control_thread(adsp_controller_t* control) {
  // convert desired value to parameter type
  float desired_vol_db = -6;
  int32_t desired_vol_raw = adsp_dB_to_gain(desired_vol_db);

  adsp_stage_control_cmd_t command = {
    .instance_id = volume_stage_index,
    .cmd_id = CMD_VOLUME_CONTROL_TARGET_GAIN,
    .payload_len = sizeof(desired_vol_raw),
    .payload = &desired_vol_raw
  };

  // try write until success
  while(ADSP_CONTROL_SUCCESS != adsp_write_module_config(control, &command));

  // DONE!
}

void audio_source_sink(adsp_pipeline_t* p) {
  // sends and receives audio to the pipeline
}

void dsp_main(void) {
  adsp_pipeline_t* dsp = adsp_auto_pipeline_init();

  // created a controller instance for each thread.
  adsp_controller_t control;
  adsp_controller_init(&control, dsp);

  PAR_FUNCS(
    PFUNC(audio_source_sink, dsp),
    PFUNC(control_thread, &control),
    PFUNC(adsp_auto_pipeline_main, dsp)
  );
}

Lib Audio DSP$$$Run-Time Control User Guide$$$Control Interface Walkthrough$$$Reading the Configuration of a Stage£££doc/04_run_time_control_guide/control_interface_walkthrough.html#reading-the-configuration-of-a-stage

In some cases it makes sense to read back the configuration of the stage. Some stages have dynamic values that are updated as the audio is processed and can be read back to the control thread. Volume control is an example of this as it will smoothly adjust the gain towards CMD_VOLUME_CONTROL_TARGET_GAIN; the current value of the gain which is actually being applied can be read by reading from the parameter CMD_VOLUME_CONTROL_GAIN. The API for reading is largely the same as writing, except the control API will write to the payload buffer.

This code example shows how to read the current CMD_VOLUME_CONTROL_GAIN parameter from the “volume” stage that is created in the example above.

int32_t read_volume_gain(adsp_controller_t* control) {
  int32_t gain_raw;

  adsp_stage_control_cmd_t command = {
    .instance_id = volume_stage_index,
    .cmd_id = CMD_VOLUME_CONTROL_GAIN,
    .payload_len = sizeof(gain_raw),
    .payload = &gain_raw
  };

  // try write until success
  while(ADSP_CONTROL_SUCCESS != adsp_read_module_config(control, &command));

  return gain_raw;
}

Lib Audio DSP$$$Run-Time Control User Guide$$$Control Interface Walkthrough$$$Reading the Configuration of a Stage$$$Control Interface Details£££doc/04_run_time_control_guide/control_interface_walkthrough.html#control-interface-details

This section provides a brief overview of how the control interface works.

Each stage that is included in the generated DSP pipeline has its own state which it will maintain as it processes audio. It also has a structure that contains its configuration parameters. Finally, it has a control state variable which is used to communicate between the DSP and control threads. Threads that wish to read or write to the configuration of a stage use the control API that is discussed above.

For a write command, the controlling thread will check that a command is not ongoing by querying the control state of the stage. If the stage is not processing a control command then the control thread will update the configuration struct for the stage and write to the control state variable that new parameters are available. When the DSP thread next gets an opportunity the stage will see that the parameters have been updated and update its internal state to match. When this is complete the control state variable will be cleared.

For a read command the process is similar. The control thread requests a read by updating the control state variable. The stage will see this and update the configuration struct with the latest value and notify the control thread, via the control state variable, that it has completed the request.

The control API ensures thread safety through the use of the adsp_controller_t struct. As long as each thread uses a unique instance of adsp_controller_t then the control APIs will return ADSP_CONTROL_BUSY if a command that was initialised by another adsp_controller_t is ongoing.

Lib Audio DSP$$$Run-Time Control User Guide$$$Run-Time Control Helper Functions£££doc/04_run_time_control_guide/control_helper.html#run-time-control-helper-functions

Most DSP Stages have fixed point control parameters. To aid conversion from typical tuning units (e.g. decibels) to the correct fixed point format, the helper functions below have been provided.

Lib Audio DSP$$$Run-Time Control User Guide$$$Run-Time Control Helper Functions$$$Biquad helpers£££doc/04_run_time_control_guide/control_helper.html#biquad-helpers

Functions

void adsp_design_biquad_bypass(q2_30 coeffs[5])

Design biquad filter bypass This function creeates a bypass biquad filter. Only the b0 coefficient is set.

Parameters:

coeffs – Bypass filter coefficients

void adsp_design_biquad_mute(q2_30 coeffs[5])

Design mute biquad filter This function creates a mute biquad filter. All the coefficients are 0.

Parameters:

coeffs – Mute filter coefficients

left_shift_t adsp_design_biquad_gain(q2_30 coeffs[5], const float gain_db)

Design gain biquad filter This function creates a biquad filter with a specified gain.

Parameters:

coeffs – Gain filter coefficients
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

void adsp_design_biquad_lowpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)

Design lowpass biquad filter This function creates a biquad filter with a lowpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Lowpass filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_highpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)

Design highpass biquad filter This function creates a biquad filter with a highpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Highpass filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_bandpass(q2_30 coeffs[5], const float fc, const float fs, const float bandwidth)

Design bandpass biquad filter This function creates a biquad filter with a bandpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Bandpass filter coefficients
fc – Central frequency
fs – Sampling frequency
bandwidth – Bandwidth

void adsp_design_biquad_bandstop(q2_30 coeffs[5], const float fc, const float fs, const float bandwidth)

Design bandstop biquad filter This function creates a biquad filter with a bandstop response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Bandstop filter coefficients
fc – Central frequency
fs – Sampling frequency
bandwidth – Bandwidth

void adsp_design_biquad_notch(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)

Design notch biquad filter This function creates a biquad filter with an notch response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Notch filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_allpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)

Design allpass biquad filter This function creates a biquad filter with an allpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Allpass filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q

left_shift_t adsp_design_biquad_peaking(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)

Design peaking biquad filter This function creates a biquad filter with a peaking response fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 18 dB, otherwise the coefficients may overflow. If the gain is greater than 18 dB, it is saturated to that value.

Parameters:

coeffs – Peaking filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_const_q(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)

Design constant Q peaking biquad filter This function creates a biquad filter with a constant Q peaking response.

Constant Q means that the bandwidth of the filter remains constant as the gain varies. It is commonly used for graphic equalisers. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 18 dB, otherwise the coefficients may overflow. If the gain is greater than 18 dB, it is saturated to that value.

Parameters:

coeffs – Constant Q filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_lowshelf(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)

Design lowshelf biquad filter This function creates a biquad filter with a lowshelf response.

The Q factor is defined in a similar way to standard low pass, i.e. Q > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 12 dB, otherwise the coefficients may overflow. If the gain is greater than 12 dB, it is saturated to that value.

Parameters:

coeffs – Lowshelf filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_highshelf(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)

Design highshelf biquad filter This function creates a biquad filter with a highshelf response.

The Q factor is defined in a similar way to standard high pass, i.e. Q > 0.707 will yield peakiness. The level change at f will be boost_db/2. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 12 dB, otherwise the coefficients may overflow. If the gain is greater than 12 dB, it is saturated to that value.

Parameters:

coeffs – Highshelf filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

void adsp_design_biquad_linkwitz(q2_30 coeffs[5], const float f0, const float fs, const float q0, const float fp, const float qp)

Design Linkwitz transform biquad filter This function creates a biquad filter with a Linkwitz transform response.

The Linkwitz Transform is commonly used to change the low frequency roll off slope of a loudspeaker. When applied to a loudspeaker, it will change the cutoff frequency from f0 to fp, and the quality factor from q0 to qp. f0 and fp must be less than fs/2, otherwise they will be saturated to fs/2.

Parameters:

coeffs – Linkwitz filter coefficients
f0 – Original cutoff frequency
fs – Sampling frequency
q0 – Original quality factor at f0
fp – Target cutoff frequency
qp – Target quality factor of the filter

Lib Audio DSP$$$Run-Time Control User Guide$$$Run-Time Control Helper Functions$$$DRC helpers£££doc/04_run_time_control_guide/control_helper.html#drc-helpers

static inline int32_t calc_alpha(float fs, float time)

Convert an attack or release time in seconds to an EWM alpha value as a fixed point int32 number in Q_alpha format. If the desired time is too large or small to be represented in the fixed point format, it is saturated.

Parameters:

fs – sampling frequency in Hz
time – attack/release time in seconds

Returns:

int32_t attack/release alpha as an int32_t

static inline int32_t calculate_peak_threshold(float level_db)

Convert a peak compressor/limiter/expander threshold in decibels to an int32 fixed point gain in Q_SIG Q format. If the threshold is higher than representable in the fixed point format, it is saturated. The minimum threshold returned by this function is 1.

Parameters:

level_db – the desired threshold in decibels

Returns:

int32_t the threshold as a fixed point integer.

static inline int32_t calculate_rms_threshold(float level_db)

Convert an RMS² compressor/limiter/expander threshold in decibels to an int32 fixed point gain in Q_SIG Q format. If the threshold is higher than representable in the fixed point format, it is saturated. The minimum threshold returned by this function is 1.

Parameters:

level_db – the desired threshold in decibels

Returns:

int32_t the threshold as a fixed point integer.

static inline float rms_compressor_slope_from_ratio(float ratio)

Convert a compressor ratio to the slope, where the slope is defined as (1 - 1 / ratio) / 2.0. The division by 2 compensates for the RMS envelope detector returning the RMS². The ratio must be greater than 1, if it is not the ratio is set to 1.

Parameters:

ratio – the desired compressor ratio

Returns:

float slope of the compressor

static inline float peak_expander_slope_from_ratio(float ratio)

Convert an expander ratio to the slope, where the slope is defined as (1 - ratio). The ratio must be greater than 1, if it is not the ratio is set to 1.

Parameters:

ratio – the desired expander ratio

Returns:

float slope of the expander

Lib Audio DSP$$$Run-Time Control User Guide$$$Run-Time Control Helper Functions$$$Reverb helpers£££doc/04_run_time_control_guide/control_helper.html#reverb-helpers

Functions

static inline int32_t adsp_reverb_float2int(float x)

Convert a floating point value to the Q_RVR format, saturate out of range values. Accepted range is 0 to 1.

Parameters:

x – A floating point number, will be capped to [0, 1]

Returns:

Q_RVR int32_t value

static inline int32_t adsp_reverb_db2int(float db)

Convert a floating point gain in decibels into a linear Q_RVR value for use in controlling the reverb gains.

Parameters:

db – Floating point value in dB, values above 0 will be clipped.

Returns:

Q_RVR fixed point linear gain.

static inline int32_t adsp_reverb_calculate_damping(float damping)

Convert a user damping value into a Q_RVR fixed point value suitable for passing to a reverb.

Parameters:

damping – The chose value of damping.

Returns:

Damping as a Q_RVR fixed point integer, clipped to the accepted range.

static inline int32_t adsp_reverb_calculate_feedback(float decay)

Calculate a Q_RVR feedback value for a given decay. Use to calculate the feedback parameter in reverb_room.

Parameters:

decay – The desired decay value.

Returns:

Calculated feedback as a Q_RVR fixed point integer.

static inline int32_t adsp_reverb_room_calc_gain(float gain_db)

Calculate the reverb gain in linear scale.

Will convert a gain in dB to a linear scale in Q_RVR format. To be used for converting wet and dry gains for the room_reverb.

Parameters:

gain_db – Gain in dB

Returns:

int32_t Linear gain in a Q_RVR format

void adsp_reverb_wet_dry_mix(int32_t gains[2], float mix)

Calculate the wet and dry gains according to the mix amount.

When the mix is set to 0, only the dry signal will be output. The wet gain will be 0 and the dry gain will be max. When the mix is set to 1, only they wet signal will be output. The wet gain is max, the dry gain will be 0. In order to maintain a consistent signal level across all mix values, the signals are panned with a -4.5 dB panning law.

Parameters:

gains – Output gains: [0] - Dry; [1] - Wet
mix – Mix applied from 0 to 1

reverb_room_t adsp_reverb_room_init(float fs, float max_room_size, float room_size, float decay, float damping, float wet_gain, float dry_gain, float pregain, float max_predelay, float predelay, void *reverb_heap)

Initialise a reverb room object A room reverb effect based on Freeverb by Jezar at Dreampoint.

Parameters:

fs – Sampling frequency
max_room_size – Maximum room size of delay filters
room_size – Room size compared to the maximum room size [0, 1]
decay – Length of the reverb tail [0, 1]
damping – High frequency attenuation
wet_gain – Wet gain in dB
dry_gain – Dry gain in dB
pregain – Linear pre-gain
max_predelay – Maximum size of the predelay buffer in ms
predelay – Initial predelay in ms
reverb_heap – Pointer to heap to allocate reverb memory

Returns:

reverb_room_t Initialised reverb room object

void adsp_reverb_room_st_calc_wet_gains(int32_t wet_gains[2], float wet_gain, float width)

Calculate the stereo wet gains of the stereo reverb room.

Parameters:

wet_gains – Output linear wet_1 and wet_2 gains in Q_RVR
wet_gain – Input wet gain in dB
width – Stereo separation of the room [0, 1]

void adsp_reverb_st_wet_dry_mix(int32_t gains[3], float mix, float width)

Calculate the stereo wet and dry gains according to the mix amount.

Parameters:

gains – Output gains: [0] - Dry; [1] - Wet_1; [2] - Wet_2
mix – Mix applied from 0 to 1
width – Stereo separation of the room [0, 1]

reverb_room_st_t adsp_reverb_room_st_init(float fs, float max_room_size, float room_size, float decay, float damping, float width, float wet_gain, float dry_gain, float pregain, float max_predelay, float predelay, void *reverb_heap)

Initialise a stereo reverb room object A room reverb effect based on Freeverb by Jezar at Dreampoint.

Parameters:

fs – Sampling frequency
max_room_size – Maximum room size of delay filters
room_size – Room size compared to the maximum room size [0, 1]
decay – Length of the reverb tail [0, 1]
damping – High frequency attenuation
width – Stereo separation of the room [0, 1]
wet_gain – Wet gain in dB
dry_gain – Dry gain in dB
pregain – Linear pre-gain
max_predelay – Maximum size of the predelay buffer in ms
predelay – Initial predelay in ms
reverb_heap – Pointer to heap to allocate reverb memory

Returns:

reverb_room_st_t Initialised stereo reverb room object

Lib Audio DSP$$$Run-Time Control User Guide$$$Run-Time Control Helper Functions$$$Signal chain helpers£££doc/04_run_time_control_guide/control_helper.html#signal-chain-helpers

uint32_t time_to_samples(float fs, float time, time_units_t units)

Convert a time in seconds/milliseconds/samples to samples for a given sampling frequency.

Parameters:

fs – Sampling frequency
time – New delay time in specified units
units – Time units (SAMPLES, MILLISECONDS, SECONDS) . If an invalid unit is passed, SAMPLES is used.

Returns:

uint32_t Time in samples

Copyright © 2024, XMOS Ltd XMOS Ltd. is the owner or licensee of this design, code, or Information (collectively, the “Information”) and is providing it to you “AS IS” with no warranty of any kind, express or implied and shall have no liability in relation to its use. XMOS Ltd makes no representation that the Information, or any particular implementation thereof, is or will be free from any claims of infringement and again, shall have no liability in relation to any such claims. XMOS, XCORE, VocalFusion and the XMOS logo are registered trademarks of XMOS Ltd. in the United Kingdom and other countries and may not be used without written permission. Company and product names mentioned in this document are the trademarks or registered trademarks of their respective owners.