torchaudio.backend

概述

模块为音频文件 I/O 功能提供实现，这些功能是 、 和 。torchaudio.infotorchaudio.loadtorchaudio.save

目前有四种实现可用。

• “sox_io”（在 Linux/macOS 上为默认值）

• “soundfile” （在 Windows 上默认）

注意

请不要直接调用 函数，而是使用 、 ，并在适当的后端设置下使用 。torchaudio.backendtorchaudio.infotorchaudio.loadtorchaudio.save

可用性

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

"soundfile"backend 需要 .请参阅 SoundFile 文档进行安装。SoundFile

通用数据结构

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

AudioMetaData

类 （sample_rate： int， num_frames： int， num_channels： int， bits_per_sample： int，编码：str）torchaudio.backend.common.AudioMetaData

返回函数的类型。torchaudio.info

这个类由 “sox_io” 后端和 “soundfile” 后端使用，具有新的接口。

变量

• sample_rate （int） – 采样率

• num_frames （int） – 帧数

• num_channels （int） – 通道数

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

• 编码 （STR） –

  音频编码 encoding 可以采用的值是以下值之一：

  • PCM_S： 有符号整数线性 PCM

  • PCM_U：无符号整数线性 PCM

  • PCM_F： 浮点线性 PCM

  • FLAC： Flac，免费无损音频编解码器

  • ULAW： 穆法

  • ALAW： A-law

  • MP3：MP3、MPEG-1 音频层 III

  • VORBIS： OGG 沃比斯

  • AMR_WB：自适应多速率

  • AMR_NB： 自适应多速率宽带

  • OPUS：作品

  • HTK：单通道 16 位 PCM

  • UNKNOWN： 以上都不是

教程使用：AudioMetaData

音频 I/O

Sox IO 后端

后端在 Linux/macOS 上可用且为默认版本，在 Windows 上不可用。sox_io

该后端的 I/O 功能支持 TorchScript。

您可以通过以下方式从另一个后端切换到后端;sox_io

torchaudio.set_audio_backend("sox_io")

信息

