API Reference
This section provides detailed API documentation for all DawDreamer classes and functions.
Core Classes
RenderEngine
- class dawdreamer.RenderEngine(*args, **kwargs)
Bases:
objectA Render Engine loads and runs a graph of audio processors.
- get_audio(self) numpy.ndarray[dtype=float32]
- get_audio(self, name: str) numpy.ndarray[dtype=float32]
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(self, name: str) dawdreamer.ProcessorBase
Get a processor by its unique name. Returns None if not found.
- make_add_processor(self, name: str, gain_levels: collections.abc.Sequence[float] = []) dawdreamer.AddProcessor
Make an Add Processor with an optional list of gain levels
- make_compressor_processor(self, name: str, threshold: float = 0.0, ratio: float = 2.0, attack: float = 2.0, release: float = 50.0) dawdreamer.CompressorProcessor
Make a Compressor Processor
- make_delay_processor(self, name: str, rule: str = 'linear', delay: float = 10.0, wet: float = 0.10000000149011612) dawdreamer.DelayProcessor
Make a Delay Processor
- make_faust_processor(self, name: str) dawdreamer.FaustProcessor
Make a FAUST Processor
- make_filter_processor(self, name: str, mode: str = 'high', freq: float = 1000.0, q: float = 0.7071070075035095, gain: float = 1.0) dawdreamer.FilterProcessor
Make a Filter Processor
- make_oscillator_processor(self, name: str, frequency: float) dawdreamer.OscillatorProcessor
Make an Oscillator Processor
- make_panner_processor(self, name: str, rule: str = 'linear', pan: float = 0.0) dawdreamer.PannerProcessor
Make a Panner Processor
- make_playback_processor(self, name: str, data: ndarray[dtype=float32]) dawdreamer.PlaybackProcessor
Make a Playback Processor
- make_playbackwarp_processor(self, name: str, data: ndarray[dtype=float32], *, sr: float = 0) dawdreamer.PlaybackWarpProcessor
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(self, name: str, plugin_path: str) dawdreamer.PluginProcessor
Make a Plugin Processor
- make_reverb_processor(self, name: str, roomSize: float = 0.5, damping: float = 0.5, wetLevel: float = 0.33000001311302185, dryLevel: float = 0.4000000059604645, width: float = 1.0) dawdreamer.ReverbProcessor
Make a Reverb Processor
- make_sampler_processor(self, name: str, data: ndarray[dtype=float32]) dawdreamer.SamplerProcessor
Make a Sampler Processor with audio data to be used as the sample.
- remove_processor(self, name: str) bool
Remove a processor based on its unique name. Existing Python references to the processor will become invalid.
- render(self, duration: float, *, beats: bool = False) bool
Render the most recently loaded graph. By default, when beats is False, duration is measured in seconds, otherwise beats.
- set_bpm(self, bpm: float) None
- set_bpm(self, bpm: numpy.ndarray[dtype=float32], ppqn: int) bool
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:
objectThe abstract Processor Base class, which all processors subclass.
- get_audio(self) numpy.ndarray[dtype=float32]
Get the audio data of the processor after a render, assuming recording was enabled.
- get_automation(self, parameter_name: str) numpy.ndarray[dtype=float32]
- get_automation(self) dict
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_num_input_channels(self) int
Get the total number of input channels (2 indicates stereo input).
- get_num_output_channels(self) int
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(self, parameter_name: str, data: ndarray[dtype=float32], *, ppqn: int = 0) bool
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:
ProcessorBaseA Faust Processor can compile and execute FAUST code. See https://faust.grame.fr for more information.
- add_midi_note(self, note: int, velocity: int, start_time: float, duration: float, *, beats: bool = False) bool
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”);
- property code
Get the most recently compiled Faust DSP code.
- compile(self) bool
Compile the FAUST object. You must have already set a dsp file path or dsp string.
- compile_box(self, box: dawdreamer.faust.box.Box) bool
- compile_box(self, box: dawdreamer.faust.box.Box, argv: collections.abc.Sequence[str]) bool
- property compile_flags
List of compilation flags.
- compile_from_bitcode(self, bitcode: str) bool
Restore a compiled FAUST object from LLVM bitcode, avoiding recompilation from source. Bitcode can be obtained from the processor’s pickle state dict.
- compile_signals(self, signals: collections.abc.Sequence[dawdreamer.faust.signal.Signal]) bool
- compile_signals(self, signals: collections.abc.Sequence[dawdreamer.faust.signal.Signal], argv: collections.abc.Sequence[str]) bool
- 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_parameters_description(self) list
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(self, filepath: str, *, clear_previous: bool = True, beats: bool = False, all_events: bool = True) bool
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(self, filepath: str) None
After rendering, you can save the MIDI to a file using absolute times (SMPTE format).
- set_dsp_string(self, faust_code: str) bool
Set the FAUST box process with a string containing FAUST code.
PluginProcessor
- class dawdreamer.PluginProcessor
Bases:
ProcessorBaseA 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(self, note: int, velocity: int, start_time: float, duration: float, *, beats: bool = False) bool
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(self, inputs: int, outputs: int) bool
Return bool for whether this combination of input and output channels can be set.
- get_latency_samples(self) int
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_range(self, index: int, search_steps: int = 1000, convert: bool = True) dict[tuple[float, float], float | str]
- 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:
- Returns:
A dictionary holding information about the parameter range.
- Return type:
- get_parameters_description(self) list
Get a list of dictionaries describing the plugin’s parameters.
- get_plugin_parameters_description(self) list
[DEPRECATED: Use get_parameters_description]. Get a list of dictionaries describing the plugin’s parameters.
- load_midi(self, filepath: str, *, clear_previous: bool = True, beats: bool = False, all_events: bool = True) bool
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(self, filepath: str) bool
Load an FXP preset with an absolute filepath and “.fxp” extension.
- load_vst3_preset(self, filepath: str) bool
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.
- save_midi(self, filepath: str) None
After rendering, you can save the MIDI to a file using absolute times (SMPTE format).
- set_automation(self, parameter_index: int, data: ndarray[dtype=float32], *, ppqn: int = 0) bool
Set the automation based on its index.
PlaybackProcessor
- class dawdreamer.PlaybackProcessor
Bases:
ProcessorBaseThe Playback Processor can play audio data provided as an argument.
PlaybackWarpProcessor
- class dawdreamer.PlaybackWarpProcessor
Bases:
ProcessorBaseThe 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
- set_clip_positions(self, clip_positions: collections.abc.Sequence[tuple[float, float, float]]) bool
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(self, data: ndarray[dtype=float32], *, sr: float = 0) None
Set the audio as a numpy array shaped (Channels, Samples) with an optional sr kwarg for the sample rate of the data.
- 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:
ProcessorBaseA 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:
ProcessorBaseA 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:
ProcessorBaseA 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:
ProcessorBaseThe 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:
ProcessorBaseA 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:
ProcessorBaseAn 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:
ProcessorBaseThe 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(self, note: int, velocity: int, start_time: float, duration: float, *, beats: bool = False) bool
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.
- get_data(self) numpy.ndarray[dtype=float32]
Get the audio sample data.
- get_parameters_description(self) list
Get a list of dictionaries describing the plugin’s parameters.
- load_midi(self, filepath: str, *, clear_previous: bool = True, beats: bool = False, all_events: bool = True) bool
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.
OscillatorProcessor
- class dawdreamer.OscillatorProcessor
Bases:
ProcessorBaseA 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:
- dawdreamer.faust.destroyLibContext(context)
Destroy a Faust library context.
- Parameters:
context (FaustContext) – The context to destroy
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 compositionbox1 * box2- Sequential compositionbox1 , box2- Split compositionbox1 : 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 additionsig1 * sig2- Signal multiplicationsig1 - sig2- Signal subtractionsig1 / 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)
)
Further Reading
Faust Processor - Using Faust DSP in DawDreamer