README

pedalboard is a Python library for working with audio: reading, writing, rendering, adding effects, and more. It supports most popular audio file formats and 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.

pedalboard was built by Spotify's Audio Intelligence Lab to enable using studio-quality audio effects from within Python and TensorFlow. Internally at Spotify, pedalboard is used for data augmentation to improve machine learning models and to help power features like Spotify's AI DJ and AI Voice Translation. pedalboard also helps in the process of content creation, making it possible to add effects to audio without using a Digital Audio Workstation.

Features

Built-in audio I/O utilities (pedalboard.io)
- Support for reading and writing AIFF, FLAC, MP3, OGG, and WAV files on all platforms with no dependencies
- Additional support for reading AAC, AC3, WMA, and other formats depending on platform
- Support for on-the-fly resampling of audio files and streams with O(1) memory usage
- Live audio effects via <a href="https://spotify.github.io/pedalboard/reference/pedalboard.io.html#pedalboard.io.AudioStream"><code class="docutils literal">AudioStream</code></a>
Built-in support for a number of basic audio transformations, including:
- Guitar-style effects: Chorus, Distortion, Phaser, Clipping
- Loudness and dynamic range effects: Compressor, Gain, Limiter
- Equalizers and filters: HighpassFilter, LadderFilter, LowpassFilter
- Spatial effects: Convolution, Delay, Reverb
- Pitch effects: PitchShift
- Lossy compression: GSMFullRateCompressor, MP3Compressor
- Quality reduction: Resample, Bitcrush
Supports VST3® instrument and effect plugins on macOS, Windows, and Linux (<a href="https://spotify.github.io/pedalboard/reference/pedalboard.html#pedalboard.load_plugin"><code class="docutils literal">pedalboard.load_plugin</code></a>)
Supports instrument and effect 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 for single transforms, and 2-5x faster than SoxBindings (via iCorv)
  - Reads audio files up to 4x faster than librosa.load (in many cases)
Tested compatibility with TensorFlow - can be used in tf.data pipelines!

Installation

pedalboard is available via PyPI (via Platform Wheels):

pip install pedalboard

If you are new to Python, follow INSTALLATION.md for a robust guide.

Compatibility

pedalboard is thoroughly tested with Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Linux
- Tested heavily in production use cases at Spotify
- Tested automatically on GitHub with VSTs
- Platform manylinux and musllinux wheels built for x86_64 (Intel/AMD) and aarch64 (ARM/Apple Silicon)
- 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 (x86-64, Intel/AMD)

Examples

Note: If you'd rather watch a video instead of reading examples or documentation, watch <a href="https://www.youtube.com/watch?v=NYhkqXpFAlg" target="_blank">Working with Audio in Python (feat. Pedalboard) on YouTube</a>.

Quick start

python

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

# Make a Pedalboard object, containing multiple audio plugins:
board = Pedalboard([Chorus(), Reverb(room_size=0.25)])

# Open an audio file for reading, just like a regular file:
with AudioFile('some-file.wav') as f:
  
  # Open an audio file to write to:
  with AudioFile('output.wav', 'w', f.samplerate, f.num_channels) as o:
  
    # Read one second of audio at a time, until the file is empty:
    while f.tell() < f.frames:
      chunk = f.read(f.samplerate)
      
      # Run the audio through our pedalboard:
      effected = board(chunk, f.samplerate, reset=False)
      
      # Write the output to our output file:
      o.write(effected)

Note: For more information about how to process audio through Pedalboard plugins, including how the reset parameter works, see <a href="https://spotify.github.io/pedalboard/reference/pedalboard.html#pedalboard.Plugin.process"> the documentation for <code class="docutils literal">pedalboard.Plugin.process</code></a>.

Making a guitar-style pedalboard

python

# Don't do import *! (It just makes this example smaller)
from pedalboard import *
from pedalboard.io import AudioFile

# Read in a whole file, resampling to our desired sample rate:
samplerate = 44100.0
with AudioFile('guitar-input.wav').resampled_to(samplerate) as f:
  audio = f.read(f.frames)

# Make a pretty interesting sounding guitar pedalboard:
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),
])

# 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())

# ... or change parameters easily:
board[0].threshold_db = -40

# Run the audio through this pedalboard!
effected = board(audio, samplerate)

# Write the audio back as a wav file:
with AudioFile('processed-output.wav', 'w', samplerate, effected.shape[0]) as f:
  f.write(effected)

Using VST3® or Audio Unit instrument and effect plugins

python

from pedalboard import Pedalboard, Reverb, load_plugin
from pedalboard.io import AudioFile
from mido import Message # not part of Pedalboard, but convenient!

# Load a VST3 or Audio Unit plugin from a known path on disk:
instrument = load_plugin("./VSTs/Magical8BitPlug2.vst3")
effect = load_plugin("./VSTs/RoughRider3.vst3")

