Pedalboard: a Python library for adding effects to audio

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 = soundfile.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=sr)

# 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=sr, channels=effected.shape[1]) 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 = soundfile.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 Pedalboard Demo Colab notebook example.

Contributing

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

License

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.

GitHub

https://github.com/spotify/pedalboard