Torch Audiomentations

0.12.0 · active · verified Fri Apr 10

torch-audiomentations is a PyTorch library for audio data augmentation, designed for deep learning workflows. It offers fast, GPU-compatible transforms for batches of multichannel or mono audio, extending `nn.Module` for seamless integration into neural network models. The library is currently at version 0.12.0 and receives active updates with frequent releases.

Warnings

breaking Support for 1-dimensional and 2-dimensional audio tensors was removed. Only 3-dimensional audio tensors (batch_size, num_channels, num_samples) are supported.
Fix: Ensure all input audio tensors are 3-dimensional, even for mono audio (e.g., shape `(batch_size, 1, num_samples)`).
deprecated The 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.
Fix: Switch to `ObjectDict` output where applicable. Consult the documentation for the exact migration path.
gotcha Using `torch-audiomentations` in a multiprocessing context (e.g., with PyTorch's `DataLoader` `num_workers > 0`) can lead to memory leaks.
Fix: If experiencing memory leaks in a multiprocessing setup, consider running the transforms on the CPU or setting `num_workers=0` for the DataLoader.
gotcha Multi-GPU (DDP) setups are not officially supported due to testing limitations and may not work as expected.
Fix: For 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.
breaking The `librosa` dependency was entirely removed in favor of `torchaudio`.
Fix: Ensure `torchaudio` is installed and up-to-date. Any code implicitly relying on `librosa` being present through `torch-audiomentations` will break.
breaking The minimum `torchaudio` dependency was bumped from `>=0.7.0` to `>=0.9.0`.
Fix: Update `torchaudio` to at least version `0.9.0` (e.g., `pip install torchaudio>=0.9.0`).

Install

pip install torch-audiomentations Install stable version

Imports

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

Quickstart

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}")

view raw JSON →