spotify/pedalboard: a Python library for audio effects, VST3 and Audio Unit hosting

What Pedalboard solves, and who it is actually for

Most Python audio code stops at arrays. You can read a WAV with a library, apply a filter with SciPy, and write it back, but the moment you want a compressor that behaves like a studio compressor, or the specific reverb a producer already uses, you are outside the Python ecosystem. Pedalboard closes that gap. The README describes it as "a Python library for working with audio: reading, writing, rendering, adding effects, and more," and the second half of that sentence is the interesting part: it hosts VST3 on macOS, Windows and Linux, and Audio Units on macOS.

The stated audience is narrow and specific. Spotify's Audio Intelligence Lab built it for data augmentation inside machine learning pipelines, and the README says it is used internally for that purpose and to help power features like Spotify's AI DJ and AI Voice Translation. It also names content creation as a use case, adding effects to audio without a DAW. If you are training a model on audio and want to vary your training data with realistic effects, or you are generating audio in a batch job, this is the intended shape of the work. If you are a musician looking for something to play through, it is not that.

How Pedalboard is put together: JUCE, pybind11 and a chain of plugins

The repository layout tells you most of the architecture. There is a pedalboard_native directory for the C++ side, a JUCE submodule at the top level, and a pyproject.toml whose build backend is scikit_build_core with pybind11 as a build requirement. The setup.py file passes a long list of JUCE module flags, including juce_audio_basics, juce_audio_formats, juce_audio_processors and juce_dsp. So the Python objects you construct are thin bindings over JUCE classes, and the audio formats come from JUCE's format layer rather than from a Python decoder.

The central abstraction is the Pedalboard object, which the README's quick start constructs as a list of effects. You append plugins to it and it processes audio as a chain, in order. Effects are individual classes: Chorus, Distortion, Phaser, Clipping, Compressor, Gain, Limiter, HighpassFilter, LadderFilter, LowpassFilter, Convolution, Delay, Reverb, PitchShift, GSMFullRateCompressor, MP3Compressor, Resample and Bitcrush. Third-party plugins come in through pedalboard.load_plugin, which returns a plugin object you place in the same chain.

One design decision matters more than the effect list. The README states that Pedalboard releases Python's Global Interpreter Lock, so multiple CPU cores can be used without multiprocessing. That is unusual for a Python audio library and it changes how you write batch code: threads become viable where you would otherwise reach for a process pool. The README also claims speed comparisons against pySoX and SoxBindings and against librosa.load, with figures of up to 300x and up to 4x respectively. Those numbers come from the project's own comparisons, not from independent measurement, and the conditions under which they hold are not spelled out in the README.

Installing Pedalboard and running a first effect chain

Installation is a single pip command, because the project ships platform wheels. The README gives this as the whole instruction, and points readers new to Python at INSTALLATION.md for a longer guide.

pip install pedalboard

The README states compatibility with Python 3.10 through 3.15. Wheels are built for manylinux and musllinux on x86_64 and aarch64, for macOS on both Intel and Apple Silicon, and for Windows amd64. If your platform is not in that list, pip will try to build from source, which pulls in JUCE and a C++ toolchain and is a much longer path.

Once installed, the quick start in the README builds a board with two effects and processes a file in one-second blocks. The pattern is worth copying because it keeps memory flat: open the input with AudioFile, open the output with the input's samplerate and num_channels, then loop over read calls and write the result.

from pedalboard import Pedalboard, Chorus, Reverb
from pedalboard.io import AudioFile

board = Pedalboard([Chorus(), Reverb(room_size=0.25)])

with AudioFile('some-file.wav') as f:
    with AudioFile('output.wav', 'w', f.samplerate, f.num_channels) as o:
        while f.tell() < f.frames:
            o.write(board(f.read(f.samplerate), f.samplerate))

