API Reference

This section provides detailed API documentation for all DawDreamer classes and functions.

Core Classes

RenderEngine

class dawdreamer.RenderEngine(*args, **kwargs)

Bases: object

A Render Engine loads and runs a graph of audio processors.

get_audio

Overloaded function.

get_audio(self) -> numpy.ndarray[dtype=float32]

Get the most recently rendered audio as a numpy array.

get_audio(self, name: str) -> numpy.ndarray[dtype=float32]

Get the most recently rendered audio for a specific processor.

get_processor: Get a processor by its unique name. Returns None if not found.

load_graph: Load a directed acyclic graph of processors.

make_add_processor: Make an Add Processor with an optional list of gain levels

make_compressor_processor: Make a Compressor Processor

make_delay_processor: Make a Delay Processor

make_faust_processor: Make a FAUST Processor

make_filter_processor: Make a Filter Processor

make_oscillator_processor: Make an Oscillator Processor

make_panner_processor: Make a Panner Processor

make_playback_processor: Make a Playback Processor

make_playbackwarp_processor: Make a Playback Processor that can do time-stretching and pitch-shifting. The sr kwarg (sample rate of the data) is optional and defaults to the engine’s sample rate.

make_plugin_processor: Make a Plugin Processor

make_reverb_processor: Make a Reverb Processor

make_sampler_processor: Make a Sampler Processor with audio data to be used as the sample.

remove_processor: Remove a processor based on its unique name. Existing Python references to the processor will become invalid.

render: Render the most recently loaded graph. By default, when beats is False, duration is measured in seconds, otherwise beats.

set_bpm

Overloaded function.

set_bpm(self, bpm: float) -> None

Set the beats-per-minute of the engine as a constant rate.

set_bpm(self, bpm: numpy.ndarray[dtype=float32], ppqn: int) -> bool

Set the beats-per-minute of the engine using a 1D numpy array and a constant PPQN. If the values in the array suddenly change every PPQN samples, the tempo change will occur “on-the-beat.”

ProcessorBase

class dawdreamer.ProcessorBase

Bases: object

The abstract Processor Base class, which all processors subclass.

get_audio: Get the audio data of the processor after a render, assuming recording was enabled.

get_automation

Overloaded function.

get_automation(self, parameter_name: str) -> numpy.ndarray[dtype=float32]

Get a parameter’s automation as a numpy array. It should return whatever array was passed previously to set_automation, whether it’s PPQN-rate data or audio-rate data.

parameter_namestr
The name of the parameter.

np.array
The parameter’s automation.
get_automation(self) -> dict

After rendering, get all of a parameter’s automation as a dict of multi-channel numpy arrays. Before rendering, you should have set record_automation to True on the processor. This function uses the engine’s BPM automation, if any, to bake the automation data into audio-rate data.

get_name: Get the user-defined name of a processor instance.

get_num_input_channels: Get the total number of input channels (2 indicates stereo input).

get_num_output_channels: Get the total number of output channels (2 indicates stereo output).

property record: Whether recording of this processor is enabled.

property record_automation: Whether recording of this processor’s automation is enabled.

set_automation

Set a parameter’s automation with a numpy array.

Parameters:

parameter_name (str) – The name of the parameter.
data (np.array) – An array of data for the parameter automation.
ppqn (integer) – If specified, it is the pulses-per-quarter-note rate of the automation data. If not specified or zero, the data will be interpreted at audio rate.

Return type:

None

Processors

FaustProcessor

class dawdreamer.FaustProcessor

Bases: ProcessorBase

A Faust Processor can compile and execute FAUST code. See https://faust.grame.fr for more information.

add_midi_note: Add a single MIDI note whose note and velocity are integers between 0 and 127. By default, when beats is False, the start time and duration are measured in seconds, otherwise beats.

property auto_import: The auto import string. Default is import(“stdfaust.lib”);

clear_midi: Remove all MIDI notes.

property code: Get the most recently compiled Faust DSP code.

compile: Compile the FAUST object. You must have already set a dsp file path or dsp string.

compile_box

property compile_flags: List of compilation flags.

compile_signals

property compiled: Did the most recent DSP code compile?

property dynamic_voices: If enabled (default), voices are dynamically enabled and disabled to save computation. This parameter only matters if polyphony is enabled.

