The pedalboard API

class pedalboard.AudioProcessorParameter(plugin: ExternalPlugin, parameter_name: str, search_steps: int = 1000)#

A wrapper around various different parameters exposed by VST3Plugin or AudioUnitPlugin instances.

AudioProcessorParameter objects are rarely used directly, and usually used via their implicit interface:

my_plugin = load_plugin("My Cool Audio Effect.vst3")
# Print all of the parameter names:
print(my_plugin.parameters.keys())
# ["mix", "delay_time_ms", "foobar"]
# Access each parameter as if it were just a Python attribute:
my_plugin.mix = 0.5
my_plugin.delay_time_ms = 400

Note

AudioProcessorParameter tries to guess the range of valid parameter values, as well as the type/unit of the parameter, when instantiated. This guess may not always be accurate. Raw control over the underlying parameter’s value can be had by accessing the raw_value attribute, which is always bounded on [0, 1] and is passed directly to the underlying plugin object.

property label: Optional[str]#

The units used by this parameter (Hz, dB, etc).

May be None if the plugin does not expose units for this parameter or if automatic unit detection fails.

property units: Optional[str]#

Alias for “label” - the units used by this parameter (Hz, dB, etc).

May be None if the plugin does not expose units for this parameter or if automatic unit detection fails.

class pedalboard.ExternalPlugin#

A wrapper around a third-party effect plugin.

Don’t use this directly; use one of pedalboard.VST3Plugin or pedalboard.AudioUnitPlugin instead.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#
__call__(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]: Run an audio or MIDI buffer through this plugin, returning audio. Alias for process().

process(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#

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

Pass a buffer of audio (as a 32- or 64-bit NumPy array) or a list of MIDI messages to this plugin, returning audio.

(If calling this multiple times with multiple effect plugins, consider creating a pedalboard.Pedalboard object instead.)

When provided audio as input, 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.

If provided MIDI messages as input, the provided midi_messages must be a Python List containing one of the following types:

Objects with a bytes() method and time property (such as mido:messages from Mido - MIDI Objects for Python, not included with Pedalboard)

Tuples that look like: (midi_bytes: bytes, timestamp_in_seconds: float)

Tuples that look like: (midi_bytes: List[int], timestamp_in_seconds: float)

The returned array will contain duration seconds worth of audio at the provided sample_rate.

Each MIDI message will be sent to the plugin at its timestamp, where a timestamp of 0 indicates the start of the buffer, and a timestamp equal to duration indicates the end of the buffer. (Any MIDI messages whose timestamps are greater than duration will be ignored.)

The provided buffer_size argument will be used to control the size of each chunk of audio returned by the plugin at once. Higher buffer sizes may speed up processing, but may cause increased memory usage.

The reset flag determines if this plugin should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio or MIDI stream, set reset to False.

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

Examples

Running audio through an external effect plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_effect
with AudioFile("input-audio.wav") as f:
    output_audio = plugin(f.read(), f.samplerate)

Rendering MIDI via an external instrument plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile
from mido import Message # not part of Pedalboard, but convenient!

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_instrument

sample_rate = 44100
num_channels = 2
with AudioFile("output-audio.wav", "w", sample_rate, num_channels) as f:
    f.write(plugin(
        [Message("note_on", note=60), Message("note_off", note=60, time=4)],
        sample_rate=sample_rate,
        duration=5,
        num_channels=num_channels
    ))

Support for instrument plugins introduced in v0.7.4.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

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[Plugin]] = None)#

A container for a series of Plugin objects, to use for processing audio, like a guitar pedalboard.

Pedalboard objects act like regular Python List objects, but come with an additional process() method (also aliased to __call__()), allowing audio to be passed through the entire Pedalboard object for processing:

my_pedalboard = Pedalboard()
my_pedalboard.append(Reverb())
output_audio = my_pedalboard(input_audio)

Warning

Pedalboard objects may only contain effects plugins (i.e.: those for which is_effect is True), and cannot contain instrument plugins (i.e.: those for which is_instrument is True).

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

append(plugin: Plugin) → None#: Append a plugin to the end of this container.

insert(index: int, plugin: Plugin) → None#: Insert a plugin at the specified index.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

remove(plugin: Plugin) → None#: Remove a plugin by its value.

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.

