pedalboard: A C++ repository from konoikon

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.

Usage

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!
- Even when only using one thread:
  - Processes audio up to 300x faster than pySoX
Tested compatibility with TensorFlow - can be used in tf.data pipelines!

Installation

pedalboard is available via PyPI (via Platform Wheels):

pip install pedalboard

Compatibility

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

Examples

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)

Loading a VST3® plugin and manipulating its parameters

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:

Contributing

Contributions to pedalboard are welcomed! See CONTRIBUTING.md for details.

License

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.