目录
目录

torchaudio.backend

概述

torchaudio.backend 模块提供了音频文件输入/输出功能的实现，包括 torchaudio.info、torchaudio.load 和 torchaudio.save。

注意

版本 2.1 将修订 torchaudio.info, torchaudio.load, 和 torchaudio.save，以允许通过函数参数选择后端，而不是 torchaudio.set_audio_backend，其中 FFmpeg 是默认后端。 新逻辑可以在当前版本中通过设置环境变量 TORCHAUDIO_USE_BACKEND_DISPATCHER=1 来启用。 有关新 API 的详细信息，请参阅 未来 API。

目前有两种可用的实现。

  • "sox_io"（Linux/macOS 上的默认值）

  • "soundfile"（Windows 默认）

注意

请勿直接在 torchaudio.backend 中调用函数，而应使用 torchaudio.info、torchaudio.load 和 torchaudio.save，并通过 torchaudio.set_audio_backend() 设置正确的后端。

可用性

"sox_io" 后端需要 C++ 扩展模块，该模块包含在 Linux/macOS 二进制发行版中。此后端在 Windows 上不可用。

"soundfile" 后端需要 SoundFile。请参考 SoundFile文档 以获取安装说明。

常用数据结构

用于报告音频文件元数据的结构。

AudioMetaData

class torchaudio.backend.common.AudioMetaData(sample_rate: int, num_frames: int, num_channels: int, bits_per_sample: int, encoding: str)[source]

torchaudio.info 函数的返回类型。

此类被 "sox_io" backend 和 "soundfile" backend 使用。

Variables:

  • sample_rate (int) – 采样率

  • num_frames (int) – 帧数

  • num_channels (int) – 通道数量

  • bits_per_sample (int) – 每个样本的位数。对于有损格式，或当无法准确推断时，此值为 0。

  • 编码 (str) –

    音频编码 编码可采用的值如下之一：

    • PCM_S: Signed integer linear PCM

    • PCM_U: Unsigned integer linear PCM

    • PCM_F: Floating point linear PCM

    • FLAC: Flac, Free Lossless Audio Codec

    • ULAW: Mu-law

    • ALAW: A-law

    • MP3 : MP3, MPEG-1 Audio Layer III

    • VORBIS: OGG Vorbis

    • AMR_WB: Adaptive Multi-Rate Wideband

    • AMR_NB: Adaptive Multi-Rate Narrowband

    • OPUS: Opus

    • HTK: Single channel 16-bit PCM

    • UNKNOWN : None of above

Tutorials using AudioMetaData:
Audio I/O

音频输入输出

音频输入输出

Sox IO 后端

sox_io 后端在 Linux/macOS 上可用且为默认设置，但在 Windows 上不可用。

此后端的 I/O 函数支持 TorchScript。

您可以使用以下命令从另一个后端切换到 sox_io 后端；

torchaudio.set_audio_backend("sox_io")

信息

torchaudio.backend.sox_io_backend.info(filepath: str, format: Optional[str] = None) → AudioMetaData[source]

获取音频文件的信号信息。

Parameters:

  • filepath (路径类对象 或 文件类对象) –

    音频数据的来源。当函数未通过 TorchScript 编译时， （例如 torch.jit.script），接受以下类型；

    • path-like: file path

    • file-like: Object with read(size: int) -> bytes method, which returns byte string of at most size length.

    当函数由 TorchScript 编译时，仅允许 str 种类型。

    注意

    • 当输入类型为文件对象时，此函数无法 获取某些格式的正确长度 (num_samples)， 例如 vorbis。 在这种情况下，num_samples 的值为 0。

    • 此参数被故意标注为 str，仅出于 TorchScript 编译器兼容性的考虑。

  • format (str 或 None, 可选) – 使用给定的格式覆盖格式检测。 当 libsox 无法从文件头或扩展名推断格式时，提供此参数可能会有所帮助。

Returns:

给定音频的元数据。

Return type:

AudioMetaData

加载

