PyTorch 中的音频数据增强。灵感来源于 audiomentations。

• 支持 CPU 和 GPU (CUDA) - 速度优先
• 支持多通道（或单声道）音频批次
• 变换扩展了 nn.Module，因此可以作为 PyTorch 神经网络模型的一部分进行集成
• 大多数变换是可微的
• 三种模式：per_batch、per_example 和 per_channel
• 跨平台兼容性
• 宽松的 MIT 许可证
• 目标是高测试覆盖率

安装

pip install torch-audiomentations

使用示例

import torch
from torch_audiomentations import Compose, Gain, PolarityInversion


# 初始化增强可调用对象
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")

# 创建一个包含白噪声的示例张量。
# 该张量表示 8 个音频片段，每个片段有 2 个通道（立体声），时长 2 秒，采样率为 16 kHz。
audio_samples = torch.rand(size=(8, 2, 32000), dtype=torch.float32, device=torch_device) - 0.5

# 应用增强。这会独立地改变批次中（部分）音频片段的增益和极性。
perturbed_audio_samples = apply_augmentation(audio_samples, sample_rate=16000)

已知问题

• 目标数据处理仍处于实验阶段 (#3)。解决方法：如果目标数据与输入具有相同形状，目前可以使用 freeze_parameters 和 unfreeze_parameters。
• 在多进程环境中使用 torch-audiomentations 可能会导致内存泄漏 (#132)。解决方法：如果在多进程环境中使用 torch-audiomentations，最好在 CPU 上运行变换。
• 不正式支持多 GPU / DDP (#136)。作者没有多 GPU 配置来测试和修复此问题。如果您愿意为此捐赠硬件，请联系我们。解决方法：改用单 GPU 运行变换。
• PitchShift 不支持小幅度音高变换，尤其是在低采样率下 (#151)。解决方法：如果需要对低采样率音频应用小幅度音高变换，可以直接使用 audiomentations 中的 PitchShift 或 torch-pitch-shift，而无需使用计算高效音高变换目标的函数。

贡献

欢迎贡献者！ 加入 Asteroid 的 Slack 与我们一起讨论 torch-audiomentations。

动机：速度

我们不希望数据增强成为模型训练速度的瓶颈。以下是运行 1D 卷积所需时间的比较：

注意：并非所有变换与 CPU 相比都有如此显著的速度提升。一般来说，在 GPU 上运行音频数据增强并不总是最佳选择。更多信息请参阅这篇文章：https://iver56.github.io/audiomentations/guides/cpu_vs_gpu/

当前状态

torch-audiomentations 处于早期开发阶段，因此 API 可能会发生变化。

波形变换

每个变换都具有 mode、p 和 p_mode——这些参数决定了增强如何执行。

• mode 决定增强的随机化如何分组和应用。
• p 决定应用增强的概率。
• p_mode 决定增强的开启或关闭方式。

此可视化展示了不同 mode 和 p_mode 组合如何执行增强。

AddBackgroundNoise

新增于 v0.5.0

向输入音频添加背景噪声。

AddColoredNoise

新增于 v0.7.0

向输入音频添加彩色噪声。

ApplyImpulseResponse

新增于 v0.5.0

将给定音频与冲激响应进行卷积。

BandPassFilter

新增于 v0.9.0

对输入音频应用带通滤波。

BandStopFilter

新增于 v0.10.0

对输入音频应用带阻滤波，也称为陷波滤波器。

Gain

新增于 v0.1.0

通过随机振幅因子乘以音频，以降低或增加音量。此技术可以帮助模型对输入音频的整体增益具有一定不变性。

警告：此变换可能会返回超出 [-1, 1] 范围的样本，这可能导致削波或环绕失真，具体取决于后续对音频的处理方式。另请参阅 https://en.wikipedia.org/wiki/Clipping_(audio)#Digital_clipping

HighPassFilter

新增于 v0.8.0

对输入音频应用高通滤波。

Identity

新增于 v0.11.0

此变换返回未更改的输入。在需要禁用数据增强的情况下，可用于简化代码。

LowPassFilter

新增于 v0.8.0

对输入音频应用低通滤波。

PeakNormalization

新增于 v0.2.0

应用恒定增益，使批次中每个音频片段中的最高信号电平达到 0 dBFS，即当所有样本必须介于 -1 和 1 之间时允许的最响度级别。

此变换有一个替代模式（apply_to="only_too_loud_sounds"），仅对那些信号值严重超出 [-1, 1] 范围的音频片段应用增益。这有助于避免过响音频出现数字削波，同时保持其他音频不变。

PitchShift

新增于 v0.9.0

在不改变节奏的情况下升高或降低音高。

极性反转

在 v0.1.0 中添加

将音频样本上下翻转，从而反转其极性。换句话说，就是将波形乘以 -1，使负值变为正值，反之亦然。单独播放时，结果听起来与原始音频相同。然而，当与其他音频源混合时，结果可能会有所不同。这种波形反转技术有时用于音频抵消或获取两个波形之间的差异。不过，在音频数据增强的背景下，这种变换在训练对相位敏感的机器学习模型时可能很有用。

时移

在 v0.5.0 中添加

将音频向前或向后移动，可以选择是否循环。

通道混洗

在 v0.6.0 中添加

对于多声道音频输入（例如立体声），可以随机混洗声道顺序，比如将左声道变为右声道，反之亦然。这种变换有助于缓解输入多声道波形的机器学习模型中的位置偏差问题。

如果输入音频是单声道，则此变换不会产生任何效果，只会发出警告。

时间反转

在 v0.10.0 中添加

类似于视觉领域中对图像进行随机翻转一样，沿着时间轴反转（倒置）音频。这在音频分类任务中可能具有一定的意义。该方法已在论文《AudioCLIP：将 CLIP 扩展至图像、文本和音频》中成功应用，详见 arXiv:2106.13043。

更改记录

尚未发布

新增

• 添加新变换：Mix、Padding、RandomCrop 和 SpliceOut

[v0.12.0] - 2025-01-15

移除

• 移除对 librosa 的依赖，改为使用 torchaudio

[v0.11.2] - 2025-01-09

修复

• 修复在多 GPU 训练时 transform_parameters 中与设备相关的错误
• 修复 AddColoredNoise 中与形状相关的边缘情况错误
• 修复将不兼容的 Path 数据类型传递给 torchaudio.info 的问题

[v0.11.1] - 2024-02-07

变更

• 在 LowPassFilter 和 HighPassFilter 中增加对固定截止频率的支持
• 在 AddColoredNoise 中增加对 min_f_decay == max_f_decay 的支持
• 将 torchaudio 的最低版本要求从 >=0.7.0 提升至 >=0.9.0

修复

• 修复 Shift 中不准确的类型提示
• 移除 set_backend，以避免 torchaudio 产生的 UserWarning

[v0.11.0] - 2022-06-29

新增

• 添加新变换：Identity
• 增加处理目标与输入同时进行的 API。部分变换已经实验性地支持此功能。

变更

• 增加 ObjectDict 输出类型，作为 torch.Tensor 的替代选项。目前该替代选项为可选（出于向后兼容性考虑），但请注意，旧的输出类型（torch.Tensor）已被弃用，并将在未来的版本中完全移除。
• 允许为 AddBackgroundNoise 和 ApplyImpulseResponse 指定文件路径、文件夹路径、文件列表或文件夹列表。
• 要求使用更新版本的 torch-pitch-shift，以确保 PitchShift 能够兼容 torchaudio 0.11。

修复

• 修复 BandPassFilter 在 GPU 上无法正常工作的问题。

[v0.10.1] - 2022-03-24

新增

• 在 AddBackgroundNoise 中增加对最小信噪比等于最大信噪比的支持
• 增加对 librosa 0.9.0 的支持。

修复

• 修复 AddBackgroundNoise 中加载的音频片段有时会被重新采样为不兼容长度的问题。

[v0.10.0] - 2022-02-11

新增

• 实现 OneOf 和 SomeOf，用于从一组变换中随机选择一个或多个应用
• 实现新变换：BandStopFilter 和 TimeInversion

变更

• 将 ir_paths 放入 ApplyImpulseResponse 的 transform_parameters 中，以便检查所使用的脉冲响应。这也使 freeze_parameters() 表现出预期的行为。

修复

• 修复 BandPassFilter 中实际带宽是预期值两倍的问题。默认值已相应更新。如果您之前指定了 min_bandwidth_fraction 和/或 max_bandwidth_fraction，现在需要将这些数值加倍才能获得与以前相同的效果。

[v0.9.1] - 2021-12-20

新增

• 正式声明支持 Python >=3.9。

[v0.9.0] - 2021-10-11

新增

• 在 ApplyImpulseResponse 中添加参数 compensate_for_propagation_delay
• 实现 BandPassFilter
• 实现 PitchShift

移除

• 已移除对 torchaudio <=0.6 的支持。

[v0.8.0] - 2021-06-15

新增

• 实现 HighPassFilter 和 LowPassFilter

弃用

• 对 torchaudio <=0.6 的支持已被弃用，未来将被移除。

移除

• 已移除对 PyTorch <=1.6 的支持。

[v0.7.0] - 2021-04-16

新增

• 实现 AddColoredNoise

弃用

• 对 PyTorch <=1.6 的支持已被弃用，未来将被移除。

[v0.6.0] - 2021-02-22

新增

• 实现 ShuffleChannels

[v0.5.1] - 2020-12-18

修复

• 修复 AddBackgroundNoise 在 CUDA 上无法正常工作的问题
• 修复查找音频文件时无法找到符号链接的音频文件或文件夹的问题
• 尽可能使用 torch.fft.rfft 替代 torch.rfft（已在 PyTorch 1.7 中弃用）。此外，这一改动还提升了 ApplyImpulseResponse 的性能。

[v0.5.0] - 2020-12-08

新增

• 发布 AddBackgroundNoise 和 ApplyImpulseResponse
• 实现 Shift

变更

• 将 sample_rate 设置为可选。允许在 __init__ 中指定 sample_rate，而不是在 forward 中指定。这意味着现在可以在 Compose 中使用 torchaudio 的变换。

移除

• 移除对 1 维和 2 维音频张量的支持。目前仅支持 3 维音频张量。

修复

• 修复无法使用 nn.Module 子类的 parameters 方法的问题
• 修复无法找到文件扩展名为大写的文件的问题。

[v0.4.0] - 2020-11-10

新增

• 实现 Compose 以应用多个变换
• 实现实用函数 from_dict 和 from_yaml，用于从字典、JSON 或 YAML 中加载数据增强配置
• 正式支持大多数变换的可微性。

[v0.3.0] - 2020-10-27

新增

• 增加对 per_batch 和 per_channel 等替代模式的支持。

变更

• 变换在评估模式下会返回未经修改的输入。

[v0.2.0] - 2020-10-19

新增

• 实现 PeakNormalization
• 在 API 中公开 convolve

变更

• 简化了使用 CUDA 张量的 API。设备现在会根据输入张量自动推断。

[v0.1.0] - 2020-10-12

新增

• 初始发布，包含 Gain 和 PolarityInversion。

开发

设置

可以通过 conda 创建一个支持 GPU 的 torch-audiomentations 开发环境：

• conda env create

运行测试

pytest

规范

• 使用 black 格式化 Python 代码
• 使用 Google 风格的文档字符串
• 使用显式的相对导入，而非绝对导入

致谢

torch-audiomentations 的开发得到了 Nomono 的大力支持。

感谢所有为改进 torch-audiomentations 做出贡献的 贡献者。

torch-audiomentations 快速上手指南

torch-audiomentations 是一个基于 PyTorch 的音频数据增强库，专为深度学习模型训练设计。它支持 CPU 和 GPU 加速，可直接作为 nn.Module 集成到神经网络中，并支持批量多通道音频处理。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：跨平台支持 (Linux, macOS, Windows)
• Python 版本：建议 Python 3.8 及以上
• 核心依赖：
  • torch (PyTorch)
  • torchaudio (版本 >= 0.9.0)
• 硬件加速：可选 NVIDIA GPU (需安装对应的 CUDA 版本以启用 GPU 加速)

安装步骤

推荐使用 pip 进行安装。国内开发者建议使用清华或阿里镜像源以提升下载速度。

使用默认源安装：

pip install torch-audiomentations

使用国内镜像源安装（推荐）：

pip install torch-audiomentations -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下示例展示了如何初始化一个包含增益调整 (Gain) 和极性反转 (PolarityInversion) 的增强管道，并将其应用于一个批次的立体声音频张量。

import torch
from torch_audiomentations import Compose, Gain, PolarityInversion


# 1. 初始化增强组合 (Compose)
apply_augmentation = Compose(
    transforms=[
        Gain(
            min_gain_in_db=-15.0,
            max_gain_in_db=5.0,
            p=0.5,  # 50% 的概率应用此变换
        ),
        PolarityInversion(p=0.5)  # 50% 的概率应用此变换
    ]
)

# 2. 设置设备 (自动检测 CUDA 或 CPU)
torch_device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# 3. 创建示例音频张量
# 形状说明：(Batch_Size=8, Channels=2, Samples=32000)
# 代表 8 段立体声音频，采样率 16kHz，时长 2 秒
audio_samples = torch.rand(size=(8, 2, 32000), dtype=torch.float32, device=torch_device) - 0.5

# 4. 应用增强
# 注意：必须传入 sample_rate 参数
perturbed_audio_samples = apply_augmentation(audio_samples, sample_rate=16000)

# 输出结果形状与输入一致
print(perturbed_audio_samples.shape) 

关键特性提示：

• 模式选择：大多数变换支持 per_batch（整批统一）、per_example（每段音频独立）和 per_channel（每声道独立）三种随机化模式。
• 可微分性：大部分变换是可微分的，适合端到端训练。
• 设备兼容：代码会自动根据输入张量所在的设备（CPU/GPU）执行运算，无需手动迁移变换对象。