torchaudio.backend¶

概述¶

torchaudio.backend 模块提供了音频文件读写的实现功能，包括 torchaudio.info、torchaudio.load、torchaudio.load_wav 和 torchaudio.save。

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

“sox_io”（Linux/macOS 默认）
“sox” （已弃用，将在0.9.0版本中移除）
“soundfile”（Windows 默认）
“soundfile” (旧接口) (已废弃，将在0.9.0版本中移除)

使用"sox"后端是强烈不建议的，因为它无法正确处理16位整数WAV以外的其他格式。有关详细信息，请参阅#726。

注意

请不要直接调用torchaudio.backend中的函数，而是使用torchaudio.info、torchaudio.load、torchaudio.load_wav和torchaudio.save，并使用torchaudio.set_audio_backend()正确设置后端。

可用性¶

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

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

默认后端的更改和弃用¶

后端模块正在进行重大重构。下表总结了弃用和移除的时间线。

Backend

0.8.0

0.9.0

"sox_io"

Default on Linx/macOS

Default on Linux/macOS

"sox" (deprecated)

Available

Removed

"soundfile"

Default on Windows

Default on Windows

"soundfile" (legacy interface, deprecated)

Available

Removed

The "sox" 和 "soundfile" (legacy interface) 后端已被弃用，并将在 0.9.0 版本中移除。

常用数据结构¶

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

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) – 音频编码。

信号信息（已弃用）¶

class torchaudio.backend.common.SignalInfo(channels: Optional[int] = None, rate: Optional[float] = None, precision: Optional[int] = None, length: Optional[int] = None)[source]¶

torchaudio.info函数的一种返回类型。

此类由 “sox” 后端（已废弃）和 “soundfile” 后端与旧接口（已废弃）使用。

参见 https://fossies.org/dox/sox-14.4.2/structsox__signalinfo__t.html

Variables

通道 (可选[整数]) – 通道的数量
采样率 (可选[浮点数]) – 采样率
精度 (可选[整数]) – 位深度
长度 (可选[整数]) – 对于 sox 后端, 样本的数量。 (帧数 * 通道数)。对于 soundfile 后端, 帧数。

编码信息 (已弃用)¶

class torchaudio.backend.common.EncodingInfo(encoding: Any = None, bits_per_sample: Optional[int] = None, compression: Optional[float] = None, reverse_bytes: Any = None, reverse_nibbles: Any = None, reverse_bits: Any = None, opposite_endian: Optional[bool] = None)[source]¶

torchaudio.info函数的一种返回类型。

此类由 “sox” 后端（已废弃）和 “soundfile” 后端与旧接口（已废弃）使用。

参见 https://fossies.org/dox/sox-14.4.2/structsox__encodinginfo__t.html

Variables

编码 (可选[整数]) – sox_encoding_t
bits_per_sample (可选[int]) – 位深度
压缩 (可选[浮点数]) – 压缩选项
reverse_bytes (任意) –
反向 nibbles (任意) –
反向位 (任意) –
opposite_endian (可选[bool]) –

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
- 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 位有符号整数和 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]。

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.load_wav(filepath: str, frame_offset: int = 0, num_frames: int = -1, channels_first: bool = True) → Tuple[torch.Tensor, int][source]¶

加载波形文件。

此函数仅出于与其他后端兼容的目的而定义，适用于简单的用例，例如 torchaudio.load_wav(filepath)。实现方式与load()相同。

保存¶

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 等。

Sox 后端（已弃用）¶

The "sox" 后端在 Linux/macOS 上可用，但在 Windows 上不可用。此后端已弃用，并将在 0.9.0 版本中移除。

你可以通过以下方式从另一个后端切换到sox后端。

torchaudio.set_audio_backend("sox")

信息¶

torchaudio.backend.sox_backend.info(filepath: str) → Tuple[torchaudio.backend.common.SignalInfo, torchaudio.backend.common.EncodingInfo][source]¶

从音频文件中获取元数据而无需加载信号。

Parameters

文件路径 – 音频文件的路径

Returns

A si (sox_signalinfo_t) signal: 作为 Python 对象的信息。一个 ei（sox_encodinginfo_t）编码信息。

Return type

(sox_signalinfo_t, sox编码信息_t)

Example

>>> si, ei = torchaudio.info('foo.wav')
>>> rate, channels, encoding = si.rate, si.channels, ei.encoding

加载¶

torchaudio.backend.sox_backend.load(filepath: str, out: Optional[torch.Tensor] = None, normalization: bool = True, channels_first: bool = True, num_frames: int = 0, offset: int = 0, signalinfo: torchaudio.backend.common.SignalInfo = None, encodinginfo: torchaudio.backend.common.EncodingInfo = None, filetype: Optional[str] = None) → Tuple[torch.Tensor, int][source]¶