torchaudio.backend.sox_io_backend.load(filepath: str, frame_offset: int = 0, num_frames: int = -1, normalize: bool = True, channels_first: bool = True, format: Optional[str] = None) → Tuple[Tensor, int][source]

从文件加载音频数据。

注意

此函数可以处理底层 libsox 支持的所有编解码器， 但已在以下格式上进行了测试；

  • WAV, AMB

    • 32-bit floating-point

    • 32-bit signed integer

    • 24-bit signed integer

    • 16-bit signed integer

    • 8-bit unsigned integer (WAV only)

  • MP3

  • FLAC

  • OGG/VORBIS

  • OPUS

  • SPHERE

  • AMR-NB

要加载 MP3、FLAC、OGG/VORBIS、OPUS 以及其他 libsox 原生不支持的编解码器，您的 torchaudio 安装必须链接到 libsox 以及相应的编解码器库，例如 libmad 或 libmp3lame 等。

默认情况下（normalize=True, channels_first=True），此函数返回一个 dtype 为 float32 且形状为 [channel, time] 的 Tensor。

警告

normalize 参数不执行音量归一化。 它仅将样本类型从原生样本类型转换为 torch.float32。

当输入格式为整数类型的 WAV（例如 32 位有符号整数、16 位有符号整数、24 位有符号整数和 8 位无符号整数）时，通过提供 normalize=False，此函数可以返回整数 Tensor，其中样本在对应数据类型的整个范围内表示，即对于 32 位有符号 PCM 为 int32 tensor，对于 16 位有符号 PCM 为 int16，对于 8 位无符号 PCM 为 uint8。由于 torch 不支持 int24 数据类型，24 位有符号 PCM 会被转换为 int32 tensors。

normalize 参数对 32 位浮点 WAV 及其他格式（如 flac 和 mp3）无效。

对于这些格式，此函数始终返回一个包含值的 float32 张量。

Parameters:

  • filepath (路径类对象 或 文件类对象) –

    音频数据的来源。当函数未通过 TorchScript 编译时， （例如 torch.jit.script），接受以下类型；

    • path-like: file path

    • file-like: Object with read(size: int) -> bytes method, which returns byte string of at most size length.

    当函数由 TorchScript 编译时，仅允许 str 种类型。

    注意：由于与 TorchScript 编译器的兼容性，此参数被特意注释为 str。

  • frame_offset (int) – 开始读取数据之前要跳过的帧数。

  • num_frames (int, optional) – 要读取的最大帧数。-1 表示从 frame_offset 开始读取所有剩余样本。 如果给定文件中的帧数不足，此函数可能会返回较少的帧数。

  • normalize (bool, 可选) –

    当 True 时，此函数将原生样本类型转换为 float32。 默认值：True。

    如果输入文件是整数 WAV，给出 False 将把生成的 Tensor 类型更改为 整数类型。 此参数对除整数 WAV 类型以外的格式无效。

  • channels_first (bool, optional) – 当为 True 时，返回的 Tensor 维度为 [channel, time]。 否则，返回的 Tensor 维度为 [time, channel]。

  • format (str 或 None, 可选) – 使用给定的格式覆盖格式检测。 当 libsox 无法从文件头或扩展名推断格式时，提供此参数可能会有所帮助。

Returns:

Resulting Tensor and sample rate.

如果输入文件具有整数 wav 格式和 normalize=False，则它具有整数类型，否则为 float32 类型。如果 channels_first=True，则具有 [channel, time]，否则为 [time, channel]。

Return type:

(torch.Tensor, int)

保存

torchaudio.backend.sox_io_backend.save(filepath: str, src: Tensor, sample_rate: int, channels_first: bool = True, compression: Optional[float] = None, format: Optional[str] = None, encoding: Optional[str] = None, bits_per_sample: Optional[int] = None)[source]

将音频数据保存到文件。

