The pedalboard API#

This module provides classes and functions for adding effects to audio. Most classes in this module are subclasses of Plugin, each of which allows applying effects to an audio buffer or stream.

For audio I/O classes (i.e.: reading and writing audio files), see pedalboard.io.

class pedalboard.AudioUnitPlugin(path_to_plugin_file: str, parameter_values: Dict[str, Union[str, int, float, bool]] = {}, plugin_name: Optional[str] = None)#

A wrapper around third-party, non-Pedalboard audio effects plugins in Apple’s Audio Unit format.

Audio Unit plugins are only supported on macOS. This class will be unavailable on non-macOS platforms. Plugin files must be installed in the appropriate system-wide path for them to be loadable (usually /Library/Audio/Plug-Ins/Components/ or ~/Library/Audio/Plug-Ins/Components/).

For a plugin wrapper that works on Windows and Linux as well, see pedalboard.VST3Plugin.

static get_plugin_names_for_file(filename: str) List[str]#

Return a list of plugin names contained within a given Audio Unit bundle (i.e.: a .component file). If the provided file cannot be scanned, an ImportError will be raised.

Note that most Audio Units have a single plugin inside, but this method can be useful to determine if multiple plugins are present in one bundle, and if so, what their names are.

property name#

The name of this plugin, as reported by the plugin itself.

process(self: pedalboard_native.Plugin, input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[numpy.float32]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset(self: pedalboard_native.Plugin) None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

show_editor(self: pedalboard_native._AudioUnitPlugin) None#

Show the UI of this plugin as a native window. This method will block until the window is closed or a KeyboardInterrupt is received.

class pedalboard.Bitcrush(bit_depth: float = 8)#

A plugin that reduces the signal to a given bit depth, giving the audio a lo-fi, digitized sound. Floating-point bit depths are supported.

Bitcrushing changes the amount of “vertical” resolution used for an audio signal (i.e.: how many unique values could be used to represent each sample). For an effect that changes the “horizontal” resolution (i.e.: how many samples are available per second), see pedalboard.Resample.

property bit_depth: float#

The bit depth to quantize the signal to. Must be between 0 and 32 bits. May be an integer, decimal, or floating-point value. Each audio sample will be quantized onto 2 ** bit_depth values.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Chain#

Run zero or more plugins as a plugin. Useful when used with the Mix plugin.

append(self: pedalboard_native.PluginContainer, arg0: pedalboard_native.Plugin) None#
insert(self: pedalboard_native.PluginContainer, index: int, plugin: pedalboard_native.Plugin) None#
process(*args, **kwargs)#

Overloaded function.

  1. process(self: pedalboard_native.utils.Chain, input_array: numpy.ndarray[numpy.float32], sample_rate: float, buffer_size: int = 8192, reset: bool = True) -> numpy.ndarray[numpy.float32]

Run a 32-bit floating point audio buffer through this plugin.(Note: if calling this multiple times with multiple plugins, consider using pedalboard.process(…) instead.)

  1. process(self: pedalboard_native.utils.Chain, input_array: numpy.ndarray[numpy.float64], sample_rate: float, buffer_size: int = 8192, reset: bool = True) -> numpy.ndarray[numpy.float32]

Run a 64-bit floating point audio buffer through this plugin.(Note: if calling this multiple times with multiple plugins, consider using pedalboard.process(…) instead.) The buffer will be converted to 32-bit for processing.

remove(self: pedalboard_native.PluginContainer, plugin: pedalboard_native.Plugin) None#
reset(self: pedalboard_native.Plugin) None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Chorus(rate_hz: float = 1.0, depth: float = 0.25, centre_delay_ms: float = 7.0, feedback: float = 0.0, mix: float = 0.5)#

A basic chorus effect.

This audio effect can be controlled via the speed and depth of the LFO controlling the frequency response, a mix control, a feedback control, and the centre delay of the modulation.

Note: To get classic chorus sounds try to use a centre delay time around 7-8 ms with a low feeback volume and a low depth. This effect can also be used as a flanger with a lower centre delay time and a lot of feedback, and as a vibrato effect if the mix value is 1.

property rate_hz: float#

The speed of the chorus effect’s low-frequency oscillator (LFO), in Hertz. This value must be between 0 Hz and 100 Hz.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Compressor(threshold_db: float = 0, ratio: float = 1, attack_ms: float = 1.0, release_ms: float = 100)#

A dynamic range compressor, used to reduce the volume of loud sounds and “compress” the loudness of the signal.

For a lossy compression algorithm that introduces noise or artifacts, see pedalboard.MP3Compressor or pedalboard.GSMCompressor.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Convolution(impulse_response_filename: str, mix: float = 1.0)#

An audio convolution, suitable for things like speaker simulation or reverb modeling.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Delay(delay_seconds: float = 0.5, feedback: float = 0.0, mix: float = 0.5)#

A digital delay plugin with controllable delay time, feedback percentage, and dry/wet mix.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Distortion(drive_db: float = 25)#

A distortion effect, which applies a non-linear (tanh, or hyperbolic tangent) waveshaping function to apply harmonically pleasing distortion to a signal.

This plugin produces a signal that is roughly equivalent to running: def distortion(x): return tanh(x * db_to_gain(drive_db))

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.GSMFullRateCompressor(quality: pedalboard.Resample.Quality = Quality.WindowedSinc)#

An audio degradation/compression plugin that applies the GSM “Full Rate” compression algorithm to emulate the sound of a 2G cellular phone connection. This plugin internally resamples the input audio to a fixed sample rate of 8kHz (required by the GSM Full Rate codec), although the quality of the resampling algorithm can be specified.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Gain(gain_db: float = 1.0)#

A gain plugin that increases or decreases the volume of a signal by amplifying or attenuating it by the provided value (in decibels). No distortion or other effects are applied.

Think of this as a volume control.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.HighShelfFilter(cutoff_frequency_hz: float = 440, gain_db: float = 0.0, q: float = 0.7071067690849304)#

A high shelf filter plugin with variable Q and gain, as would be used in an equalizer. Frequencies above the cutoff frequency will be boosted (or cut) by the provided gain (in decibels).

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.HighpassFilter(cutoff_frequency_hz: float = 50)#

Apply a first-order high-pass filter with a roll-off of 6dB/octave. The cutoff frequency will be attenuated by -3dB (i.e.: \(\frac{1}{\sqrt{2}}\) as loud, expressed as a gain factor) and lower frequencies will be attenuated by a further 6dB per octave.)

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.IIRFilter#