pedalboard.load_plugin(path_to_plugin_file: str, parameter_values: Dict[str, Union[str, int, float, bool]] = {}, plugin_name: Optional[str] = None, initialization_timeout: float = 10.0) → 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.
initialization_timeout (float) –
The number of seconds that Pedalboard will spend trying to load this plugin. Some plugins load resources asynchronously in the background on startup; using larger values for this parameter can give these plugins time to load properly.

Introduced in v0.7.6.

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

class pedalboard.AudioUnitPlugin(path_to_plugin_file: str, parameter_values: Optional[object] = None, plugin_name: Optional[str] = None, initialization_timeout: float = 10.0)#

A wrapper around third-party, audio effect or instrument 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.)

Warning

Some Audio Unit plugins may throw errors, hang, generate incorrect output, or outright crash if called from background threads. If you find that a Audio Unit plugin is not working as expected, try calling it from the main thread instead and open a GitHub Issue to track the incompatibility.

Support for instrument plugins introduced in v0.7.4.

Support for running Audio Unit plugins on background threads introduced in v0.8.8.

Support for loading AUv3 plugins ( .appex bundles) introduced in v0.9.5.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#
__call__(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]: Run an audio or MIDI buffer through this plugin, returning audio. Alias for process().

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 or .appex 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.

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

process(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]

Pass a buffer of audio (as a 32- or 64-bit NumPy array) or a list of MIDI messages to this plugin, returning audio.

(If calling this multiple times with multiple effect plugins, consider creating a pedalboard.Pedalboard object instead.)

When provided audio as input, 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.

If provided MIDI messages as input, the provided midi_messages must be a Python List containing one of the following types:

Objects with a bytes() method and time property (such as mido:messages from Mido - MIDI Objects for Python, not included with Pedalboard)

Tuples that look like: (midi_bytes: bytes, timestamp_in_seconds: float)

Tuples that look like: (midi_bytes: List[int], timestamp_in_seconds: float)

The returned array will contain duration seconds worth of audio at the provided sample_rate.

Each MIDI message will be sent to the plugin at its timestamp, where a timestamp of 0 indicates the start of the buffer, and a timestamp equal to duration indicates the end of the buffer. (Any MIDI messages whose timestamps are greater than duration will be ignored.)

The provided buffer_size argument will be used to control the size of each chunk of audio returned by the plugin at once. Higher buffer sizes may speed up processing, but may cause increased memory usage.

The reset flag determines if this plugin should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio or MIDI stream, set reset to False.

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

Examples

Running audio through an external effect plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_effect
with AudioFile("input-audio.wav") as f:
    output_audio = plugin(f.read(), f.samplerate)

Rendering MIDI via an external instrument plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile
from mido import Message # not part of Pedalboard, but convenient!

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_instrument

sample_rate = 44100
num_channels = 2
with AudioFile("output-audio.wav", "w", sample_rate, num_channels) as f:
    f.write(plugin(
        [Message("note_on", note=60), Message("note_off", note=60, time=4)],
        sample_rate=sample_rate,
        duration=5,
        num_channels=num_channels
    ))

Support for instrument plugins introduced in v0.7.4.

show_editor(close_event: Optional[Event] = None) → None#

Show the UI of this plugin as a native window.

This method may only be called on the main thread, and will block the main thread until any of the following things happens:

the window is closed by clicking the close button

the window is closed by pressing the appropriate (OS-specific) keyboard shortcut

a KeyboardInterrupt (Ctrl-C) is sent to the program

the threading.Event.set() method is called (by another thread) on a provided threading.Event object

An example of how to programmatically close an editor window:

import pedalboard
from threading import Event, Thread

plugin = pedalboard.load_plugin("../path-to-my-plugin-file")
close_window_event = Event()

def other_thread():
    # do something to determine when to close the window
    if should_close_window:
        close_window_event.set()

thread = Thread(target=other_thread)
thread.start()

# This will block until the other thread calls .set():
plugin.show_editor(close_window_event)

property category: str#

A category that this plugin falls into, such as “Dynamics”, “Reverbs”, etc.

Introduced in v0.9.4.

property descriptive_name: str#

A more descriptive name for this plugin. This may be the same as the ‘name’ field, but some plugins may provide an alternative name.