property faust_assets_path: Absolute path to directory containing audio files to be used by Faust.

property faust_assets_paths: List of absolute paths to directories containing audio files to be used by Faust.

property faust_libraries_path: Absolute path to directory containing your custom “.lib” files containing Faust code.

property faust_libraries_paths: List of absolute paths to directories containing your custom “.lib” files containing Faust code.

get_parameter

get_parameters_description: Get a list of dictionaries describing the parameters of the most recently compiled FAUST code.

property group_voices: If grouped, all polyphonic voices will share the same parameters. This parameter only matters if polyphony is enabled.

load_midi: Load MIDI from a file. If all_events is True, then all events (not just Note On/Off) will be loaded. By default, when beats is False, notes will be converted to absolute times and will not be affected by the Render Engine’s BPM. By default, clear_previous is True.

property n_midi_events: The number of MIDI events stored in the buffer. Note that note-ons and note-offs are counted separately.

property num_voices: The number of voices for polyphony. Set to zero to disable polyphony. One or more enables polyphony.

property opt_level: LLVM IR to IR optimization level (from -1 to 4, -1 means ‘maximum possible value’ * since the maximum value may change with new LLVM versions)

property release_length: If using polyphony, specifying the release length accurately can help avoid warnings about voices being stolen.

save_midi: After rendering, you can save the MIDI to a file using absolute times (SMPTE format).

set_dsp: Set the FAUST box process with a file.

set_dsp_string: Set the FAUST box process with a string containing FAUST code.

set_parameter

set_soundfiles: Set the audio data that the FaustProcessor can use with the soundfile primitive.

PluginProcessor

class dawdreamer.PluginProcessor

Bases: ProcessorBase

A Plugin Processor can load VST “.dll” and “.vst3” files on Windows. It can load “.vst”, “.vst3”, and “.component” files on macOS. The files can be for either instruments or effects. Some plugins such as ones that do sidechain compression can accept two inputs when loading a graph.

add_midi_note: Add a single MIDI note whose note and velocity are integers between 0 and 127. By default, when beats is False, the start time and duration are measured in seconds, otherwise beats.

can_set_bus: Return bool for whether this combination of input and output channels can be set.

clear_midi: Remove all MIDI notes.

disable_nonmain_buses: Disable all non-main buses (aux and sidechains).

enable_all_buses: Enable all buses. This may help with plugins with non-stereo outputs.

get_latency_samples: Get the latency measured in samples of the plugin. DawDreamer doesn’t compensate this, so you are encouraged to delay other processors by this amount to compensate. Also, this value depends on the plugin’s parameters, so it can change over time, and the output of this function doesn’t represent that.

get_parameter: Get a parameter’s value.

get_parameter_name: Get a parameter’s name.

get_parameter_range

Return a dictionary with information about the parameter’s range. The dictionary’s keys are tuples of the form (domain1, domain2): where 0<=domain1<domain2<=1. The dictionary’s values can be str if convert is False. Otherwise, they may be floats if the automatic conversion succeeds.

Parameters:

index (int) – The index of the parameter.
search_steps (int) – The number of search steps to use when finding unique text labels the parameter can display.
convert (bool) – Whether to try to automatically convert the text to floats.

Returns:

A dictionary holding information about the parameter range.

Return type:

dict

get_parameter_text: Get a parameter’s value as text.

get_parameters_description: Get a list of dictionaries describing the plugin’s parameters.

get_patch

get_plugin_parameter_size: Get the number of parameters.

get_plugin_parameters_description

Use get_parameters_description]. Get a list of dictionaries describing the plugin’s parameters.