An abstract class that implements various kinds of infinite impulse response (IIR) filter designs. This should not be used directly; use HighShelfFilter, LowShelfFilter, or PeakFilter directly instead.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Invert#

Flip the polarity of the signal. This effect is not audible on its own and takes no parameters. This effect is mathematically identical to def invert(x): return -x.

Inverting a signal may be useful to cancel out signals in many cases; for instance, Invert can be used with the Mix plugin to remove the original signal from an effects chain that contains multiple signals.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.LadderFilter(mode: pedalboard.LadderFilter.Mode = Mode.LPF12, cutoff_hz: float = 200, resonance: float = 0, drive: float = 1.0)#

A multi-mode audio filter based on the classic Moog synthesizer ladder filter, invented by Dr. Bob Moog in 1968.

Depending on the filter’s mode, frequencies above, below, or on both sides of the cutoff frequency will be attenuated. Higher values for the resonance parameter may cause peaks in the frequency response around the cutoff frequency.

class Mode(value)#

The type of filter architecture to use.

LPF12 = 0#

A low-pass filter with 12 dB of attenuation per octave above the cutoff frequency.

HPF12 = 1#

A high-pass filter with 12 dB of attenuation per octave below the cutoff frequency.

BPF12 = 2#

A band-pass filter with 12 dB of attenuation per octave on both sides of the cutoff frequency.

LPF24 = 3#

A low-pass filter with 24 dB of attenuation per octave above the cutoff frequency.

HPF24 = 4#

A high-pass filter with 24 dB of attenuation per octave below the cutoff frequency.

BPF24 = 5#

A band-pass filter with 24 dB of attenuation per octave on both sides of the cutoff frequency.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Limiter(threshold_db: float = - 10.0, release_ms: float = 100.0)#

A simple limiter with standard threshold and release time controls, featuring two compressors and a hard clipper at 0 dB.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.LowShelfFilter(cutoff_frequency_hz: float = 440, gain_db: float = 0.0, q: float = 0.7071067690849304)#

A low shelf filter with variable Q and gain, as would be used in an equalizer. Frequencies below the cutoff frequency will be boosted (or cut) by the provided gain value.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.LowpassFilter(cutoff_frequency_hz: float = 50)#