Introduced in v0.9.4.

property has_shared_container: bool#

True iff this plugin is part of a multi-plugin container.

Introduced in v0.9.4.

property identifier: str#

A string that can be saved and used to uniquely identify this plugin (and version) again.

Introduced in v0.9.4.

property is_instrument: bool#

True iff this plugin identifies itself as an instrument (generator, synthesizer, etc) plugin.

Introduced in v0.9.4.

property manufacturer_name: str#

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

Introduced in v0.9.4.

property name: str#: The name of this plugin.

property raw_state: bytes#

A bytes object representing the plugin’s internal state.

For the Audio Unit format, this is usually a binary property list that can be decoded or encoded with the built-in plistlib package.

Warning

This property can be set to change the plugin’s internal state, but providing invalid data may cause the plugin to crash, taking the entire Python process down with it.

property reported_latency_samples: int#

The number of samples of latency (delay) that this plugin reports to introduce into the audio signal due to internal buffering and processing. Pedalboard automatically compensates for this latency during processing, so this property is present for informational purposes. Note that not all plugins correctly report the latency that they introduce, so this value may be inaccurate (especially if the plugin reports 0).

Introduced in v0.9.12.

property version: str#

The version string for this plugin, as reported by the plugin itself.

Introduced in v0.9.4.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

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.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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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(plugins: List[Plugin])#

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

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

append(plugin: Plugin) → None#: Append a plugin to the end of this container.

insert(index: int, plugin: Plugin) → None#: Insert a plugin at the specified index.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

remove(plugin: Plugin) → None#: Remove a plugin by its value.

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.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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.Clipping(threshold_db: float = -6.0)#

A distortion plugin that adds hard distortion to the signal by clipping the signal at the provided threshold (in decibels).

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: Union[str, ndarray[Any, dtype[float32]]], mix: float = 1.0, sample_rate: Optional[float] = None)#

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

The convolution impulse response can be specified either by filename or as a 32-bit floating point NumPy array. If a NumPy array is provided, the sample_rate argument must also be provided to indicate the sample rate of the impulse response.

Support for passing NumPy arrays as impulse responses introduced in v0.9.10.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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))

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: Quality = Quality.WindowedSinc8)#

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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).

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.)

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: 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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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).

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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 10.0; lower is better).

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

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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(plugins: List[Plugin])#

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

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

append(plugin: Plugin) → None#: Append a plugin to the end of this container.

insert(index: int, plugin: Plugin) → None#: Insert a plugin at the specified index.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

remove(plugin: Plugin) → None#: Remove a plugin by its value.

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.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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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 is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

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

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

append(plugin: Plugin) → None#: Append a plugin to the end of this container.

insert(index: int, plugin: Plugin) → None#: Insert a plugin at the specified index.

remove(plugin: Plugin) → None#: Remove a plugin by its value.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: Quality = Quality.WindowedSinc32)#

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 which specific resampling algorithm to use.

Resampling algorithms each provide a different tradeoff between speed and quality. Pedalboard provides two different types of resampling algorithms:

Aliasing algorithms, which cause high frequencies to appear as lower frequencies.

Non-aliasing algorithms, which filter out high frequencies when downsampling and avoid introducing extra high-frequency content when upsampling. (These algorithms were introduced in Pedalboard v0.9.15.)

Aliasing algorithms include ZeroOrderHold, Linear, CatmullRom, Lagrange, and WindowedSinc.

Non-aliasing algorithms include WindowedSinc256, WindowedSinc128, WindowedSinc64, WindowedSinc32, WindowedSinc16, and WindowedSinc8.

Choosing an algorithm to use depends on the signal being resampled, the relationship between the source and target sample rates, and the application of the resampled signal.

If downsampling by an integer factor (i.e.: from 44.1kHz to 22050Hz, or 48kHz to 24kHz), and if the source signal has no high-frequency content above half of the target sample rate the ZeroOrderHold algorithm will be the fastest by far and will produce no artifacts.

In all other cases, any of the numbered WindowedSinc algorithms (i.e.: WindowedSinc256, WindowedSinc64) will produce a clean signal with no artifacts. Higher numbers will produce a cleaner signal with less roll-off of high frequency content near the Nyquist frequency of the new sample rate.