Parameters:

  • filepath (str 或 pathlib.Path) – 保存文件的路径。 此函数也处理 pathlib.Path 对象，但为了与 TorchScript 编译器兼容，被标注为 str。

  • src (torch.Tensor) – 要保存的音频数据。必须是二维张量。

  • sample_rate (int) – 采样率

  • channels_first (bool, optional) – 如果为 True，则给定的张量被解释为 [channel, time]， 否则为 [time, channel]。

  • compression (float 或 None, 可选) –

    用于除 WAV 以外的格式。 这对应于 -C 选项的 sox 命令。

    "mp3"

    比特率（在 kbps）配合质量因子，例如 128.2，或者 使用质量因子的 VBR 编码，例如 -4.2。默认值：-4.5。

    "flac"

    从 0 到 8 的整数。8 为默认值且代表最高压缩率。

    "ogg", "vorbis"

    数字从 -1 到 10；-1 是最高压缩率和最低质量。默认值：3。

    在 http://sox.sourceforge.net/soxformat.html 查看详情。

  • format (str 或 None, 可选) –

    覆盖音频格式。 当 filepath 参数为路径类对象时，音频格式将从文件扩展名推断。如果缺少文件扩展名或扩展名不同，您可以使用此参数指定正确的格式。

    当 filepath 个参数为类文件对象时，此参数是必需的。

    有效值为 "wav"、"mp3"、"ogg"、"vorbis"、"amr-nb"、 "amb"、"flac"、"sph"、"gsm" 和 "htk"。

  • encoding (str 或 None，可选) –

    更改支持格式的编码。 此参数仅对支持的格式有效，例如 "wav"、""amb" 和 "sph"。有效值为：

    • "PCM_S" (signed integer Linear PCM)

    • "PCM_U" (unsigned integer Linear PCM)

    • "PCM_F" (floating point PCM)

    • "ULAW" (mu-law)

    • "ALAW" (a-law)

    Default values

    如果未提供，则根据 format 和 bits_per_sample 选择默认值。

    "wav", "amb"
    • 如果未提供 encoding 和 bits_per_sample，则 dtype 为
      Tensor 用于确定默认值。

      • "PCM_U" if dtype is uint8

      • "PCM_S" if dtype is int16 or int32

      • "PCM_F" if dtype is float32

    • "PCM_U" if bits_per_sample=8

    • "PCM_S" 否则

    "sph" format;

    • 默认值为 "PCM_S"

  • bits_per_sample (int 或 None，可选) –

    更改支持格式的位深度。 当 format 是 "wav"、"flac"、"sph" 或 "amb" 之一时，您可以更改位深度。有效值为 8、16、32 和 64。

    Default Value;

    如果未提供，则默认值基于 format 和 "encoding" 选取；

    "wav", "amb";
    • 如果未提供 encoding 和 bits_per_sample，则 dtype 为
      使用了张量。

      • 8 if dtype is uint8

      • 16 if dtype is int16

      • 32 if dtype is int32 or float32

    • 8 if encoding is "PCM_U", "ULAW" or "ALAW"

    • 16 如果 encoding 是 "PCM_S"

    • 32 如果 encoding 是 "PCM_F"

    "flac" format;

    • 默认值为 24

    "sph" format;

    • 16 如果 encoding 是 "PCM_U"、"PCM_S"、"PCM_F" 或未提供。

    • 8 如果 encoding 是 "ULAW" 或 "ALAW"

    "amb" format;

    • 8 if encoding is "PCM_U", "ULAW" or "ALAW"

    • 16 如果 encoding 为 "PCM_S" 或未提供。

    • 32 如果 encoding 是 "PCM_F"

支持的格式/编码/位深度/压缩包括；

"wav", "amb"

  • 32 位浮点 PCM

  • 32 位有符号整数 PCM

  • 24 位有符号整数 PCM

  • 16 位有符号整数 PCM

  • 8 位无符号整数 PCM

  • 8 位 mu-law

  • 8 位 a-law

注意：默认编码/位深度由输入张量的 dtype 决定。

"mp3"

固定比特率（如 128kHz）和可变比特率压缩。 默认：高质量可变比特率。

"flac"

  • 8-bit

  • 16-bit

  • 24 位（默认）

"ogg", "vorbis"

  • 不同的质量级别。默认值：约 112kbps