After this runs, output.wav exists at the same sample rate and channel count as the input, with chorus and reverb applied. The examples directory in the repository has three more starting points: add_reverb_to_file.py, audio_monitoring_with_effects.py, and streaming_encode_mp3.py. The last one is the interesting one if you are producing files rather than analysing them, since MP3Compressor is listed among the built-in effects.

Where Pedalboard stops being the right tool

Plugin hosting is the feature that draws people in and the feature most likely to disappoint. The README says Linux VSTs generally require a relatively modern installation with glibc above 2.27, and the pyproject.toml comments call the musllinux build experimental because "most VSTs require glibc and thus Alpine Linux isn't that useful." That is the project telling you its own container story is limited. If you build on Alpine, do not expect third-party plugins to load.

There is a second boundary around what the library does not do. It processes audio; it does not edit sessions, arrange timelines, or provide a UI. The README frames the DAW-free workflow as a feature, and for batch rendering it is. For anything interactive, it is a dead end. There is also no documented rollback or version-pinning story in the README, and no statement about how plugin state is serialised across versions, which matters if you render a large corpus and later need to reproduce it.

Finally, the licence. Pedalboard is GPL-3.0, and setup.py carries the standard GPL header. For research and internal tooling that is usually workable. For a shipped closed-source product, linking GPL code into your process is a decision to take seriously, and the project does not offer an alternative licence in the documentation it publishes.

Pedalboard against pySoX and SoxBindings

The README names two alternatives directly, and the difference is architectural rather than a matter of degree. pySoX and SoxBindings are Python wrappers around SoX, the command-line audio processor. SoX is a fixed set of transforms exposed as command-line operations. You get what SoX implements, and adding a new effect means changing SoX.

Pedalboard takes the opposite approach. It embeds JUCE and exposes plugin objects, so the effect set is open: anything packaged as VST3 or Audio Unit can be loaded through pedalboard.load_plugin and inserted into the same chain as the built-in effects. The README's speed claims against pySoX and SoxBindings are the project's own and should be treated as such, but the structural difference is the one that decides the choice. If your processing is a fixed sequence of standard transforms and you want the smallest possible dependency, a SoX wrapper is simpler. If you need a specific plugin, or you need the same effect chain to run over a training set and then over a production file, Pedalboard is the one that can express it. The GIL release reinforces that: the README states you do not need multiprocessing to use multiple cores, which is a real constraint lifted for anyone processing thousands of files.

Maintenance, releases and the GPL-3.0 licence

The last push to the repository was on 2026-09-09, and v0.9.25 was released the same day, following v0.9.24 on 2026-07-08 and v0.9.23 on 2026-05-15. The cadence is roughly every two months, which is a reasonable pace for a library whose main cost is keeping up with JUCE, Python versions and plugin formats. The repository is not archived. Nothing in the README describes a deprecation policy, a support window for older versions, or a migration guide between releases, so treat upgrades as something to test against your own audio rather than something the project will guide you through.

The upgrade cost is mostly the wheel. Because Pedalboard ships compiled platform wheels, a new release is a pip install away on supported platforms, but a Python version that has no wheel yet, or a platform outside the built set, means compiling JUCE and the bindings yourself. That is the hidden maintenance burden: the library is cheap to use and expensive to build.

The licence is GPL-3.0, as stated in the README badge, the LICENSE file and the header in setup.py. This is not legal advice, but the practical shape is that GPL-3.0 is a copyleft licence, and distributing a product that incorporates Pedalboard generally brings obligations with it. If your use is internal, research, or itself open source, that is a different calculation than distributing a closed binary. Check what your own distribution model implies before you build a product around it.

Editorial conclusion

Adopt Pedalboard if your work lives in Python: data augmentation, batch rendering, or running a VST3 you already own inside a script. Do not adopt it if you need a GUI, a DAW session, or a permissive licence for a closed-source product, since the project is GPL-3.0 and that choice propagates. Before committing, verify that the wheel exists for your platform and Python version, and confirm that the specific plugin you want to host loads on your OS, because plugin compatibility is the part the documentation is least specific about.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. spotify/pedalboard on GitHub