However, depending on your application, the artifacts introduced by each resampling method may be acceptable. Test each method to determine which is the best tradeoff between speed and accuracy for your use case.

To provide a good balance between speed and accuracy, WindowedSinc32 is the default from Pedalboard v0.9.15 onwards. (Previously, WindowedSinc was the default.)

ZeroOrderHold = 0#

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

Zero-order hold resampling chooses the next value to use based on the last value, without any interpolation. Think of it like nearest-neighbor resampling.

Warning

This algorithm produces aliasing artifacts.

Linear = 1#

A resampling method slightly less noisy than the simplest method.

Linear resampling takes the average of the two nearest values to the desired sample, which is reasonably good for downsampling.

Warning

This algorithm produces aliasing artifacts.

CatmullRom = 2#: A moderately good-sounding resampling method which is fast to run. Slightly slower than Linear resampling, but slightly higher quality.

Warning

This algorithm produces aliasing artifacts.

Lagrange = 3#: A moderately good-sounding resampling method which is slow to run. Slower than CatmullRom resampling, but slightly higher quality.

Warning

This algorithm produces aliasing artifacts.

WindowedSinc = 4#

A very high quality (and the slowest) resampling method, with no audible artifacts when upsampling.

This resampler applies a windowed sinc filter design with 100 zero-crossings of the sinc function to approximate an ideal brick-wall low-pass filter.

Warning

This algorithm produces aliasing artifacts when downsampling, but not when upsampling.

Note

This method was the default in versions of Pedalboard prior to v0.9.15.

WindowedSinc256 = 5#

The highest possible quality resampling algorithm, with no audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 256 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter does not produce aliasing artifacts when upsampling or downsampling.

Compare this in speed and quality to Resampy’s kaiser_best method.

WindowedSinc128 = 6#

A very high quality resampling algorithm, with no audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 128 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter does not produce aliasing artifacts when upsampling or downsampling.

This method is roughly as fast as Resampy’s kaiser_fast method, while producing results roughly equal in quality to Resampy’s kaiser_best method.

WindowedSinc64 = 7#

A very high quality resampling algorithm, with few audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 64 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter does not produce aliasing artifacts when upsampling or downsampling.

This method is (on average) faster than Resampy’s kaiser_fast method, and roughly equal in quality.

WindowedSinc32 = 8#

A reasonably high quality resampling algorithm, with few audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 32 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter produces very few aliasing artifacts when upsampling or downsampling.

This method is always faster than Resampy’s kaiser_fast method, while being reasonable in quality.

Note

This method is the default in Pedalboard v0.9.15 and later.

WindowedSinc16 = 9#

A medium quality resampling algorithm, with few audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 16 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter produces some aliasing artifacts when upsampling or downsampling.

This method is faster than Resampy’s kaiser_fast method, while being acceptable in quality.

WindowedSinc8 = 10#

A low quality resampling algorithm, with few audible artifacts when upsampling or downsampling.

This resampler applies a windowed sinc filter with 16 zero-crossings to approximate an ideal brick-wall low-pass filter. This filter produces noticeable aliasing artifacts when upsampling or downsampling.

This method can be more than 10x faster than Resampy’s kaiser_fast method, and is useful for applications that are tolerant of some resampling artifacts.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: 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>_.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#: Run an audio buffer through this plugin. Alias for process().

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

property is_instrument: bool#

True iff this plugin is not an audio effect and accepts only MIDI input, not audio.

Introduced in v0.7.4.

process(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[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.

The layout of the provided input_array will be automatically detected, assuming that the smaller dimension corresponds with the number of channels. If the number of samples and the number of channels are the same, each Plugin object will use the last-detected channel layout until reset() is explicitly called (as of v0.9.9).

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

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: Optional[object] = None, plugin_name: Optional[str] = None, initialization_timeout: float = 10.0)#

A wrapper around third-party, audio effect or instrument 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.)

Warning

Some VST3® plugins may throw errors, hang, generate incorrect output, or outright crash if called from background threads. If you find that a VST3® plugin is not working as expected, try calling it from the main thread instead and open a GitHub Issue to track the incompatibility.

Support for instrument plugins introduced in v0.7.4.

Support for running VST3® plugins on background threads introduced in v0.8.8.

