Package: torch-audiomentations
Audio data augmentation in PyTorch. Inspired byaudiomentations.Supports CPU and GPU (CUDA) - speed is a prioritySupports batches of multichannel (or mono) audioTransforms extendnn.Module, so they can be integrated as a part of a pytorch neural network modelMost transforms are differentiableThree modes:per_batch,per_exampleandper_channelCross-platform compatibilityPermissive MIT licenseAiming for high test coverageSetuppip install torch-audiomentationsUsage exampleimporttorchfromtorch_audiomentationsimportCompose,Gain,PolarityInversion# Initialize augmentation callableapply_augmentation=Compose(transforms=[Gain(min_gain_in_db=-15.0,max_gain_in_db=5.0,p=0.5,),PolarityInversion(p=0.5)])torch_device=torch.device("cuda"iftorch.cuda.is_available()else"cpu")# Make an example tensor with white noise.# This tensor represents 8 audio snippets with 2 channels (stereo) and 2 s of 16 kHz audio.audio_samples=torch.rand(size=(8,2,32000),dtype=torch.float32,device=torch_device)-0.5# Apply augmentation. This varies the gain and polarity of (some of)# the audio snippets in the batch independently.perturbed_audio_samples=apply_augmentation(audio_samples,sample_rate=16000)Known issuesTarget data processing is still in an experimental state (#3). Workaround: Usefreeze_parametersandunfreeze_parametersfor now if the target data is audio with the same shape as the input.Using torch-audiomentations in a multiprocessing context can lead to memory leaks (#132). Workaround: If using torch-audiomentations in a multiprocessing context, it'll probably work better to run the transforms on CPU.Multi-GPU / DDP is not officially supported (#136). The author does not have a multi-GPU setup to test & fix this. Get in touch if you want to donate some hardware for this. Workaround: Run the transforms on single GPU instead.PitchShiftdoes not support small pitch shifts, especially for low sample rates (#151). Workaround: If you need small pitch shifts applied to low sample rates, usePitchShift in audiomentationsortorch-pitch-shiftdirectly without the function for calculating efficient pitch-shift targets.ContributeContributors welcome!Join the Asteroid's slackto start discussing abouttorch-audiomentationswith us.Motivation: SpeedWe don't want data augmentation to be a bottleneck in model training speed. Here is a
comparison of the time it takes to run 1D convolution:Note: Not all transforms have a speedup this impressive compared to CPU. In general, running audio data augmentation on GPU is not always the best option. For more info, see this article:https://iver56.github.io/audiomentations/guides/cpu_vs_gpu/Current statetorch-audiomentations is in an early development stage, so the APIs are subject to change.Waveform transformsEvery transform hasmode,p, andp_mode-- the parameters that decide how the augmentation is performed.modedecides how the randomization of the augmentation is grouped and applied.pdecides the on/off probability of applying the augmentation.p_modedecides how the on/off of the augmentation is applied.This visualization shows how different combinations ofmodeandp_modewould perform an augmentation.AddBackgroundNoiseAdded in v0.5.0Add background noise to the input audio.AddColoredNoiseAdded in v0.7.0Add colored noise to the input audio.ApplyImpulseResponseAdded in v0.5.0Convolve the given audio with impulse responses.BandPassFilterAdded in v0.9.0Apply band-pass filtering to the input audio.BandStopFilterAdded in v0.10.0Apply band-stop filtering to the input audio. Also known as notch filter.GainAdded in v0.1.0Multiply the audio by a random amplitude factor to reduce or increase the volume. This
technique can help a model become somewhat invariant to the overall gain of the input audio.Warning: This transform can return samples outside the [-1, 1] range, which may lead to
clipping or wrap distortion, depending on what you do with the audio in a later stage.
See alsohttps://en.wikipedia.org/wiki/Clipping_(audio)#Digital_clippingHighPassFilterAdded in v0.8.0Apply high-pass filtering to the input audio.IdentityAdded in v0.11.0This transform returns the input unchanged. It can be used for simplifying the code
in cases where data augmentation should be disabled.LowPassFilterAdded in v0.8.0Apply low-pass filtering to the input audio.PeakNormalizationAdded in v0.2.0Apply a constant amount of gain, so that highest signal level present in each audio snippet
in the batch becomes 0 dBFS, i.e. the loudest level allowed if all samples must be between
-1 and 1.This transform has an alternative mode (apply_to="only_too_loud_sounds") where it only
applies to audio snippets that have extreme values outside the [-1, 1] range. This is useful
for avoiding digital clipping in audio that is too loud, while leaving other audio
untouched.PitchShiftAdded in v0.9.0Pitch-shift sounds up or down without changing the tempo.PolarityInversionAdded in v0.1.0Flip the audio samples upside-down, reversing their polarity. In other words, multiply the
waveform by -1, so negative values become positive, and vice versa. The result will sound
the same compared to the original when played back in isolation. However, when mixed with
other audio sources, the result may be different. This waveform inversion technique
is sometimes used for audio cancellation or obtaining the difference between two waveforms.
However, in the context of audio data augmentation, this transform can be useful when
training phase-aware machine learning models.ShiftAdded in v0.5.0Shift the audio forwards or backwards, with or without rolloverShuffleChannelsAdded in v0.6.0Given multichannel audio input (e.g. stereo), shuffle the channels, e.g. so left can become right and vice versa.
This transform can help combat positional bias in machine learning models that input multichannel waveforms.If the input audio is mono, this transform does nothing except emit a warning.TimeInversionAdded in v0.10.0Reverse (invert) the audio along the time axis similar to random flip of
an image in the visual domain. This can be relevant in the context of audio
classification. It was successfully applied in the paperAudioCLIP: Extending CLIP to Image, Text and AudioChangelogUnreleasedAddedAdd new transforms:Mix,Padding,RandomCropandSpliceOut[v0.11.1] - 2024-02-07ChangedAdd support for constant cutoff frequency inLowPassFilterandHighPassFilterAdd support for min_f_decay==max_f_decay inAddColoredNoiseBump torchaudio dependency from >=0.7.0 to >=0.9.0FixedFix inaccurate type hints inShiftRemoveset_backendto avoidUserWarningfrom torchaudio[v0.11.0] - 2022-06-29AddedAdd new transform:IdentityAdd API for processing targets alongside inputs. Some transforms experimentally
support this feature already.ChangedAddObjectDictoutput type as alternative totorch.Tensor. This alternative is opt-in for
now (for backwards-compatibility), but note that the old output type (torch.Tensor) is
deprecated and support for it will be removed in a future version.Allow specifying a file path, a folder path, a list of files or a list of folders toAddBackgroundNoiseandApplyImpulseResponseRequire newer version oftorch-pitch-shiftto ensure support for torchaudio 0.11 inPitchShiftFixedFix a bug whereBandPassFilterdidn't work on GPU[v0.10.1] - 2022-03-24AddedAdd support for min SNR == max SNR inAddBackgroundNoiseAdd support for librosa 0.9.0FixedFix a bug where loaded audio snippets were sometimes resampled to an incompatible
length inAddBackgroundNoise[v0.10.0] - 2022-02-11AddedImplementOneOfandSomeOffor applying one or more of a given set of transformsImplement new transforms:BandStopFilterandTimeInversionChangedPutir_pathsin transform_parameters inApplyImpulseResponseso it is possible
to inspect what impulse responses were used. This also givesfreeze_parameters()the expected behavior.FixedFix a bug where the actual bandwidth was twice as large as expected inBandPassFilter. The default values have been updated accordingly.
If you were previously specifyingmin_bandwidth_fractionand/ormax_bandwidth_fraction,
you now need to double those numbers to get the same behavior as before.[v0.9.1] - 2021-12-20AddedOfficially mark python>=3.9 as supported[v0.9.0] - 2021-10-11AddedAdd parametercompensate_for_propagation_delayinApplyImpulseResponseImplementBandPassFilterImplementPitchShiftRemovedSupport for torchaudio<=0.6 has been removed[v0.8.0] - 2021-06-15AddedImplementHighPassFilterandLowPassFilterDeprecatedSupport for torchaudio<=0.6 is deprecated and will be removed in the futureRemovedSupport for pytorch<=1.6 has been removed[v0.7.0] - 2021-04-16AddedImplementAddColoredNoiseDeprecatedSupport for pytorch<=1.6 is deprecated and will be removed in the future[v0.6.0] - 2021-02-22AddedImplementShuffleChannels[v0.5.1] - 2020-12-18FixedFix a bug whereAddBackgroundNoisedid not work on CUDAFix a bug where symlinked audio files/folders were not found when looking for audio filesUse torch.fft.rfft instead of the torch.rfft (deprecated in pytorch 1.7) when possible. As a
bonus, the change also improves performance inApplyImpulseResponse.[v0.5.0] - 2020-12-08AddedReleaseAddBackgroundNoiseandApplyImpulseResponseImplementShiftChangedMakesample_rateoptional. Allow specifyingsample_ratein__init__instead offorward. This means torchaudio transforms can be used inComposenow.RemovedRemove support for 1-dimensional and 2-dimensional audio tensors. Only 3-dimensional audio
tensors are supported now.FixedFix a bug where one could not use theparametersmethod of thenn.ModulesubclassFix a bug where files with uppercase filename extension were not found[v0.4.0] - 2020-11-10AddedImplementComposefor applying multiple transformsImplement utility functionsfrom_dictandfrom_yamlfor loading data augmentation
configurations from dict, json or yamlOfficially support differentiability in most transforms[v0.3.0] - 2020-10-27AddedAdd support for alternative modesper_batchandper_channelChangedTransforms now return the input unchanged when they are in eval mode[v0.2.0] - 2020-10-19AddedImplementPeakNormalizationExposeconvolvein the APIChangedSimplify API for using CUDA tensors. The device is now inferred from the input tensor.[v0.1.0] - 2020-10-12AddedInitial release withGainandPolarityInversionDevelopmentSetupA GPU-enabled development environment for torch-audiomentations can be created with conda:conda env createRun testspytestConventionsFormat python code withblackUseGoogle-style docstringsUse explicit relative imports, not absolute importsAcknowledgementsThe development of torch-audiomentations is kindly backed byNomono.Thanks toall contributorswho help improving torch-audiomentations.