Pedalboard Save

๐ŸŽ› ๐Ÿ”Š A Python library for working with audio.

Project README

Pedalboard Logo

License: GPL v3 Documentation PyPI - Python Version Supported Platforms Apple Silicon support for macOS and Linux (Docker) PyPI - Wheel Test Badge Coverage Badge PyPI - Downloads GitHub Repo stars

pedalboard is a Python library for working with audio: reading, writing, 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 third-party plugins.

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. pedalboard also helps in the process of content creation, making it possible to add effects to audio without using a Digital Audio Workstation.

Documentation

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
  • 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ยฎ plugins on macOS, Windows, and Linux (pedalboard.load_plugin)
  • 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 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  # That's it! No other dependencies required.

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

Compatibility

pedalboard is thoroughly tested with Python 3.6, 3.7, 3.8, 3.9, and 3.10 as well as experimental support for Python 3.11 and PyPy 3.7, 3.8, and 3.9.

  • Linux
    • Tested heavily in production use cases at Spotify
    • Tested automatically on GitHub with VSTs
    • Platform manylinux 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

Quick start

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

# Read in a whole audio file:
with AudioFile('some-file.wav') as f:
  audio = f.read(f.frames)
  samplerate = f.samplerate

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

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

Making a guitar-style pedalboard

# 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 plugins

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

# Load a VST3 or Audio Unit plugin 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:
with AudioFile('some-file.wav', 'r') as f:
  audio = f.read(f.frames)
  samplerate = f.samplerate
effected = vst(audio, samplerate)

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

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:

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

For more examples, see:

Contributing

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

License

pedalboard is Copyright 2021-2022 Spotify AB.

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:

VST is a registered trademark of Steinberg Media Technologies GmbH.

Open Source Agenda is not affiliated with "Pedalboard" Project. README Source: spotify/pedalboard
Stars
3,594
Open Issues
13
Last Commit
6 days ago
Repository
License

Open Source Agenda Badge

Open Source Agenda Rating