property is_effect: bool#

True iff this plugin is an audio effect and accepts audio as input.

Introduced in v0.7.4.

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.

__call__(input_array: ndarray, sample_rate: float, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]#
__call__(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]: Run an audio or MIDI buffer through this plugin, returning audio. Alias for process().

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(preset_file_path: str) → None#: Load a VST3 preset file in .vstpreset format.

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

process(midi_messages: object, duration: float, sample_rate: float, num_channels: int = 2, buffer_size: int = 8192, reset: bool = True) → ndarray[Any, dtype[float32]]

Pass a buffer of audio (as a 32- or 64-bit NumPy array) or a list of MIDI messages to this plugin, returning audio.

(If calling this multiple times with multiple effect plugins, consider creating a pedalboard.Pedalboard object instead.)

When provided audio as input, 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.

If provided MIDI messages as input, the provided midi_messages must be a Python List containing one of the following types:

Objects with a bytes() method and time property (such as mido:messages from Mido - MIDI Objects for Python, not included with Pedalboard)

Tuples that look like: (midi_bytes: bytes, timestamp_in_seconds: float)

Tuples that look like: (midi_bytes: List[int], timestamp_in_seconds: float)

The returned array will contain duration seconds worth of audio at the provided sample_rate.

Each MIDI message will be sent to the plugin at its timestamp, where a timestamp of 0 indicates the start of the buffer, and a timestamp equal to duration indicates the end of the buffer. (Any MIDI messages whose timestamps are greater than duration will be ignored.)

The provided buffer_size argument will be used to control the size of each chunk of audio returned by the plugin at once. Higher buffer sizes may speed up processing, but may cause increased memory usage.

The reset flag determines if this plugin should be reset before processing begins, clearing any state from previous calls to process. If calling process multiple times while processing the same audio or MIDI stream, set reset to False.

Note

The process() method can also be used via __call__(); i.e.: just calling this object like a function (my_plugin(...)) will automatically invoke process() with the same arguments.

Examples

Running audio through an external effect plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_effect
with AudioFile("input-audio.wav") as f:
    output_audio = plugin(f.read(), f.samplerate)

Rendering MIDI via an external instrument plugin:

from pedalboard import load_plugin
from pedalboard.io import AudioFile
from mido import Message # not part of Pedalboard, but convenient!

plugin = load_plugin("../path-to-my-plugin-file")
assert plugin.is_instrument

sample_rate = 44100
num_channels = 2
with AudioFile("output-audio.wav", "w", sample_rate, num_channels) as f:
    f.write(plugin(
        [Message("note_on", note=60), Message("note_off", note=60, time=4)],
        sample_rate=sample_rate,
        duration=5,
        num_channels=num_channels
    ))

Support for instrument plugins introduced in v0.7.4.

show_editor(close_event: Optional[Event] = None) → None#

Show the UI of this plugin as a native window.

This method may only be called on the main thread, and will block the main thread until any of the following things happens:

the window is closed by clicking the close button

the window is closed by pressing the appropriate (OS-specific) keyboard shortcut

a KeyboardInterrupt (Ctrl-C) is sent to the program

the threading.Event.set() method is called (by another thread) on a provided threading.Event object

An example of how to programmatically close an editor window:

import pedalboard
from threading import Event, Thread

plugin = pedalboard.load_plugin("../path-to-my-plugin-file")
close_window_event = Event()

def other_thread():
    # do something to determine when to close the window
    if should_close_window:
        close_window_event.set()

thread = Thread(target=other_thread)
thread.start()

# This will block until the other thread calls .set():
plugin.show_editor(close_window_event)

property category: str#

A category that this plugin falls into, such as “Dynamics”, “Reverbs”, etc.

Introduced in v0.9.4.

property descriptive_name: str#

A more descriptive name for this plugin. This may be the same as the ‘name’ field, but some plugins may provide an alternative name.

Introduced in v0.9.4.

property has_shared_container: bool#

True iff this plugin is part of a multi-plugin container.

Introduced in v0.9.4.

property identifier: str#

A string that can be saved and used to uniquely identify this plugin (and version) again.

Introduced in v0.9.4.

property is_instrument: bool#

True iff this plugin identifies itself as an instrument (generator, synthesizer, etc) plugin.