Apply a first-order low-pass filter with a roll-off of 6dB/octave. The cutoff frequency will be attenuated by -3dB (i.e.: 0.707x as loud).

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.MP3Compressor(vbr_quality: float = 2.0)#

An MP3 compressor plugin that runs the LAME MP3 encoder in real-time to add compression artifacts to the audio stream.

Currently only supports variable bit-rate mode (VBR) and accepts a floating-point VBR quality value (between 0.0 and 12.0; lower is better).

Note that the MP3 format only supports 32kHz, 44.1kHz, and 48kHz audio; if an unsupported sample rate is provided, an exception will be thrown at processing time.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Mix#

A utility plugin that allows running other plugins in parallel. All plugins provided will be mixed equally.

append(self: pedalboard_native.PluginContainer, arg0: pedalboard_native.Plugin) None#
insert(self: pedalboard_native.PluginContainer, index: int, plugin: pedalboard_native.Plugin) None#
process(self: pedalboard_native.Plugin, input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[numpy.float32]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

remove(self: pedalboard_native.PluginContainer, plugin: pedalboard_native.Plugin) None#
reset(self: pedalboard_native.Plugin) None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.NoiseGate(threshold_db: float = - 100.0, ratio: float = 10, attack_ms: float = 1.0, release_ms: float = 100.0)#

A simple noise gate with standard threshold, ratio, attack time and release time controls. Can be used as an expander if the ratio is low.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.PeakFilter(cutoff_frequency_hz: float = 440, gain_db: float = 0.0, q: float = 0.7071067690849304)#

A peak (or notch) filter with variable Q and gain, as would be used in an equalizer. Frequencies around the cutoff frequency will be boosted (or cut) by the provided gain value.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Pedalboard(plugins: Optional[List[pedalboard_native.Plugin]] = None)#

A container for a chain of plugins, to use for processing audio.

append(self: pedalboard_native.PluginContainer, arg0: pedalboard_native.Plugin) None#
insert(self: pedalboard_native.PluginContainer, index: int, plugin: pedalboard_native.Plugin) None#
process(*args, **kwargs)#

Overloaded function.

  1. process(self: pedalboard_native.utils.Chain, input_array: numpy.ndarray[numpy.float32], sample_rate: float, buffer_size: int = 8192, reset: bool = True) -> numpy.ndarray[numpy.float32]

Run a 32-bit floating point audio buffer through this plugin.(Note: if calling this multiple times with multiple plugins, consider using pedalboard.process(…) instead.)

  1. process(self: pedalboard_native.utils.Chain, input_array: numpy.ndarray[numpy.float64], sample_rate: float, buffer_size: int = 8192, reset: bool = True) -> numpy.ndarray[numpy.float32]

Run a 64-bit floating point audio buffer through this plugin.(Note: if calling this multiple times with multiple plugins, consider using pedalboard.process(…) instead.) The buffer will be converted to 32-bit for processing.

remove(self: pedalboard_native.PluginContainer, plugin: pedalboard_native.Plugin) None#
reset(self: pedalboard_native.Plugin) None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Phaser(rate_hz: float = 1.0, depth: float = 0.5, centre_frequency_hz: float = 1300.0, feedback: float = 0.0, mix: float = 0.5)#

A 6 stage phaser that modulates first order all-pass filters to create sweeping notches in the magnitude frequency response. This audio effect can be controlled with standard phaser parameters: the speed and depth of the LFO controlling the frequency response, a mix control, a feedback control, and the centre frequency of the modulation.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.PitchShift(semitones: float = 0.0)#

A pitch shifting effect that can change the pitch of audio without affecting its duration.

This effect uses Chris Cannam’s wonderful *Rubber Band* library audio stretching library.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Plugin#

A generic audio processing plugin. Base class of all Pedalboard plugins.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.PluginContainer(plugins: List[pedalboard.Plugin])#

A generic audio processing plugin that contains zero or more other plugins. Not intended for direct use.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.Resample(target_sample_rate: float = 8000.0, quality: pedalboard.Resample.Quality = Quality.WindowedSinc)#

A plugin that downsamples the input audio to the given sample rate, then upsamples it back to the original sample rate. Various quality settings will produce audible distortion and aliasing effects.

class Quality(value)#

Indicates a specific resampling algorithm to use.

ZeroOrderHold = 0#

The lowest quality and fastest resampling method, with lots of audible artifacts.

Linear = 1#

A resampling method slightly less noisy than the simplest method, but not by much.

CatmullRom = 2#

A moderately good-sounding resampling method which is fast to run.

Lagrange = 3#

A moderately good-sounding resampling method which is slow to run.

WindowedSinc = 4#

The highest quality and slowest resampling method, with no audible artifacts.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

property quality: pedalboard.Resample.Quality#

The resampling algorithm used to resample the audio.

property target_sample_rate: float#

The sample rate to resample the input audio to. This value may be a floating-point number, in which case a floating-point sampling rate will be used. Note that the output of this plugin will still be at the original sample rate; this is merely the sample rate used for quality reduction.

class pedalboard.Reverb(room_size: float = 0.5, damping: float = 0.5, wet_level: float = 0.33, dry_level: float = 0.4, width: float = 1.0, freeze_mode: float = 0.0)#

A simple reverb effect. Uses a simple stereo reverb algorithm, based on the technique and tunings used in FreeVerb <https://ccrma.stanford.edu/~jos/pasp/Freeverb.html>_.

process(input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.float32]]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset() None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

