pedalboard

library0.9.24pypypi✓ verified 22d ago

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.

ai-ml data

pip install pedalboard

package ↗homepage ↗

INSTALL

IMPORT

SIG · PEDALBOARD

pedalboard

ai-mlpythonv0.9.24

Install

4.1s avg

Import

243ms

Disk

104MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.24 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 4.1s

py 3.11

✓ —

✓ 4s

py 3.12

✓ —

✓ 3.7s

py 3.13

✕ build_error

✓ 3.9s

py 3.9

✓ —

✓ 5s

104MB installed

● package 104MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pedalboard

✓ from pedalboard import Pedalboard

✗ import pedalboard; board = pedalboard.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

✗ from pedalboard import AudioFile

Audio I/O utilities are located in the `pedalboard.io` submodule.

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

Debug

Known issues

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

affects: 0.9.16+

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pedalboard'

The 'pedalboard' library is not installed in the current Python environment or is not accessible via the Python path.

fix

Run `pip install pedalboard` in your terminal to install the library.

ImportError: Failed to load plugin as VST3Plugin. Errors were: VST3Plugin: Unable to load plugin <path_to_plugin>: unsupported plugin format or load failure.

The specified VST3 plugin file is either not found at the given path, is corrupted, or is not a valid VST3 plugin that the 'pedalboard' library can process. This can also occur with 'shell' VSTs that bundle multiple plugins.

fix

Verify the exact path to the .vst3 file is correct. Ensure the plugin is a standalone VST3 and not a wrapper or shell that 'pedalboard' might not directly support. Check the plugin's compatibility with 'pedalboard' and your operating system.

Python.exe has stopped working / Windows fatal exception: access violation (or similar silent crash) when using pedalboard.load_plugin() or pedalboard.io.AudioFile on Windows

This often indicates a low-level crash due to incompatibilities between 'pedalboard' (or its underlying C++ components), specific VST3 plugins, Python versions, NumPy versions, or conflicts with other C++-wrapped libraries like PyQt6, especially on Windows.

fix

Update 'pedalboard' and 'numpy' to their latest versions (`pip install --upgrade pedalboard numpy`). If the issue persists, try using a different Python version (e.g., Python 3.9, 3.10, or 3.11 have shown better stability in some cases) or isolating 'pedalboard' usage from other potentially conflicting libraries.

MemoryError: Unable to allocate array with shape (...) / Application becomes unresponsive and crashes when processing large audio files

Attempting to read an entire large audio file into memory at once using `pedalboard.io.AudioFile.read()` without specifying a chunk size can lead to excessive memory consumption and crashes.

fix

Process large audio files in smaller, manageable chunks using a loop with `AudioFile.read(chunk_size)` to avoid loading the entire file into RAM simultaneously.

Upgrade

Version history

0.9.24latest on PyPI · released Jul 8, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

5 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pedalboard/ ↗

homepagehttps://spotify.github.io/pedalboard/ ↗