目录
目录

torchaudio.backend

概述

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

目前共有四种实现可供选择。

注意

请勿直接在 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” 后端 和 “soundfile” 后端的新接口 使用。

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

    • AMR_NB: Adaptive Multi-Rate Wideband

    • OPUS: Opus

    • UNKNOWN : None of above

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) → torchaudio.backend.common.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），例如 mp3 和 vorbis。在这种情况下，num_samples 的值为 0。

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

  • 格式 (str, 可选) – 使用给定的格式覆盖格式检测。 当 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[torch.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），此函数返回具有 float32 数据类型和 [channel, time] 形状的张量。样本已归一化，使其范围适配于 [-1.0, 1.0]。

当输入格式为整数类型的 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 Tensor，其值已归一化为 [-1.0, 1.0]。

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) – 要读取的最大帧数。 -1 表示读取剩余所有样本，从 frame_offset 开始。 如果给定文件中的帧数不足，此函数可能会返回较少的帧数。

  • 归一化 (bool) – 当值为 True 时，此函数始终返回 float32，并会将采样值归一化至 [-1.0, 1.0]。 如果输入文件是整数WAV格式，提供 False 将使结果张量类型更改为整数类型。 此参数对除整数WAV格式以外的其他格式无效。

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

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

Returns

Resulting Tensor and sample rate.

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

Return type

Tuple[torch.Tensor, int]

保存

torchaudio.backend.sox_io_backend.save(filepath: str, src: torch.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) – 如果为 True，则给定张量被解释为 [channel, time]，否则为 [time, channel]。

  • 压缩 (可选[浮点数]) –

    用于除 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, 可选) –

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

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

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

  • 编码 (str, 可选) –

    更改支持格式的编码。 此参数仅对支持的格式有效，例如 "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 为
      张量用于确定默认值。 - 如果数据类型为 "PCM_U"，则使用该值 - 如果数据类型为 uint8，则使用该值 - 如果数据类型为 "PCM_S"，则使用该值 - 如果数据类型为 int16 或 int32` - ``"PCM_F"（当数据类型为 float32 时）

    • "PCM_U" if bits_per_sample=8

    • "PCM_S" 否则

    "sph" format;

    • 默认值为 "PCM_S"

  • bits_per_sample (int, 可选) –

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

    Default Value;

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

    "wav", "amb";
    • 如果未提供 encoding 和 bits_per_sample，则 dtype 为
      张量被使用。 - 8 如果数据类型为 uint8 - 16 如果数据类型为 int16 - 32 如果数据类型为 int32 或 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) → torchaudio.backend.common.AudioMetaData[source]

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

注意

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

Parameters

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

  • format (str, optional) – 未使用。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[torch.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），此函数返回具有 float32 数据类型和 [channel, time] 形状的张量。样本已归一化，使其范围适配于 [-1.0, 1.0]。

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

normalize 参数对 32 位浮点 WAV 和其他格式（如 flac 和 mp3）没有影响。 对于这些格式，此函数始终返回 float32 Tensor，其值已归一化为 [-1.0, 1.0]。

注意

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

Parameters

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

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

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

  • 归一化 (bool) – 当值为 True 时，此函数始终返回 float32，并会将采样值归一化至 [-1.0, 1.0]。 如果输入文件是整数WAV格式，提供 False 将使结果张量类型更改为整数类型。 此参数对除整数WAV格式以外的其他格式无效。

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

  • format (str, optional) – 未使用。PySoundFile 不接受格式提示。

Returns

Resulting Tensor and sample rate.

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

Return type

Tuple[torch.Tensor, int]

保存

torchaudio.backend.soundfile_backend.save(filepath: str, src: torch.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) – 如果为 True，则给定张量被解释为 [channel, time]，否则为 [time, channel]。

  • 压缩 (可选[浮点数]) – 不使用。 它仅用于与“sox_io”后端的接口兼容性。

  • format (str, 可选) –

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

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

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

  • 编码 (str, 可选) –

    更改支持格式的编码。 此参数仅对支持的格式有效，例如 "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, 可选) – 更改支持格式的位深度。 当 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: Default encoding/bit depth is determined by the dtype of

输入张量。

"flac"

  • 8-bit

  • 16-bit

  • 24 位（默认）

"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 的全面开发人员文档

查看文档

教程

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

查看教程

资源

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

查看资源