torchaudio.backend.sox_io_backend.info(文件路径：str，格式：可选[str] = None） → torchaudio.backend.common.AudioMetaData

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

参数

• filepath （路径类对象或文件类对象） –

  音频数据源。当函数没有被 TorchScript 编译时， （例如），接受以下类型;torch.jit.script

  • path-like： 文件路径

  • file-like： 具有方法的对象， 返回最大长度的字节字符串。read(size: int) -> bytessize

  当函数由 TorchScript 编译时，只允许使用 type。str

  注意

  • 当输入类型为类文件对象时，此函数不能 为某些格式获取正确的长度 （）， 例如 和 。 在本例中，的值为 。num_samplesmp3vorbisnum_samples0

  • 此参数被有意注释为仅由于 TorchScript 编译器兼容性。str

• format （str 或 None，可选） – 使用给定格式覆盖格式检测。 当 libsox 无法推断格式时，提供参数可能会有所帮助 from 标头或扩展。

返回

给定音频的元数据。

返回类型

AudioMetaData

负荷

torchaudio.backend.sox_io_backend.load(文件路径：str，frame_offset：int = 0，num_frames：int = - 1，归一化： bool = True， channels_first： bool = True， 格式： 可选[str] = None） → Tuple[torch.Tensor， int]

从文件加载音频数据。

注意

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

• WAV、AMB

  • 32 位浮点

  • 32 位有符号整数

  • 24 位有符号整数

  • 16 位有符号整数

  • 8 位无符号整数（仅限 WAV）

• MP3 的

• FLAC的

• OGG/VORBIS

• 作品

• 球

• AMR-NB 系列

加载 、 、 和其他编解码器不会 handle 时，您的安装必须链接到相应的编解码器库，例如 OR 等。MP3FLACOGG/VORBISOPUSlibsoxtorchaudiolibsoxlibmadlibmp3lame

默认情况下 （， ），此函数返回 dtype 的 Tensor 和 [channel， time] 的形状。normalize=Truechannels_first=Truefloat32

警告

normalize参数不执行卷规范化。 它仅将 sample 类型从原生 sample 转换为 torch.float32 类型。

当输入格式为整数类型的 WAV 时，例如 32 位有符号整数、16 位 有符号整数、24 位有符号整数和 8 位无符号整数，通过提供 ， 该函数可以返回整数 Tensor，其中样本在整个范围内表示 的相应 dtype 中，即 32 位有符号 PCM、16 位有符号 PCM 和 8 位无符号 PCM 的张量。由于 torch 没有 支持 dtype 时，24 位带符号的 PCM 将转换为 Tensor。normalize=Falseint32int16uint8int24int32

normalize参数对 32 位浮点 WAV 和其他格式（如 和 ）没有影响。flacmp3

对于这些格式，此函数始终返回带有值的 Tensor。float32

参数

• filepath （路径类对象或文件类对象） –

  音频数据源。当函数没有被 TorchScript 编译时， （例如），接受以下类型;torch.jit.script

  • path-like： 文件路径

  • file-like： 具有方法的对象， 返回最大长度的字节字符串。read(size: int) -> bytessize

  当函数由 TorchScript 编译时，只允许使用 type。str

  注意：此参数被有意注释为仅由于 TorchScript 编译器兼容性。str

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

• num_frames （int， optional） – 要读取的最大帧数。 读取所有剩余样本， 从 . 如果没有足够的帧数，此函数可能会返回较少的帧数 帧。-1frame_offset

• normalize （布尔值，可选） –

  当 时，此函数将本机样本类型转换为 。 违约：。Truefloat32True

  如果 input file 是整数 WAV，则 give 会将生成的 Tensor 类型更改为 integer 类型。 此参数对整数 WAV 类型以外的格式没有影响。False

• channels_first （bool， optional） – 当为 True 时，返回的 Tensor 具有维度 [channel， time]。 否则，返回的 Tensor 的维度为 [time， channel]。

• format （str 或 None，可选） – 使用给定格式覆盖格式检测。 当 libsox 无法推断格式时，提供参数可能会有所帮助 from 标头或扩展。

返回

生成的 Tensor 和 sample rate。

如果输入文件具有整数 wav 格式，并且 ，则它具有 integer 类型，else 类型。如果 ，则为 [channel， time] else [time， channel]。normalize=Falsefloat32channels_first=True

返回类型

(torch。张量、int)

救

torchaudio.backend.sox_io_backend.save(文件路径：str，src：torch。张量，sample_rate：int，channels_first：bool = True，压缩：Optional[float] = 无，格式：可选[str] = 无，编码：可选[str] = 无，bits_per_sample：可选[int] = 无）

将音频数据保存到文件。

参数

• filepath （str 或 pathlib.Path） – 保存文件的路径。 此函数也处理对象，但带有 Comments 至于 TorchScript 编译器兼容性。pathlib.Pathstr

• src （Torch.Tensor） – 要保存的音频数据。必须是 2D 张量。

• sample_rate （int） – 采样率

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

• compression （float 或 None，可选） –

  用于 WAV 以外的格式。 这对应于 command 的 option。-Csox

  "mp3"

  具有品质因数的比特率 （in），例如 ，或 具有品质因数的 VBR 编码，例如 .违约：。kbps128.2-4.2-4.5

  "flac"

  整数 from to 。 是默认且最高的压缩率。088

  "ogg","vorbis"

  编号 from 到 ; 是最高的压缩率 和最低质量。违约：。-110-13

  有关详细信息，请参阅 http://sox.sourceforge.net/soxformat.html。

• format （str 或 None，可选） –

  覆盖音频格式。 当 argument 是 path-like object 时，音频格式是从 文件扩展名。如果文件扩展名缺失或不同，您可以指定 使用此参数的正确格式。filepath

  当 argument 是 file-like object 时，此参数是必需的。filepath

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

• encoding （str 或 None，可选） –

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

  • "PCM_S"（有符号整数线性 PCM）

  • "PCM_U"（无符号整数线性 PCM）

  • "PCM_F"（浮点 PCM）

  • "ULAW"（mu-law）

  • "ALAW"（A-法律）

  默认值

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

  "wav","amb"

  • 如果两者都未提供 和 ，则encodingbits_per_sampledtype

    Tensor 用于确定默认值。

    • "PCM_U"如果 dtype 为uint8

    • "PCM_S"如果 dtype 为 或int16int32

    • "PCM_F"如果 dtype 为float32

  • "PCM_U"如果bits_per_sample=8

  • "PCM_S"否则

  "sph"格式;

  • 默认值为"PCM_S"

• bits_per_sample （int 或 None，可选） –

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

  默认值;

  如果未提供，则根据 和 选择默认值format"encoding";

  "wav","amb";

  • 如果两者都未提供 和 ，则encodingbits_per_sampledtype

    Tensor 的 Tensor 被使用。

    • 8如果 dtype 为uint8

    • 16如果 dtype 为int16

    • 32如果 dtype 为 或int32float32

  • 8if 是 ， 或encoding"PCM_U""ULAW""ALAW"

  • 16if 是encoding"PCM_S"

  • 32if 是encoding"PCM_F"

  "flac"格式;

  • 默认值为24

  "sph"格式;

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

  • 8if is 或encoding"ULAW""ALAW"

  "amb"格式;

  • 8if 是 ， 或encoding"PCM_U""ULAW""ALAW"

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

  • 32if 是encoding"PCM_F"

支持的格式/编码/位深度/压缩是;

"wav","amb"

• 32 位浮点 PCM

• 32 位有符号整数 PCM

• 24 位有符号整数 PCM

• 16 位有符号整数 PCM

• 8 位无符号整数 PCM

• 8 位 mu law

• 8 位 A-law

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

"mp3"

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

"flac"

• 8 位

• 16 位

• 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 格式。

注意

要保存为本机无法处理的格式（例如 、 和 ），您安装的 具有 链接到相应的编解码器库，例如 OR 等。libsox"mp3""flac""ogg""vorbis"torchaudiolibsoxlibmadlibmp3lame

Soundfile 后端

安装 SoundFile 后，后端可用。此后端是 Windows 上的默认值。"soundfile"

您可以通过以下方式从另一个后端切换到后端;"soundfile"

torchaudio.set_audio_backend("soundfile")

信息

torchaudio.backend.soundfile_backend.info(文件路径：str，格式：可选[str] = None） → torchaudio.backend.common.AudioMetaData

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

注意

filepathargument 被有意注释为 only，即使它也接受 object。这是为了与 backend 保持一致， 由于 TorchScript 编译器兼容性，它对类型注释有限制。strpathlib.Path"sox_io"

参数

• filepath （path-like object or file-like object） （file-like object） （音频数据源）。

• format （str 或 None，可选） – 未使用。PySoundFile 不接受格式提示。

返回

给定音频的元数据。

返回类型

AudioMetaData

负荷

torchaudio.backend.soundfile_backend.load(文件路径：str，frame_offset：int = 0，num_frames：int = - 1，归一化： bool = True， channels_first： bool = True， 格式： 可选[str] = None） → Tuple[torch.Tensor， int]

从文件加载音频数据。

注意

此函数可以处理的格式取决于 soundfile 安装。 此函数在以下格式上进行了测试;

• WAV

  • 32 位浮点

  • 32 位有符号整数

  • 16 位有符号整数

  • 8 位无符号整数

• FLAC的

• OGG/VORBIS

• 球

默认情况下 （， ），此函数返回 dtype 的 Tensor 和 [channel， time] 的形状。normalize=Truechannels_first=Truefloat32

警告

normalize参数不执行卷规范化。 它仅将 sample 类型从原生 sample 转换为 torch.float32 类型。

当输入格式为整数类型的 WAV 时，例如 32 位有符号整数、16 位 有符号整数、24 位有符号整数和 8 位无符号整数，通过提供 ， 该函数可以返回整数 Tensor，其中样本在整个范围内表示 的相应 dtype 中，即 32 位有符号 PCM、16 位有符号 PCM 和 8 位无符号 PCM 的张量。由于 torch 没有 支持 dtype 时，24 位带符号的 PCM 将转换为 Tensor。normalize=Falseint32int16uint8int24int32

normalize参数对 32 位浮点 WAV 和其他格式（如 和 ）没有影响。flacmp3

对于这些格式，此函数始终返回带有值的 Tensor。float32

注意

filepathargument 被有意注释为 only，即使它也接受 object。这是为了与 backend 保持一致， 由于 TorchScript 编译器兼容性，它对类型注释有限制。strpathlib.Path"sox_io"

参数

• filepath （path-like object or file-like object） （file-like object） （音频数据源）。

• frame_offset （int， optional） – 在开始读取数据之前要跳过的帧数。

• num_frames （int， optional） – 要读取的最大帧数。 读取所有剩余样本， 从 . 如果没有足够的帧数，此函数可能会返回较少的帧数 帧。-1frame_offset

• normalize （布尔值，可选） –

  当 时，此函数将本机样本类型转换为 。 违约：。Truefloat32True

  如果 input file 是整数 WAV，则 give 会将生成的 Tensor 类型更改为 integer 类型。 此参数对整数 WAV 类型以外的格式没有影响。False

• channels_first （bool， optional） – 当为 True 时，返回的 Tensor 具有维度 [channel， time]。 否则，返回的 Tensor 的维度为 [time， channel]。

• format （str 或 None，可选） – 未使用。PySoundFile 不接受格式提示。

返回

生成的 Tensor 和 sample rate。

如果输入文件具有整数 wav 格式且标准化处于关闭状态，则它具有 integer 类型，else 类型。如果 ，则为 [channel， time] else [time， channel]。float32channels_first=True

返回类型

(torch。张量、int)

救

torchaudio.backend.soundfile_backend.save(文件路径：str，src：torch。张量，sample_rate：int，channels_first：bool = True，压缩：Optional[float] = 无，格式：可选[str] = 无，编码：可选[str] = 无，bits_per_sample：可选[int] = 无）

将音频数据保存到文件。

注意

此函数可以处理的格式取决于 soundfile 安装。 此函数在以下格式上进行了测试;

• WAV

  • 32 位浮点

  • 32 位有符号整数

  • 16 位有符号整数

  • 8 位无符号整数

• FLAC的

• OGG/VORBIS

• 球

注意

filepathargument 被有意注释为 only，即使它也接受 object。这是为了与 backend 保持一致， 由于 TorchScript 编译器兼容性，它对类型注释有限制。strpathlib.Path"sox_io"

参数

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

• src （Torch.Tensor） – 要保存的音频数据。必须是 2D 张量。

• sample_rate （int） – 采样率

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

• compression （float of None， optional） （未使用。 它仅用于与 “sox_io” 后端的接口兼容性。

• format （str 或 None，可选） –

  覆盖音频格式。 当 argument 为 path-like object时，audio 格式为 从文件扩展名推断。如果缺少文件扩展名或 不同，则可以使用此参数指定正确的格式。filepath

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

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

• encoding （str 或 None，可选） –

  更改受支持格式的编码。 此参数仅对支持的格式有效，sush as 和 .有效值为;"wav"""flac""sph"

  • "PCM_S"（有符号整数线性 PCM）

  • "PCM_U"（无符号整数线性 PCM）

  • "PCM_F"（浮点 PCM）

  • "ULAW"（mu-law）

  • "ALAW"（A-法律）

• bits_per_sample （int 或 None，可选） – 更改 支持的格式。 当 是 、 或 之一时 ， 您可以更改位深度。 有效值为 、 、 和 。format"wav""flac""sph"816243264

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

"wav"

• 32 位浮点 PCM

• 32 位有符号整数 PCM

• 24 位有符号整数 PCM

• 16 位有符号整数 PCM

• 8 位无符号整数 PCM

• 8 位 mu law

• 8 位 A-law

注意：

默认编码/位深度由 输入 Tensor。

"flac"

• 8 位

• 16 位 （默认）

• 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