从磁盘加载音频文件到张量中

Parameters

文件路径 – 音频文件的路径
out – 可选的输出张量，用于代替创建一个新的张量。(默认值：None)
归一化 – 可选的归一化。如果布尔值为True，则输出将除以1 << 31。假设输入是带符号的32位音频，这将归一化为[-1, 1]。如果为float，则输出将除以该数字。如果为Callable，则输出作为参数传递给给定函数，然后输出将除以结果。(默认值：True)
channels_first – 设置结果中的通道优先或长度优先。（默认值：True）
num_frames – 要加载的帧数。0 表示在偏移量之后加载所有内容。 (默认值：0)
偏移量 – 从文件开头开始加载数据的帧数。（默认值：0）
信号信息 – 一个 sox_signalinfo_t 类型，当音频类型无法自动确定时可能会有帮助。（默认值：None）
编码信息 – 一个 sox_encodinginfo_t 类型，如果音频类型无法自动确定时可以设置。（默认值：None）
文件类型 – 如果sox无法自动确定，则设置一个文件类型或扩展名。 (默认值：None)

Returns

An output tensor of size [C x L] or [L x C] where: L 是音频帧的数量， C 是通道的数量。一个整数，表示音频的采样率（如文件元数据中所列）。

Return type

(Tensor, 整数)

Example

>>> data, sample_rate = torchaudio.load('foo.mp3')
>>> print(data.size())
torch.Size([2, 278756])
>>> print(sample_rate)
44100
>>> data_vol_normalized, _ = torchaudio.load('foo.mp3', normalization=lambda x: torch.abs(x).max())
>>> print(data_vol_normalized.abs().max())
1.

torchaudio.backend.sox_backend.load_wav(filepath, **kwargs)[source]¶

加载一个波形文件。

它假设该 wav 文件每样本使用 16 位，需要通过将输入右移 16 位来进行归一化。

Parameters

文件路径 – 音频文件的路径

Returns

An output tensor of size [C x L] or [L x C] where L is the number: 音频帧的数量，C 是通道数。一个整数，表示音频的采样率（如文件元数据中所列）

Return type

(Tensor, 整数)

保存¶

torchaudio.backend.sox_backend.save(filepath: str, src: torch.Tensor, sample_rate: int, precision: int = 16, channels_first: bool = True) → None[source]¶

将张量保存为音频文件。

Parameters

文件路径 – 音频文件的路径
src – 输入的2D张量，形状为[C x L]或[L x C]，其中L是音频帧的数量，C是通道数
sample_rate – 一个整数，表示音频的采样率（如文件元数据中所列）
位精度（默认值 (精度) – 16 )
channels_first (bool, 可选) – 设置结果中的通道优先或长度优先。（默认值：True）

其他¶

torchaudio.backend.sox_backend.get_sox_bool(i: int = 0) → Any[source]¶

获取 sox 编码信息选项中 sox_bool 的枚举值。

Parameters: i (整数, 可选) – 选择类型或获取所有可能选项的字典使用 __members__ 在未指定时查看所有选项。 (默认: sox_false 或 0)
Returns: 一个 sox_bool 类型
Return type: sox_bool

torchaudio.backend.sox_backend.get_sox_encoding_t(i: int = None) → torchaudio.backend.common.EncodingInfo[source]¶

获取 sox 编码的 sox_encoding_t 枚举值。

Parameters: i (int, 可选) – 选择类型或获取所有可能选项的字典使用 __members__ 在未指定时查看所有选项。 (默认: None)
Returns: 用于输出编码的 sox_encoding_t 类型
Return type: sox_encoding_t

torchaudio.backend.sox_backend.get_sox_option_t(i: int = 2) → Any[source]¶

获取 sox_option_t 的枚举值以用于 sox 编码信息选项。

Parameters: i (int, 可选) – 选择类型或获取所有可能选项的字典使用 __members__ 在未指定时查看所有选项。 (默认：sox_option_default 或 2)
Returns: 一种 sox_option_t 类型
Return type: sox_option_t

torchaudio.backend.sox_backend.save_encinfo(filepath: str, src: torch.Tensor, channels_first: bool = True, signalinfo: Optional[torchaudio.backend.common.SignalInfo] = None, encodinginfo: Optional[torchaudio.backend.common.EncodingInfo] = None, filetype: Optional[str] = None) → None[source]¶

将一个音频信号张量保存到磁盘上，格式为标准格式，如 mp3、wav 等。

Parameters

