torchaudio

注意

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

当前 API

I/O 功能

音频输入/输出功能在 torchaudio.backend 模块中实现，但为了方便使用，以下函数在 torchaudio 模块中提供。有多种后端可供选择，您可以使用 set_audio_backend() 切换后端。

有关详细信息，请参阅 torchaudio.backend，有关用法，请参阅 音频 I/O 教程。

torchaudio.info(filepath: str, ...)

获取音频文件的元数据。有关详细信息，请参阅 torchaudio.backend。

torchaudio.load(filepath: str, ...)

将音频文件加载到 torch.Tensor 对象中。有关详细信息，请参阅 torchaudio.backend。

torchaudio.save(filepath: str, src: torch.Tensor, sample_rate: int, ...)

将 torch.Tensor 对象保存为音频格式。有关详细信息，请参阅 torchaudio.backend。

后端工具

torchaudio.list_audio_backends() → List[str]

列出可用的后端

Returns:

可用后端的列表。

Return type:

列表[字符串]

torchaudio.get_audio_backend() → Optional[str]

获取当前后端的名称

Returns:

当前后端的名称，或者如果未分配后端则为 None。

Return type:

Optional[str]

torchaudio.set_audio_backend(backend: Optional[str])

设置 I/O 操作的后端

Parameters:

backend (str 或 None) – 后端的名称。 根据系统的可用性，可能是 "sox_io" 或 "soundfile"。如果提供了 None，则当前后端将处于未分配状态。

未来 API

在下一个版本中，torchaudio.info、torchaudio.load 和 torchaudio.save 都将允许通过参数 backend 选择要使用的后端。 这些函数将支持使用 FFmpeg、SoX 或 SoundFile（前提是已安装相应的库）。 如果没有明确选择后端，函数将根据优先级顺序（FFmpeg、SoX、SoundFile）和库的可用性自动选择一个后端。

请注意，只有 FFmpeg 和 SoundFile 支持文件类对象。

这些功能可以在当前版本中通过设置环境变量 TORCHAUDIO_USE_BACKEND_DISPATCHER=1 来启用。

torchaudio.info(uri: Union[BinaryIO, str, PathLike], format: Optional[str] = None, buffer_size: int = 4096, backend: Optional[str] = None) → AudioMetaData

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

Parameters:

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

  音频数据来源。接受以下类型：

  • path-like: file path

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

  注意

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

• format (str 或 None, 可选) – 如果不是 None，则解释为可能允许后端覆盖检测到的格式的提示。 （默认值：None）

• buffer_size (int, optional) – 处理类文件对象时使用的缓冲区大小，单位为字节。（默认值：4096）

• backend (str 或 None, 可选) – 要使用的 I/O 后端。如果为 None，函数将根据输入和可用的后端选择后端。 否则，必须是 [“ffmpeg”, “sox”, “soundfile”] 之一，且相应的后端可用。 （默认值：None）

Returns:

给定音频的元数据。

Return type:

AudioMetaData

torchaudio.load(uri: Union[BinaryIO, str, PathLike], frame_offset: int = 0, num_frames: int = -1, normalize: bool = True, channels_first: bool = True, format: Optional[str] = None, buffer_size: int = 4096, backend: Optional[str] = None) → Tuple[Tensor, int]

从文件加载音频数据。

注意

此函数可处理的格式取决于后端的可用性。 此函数已在以下格式上经过测试：

• WAV

  • 32-bit floating-point

  • 32-bit signed integer

  • 24-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 张量。

Parameters:

• uri (路径类对象 或 文件类对象) – 音频数据的来源。

• 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, 可选) – 如果不是 None，则解释为可能允许后端覆盖检测到的格式的提示。 （默认值：None）

• buffer_size (int, optional) – 处理类文件对象时使用的缓冲区大小，单位为字节。（默认值：4096）

• backend (str 或 None, 可选) – 要使用的 I/O 后端。如果为 None，函数将根据输入和可用的后端选择后端。否则，必须是 [“ffmpeg”, “sox”, “soundfile”] 之一，且相应的后端必须可用。（默认值：None）

Returns:

Resulting Tensor and sample rate.

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

Return type:

(torch.Tensor, int)

torchaudio.save(uri: Union[BinaryIO, str, PathLike], src: Tensor, sample_rate: int, channels_first: bool = True, format: Optional[str] = None, encoding: Optional[str] = None, bits_per_sample: Optional[int] = None, buffer_size: int = 4096, backend: Optional[str] = None)

将音频数据保存到文件。

注意

此函数支持的格式取决于后端的可获得性。 本函数已在以下格式上经过测试：

• WAV

  • 32-bit floating-point

  • 32-bit signed integer

  • 16-bit signed integer

  • 8-bit unsigned integer

• FLAC

• OGG/VORBIS

Parameters:

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

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

• sample_rate (int) – 采样率

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

• format (str 或 None, 可选) –

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

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

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

• encoding (str 或 None，可选) –

  更改支持格式的编码。 此参数仅对支持的格式有效，即 "wav" 和 ""flac"`。有效值为

  • "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" 之一时，您可以更改位深度。 有效值为 8、16、24、32 和 64。

• buffer_size (int, optional) – 处理类文件对象时使用的缓冲区大小，单位为字节。（默认值：4096）

• backend (str 或 None, 可选) – 要使用的 I/O 后端。如果为 None，函数将根据输入和可用的后端选择后端。否则，必须是 [“ffmpeg”, “sox”, “soundfile”] 之一，且相应的后端必须可用。（默认值：None）

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

"wav"

• 32 位浮点 PCM

• 32 位有符号整数 PCM

• 24 位有符号整数 PCM

• 16 位有符号整数 PCM

• 8 位无符号整数 PCM

• 8 位 mu-law

• 8 位 a-law

Note:

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

"flac"

• 16 位（默认）

• 24-bit

"ogg"

• 不接受更改配置。