print(effect.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
effect.ratio = 15

# Render some audio by passing MIDI to an instrument:
sample_rate = 44100
audio = instrument(
  [Message("note_on", note=60), Message("note_off", note=60, time=5)],
  duration=5, # seconds
  sample_rate=sample_rate,
)

# Apply effects to this audio:
effected = effect(audio, sample_rate)

# ...or put the effect into a chain with other plugins:
board = Pedalboard([effect, Reverb()])
# ...and run that pedalboard with the same VST instance!
effected = board(audio, sample_rate)

Creating parallel effects chains

This example creates a delayed pitch-shift effect by running multiple Pedalboards in parallel on the same audio. Pedalboard objects are themselves Plugin objects, so you can nest them as much as you like:

python

from pedalboard import Pedalboard, Compressor, Delay, Distortion, Gain, PitchShift, Reverb, Mix

passthrough = Gain(gain_db=0)

delay_and_pitch_shift = Pedalboard([
  Delay(delay_seconds=0.25, mix=1.0),
  PitchShift(semitones=7),
  Gain(gain_db=-3),
])

delay_longer_and_more_pitch_shift = Pedalboard([
  Delay(delay_seconds=0.5, mix=1.0),
  PitchShift(semitones=12),
  Gain(gain_db=-6),
])

board = Pedalboard([
  # Put a compressor at the front of the chain:
  Compressor(),
  # Run all of these pedalboards simultaneously with the Mix plugin:
  Mix([
    passthrough,
    delay_and_pitch_shift,
    delay_longer_and_more_pitch_shift,
  ]),
  # Add a reverb on the final mix:
  Reverb()
])

Running Pedalboard on Live Audio

pedalboard supports streaming live audio through <a href="https://spotify.github.io/pedalboard/reference/pedalboard.io.html#pedalboard.io.AudioStream"> an <code class="docutils literal">AudioStream</code> object</a>, allowing for real-time manipulation of audio by adding effects in Python.

python

from pedalboard import Pedalboard, Chorus, Compressor, Delay, Gain, Reverb, Phaser
from pedalboard.io import AudioStream

# Open up an audio stream:
with AudioStream(
  input_device_name="Apogee Jam+",  # Guitar interface
  output_device_name="MacBook Pro Speakers"
) as stream:
  # Audio is now streaming through this pedalboard and out of your speakers!
  stream.plugins = Pedalboard([
      Compressor(threshold_db=-50, ratio=25),
      Gain(gain_db=30),
      Chorus(),
      Phaser(),
      Convolution("./guitar_amp.wav", 1.0),
      Reverb(room_size=0.25),
  ])
  input("Press enter to stop streaming...")

# The live AudioStream is now closed, and audio has stopped.

Using Pedalboard in `tf.data` Pipelines

python

import tensorflow as tf 

sr = 48000 

# Put whatever plugins you like in here:
plugins = pedalboard.Pedalboard([pedalboard.Gain(), pedalboard.Reverb()]) 

# Make a dataset containing random noise:
# NOTE: for real training, here's where you'd want to load your audio somehow:
ds = tf.data.Dataset.from_tensor_slices([np.random.rand(sr)])

# Apply our Pedalboard instance to the tf.data Pipeline:
ds = ds.map(lambda audio: tf.numpy_function(plugins.process, [audio, sr], tf.float32)) 

# Create and train a (dummy) ML model on this audio:
model = tf.keras.models.Sequential([tf.keras.layers.InputLayer(input_shape=(sr,)), tf.keras.layers.Dense(1)])
model.compile(loss="mse") 
model.fit(ds.map(lambda effected: (effected, 1)).batch(1), epochs=10)

For more examples, see:

Contributing

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

Citing

To cite pedalboard in academic work, use its entry on Zenodo:

To cite via BibTeX:

tex

@software{sobot_peter_2023_7817838,
  author       = {Sobot, Peter},
  title        = {Pedalboard},
  month        = jul,
  year         = 2021,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.7817838},
  url          = {https://doi.org/10.5281/zenodo.7817838}
}

License

pedalboard is licensed under the GNU General Public License v3. pedalboard includes a number of libraries that are statically compiled, and which carry the following licenses:

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.
The PitchShift plugin and time_stretch functions use the Rubber Band Library, which is dual-licensed under a commercial license and the GPLv2 (or newer). FFTW is also included to speed up Rubber Band, and is licensed under the GPLv2 (or newer).
The MP3Compressor plugin uses libmp3lame from the LAME project, which is licensed under the LGPLv2 and upgraded to the GPLv3 for inclusion in this project (as permitted by the LGPLv2).
The GSMFullRateCompressor plugin uses libgsm, which is licensed under the ISC license and compatible with the GPLv3.
WAV files with formats not natively supported by JUCE (ADPCM, A-law, µ-law, 64-bit float) are decoded using dr_wav by David Reid, which is released into the public domain.

VST is a registered trademark of Steinberg Media Technologies GmbH.

Features

Installation

Compatibility

Examples

Quick start

Making a guitar-style pedalboard

Using VST3® or Audio Unit instrument and effect plugins

Creating parallel effects chains

Running Pedalboard on Live Audio

Using Pedalboard in tf.data Pipelines

Contributing

Citing

License

Using Pedalboard in `tf.data` Pipelines