Torchaudio

注意

版本 2.1 将修改 、 ，并允许通过函数参数而不是 进行后端选择，其中 FFmpeg 是默认后端。 在当前版本中，可以通过设置 environment variable 来启用新的 API。 有关新 API 的详细信息，请参阅未来的 API。torchaudio.infotorchaudio.loadtorchaudio.savetorchaudio.set_audio_backendTORCHAUDIO_USE_BACKEND_DISPATCHER=1

当前 API

I/O 功能

音频 I/O 函数在 torchaudio.backend 模块中实现，但为了便于使用，模块上提供了以下函数。有不同的后端可用，您可以使用 .torchaudioset_audio_backend()

有关详细信息，请参阅 torchaudio.backend，使用方法请参考 Audio I/O 教程。

torchaudio 中。info（filepath： str， ...)

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

torchaudio 中。load（filepath： str， ...)

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

torchaudio 中。save（filepath： str， src： torch.张量、sample_rate：int、...)

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

后端实用程序

torchaudio 中。list_audio_backends（） → List[str]

列出可用的后端

结果

可用后端的列表。

返回类型：

列表[str]

torchaudio 中。get_audio_backend（） → 可选[str]

获取当前后端的名称

结果

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

返回类型：

可选[str]

torchaudio 中。set_audio_backend（backend： Optional[str]）

设置 I/O 操作的后端

参数

backend （str 或 None） – 后端的名称。 其中一项或基于可用性 的系统。如果提供，则当前后端未分配。"sox_io""soundfile"None

未来 API

在下一个版本中，每个 、 和 都将允许选择要通过 parameter 使用的后端。 这些函数将支持使用 FFmpeg、SoX 和 SoundFile 中的任何一个，前提是安装了相应的库。 如果未明确选择后端，则函数将选择一个后端以使用给定的优先顺序（FFmpeg、SoX、SoundFile）和库可用性。torchaudio.infotorchaudio.loadtorchaudio.savebackend

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

在当前版本中，可以通过设置 environment variable 来启用这些功能。TORCHAUDIO_USE_BACKEND_DISPATCHER=1

torchaudio 中。info（uri： Union[BinaryIO， str， PathLike]， format： 可选[str] = 无，buffer_size：int = 4096，后端：可选[str] = 无） → AudioMetaData

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

参数

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

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

  • path-like： 文件路径

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

  注意

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

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

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

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

结果

给定音频的元数据。

返回类型：

AudioMetaData

torchaudio 中。load（uri： Union[BinaryIO， str， PathLike]， frame_offset： int = 0， num_frames： int = -1， 归一化： bool = True，channels_first： bool = True， 格式： Optional[str] = None，buffer_size： int = 4096， 后端： 可选[str] = 无） → 元组[Tensor， int]

从文件加载音频数据。

注意

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

• WAV

  • 32 位浮点

  • 32 位有符号整数

  • 24 位有符号整数

  • 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

参数

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

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

• backend （str 或 None，可选） – 要使用的 I/O 后端。如果 ，函数会选择给定输入和可用后端的后端。 否则，必须是 [“ffmpeg”， “sox”， “soundfile”] 之一，其对应的 backend 可用。（默认：NoneNone)

结果

生成的 Tensor 和 sample rate。

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

返回类型：

(torch。张量、int)

torchaudio 中。save（uri： Union[BinaryIO， str， PathLike]， src： 张量， sample_rate： int， channels_first： bool = True， 格式： 可选[str] = 无，编码：可选[str] = 无，bits_per_sample： 可选[int] = 无，buffer_size：int = 4096，后端： 可选 [str] = 无)

将音频数据保存到文件。

注意

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

• WAV

  • 32 位浮点

  • 32 位有符号整数

  • 16 位有符号整数

  • 8 位无符号整数

• FLAC的

• OGG/VORBIS

参数

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

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

• sample_rate （int） – 采样率

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

• format （str 或 None，可选） –

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

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

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

• encoding （str 或 None，可选） –

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

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

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

  • "PCM_F"（浮点 PCM）

  • "ULAW"（mu-law）

  • "ALAW"（A-法律）

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

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

• backend （str 或 None，可选） – 要使用的 I/O 后端。如果 ，函数会选择给定输入和可用后端的后端。 否则，必须是 [“ffmpeg”， “sox”， “soundfile”] 之一，其对应的 backend 可用。（默认：NoneNone)

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

"wav"

• 32 位浮点 PCM

• 32 位有符号整数 PCM

• 24 位有符号整数 PCM

• 16 位有符号整数 PCM

• 8 位无符号整数 PCM

• 8 位 mu law

• 8 位 A-law

注意：

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

"flac"

• 16 位 （默认）

• 24 位

"ogg"

• 不接受更改配置。