"sph"

  • 8 位有符号整数 PCM

  • 16 位有符号整数 PCM

  • 24 位有符号整数 PCM

  • 32 位有符号整数 PCM（默认）

  • 8 位 mu-law

  • 8 位 a-law

  • 16 位 a-law

  • 24 位 a-law

  • 32 位 a-law

"amr-nb"

比特率范围为 4.75 kbit/s 至 12.2 kbit/s。默认值：4.75 kbit/s

"gsm"

有损语音压缩，CPU 密集型。

"htk"

使用默认的 16 位单通道 PCM 格式。

注意

若要保存为 libsox 原生不支持的格式（例如 "mp3"、 "flac"、"ogg" 和 "vorbis"），您的 torchaudio 安装必须链接到 libsox 以及相应的编解码器库，例如 libmad 或 libmp3lame 等。

Soundfile 后端

当安装 SoundFile 时，"soundfile" 后端可用。此后端是 Windows 上的默认设置。

您可以使用以下命令从另一个后端切换到 "soundfile" 后端；

torchaudio.set_audio_backend("soundfile")

信息

torchaudio.backend.soundfile_backend.info(filepath: str, format: Optional[str] = None) → AudioMetaData[source]

获取音频文件的信号信息。

注意

filepath 参数被有意地仅标注为 str，尽管它也接受 pathlib.Path 对象。这是为了与 "sox_io" 后端保持一致， 由于 TorchScript 编译器的兼容性限制，该后端在类型注解上存在约束。

Parameters:

  • filepath (path-like object 或 file-like object) – 音频数据的来源。

  • format (str 或 None, 可选) – 未使用。PySoundFile 不接受格式提示。

Returns:

给定音频的元数据。

Return type:

AudioMetaData

加载

torchaudio.backend.soundfile_backend.load(filepath: str, frame_offset: int = 0, num_frames: int = -1, normalize: bool = True, channels_first: bool = True, format: Optional[str] = None) → Tuple[Tensor, int][source]

从文件加载音频数据。

注意

此函数可处理的格式取决于 soundfile 的安装情况。 本函数已在以下格式上经过测试；

  • WAV

    • 32-bit floating-point

    • 32-bit signed integer

    • 16-bit signed integer

    • 8-bit unsigned integer

  • FLAC

  • OGG/VORBIS

  • SPHERE

默认情况下（normalize=True, channels_first=True），此函数返回一个 dtype 为 float32 且形状为 [channel, time] 的 Tensor。

警告

normalize 参数不执行音量归一化。 它仅将样本类型从原生样本类型转换为 torch.float32。

当输入格式为整数类型的 WAV（例如 32 位有符号整数、16 位有符号整数、24 位有符号整数和 8 位无符号整数）时，通过提供 normalize=False，此函数可以返回整数 Tensor，其中样本在对应数据类型的整个范围内表示，即对于 32 位有符号 PCM 为 int32 tensor，对于 16 位有符号 PCM 为 int16，对于 8 位无符号 PCM 为 uint8。由于 torch 不支持 int24 数据类型，24 位有符号 PCM 会被转换为 int32 tensors。

normalize 参数对 32 位浮点 WAV 及其他格式（如 flac 和 mp3）无效。

对于这些格式，此函数始终返回一个包含值的 float32 张量。

注意

filepath 参数被有意地仅标注为 str，尽管它也接受 pathlib.Path 对象。这是为了与 "sox_io" 后端保持一致， 由于 TorchScript 编译器的兼容性限制，该后端在类型注解上存在约束。

Parameters:

  • filepath (path-like object 或 file-like object) – 音频数据的来源。

  • frame_offset (int, optional) – 开始读取数据之前要跳过的帧数。

  • num_frames (int, optional) – 要读取的最大帧数。-1 表示从 frame_offset 开始读取所有剩余样本。 如果给定文件中的帧数不足，此函数可能会返回较少的帧数。

  • normalize (bool, 可选) –

    当 True 时，此函数将原生样本类型转换为 float32。 默认值：True。

    如果输入文件是整数 WAV，给出 False 将把生成的 Tensor 类型更改为 整数类型。 此参数对除整数 WAV 类型以外的格式无效。

  • channels_first (bool, optional) – 当为 True 时，返回的 Tensor 维度为 [channel, time]。 否则，返回的 Tensor 维度为 [time, channel]。

  • format (str 或 None, 可选) – 未使用。PySoundFile 不接受格式提示。