Type:: [DEPRECATED

load_midi: Load MIDI from a file. If all_events is True, then all events (not just Note On/Off) will be loaded. By default, when beats is False, notes will be converted to absolute times and will not be affected by the Render Engine’s BPM. By default, clear_previous is True.

load_preset: Load an FXP preset with an absolute filepath and “.fxp” extension.

load_state: Load the state from a file.

load_vst3_preset: Load a VST3 preset with an absolute filepath and “.vstpreset” extension.

property n_midi_events: The number of MIDI events stored in the buffer. Note that note-ons and note-offs are counted separately.

open_editor: Open the UI editor for the plugin.

save_midi: After rendering, you can save the MIDI to a file using absolute times (SMPTE format).

save_state: Save the state to a file.

set_automation: Set the automation based on its index.

set_bus: Set the number of input and output channels. An error will be thrown for an unaccepted option.

set_parameter: Set a parameter’s value to a constant.

set_patch

PlaybackProcessor

class dawdreamer.PlaybackProcessor

Bases: ProcessorBase

The Playback Processor can play audio data provided as an argument.

set_data: Set the audio as a numpy array shaped (Channels, Samples).

PlaybackWarpProcessor

class dawdreamer.PlaybackWarpProcessor

Bases: ProcessorBase

The Playback Warp Processor can play audio data while time-stretching and pitch-shifting it thanks to the Rubberband library (https://github.com/breakfastquay/rubberband). This processor can load Ableton Live “.asd” files to do beat-matching.

property end_marker: The end position in beats (typically quarter notes) relative to 1.1.1

property loop_end: The loop end position in beats (typically quarter notes) relative to 1.1.1

property loop_on: Whether looping is enabled

property loop_start: The loop start position in beats (typically quarter notes) relative to 1.1.1

class option(value)

Bases: IntEnum

OptionChannelsApart = 0

OptionChannelsTogether = 268435456

OptionDetectorCompound = 0

OptionDetectorPercussive = 1024

OptionDetectorSoft = 2048

OptionFormantPreserved = 16777216

OptionFormantShifted = 0

OptionPhaseIndependent = 8192

OptionPhaseLaminar = 0

OptionPitchHighConsistency = 67108864

OptionPitchHighQuality = 33554432

OptionPitchHighSpeed = 0

OptionSmoothingOff = 0

OptionSmoothingOn = 8388608

OptionTransientsCrisp = 0

OptionTransientsMixed = 256

OptionTransientsSmooth = 512

OptionWindowLong = 2097152

OptionWindowShort = 1048576

OptionWindowStandard = 0

reset_options: Set Rubber Band’s stretcher’s options to DawDreamer’s default.

reset_warp_markers: Reset the warp markers with a BPM.

set_clip_file: Load an Ableton Live file with an “.asd” extension

set_clip_positions

Set one or more positions at which the clip should play.

Parameters:: clip_positions (list) – A list of length-3 lists. Each length-3 list consists of a global clip start time, a global clip start end time, and a local start offset.
Return type:: None

set_data: Set the audio as a numpy array shaped (Channels, Samples) with an optional sr kwarg for the sample rate of the data.

set_options: Config Rubber Band’s stretcher with an enum option.

property start_marker: The start position in beats (typically quarter notes) relative to 1.1.1

property time_ratio: The time ratio has an effect if an Ableton ASD file hasn’t been loaded or if warp_on is false. A value of 2.0 for the time ratio will play the audio in double the amount of time, so it will sound slowed down.

property transpose: The pitch transposition in semitones

property warp_markers: Get/set the warp markers as an (N, 2) numpy array of time positions in samples and positions in beats.

property warp_on: Whether warping is enabled.

FilterProcessor

class dawdreamer.FilterProcessor

Bases: ProcessorBase

A Filter Processor applies one of several kinds of filters. The filter cutoff, Q-value and gain can be adjusted, but the filter mode cannot under automation.

property frequency: The frequency cutoff in Hz.

property gain: The gain parameter only matters when the mode is low_shelf or high_shelf. A value of 1.0 has no effect.

property mode: Choose from “low”, “high”, “band”, “low_shelf”, “high_shelf”, “notch”.

property q: The Q-value. A safe choice is 1./rad(2)=0.707107.

CompressorProcessor

class dawdreamer.CompressorProcessor

Bases: ProcessorBase

A compressor from JUCE.

property attack: The compressor’s attack in millisecods.

property ratio: The ratio of the compressor. It must be greater than or equal to 1.0.

property release: The compressor’s release in millisecods.

property threshold: The compressor’s threshold in decibels.

ReverbProcessor

class dawdreamer.ReverbProcessor

Bases: ProcessorBase

A Reverb Processor applies reverb with the FreeVerb algorithm.

property damping: The damping amount between 0.0 and 1.0.

property dry_level: A dry level between 0.0 and 1.0.

property room_size: The room size between 0.0 and 1.0.

property wet_level: A wet level between 0.0 and 1.0.

property width: The stereo width from 0.0 to 1.0.

PannerProcessor

class dawdreamer.PannerProcessor

Bases: ProcessorBase

The Panner Processor class

property pan: The pan value between -1.0 and 1.0.

property rule: The rule must be among “linear”, “balanced”, “sin3dB”, “sin4p5dB”, “sin6dB”, “squareRoot3dB”, “squareRoot4p5dB.”

DelayProcessor

class dawdreamer.DelayProcessor

Bases: ProcessorBase

A delay from JUCE.

property delay: The delay in milliseconds.

property wet: A wet level between 0.0 and 1.0.

AddProcessor

class dawdreamer.AddProcessor

Bases: ProcessorBase

An Add Processor adds one or more stereo inputs with corresponding gain parameters.

property gain_levels: A list of gain levels to apply to the corresponding inputs.

SamplerProcessor

class dawdreamer.SamplerProcessor

Bases: ProcessorBase

The Sampler Processor works like a basic Sampler instrument. It takes a typically short audio sample and can play it back at different pitches and speeds. It has parameters for an ADSR envelope controlling the amplitude and another for controlling a low-pass filter cutoff. Unlike a VST, the parameters don’t need to be between 0 and 1. For example, you can set an envelope attack parameter to 50 to represent 50 milliseconds.

add_midi_note: Add a single MIDI note whose note and velocity are integers between 0 and 127. By default, when beats is False, the start time and duration are measured in seconds, otherwise beats.

clear_midi: Remove all MIDI notes.

get_data: Get the audio sample data.

get_parameter: Get a parameter’s value.

get_parameter_name: Get a parameter’s name.

get_parameter_size: Get the number of parameters.

get_parameter_text: Get a parameter’s value as text.

get_parameters_description: Get a list of dictionaries describing the plugin’s parameters.

load_midi: Load MIDI from a file. If all_events is True, then all events (not just Note On/Off) will be loaded. By default, when beats is False, notes will be converted to absolute times and will not be affected by the Render Engine’s BPM. By default, clear_previous is True.

property n_midi_events: The number of MIDI events stored in the buffer. Note that note-ons and note-offs are counted separately.

save_midi: After rendering, you can save the MIDI to a file using absolute times (SMPTE format).

set_data: Set an audio sample.

set_parameter: Set a parameter’s value to a constant.

OscillatorProcessor

class dawdreamer.OscillatorProcessor

Bases: ProcessorBase

A simple sine oscillator, mainly for testing.

Faust API

DawDreamer includes Python bindings for Faust’s Box and Signal APIs, allowing programmatic construction of DSP graphs.

The Faust APIs provide two complementary approaches to building audio processors:

Box API: High-level, component-based approach for building audio processors
Signal API: Low-level, signal-processing approach for fine-grained control

See the Faust Box API Example for practical usage.

Faust Module

The main dawdreamer.faust module provides:

class dawdreamer.faust.FaustContext: Context manager for Faust compilation and execution.

dawdreamer.faust.createLibContext()

Create a Faust library context.

Returns:: Faust library context
Return type:: FaustContext

dawdreamer.faust.destroyLibContext(context)

Destroy a Faust library context.

Parameters:: context (FaustContext) – The context to destroy

dawdreamer.faust.boxToSignals(box)

Convert a Box to Signal representation.

Parameters:: box (Box) – A Faust Box object
Returns:: List of Signal objects
Return type:: list[Signal]

Faust Box API

The Box API provides a functional, component-based approach to building audio processors.

Core Types:

class dawdreamer.faust.box.Box

Base class for all Faust Box objects. Boxes can be combined using standard operators.

Operators:

box1 + box2 - Parallel composition
box1 * box2 - Sequential composition
box1 , box2 - Split composition
box1 : box2 - Sequential composition (alternative syntax)

class dawdreamer.faust.box.SType: Signal type enumeration for Faust boxes.

Box Construction Functions:

Audio Primitives

dawdreamer.faust.box.boxInt(n): Create an integer constant box.

dawdreamer.faust.box.boxReal(x): Create a real (float) constant box.

dawdreamer.faust.box.boxWire(): Create a wire (identity) box that passes input to output unchanged.

dawdreamer.faust.box.boxCut(): Create a cut box that terminates a signal.

Math Operations

dawdreamer.faust.box.boxAdd(box1, box2): Addition: box1 + box2

dawdreamer.faust.box.boxSub(box1, box2): Subtraction: box1 - box2

dawdreamer.faust.box.boxMul(box1, box2): Multiplication: box1 * box2

dawdreamer.faust.box.boxDiv(box1, box2): Division: box1 / box2

dawdreamer.faust.box.boxAbs(box): Absolute value: abs(box)

Trigonometric Functions

dawdreamer.faust.box.boxSin(box): Sine function

dawdreamer.faust.box.boxCos(box): Cosine function

dawdreamer.faust.box.boxTan(box): Tangent function

dawdreamer.faust.box.boxAsin(box): Arcsine function

dawdreamer.faust.box.boxAcos(box): Arccosine function

dawdreamer.faust.box.boxAtan(box): Arctangent function

dawdreamer.faust.box.boxAtan2(box1, box2): Two-argument arctangent

Delay and Memory

dawdreamer.faust.box.boxDelay(): Create a one-sample delay

dawdreamer.faust.box.boxIntCast(box): Cast to integer

dawdreamer.faust.box.boxFloatCast(box): Cast to float

User Interface Elements

dawdreamer.faust.box.boxButton(label): Create a button UI element

dawdreamer.faust.box.boxCheckbox(label): Create a checkbox UI element

dawdreamer.faust.box.boxVSlider(label, init, min, max, step): Create a vertical slider

dawdreamer.faust.box.boxHSlider(label, init, min, max, step): Create a horizontal slider

dawdreamer.faust.box.boxNumEntry(label, init, min, max, step): Create a numeric entry field

dawdreamer.faust.box.boxVBargraph(label, min, max): Create a vertical bargraph (output display)

dawdreamer.faust.box.boxHBargraph(label, min, max): Create a horizontal bargraph (output display)

Example:

import dawdreamer as daw
from dawdreamer.faust import box

# Create a simple oscillator with volume control
freq = box.boxHSlider("frequency", 440, 20, 20000, 1)
gain = box.boxHSlider("volume", 0.5, 0, 1, 0.01)

# Build the signal chain
osc = box.boxSin(freq)
output = box.boxMul(osc, gain)

# Convert to Faust DSP string and use in processor
# (See examples/Box_API for complete usage)

Faust Signal API

The Signal API provides low-level signal processing primitives.

class dawdreamer.faust.signal.Signal

Base class for Faust Signal objects representing audio signals.

Operators:

sig1 + sig2 - Signal addition
sig1 * sig2 - Signal multiplication
sig1 - sig2 - Signal subtraction
sig1 / sig2 - Signal division

Signal Construction Functions:

dawdreamer.faust.signal.sigInt(n): Create an integer constant signal

dawdreamer.faust.signal.sigReal(x): Create a real (float) constant signal

dawdreamer.faust.signal.sigInput(n): Reference the nth input signal

dawdreamer.faust.signal.sigDelay(sig, delay): Delay a signal by specified samples

dawdreamer.faust.signal.sigIntCast(sig): Cast signal to integer

dawdreamer.faust.signal.sigFloatCast(sig): Cast signal to float

Example:

import dawdreamer as daw
from dawdreamer.faust import signal as sig

# Create a simple delay effect
input_sig = sig.sigInput(0)
delay_time = sig.sigInt(4410)  # 100ms at 44.1kHz
delayed = sig.sigDelay(input_sig, delay_time)

# Mix dry and wet
dry_gain = sig.sigReal(0.7)
wet_gain = sig.sigReal(0.3)
output = sig.sigAdd(
    sig.sigMul(input_sig, dry_gain),
    sig.sigMul(delayed, wet_gain)
)

API Reference

Core Classes

RenderEngine

ProcessorBase

Processors

FaustProcessor

PluginProcessor

PlaybackProcessor

PlaybackWarpProcessor

FilterProcessor

CompressorProcessor

ReverbProcessor

PannerProcessor

DelayProcessor

AddProcessor

SamplerProcessor

OscillatorProcessor

Faust API

Faust Module

Faust Box API

Audio Primitives

Math Operations

Trigonometric Functions

Delay and Memory

User Interface Elements

Faust Signal API

Further Reading

Indices and Tables