Pedalboard

0.9.22 · active · verified Sat Apr 11

Pedalboard is a Python library for working with audio: reading, writing, rendering, adding effects, and more. Built by Spotify's Audio Intelligence Lab, it supports most popular audio file formats, a number of common audio effects out of the box, and also allows the use of VST3® and Audio Unit formats for loading third-party software instruments and effects. It's designed for high-performance audio processing, including use in machine learning workflows with TensorFlow. The current version is 0.9.22 and it is actively maintained.

Warnings

breaking Pedalboard v0.9.16 and later no longer support Python 3.8. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python interpreter to version 3.10 or higher (e.g., Python 3.11, 3.12).
gotcha When using VST3® or Audio Unit plugins via `pedalboard.load_plugin`, some plugins may not work as expected or can even cause the Python interpreter to crash without warning. This is due to variations in plugin adherence to specifications.
Fix: Consult the `COMPATIBILITY.md` file in the Pedalboard GitHub repository for known compatible plugins. Exercise caution and test thoroughly when integrating third-party plugins.
gotcha While Pedalboard supports real-time audio processing via `AudioStream`, it was primarily designed for batch processing. Latency guarantees are not always explicit, and performance in strictly low-latency live applications can depend heavily on system resources and plugin complexity.
Fix: Test your specific live audio setup extensively to ensure acceptable latency. Monitor CPU usage and buffer sizes. For critical low-latency applications, consider dedicated audio frameworks if Pedalboard does not meet requirements.
gotcha Calling `Plugin.show_editor()` for VST/AU plugins can lead to GUI issues in some environments, such as 'BadWindow' crashes in X11 or borderless windows on Windows systems.
Fix: If experiencing GUI issues, try updating your display drivers or using a different windowing environment. For production, consider running plugins headless if GUI interaction is not strictly necessary.

Install

pip install pedalboard Install the latest version

Imports

Pedalboard
```
from pedalboard import Pedalboard
```
While 'import pedalboard' works, importing specific classes like 'Pedalboard' and effect plugins directly is the idiomatic and cleaner way for most uses.
AudioFile
```
from pedalboard.io import AudioFile
```
Audio I/O utilities are located in the `pedalboard.io` submodule.

Quickstart

This quickstart generates a simple sine wave, applies a chorus, reverb, and gain effect using a `Pedalboard` object, and then saves the processed audio to a WAV file. It demonstrates the basic workflow of creating a pedalboard and processing audio buffers.

import numpy as np
from pedalboard import Pedalboard, Chorus, Reverb, Gain
from pedalboard.io import AudioFile

# Generate a 1-second sine wave at 44.1 kHz
samplerate = 44100
duration = 1.0 # seconds
frequency = 440.0 # Hz
t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)
audio = 0.5 * np.sin(2 * np.pi * frequency * t)

# Ensure audio is float32 for Pedalboard
audio = audio.astype(np.float32)

# Create a Pedalboard with some effects
board = Pedalboard([
    Chorus(rate_hz=1.0, depth=0.5, mix=0.5),
    Reverb(room_size=0.7, dampening=0.5, wet_level=0.2, dry_level=0.8),
    Gain(gain_db=3.0)
])

# Process the audio
effected_audio = board(audio, samplerate, reset=False)

# Write the output to a WAV file
output_filename = 'output_effected_audio.wav'
with AudioFile(output_filename, 'w', samplerate, effected_audio.shape[0]) as f:
    f.write(effected_audio)

print(f"Processed audio saved to {output_filename}")

view raw JSON →