Introduced in v0.9.4.

property manufacturer_name: str#

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

Introduced in v0.9.4.

property name: str#: The name of this plugin.

property preset_data: bytes#: Get or set the current plugin state as bytes in .vstpreset format.

Warning

This property can be set to change the plugin’s internal state, but providing invalid data may cause the plugin to crash, taking the entire Python process down with it.

property raw_state: bytes#

A bytes object representing the plugin’s internal state.

For the VST3 format, this is usually an XML-encoded string prefixed with an 8-byte header and suffixed with a single null byte.

Warning

This property can be set to change the plugin’s internal state, but providing invalid data may cause the plugin to crash, taking the entire Python process down with it.

property reported_latency_samples: int#

The number of samples of latency (delay) that this plugin reports to introduce into the audio signal due to internal buffering and processing. Pedalboard automatically compensates for this latency during processing, so this property is present for informational purposes. Note that not all plugins correctly report the latency that they introduce, so this value may be inaccurate (especially if the plugin reports 0).

Introduced in v0.9.12.

property version: str#

The version string for this plugin, as reported by the plugin itself.

Introduced in v0.9.4.

pedalboard.time_stretch(input_audio: ndarray[Any, dtype[float32]], samplerate: float, stretch_factor: Union[float, ndarray[Any, dtype[float64]]] = 1.0, pitch_shift_in_semitones: Union[float, ndarray[Any, dtype[float64]]] = 0.0, high_quality: bool = True, transient_mode: str = 'crisp', transient_detector: str = 'compound', retain_phase_continuity: bool = True, use_long_fft_window: Optional[bool] = None, use_time_domain_smoothing: bool = False, preserve_formants: bool = True) → ndarray[Any, dtype[float32]]#

Time-stretch (and optionally pitch-shift) a buffer of audio, changing its length.

Using a higher stretch_factor will shorten the audio - i.e., a stretch_factor of 2.0 will double the speed of the audio and halve the length of the audio, without changing the pitch of the audio.

This function allows for changing the pitch of the audio during the time stretching operation. The stretch_factor and pitch_shift_in_semitones arguments are independent and do not affect each other (i.e.: you can change one, the other, or both without worrying about how they interact).

Both stretch_factor and pitch_shift_in_semitones can be either floating-point numbers or NumPy arrays of double-precision floating point numbers. Providing a NumPy array allows the stretch factor and/or pitch shift to vary over the length of the output audio.

Note

If a NumPy array is provided for stretch_factor or pitch_shift_in_semitones:

The length of each array must be the same as the length of the input audio.
More frequent changes in the stretch factor or pitch shift will result in slower processing, as the audio will be processed in smaller chunks.
Changes to the stretch_factor or pitch_shift_in_semitones more frequent than once every 1,024 samples (23 milliseconds at 44.1kHz) will not have any effect.

The additional arguments provided to this function allow for more fine-grained control over the behavior of the time stretcher:

high_quality (the default) enables a higher quality time stretching mode. Set this option to False to use less CPU power.

transient_mode controls the behavior of the stretcher around transients (percussive parts of the audio). Valid options are "crisp" (the default), "mixed", or "smooth".

transient_detector controls which method is used to detect transients in the audio signal. Valid options are "compound" (the default), "percussive", or "soft".

retain_phase_continuity ensures that the phases of adjacent frequency bins in the audio stream are kept as similar as possible. Set this to False for a softer, phasier sound.

use_long_fft_window controls the size of the fast-Fourier transform window used during stretching. The default (None) will result in a window size that varies based on other parameters and should produce better results in most situations. Set this option to True to result in a smoother sound (at the expense of clarity and timing), or False to result in a crisper sound.

use_time_domain_smoothing can be enabled to produce a softer sound with audible artifacts around sharp transients. This option mixes well with use_long_fft_window=False.

preserve_formants allows shifting the pitch of notes without substantially affecting the pitch profile (formants) of a voice or instrument.

Warning

This is a function, not a Plugin instance, and cannot be used in Pedalboard objects, as it changes the duration of the audio stream.

Note

The ability to pass a NumPy array for stretch_factor and pitch_shift_in_semitones was added in Pedalboard v0.9.8.

The pedalboard API#

The `pedalboard` API#