Package: pedalboard
pedalboardis 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 ofVST3®andAudio Unitformats for loading third-party software instruments and effects.pedalboardwas built bySpotify's Audio Intelligence Labto enable using studio-quality audio effects from within Python and TensorFlow. Internally at Spotify,pedalboardis used fordata augmentationto improve machine learning models and to help power features likeSpotify's AI DJandAI Voice Translation.pedalboardalso helps in the process of content creation, making it possible to add effects to audio without using a Digital Audio Workstation.FeaturesBuilt-in audio I/O utilities (pedalboard.io)Support for reading and writing AIFF, FLAC, MP3, OGG, and WAV files on all platforms with no dependenciesAdditional support for reading AAC, AC3, WMA, and other formats depending on platformSupport for on-the-fly resampling of audio files and streams withO(1)memory usageLive audio effects viaAudioStreamBuilt-in support for a number of basic audio transformations, including:Guitar-style effects:Chorus,Distortion,Phaser,ClippingLoudness and dynamic range effects:Compressor,Gain,LimiterEqualizers and filters:HighpassFilter,LadderFilter,LowpassFilterSpatial effects:Convolution,Delay,ReverbPitch effects:PitchShiftLossy compression:GSMFullRateCompressor,MP3CompressorQuality reduction:Resample,BitcrushSupports VST3® instrument and effect plugins on macOS, Windows, and Linux (pedalboard.load_plugin)Supports instrument and effect Audio Units on macOSStrong thread-safety, memory usage, and speed guaranteesReleases Python's Global Interpreter Lock (GIL) to allow use of multiple CPU coresNo need to usemultiprocessing!Even when only using one thread:Processes audio up to300xfaster thanpySoXfor single transforms, and 2-5x faster thanSoxBindings(viaiCorv)Reads audio files up to4xfaster thanlibrosa.load(in many cases)Tested compatibility with TensorFlow - can be used intf.datapipelines!Installationpedalboardis available via PyPI (viaPlatform Wheels):pip install pedalboard  # That's it! No other dependencies required.If you are new to Python, followINSTALLATION.mdfor a robust guide.Compatibilitypedalboardis thoroughly tested with Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, and 3.12 as well as experimental support for PyPy 3.7, 3.8, and 3.9.LinuxTested heavily in production use cases at SpotifyTested automatically on GitHub with VSTsPlatformmanylinuxandmusllinuxwheels built forx86_64(Intel/AMD) andaarch64(ARM/Apple Silicon)Most Linux VSTs require a relatively modern Linux installation (with glibc > 2.27)macOSTested manually with VSTs and Audio UnitsTested automatically on GitHub with VSTsPlatform wheels available for both Intel and Apple SiliconCompatible with a wide range of VSTs and Audio UnitsWindowsTested automatically on GitHub with VSTsPlatform wheels available foramd64(x86-64, Intel/AMD)ExamplesNote: If you'd rather watch a video instead of reading examples or documentation,watchWorking with Audio in Python (feat. Pedalboard)on YouTube.Quick startfrompedalboardimportPedalboard,Chorus,Reverbfrompedalboard.ioimportAudioFile# 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:withAudioFile('some-file.wav')asf:# Open an audio file to write to:withAudioFile('output.wav','w',f.samplerate,f.num_channels)aso:# Read one second of audio at a time, until the file is empty:whilef.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 theresetparameter works,
seethe documentation forpedalboard.Plugin.process.Making a guitar-style pedalboard# Don't do import *! (It just makes this example smaller)frompedalboardimport*frompedalboard.ioimportAudioFile# Read in a whole file, resampling to our desired sample rate:samplerate=44100.0withAudioFile('guitar-input.wav').resampled_to(samplerate)asf: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:withAudioFile('processed-output.wav','w',samplerate,effected.shape[0])asf:f.write(effected)Using VST3® or Audio Unit instrument and effect pluginsfrompedalboardimportPedalboard,Reverb,load_pluginfrompedalboard.ioimportAudioFilefrommidoimportMessage# 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 15effect.ratio=15# Render some audio by passing MIDI to an instrument:sample_rate=44100audio=instrument([Message("note_on",note=60),Message("note_off",note=60,time=5)],duration=5,# secondssample_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 chainsThis example creates a delayed pitch-shift effect by running
multiple Pedalboards in parallel on the same audio.Pedalboardobjects are themselvesPluginobjects, so you can nest them
as much as you like:frompedalboardimportPedalboard,Compressor,Delay,Distortion,Gain,PitchShift,Reverb,Mixpassthrough=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 AudioOn macOS or Windows, Pedalboard supports streaming live audio throughanAudioStreamobject,
allowing for real-time manipulation of audio by adding effects in Python.frompedalboardimportPedalboard,Chorus,Compressor,Delay,Gain,Reverb,Phaserfrompedalboard.ioimportAudioStream# Open up an audio stream:withAudioStream(input_device_name="Apogee Jam+",# Guitar interfaceoutput_device_name="MacBook Pro Speakers")asstream:# 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 intf.dataPipelinesimporttensorflowastfsr=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(lambdaaudio: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(lambdaeffected:(effected,1)).batch(1),epochs=10)For more examples, see:the "examples" folder of this repositorythe "Pedalboard Demo" Colab notebookWorking with Audio in Python (feat. Pedalboard)by Peter Sobot at EuroPython 2022an interactive web demo on Hugging Face Spaces and Gradio(via@AK391)ContributingContributions topedalboardare welcomed! SeeCONTRIBUTING.mdfor details.CitingTo citepedalboardin academic work, useits entry on Zenodo:To cite via BibTeX:@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}}Licensepedalboardis Copyright 2021-2023 Spotify AB.pedalboardis licensed under theGNU General Public License v3.pedalboardincludes a number of libraries that are statically compiled, and which carry the following licenses:The core audio processing code is pulled fromJUCE 6, which isdual-licensed under a commercial license and the GPLv3.TheVST3 SDK, bundled with JUCE, is owned bySteinberg® Media Technologies GmbHand licensed under the GPLv3.ThePitchShiftplugin usesthe Rubber Band Library, which isdual-licensed under a commercial licenseand the GPLv2 (or newer).TheMP3Compressorplugin useslibmp3lame from the LAME project, which islicensed under the LGPLv2andupgraded to the GPLv3 for inclusion in this project (as permitted by the LGPLv2).TheGSMFullRateCompressorplugin useslibgsm, which islicensed under the ISC licenseandcompatible with the GPLv3.VST is a registered trademark of Steinberg Media Technologies GmbH.