class pedalboard.VST3Plugin(path_to_plugin_file: str, parameter_values: Dict[str, Union[str, int, float, bool]] = {}, plugin_name: Optional[str] = None)#

A wrapper around third-party, non-Pedalboard audio effects plugins in Steinberg GmbH’s VST3® format.

VST3® plugins are supported on macOS, Windows, and Linux. However, VST3® plugin files are not cross-compatible with different operating systems; a platform-specific build of each plugin is required to load that plugin on a given platform. (For example: a Windows VST3 plugin bundle will not load on Linux or macOS.)

static get_plugin_names_for_file(arg0: str) List[str]#

Return a list of plugin names contained within a given VST3 plugin (i.e.: a “.vst3”). If the provided file cannot be scanned, an ImportError will be raised.

load_preset(self: pedalboard_native._VST3Plugin, preset_file_path: str) None#

Load a VST3 preset file in .vstpreset format.

property name#

The name of this plugin.

process(self: pedalboard_native.Plugin, input_array: numpy.ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) numpy.ndarray[numpy.float32]#

Run a 32-bit or 64-bit floating point audio buffer through this plugin. (If calling this multiple times with multiple plugins, consider creating a pedalboard.Pedalboard object instead.)

The returned array may contain up to (but not more than) the same number of samples as were provided. If fewer samples were returned than expected, the plugin has likely buffered audio inside itself. To receive the remaining audio, pass another audio buffer into process with reset set to True.

If the provided buffer uses a 64-bit datatype, it will be converted to 32-bit for processing.

The provided buffer_size argument will be used to control the size of each chunk of audio provided to the plugin. Higher buffer sizes may speed up processing at the expense of memory usage.

The reset flag determines if all of the plugins should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio file or buffer, set reset to False.

reset(self: pedalboard_native.Plugin) None#

Clear any internal state stored by this plugin (e.g.: reverb tails, delay lines, LFO state, etc). The values of plugin parameters will remain unchanged.

show_editor(self: pedalboard_native._VST3Plugin) None#

Show the UI of this plugin as a native window. This method will block until the window is closed or a KeyboardInterrupt is received.

pedalboard.load_plugin(path_to_plugin_file: str, parameter_values: Dict[str, Union[str, int, float, bool]] = {}, plugin_name: Optional[str] = None) pedalboard.pedalboard.ExternalPlugin#

Load an audio plugin.

Two plugin formats are supported:
  • VST3® format is supported on macOS, Windows, and Linux

  • Audio Units are supported on macOS

Parameters
  • path_to_plugin_file (str) – The path of a VST3® or Audio Unit plugin file or bundle.

  • parameter_values (Dict[str, Union[str, int, float, bool]]) – An optional dictionary of initial values to provide to the plugin after loading. Keys in this dictionary are expected to match the parameter names reported by the plugin, but normalized to strings that can be used as Python identifiers. (These are the same identifiers that are used as keys in the .parameters dictionary of a loaded plugin.)

  • plugin_name (Optional[str]) – An optional plugin name that can be used to load a specific plugin from a multi-plugin package. If a package is loaded but a plugin_name is not provided, an exception will be thrown.

Returns

an instance of pedalboard.VST3Plugin` or pedalboard.AudioUnitPlugin

Throws:

ImportError: if the plugin cannot be found or loaded

RuntimeError: if the plugin file contains more than one plugin, but no plugin_name was provided