filepath (str) – 音频文件路径
输入 (张量) – 形状为[C x L]或[L x C]的2D张量，其中L是音频帧的数量，C是通道数
channels_first (bool, 可选) – 设置结果中的通道优先或长度优先。（默认值：True）
信号信息 (sox_signalinfo_t, 可选) – 一个类型为sox_signalinfo_t的信息，当音频类型无法自动确定时可能会有帮助（默认值：None）。
编码信息 (sox_encodinginfo_t, 可选) – 一个 sox_encodinginfo_t 类型，如果音频类型无法自动确定时可以设置（默认值：None）。
文件类型 (str, 可选) – 如果sox无法自动确定，则设置一个文件类型或扩展名。（默认值：None）

Example

>>> data, sample_rate = torchaudio.load('foo.mp3')
>>> torchaudio.save('foo.wav', data, sample_rate)

torchaudio.backend.sox_backend.sox_encodinginfo_t() → torchaudio.backend.common.EncodingInfo[source]¶

创建一个 `sox_encodinginfo_t` 对象。此对象可用于设置编码类型、位精度、压缩因子、字节反转、半字节反转、位反转和字节序。它可以在效果链中用于对最终输出进行编码，或者保存为特定编码的文件。例如，可以使用 sox ulaw 编码来进行 8 位 ulaw 编码。注意，在张量输出中，结果将是 32 位数字，但唯一值的数量将由位精度决定。

Returns: sox_encodinginfo_t(object)

编码（sox_encoding_t），输出编码
每样本位数 (int)，位精度，与 sox_signalinfo_t 中的 precision 相同
压缩（浮点数），有损格式的压缩率，0.0 表示默认压缩
反向字节 (sox_option_t)，反向字节，使用 sox_option_default
反向 nibble （sox_option_t），反向 nibble，使用 sox_option_default
反向位（sox_option_t），反向字节，使用 sox_option_default
相反字节序（sox_bool），更改字节序，使用 sox_false

Example

>>> ei = torchaudio.sox_encodinginfo_t()
>>> ei.encoding = torchaudio.get_sox_encoding_t(1)
>>> ei.bits_per_sample = 16
>>> ei.compression = 0
>>> ei.reverse_bytes = torchaudio.get_sox_option_t(2)
>>> ei.reverse_nibbles = torchaudio.get_sox_option_t(2)
>>> ei.reverse_bits = torchaudio.get_sox_option_t(2)
>>> ei.opposite_endian = torchaudio.get_sox_bool(0)

torchaudio.backend.sox_backend.sox_signalinfo_t() → torchaudio.backend.common.SignalInfo[source]¶

创建一个 sox_signalinfo_t 对象。此对象主要用于设置样本率、声道数、长度、位精度和头留倍数。

Returns: sox_signalinfo_t(object)

速率（浮点数），采样率作为浮点数，实际上很可能是整数浮点数。
通道（int），音频通道的数量
精度（int），位精度
长度（整数），音频以样本乘以通道为单位的长度，0 表示未指定，-1 表示未知。
倍数 (float，可选)，效果的增益乘数，None 表示无乘数

Example

>>> si = torchaudio.sox_signalinfo_t()
>>> si.channels = 1
>>> si.rate = 16000.
>>> si.precision = 16
>>> si.length = 0

Soundfile 后端¶

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

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

torchaudio.set_audio_backend("soundfile")

注意

如果你是从“soundfile” (legacy interface) <soundfile_legacy_backend>后端切换过来的，请在切换后端之前设置torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE标志。

信息¶

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

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

Parameters

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

音频数据的来源。 .. 注意：

* This argument is intentionally annotated as ``str`` only,
  for the consistency with "sox_io" backend, which has a restriction
  on type annotation due to TorchScript compiler compatiblity.

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]。

Parameters

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

音频数据的来源。 .. 注意：

* This argument is intentionally annotated as ``str`` only,
  for the consistency with "sox_io" backend, which has a restriction
  on type annotation due to TorchScript compiler compatiblity.

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.load_wav(filepath: str, frame_offset: int = 0, num_frames: int = -1, channels_first: bool = True) → Tuple[torch.Tensor, int][source]¶

加载波形文件。

此函数仅出于与其他后端兼容的目的而定义，适用于简单的用例，例如 torchaudio.load_wav(filepath)。实现方式与load()相同。

保存¶

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

Parameters

文件路径 (str 或 pathlib.Path) – 音频文件的路径。此函数也处理 pathlib.Path 对象，但为了与“sox_io”后端保持一致，并确保TorchScript编译器兼容性，其被标注为 str。
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

旧版接口（已弃用）¶

"soundfile" 后端提供了旧接口以保证向后兼容，然而该接口已弃用，并将在 0.9.0 版本中移除。

切换到此后端/界面之前，设置torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE标志。在切换后端之前进行设置。

torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio.set_audio_backend("soundfile")  # The legacy interface

信息¶

torchaudio.backend.soundfile_backend.info(filepath: str) → Tuple[torchaudio.backend.common.SignalInfo, torchaudio.backend.common.EncodingInfo][source]¶

从音频文件中获取元数据而无需加载信号。

Parameters

文件路径 – 音频文件的路径

Returns

A si (sox_signalinfo_t) signal: 作为 Python 对象的信息。一个 ei（sox_encodinginfo_t）编码信息。

Return type

(sox_signalinfo_t, sox编码信息_t)

Example

>>> si, ei = torchaudio.info('foo.wav')
>>> rate, channels, encoding = si.rate, si.channels, ei.encoding

加载¶

torchaudio.backend.soundfile_backend.load(filepath: str, out: Optional[torch.Tensor] = None, normalization: Optional[bool] = True, channels_first: Optional[bool] = True, num_frames: int = 0, offset: int = 0, signalinfo: torchaudio.backend.common.SignalInfo = None, encodinginfo: torchaudio.backend.common.EncodingInfo = None, filetype: Optional[str] = None) → Tuple[torch.Tensor, int][source]¶

从磁盘加载音频文件到张量中

Parameters

文件路径 – 音频文件的路径
out – 可选的输出张量，用于代替创建一个新的张量。(默认值：None)
归一化 – 可选的归一化。如果布尔值为True，则输出将除以1 << 31。假设输入是带符号的32位音频，这将归一化为[-1, 1]。如果为float，则输出将除以该数字。如果为Callable，则输出作为参数传递给给定函数，然后输出将除以结果。(默认值：True)
channels_first – 设置结果中的通道优先或长度优先。（默认值：True）
num_frames – 要加载的帧数。0 表示在偏移量之后加载所有内容。 (默认值：0)
偏移量 – 从文件开头开始加载数据的帧数。（默认值：0）
信号信息 – 一个 sox_signalinfo_t 类型，当音频类型无法自动确定时可能会有帮助。（默认值：None）
编码信息 – 一个 sox_encodinginfo_t 类型，如果音频类型无法自动确定时可以设置。（默认值：None）
文件类型 – 如果sox无法自动确定，则设置一个文件类型或扩展名。 (默认值：None)

Returns

An output tensor of size [C x L] or [L x C] where: L 是音频帧的数量， C 是通道的数量。一个整数，表示音频的采样率（如文件元数据中所列）。

Return type

(Tensor, 整数)

Example

>>> data, sample_rate = torchaudio.load('foo.mp3')
>>> print(data.size())
torch.Size([2, 278756])
>>> print(sample_rate)
44100
>>> data_vol_normalized, _ = torchaudio.load('foo.mp3', normalization=lambda x: torch.abs(x).max())
>>> print(data_vol_normalized.abs().max())
1.

torchaudio.backend.soundfile_backend.load_wav(filepath, **kwargs)[source]¶

加载一个波形文件。

它假设该 wav 文件每样本使用 16 位，需要通过将输入右移 16 位来进行归一化。

Parameters

文件路径 – 音频文件的路径

Returns

An output tensor of size [C x L] or [L x C] where L is the number: 音频帧的数量，C 是通道数。一个整数，表示音频的采样率（如文件元数据中所列）

Return type

(Tensor, 整数)

保存¶

torchaudio.backend.soundfile_backend.save(filepath: str, src: torch.Tensor, sample_rate: int, precision: int = 16, channels_first: bool = True) → None[source]¶

将张量保存为音频文件。

Parameters

文件路径 – 音频文件的路径
src – 输入的2D张量，形状为[C x L]或[L x C]，其中L是音频帧的数量，C是通道数
sample_rate – 一个整数，表示音频的采样率（如文件元数据中所列）
位精度（默认值 (精度) – 16 )
channels_first (bool, 可选) – 设置结果中的通道优先或长度优先。（默认值：True）

torchaudio.backend¶

概述¶

可用性¶

默认后端的更改和弃用¶

常用数据结构¶

AudioMetaData¶

信号信息（已弃用）¶

编码信息 (已弃用)¶

Sox IO 后端¶

信息¶

加载¶

保存¶

Sox 后端（已弃用）¶

信息¶

加载¶

保存¶

其他¶

Soundfile 后端¶

信息¶

加载¶

保存¶

旧版接口（已弃用）¶

信息¶

加载¶

保存¶

文档

教程

资源

Backend	0.8.0	0.9.0
`"sox_io"`	Default on Linx/macOS	Default on Linux/macOS
`"sox"` (deprecated)	Available	Removed
`"soundfile"`	Default on Windows	Default on Windows
`"soundfile"` (legacy interface, deprecated)	Available	Removed