Returns:

Resulting Tensor and sample rate.

如果输入文件为整数 wav 格式且未启用归一化，则其类型为整数类型，否则为 float32 类型。如果为 channels_first=True，则为 [channel, time]，否则为 [time, channel]。

Return type:

(torch.Tensor, int)

保存

torchaudio.backend.soundfile_backend.save(filepath: str, src: Tensor, sample_rate: int, channels_first: bool = True, compression: Optional[float] = None, format: Optional[str] = None, encoding: Optional[str] = None, bits_per_sample: Optional[int] = None)[source]

将音频数据保存到文件。

注意

此函数可处理的格式取决于 soundfile 的安装情况。 本函数已在以下格式上经过测试；

  • WAV

    • 32-bit floating-point

    • 32-bit signed integer

    • 16-bit signed integer

    • 8-bit unsigned integer

  • FLAC

  • OGG/VORBIS

  • SPHERE

注意

filepath 参数被有意地仅标注为 str，尽管它也接受 pathlib.Path 对象。这是为了与 "sox_io" 后端保持一致， 由于 TorchScript 编译器的兼容性限制，该后端在类型注解上存在约束。

Parameters:

  • filepath (str 或 pathlib.Path) – 音频文件的路径。

  • src (torch.Tensor) – 要保存的音频数据。必须是二维张量。

  • sample_rate (int) – 采样率

  • channels_first (bool, optional) – 如果为 True，则给定的张量被解释为 [channel, time]， 否则为 [time, channel]。

  • compression (python:float of None, optional) – 未使用。 此处仅为了与“sox_io”后端保持接口兼容性。

  • format (str 或 None, 可选) –

    覆盖音频格式。 当 filepath 参数为路径类对象时，音频格式将从文件扩展名推断。如果缺少文件扩展名或扩展名不同，您可以使用此参数指定正确的格式。

    当 filepath 参数是类文件对象时， 此参数为必填项。

    有效值为 "wav"、"ogg"、"vorbis"、 "flac" 和 "sph"。

  • encoding (str 或 None，可选) –

    更改支持格式的编码。 此参数仅对支持的格式有效，例如 "wav"、""flac"和"sph"。有效值为：

    • "PCM_S" (signed integer Linear PCM)

    • "PCM_U" (unsigned integer Linear PCM)

    • "PCM_F" (floating point PCM)

    • "ULAW" (mu-law)

    • "ALAW" (a-law)

  • bits_per_sample (int 或 None，可选) – 更改支持格式的位深度。 当 format 是 "wav"、"flac" 或 "sph" 之一时，您可以更改位深度。 有效值为 8、16、24、32 和 64。

支持的格式/编码/位深度/压缩包括：

"wav"

  • 32 位浮点 PCM

  • 32 位有符号整数 PCM

  • 24 位有符号整数 PCM

  • 16 位有符号整数 PCM

  • 8 位无符号整数 PCM

  • 8 位 mu-law

  • 8 位 a-law

Note:

默认编码/位深度由输入张量的 dtype 决定。

"flac"

  • 8-bit

  • 16 位（默认）

  • 24-bit

"ogg", "vorbis"

  • 不接受更改配置。

"sph"

  • 8 位有符号整数 PCM

  • 16 位有符号整数 PCM

  • 24 位有符号整数 PCM

  • 32 位有符号整数 PCM（默认）

  • 8 位 mu-law

  • 8 位 a-law

  • 16 位 a-law

  • 24 位 a-law

  • 32 位 a-law

文档

访问 PyTorch 的全面开发人员文档

查看文档

教程

获取面向初学者和高级开发人员的深入教程

查看教程

资源

查找开发资源并解答您的问题

查看资源