Install & Compatibility
Where this runs
tested against v0.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 76.8s
py 3.11
✕ build_error
✓ 68.3s
py 3.12
✕ build_error
✓ 62s
py 3.13
✕ build_error
✓ 56.8s
py 3.9
✕ build_error
✕ timeout
4736MB installed
● package 4736MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Compose
✓ from torch_audiomentations import Compose
✗ from torch-audiomentations import Compose
The PyPI package name uses a hyphen, but the Python import path uses an underscore.
Gain
✓ from torch_audiomentations import Gain
PolarityInversion
✓ from torch_audiomentations import PolarityInversion
This example demonstrates how to apply a sequence of audio augmentations (Gain and PolarityInversion) to a batch of audio samples using `Compose`. It dynamically selects between CPU and GPU for processing.
import torch
import os
from torch_audiomentations import Compose, Gain, PolarityInversion
# Initialize augmentation callable
apply_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" if torch.cuda.is_available() else "cpu")
# Make an example tensor with white noise.
# This tensor represents 8 audio snippets with 2 channels (stereo) and 2 seconds of 16 kHz audio.
audio_samples = torch.rand(size=(8, 2, 32000), dtype=torch.float32, device=torch_device) - 0.5
# Apply augmentation.
perturbed_audio_samples = apply_augmentation(audio_samples, sample_rate=16000)
print(f"Original audio shape: {audio_samples.shape}")
print(f"Perturbed audio shape: {perturbed_audio_samples.shape}")
print(f"Running on device: {torch_device}")
Debug
Known issues
breakingSupport for 1-dimensional and 2-dimensional audio tensors was removed. Only 3-dimensional audio tensors (batch_size, num_channels, num_samples) are supported.fixEnsure all input audio tensors are 3-dimensional, even for mono audio (e.g., shape `(batch_size, 1, num_samples)`).
affects: <0.5.0 to 0.5.0+
deprecatedThe default `torch.Tensor` output type is deprecated. An `ObjectDict` output type is available and is the recommended future-proof option. Support for `torch.Tensor` output will be removed in a future version.fixSwitch to `ObjectDict` output where applicable. Consult the documentation for the exact migration path.
affects: 0.11.0+
gotchaUsing `torch-audiomentations` in a multiprocessing context (e.g., with PyTorch's `DataLoader` `num_workers > 0`) can lead to memory leaks.fixIf experiencing memory leaks in a multiprocessing setup, consider running the transforms on the CPU or setting `num_workers=0` for the DataLoader.
affects: All versions
gotchaMulti-GPU (DDP) setups are not officially supported due to testing limitations and may not work as expected.fixFor now, it's recommended to run transforms on a single GPU. Engage with the project maintainers if multi-GPU support is critical for your use case.
affects: All versions
breakingThe `librosa` dependency was entirely removed in favor of `torchaudio`.fixEnsure `torchaudio` is installed and up-to-date. Any code implicitly relying on `librosa` being present through `torch-audiomentations` will break.
affects: 0.12.0+
breakingThe minimum `torchaudio` dependency was bumped from `>=0.7.0` to `>=0.9.0`.fixUpdate `torchaudio` to at least version `0.9.0` (e.g., `pip install torchaudio>=0.9.0`).
affects: 0.11.1+
Errors
Common errors & fixes
RuntimeError: expected 3D input (got 2D input)
The input audio tensor does not have the expected (batch_size, num_channels, num_samples) shape required by torch-audiomentations.
fixReshape the input tensor to include batch and/or channel dimensions, typically using `unsqueeze()`. Example for mono audio: `audio = audio.unsqueeze(1)` for `(batch_size, num_samples)` to `(batch_size, 1, num_samples)`.
RuntimeError: Input and parameter tensors must be on the same device
The input audio tensor is on a different device (e.g., CPU) than the `torch-audiomentations` augmentation module (e.g., GPU).
fixEnsure both the augmentation module and the input tensor are on the same device using `.to(device)`. Example: `augment = augment.to(device)` and `samples = samples.to(device)`.
TypeError: expected scalar type Float but got Int
The input audio tensor has an integer data type (e.g., `torch.int16`) instead of the required `torch.float32` for augmentation operations.
fixConvert the input audio tensor to `torch.float32` before passing it to the augmentation, typically normalizing it if it comes from integer PCM data. Example: `samples = samples.to(torch.float32) / 32768.0`.
TypeError: __init__() missing 1 required positional argument: 'sample_rate'
An augmentation transform was instantiated without providing the essential `sample_rate` argument, which is required by most transforms.
fixPass the audio's sample rate when initializing the augmentation transform. Example: `augment = AddBackgroundNoise(min_snr_in_db=3.0, max_snr_in_db=30.0, sample_rate=16000)`.
ImportError: cannot import name 'AddBackgroundNoise' from 'torch_audiomentations'
Augmentation transforms are located within the `torch_audiomentations.transforms` submodule, not directly under the top-level `torch_audiomentations` package.
fixImport the transform from the correct submodule. Example: `from torch_audiomentations.transforms import AddBackgroundNoise`.
Upgrade
Version history
0.12.0latest on PyPI · released Jan 15, 2025
Audit
Dependencies
juliusrequiredRequired for audio processing utilities.
torchrequiredCore PyTorch dependency for tensor operations and neural network modules.
torch-pitch-shiftrequiredRequired for pitch shifting functionality.
torchaudiorequiredRequired for audio I/O and transformations, especially after `librosa` removal.
PyYAMLoptionalOptional dependency for loading augmentation configurations from YAML files.