pedalboard
is a Python library for adding effects to audio. It supports a number of common audio effects out of the box, and also allows the use of VST3ยฎ and Audio Unit plugin formats for third-party effects. It was built by Spotify's Audio Intelligence Lab to enable using studio-quality audio effects from within Python and TensorFlow.
Internally at Spotify, pedalboard
is used for data augmentation to improve machine learning models. pedalboard
also helps in the process of content creation, making it possible to add effects to audio without using a Digital Audio Workstation.```
- Built-in support for a number of basic audio transformations:
Convolution
Compressor
Chorus
Distortion
Gain
HighpassFilter
LadderFilter
Limiter
LowpassFilter
Phaser
Reverb
- Supports VST3ยฎ plugins on macOS, Windows, and Linux
- Supports Audio Units on macOS
- Strong thread-safety, memory usage, and speed guarantees
- Releases Python's Global Interpreter Lock (GIL) to allow use of multiple CPU cores
- No need to use
multiprocessing
!
- No need to use
- Even when only using one thread:
- Processes audio up to 300x faster than pySoX
- Releases Python's Global Interpreter Lock (GIL) to allow use of multiple CPU cores
- Tested compatibility with TensorFlow - can be used in
tf.data
pipelines!
pedalboard
is available via PyPI (via Platform Wheels):
pip install pedalboard
If you are new to Python, follow INSTALLATION.md for a robust guide.
pedalboard
is thoroughly tested with Python 3.6, 3.7, 3.8, and 3.9, as well as experimental support for PyPy 7.3.
- Linux
- Tested heavily in production use cases at Spotify
- Tested automatically on GitHub with VSTs
- Platform
manylinux
wheels built forx86_64
- Most Linux VSTs require a relatively modern Linux installation (with glibc > 2.27)
- macOS
- Tested manually with VSTs and Audio Units
- Tested automatically on GitHub with VSTs
- Platform wheels available for both Intel and Apple Silicon
- Compatible with a wide range of VSTs and Audio Units
- Windows
- Tested automatically on GitHub with VSTs
- Platform wheels available for
amd64
(Intel/AMD)
pedalboard
allows loading VST3ยฎ and Audio Unit plugins, which could contain any code.
Most plugins that have been tested work just fine with pedalboard
, but some plugins may
not work with pedalboard
; at worst, some may even crash the Python interpreter without
warning and with no ability to catch the error. For an ever-growing compatibility list,
see COMPATIBILITY.md.
Most audio plugins are "well-behaved" and conform to a set of conventions for how audio
plugins are supposed to work, but many do not conform to the VST3ยฎ or Audio Unit
specifications. pedalboard
attempts to detect some common programming errors in plugins
and can work around many issues, including automatically detecting plugins that don't
clear their internal state when asked. Even so, plugins can misbehave without pedalboard
noticing.
If audio is being rendered incorrectly or if audio is "leaking" from one process()
call
to the next in an undesired fashion, try:
- Passing silence to the plugin in between calls to
process()
, to ensure that any reverb tails or other internal state has time to fade to silence - Reloading the plugin every time audio is processed (with
pedalboard.load_plugin
)
A very basic example of how to use pedalboard
's built-in plugins:
import soundfile as sf
from pedalboard import (
Pedalboard,
Convolution,
Compressor,
Chorus,
Gain,
Reverb,
Limiter,
LadderFilter,
Phaser,
)
audio, sample_rate = sf.read('some-file.wav')
# Make a Pedalboard object, containing multiple plugins:
board = Pedalboard([
Compressor(threshold_db=-50, ratio=25),
Gain(gain_db=30),
Chorus(),
LadderFilter(mode=LadderFilter.Mode.HPF12, cutoff_hz=900),
Phaser(),
Convolution("./guitar_amp.wav", 1.0),
Reverb(room_size=0.25),
], sample_rate=sample_rate)
# Pedalboard objects behave like lists, so you can add plugins:
board.append(Compressor(threshold_db=-25, ratio=10))
board.append(Gain(gain_db=10))
board.append(Limiter())
# Run the audio through this pedalboard!
effected = board(audio)
# Write the audio back as a wav file:
with sf.SoundFile('./processed-output-stereo.wav', 'w', samplerate=sample_rate, channels=len(effected.shape)) as f:
f.write(effected)
import soundfile as sf
from pedalboard import Pedalboard, Reverb, load_plugin
# Load a VST3 package from a known path on disk:
vst = load_plugin("./VSTs/RoughRider3.vst3")
print(vst.parameters.keys())
# dict_keys([
# 'sc_hpf_hz',
# 'input_lvl_db',
# 'sensitivity_db',
# 'ratio',
# 'attack_ms',
# 'release_ms',
# 'makeup_db',
# 'mix',
# 'output_lvl_db',
# 'sc_active',
# 'full_bandwidth',
# 'bypass',
# 'program',
# ])
# Set the "ratio" parameter to 15
vst.ratio = 15
# Use this VST to process some audio:
audio, sample_rate = sf.read('some-file.wav')
effected = vst(audio, sample_rate=sample_rate)
# ...or put this VST into a chain with other plugins:
board = Pedalboard([vst, Reverb()], sample_rate=sample_rate)
# ...and run that pedalboard with the same VST instance!
effected = board(audio)
For more examples, see:
- the
examples
folder of this repository - the Pedalboard Demo Colab notebook
- an interactive web demo on Hugging Face Spaces and Gradio (via @AK391)
Contributions to pedalboard
are welcomed! See CONTRIBUTING.md for details.
pedalboard
is Copyright 2021 Spotify AB.
pedalboard
is licensed under the GNU General Public License v3, because:
- The core audio processing code is pulled from JUCE 6, which is dual-licensed under a commercial license and the GPLv3
- The VST3 SDK, bundled with JUCE, is owned by Steinbergยฎ Media Technologies GmbH and licensed under the GPLv3.
VST is a registered trademark of Steinberg Media Technologies GmbH.