torchaudio.sox_effects

资源初始化/关闭

torchaudio.sox_effects.init_sox_effects()

初始化使用 sox 效果所需的资源。

注意

您无需手动调用此函数。它会自动调用。

初始化后，您无需在多次使用 sox 效果时再次调用此函数，只要尚未调用 shutdown_sox_effects()，这样做是安全的。 一旦调用了 shutdown_sox_effects()，您将无法再使用 SoX 效果，且再次初始化将导致错误。

torchaudio.sox_effects.shutdown_sox_effects()

清理使用 sox 效果所需的资源。

注意

您无需手动调用此函数。它会自动调用。

多次调用此函数是安全的。 一旦调用 shutdown_sox_effects()，您将无法再使用 SoX 效果，且再次初始化将导致错误。

列出支持的特效

torchaudio.sox_effects.effect_names() → List[str]

获取有效的 sox 效果名称列表

Returns

可用效果名称列表。

Return type

列表[字符串]

Example

>>> torchaudio.sox_effects.effect_names()
['allpass', 'band', 'bandpass', ... ]

应用效果

将 SoX 效果链应用于 torch.Tensor 或文件，并加载为 torch.Tensor。

在 Tensor 上应用效果

torchaudio.sox_effects.apply_effects_tensor(tensor: torch.Tensor, sample_rate: int, effects: List[List[str]], channels_first: bool = True) → Tuple[torch.Tensor, int]

对给定张量应用 sox 效果

注意

此功能的工作方式与sox命令非常相似，但有一些细微差别。例如，sox命令会自动添加某些效果（例如在speed和pitch之后添加rate效果以及其他效果），而此功能仅应用给定的效果。（因此，要实际应用speed效果，您还需要指定具有所需采样率的rate效果。）

Parameters

• 张量 (torch.Tensor) – 输入的2D张量。

• sample_rate (int) – 采样率

• effects (List[List[str]]) – 效果列表。

• channels_first (bool) – 表示输入张量的维度是 [channels, time] 或 [time, channels]

Returns

生成的张量和采样率。 生成的张量与输入张量具有相同的 dtype，并且通道顺序相同。张量的形状可能会因应用的效应而有所不同。采样率也可能因应用的效应而有所不同。

Return type

Tuple[torch.Tensor, int]

Example - Basic usage

>>>
>>> # Defines the effects to apply
>>> effects = [
...     ['gain', '-n'],  # normalises to 0dB
...     ['pitch', '5'],  # 5 cent pitch shift
...     ['rate', '8000'],  # resample to 8000 Hz
... ]
>>>
>>> # Generate pseudo wave:
>>> # normalized, channels first, 2ch, sampling rate 16000, 1 second
>>> sample_rate = 16000
>>> waveform = 2 * torch.rand([2, sample_rate * 1]) - 1
>>> waveform.shape
torch.Size([2, 16000])
>>> waveform
tensor([[ 0.3138,  0.7620, -0.9019,  ..., -0.7495, -0.4935,  0.5442],
        [-0.0832,  0.0061,  0.8233,  ..., -0.5176, -0.9140, -0.2434]])
>>>
>>> # Apply effects
>>> waveform, sample_rate = apply_effects_tensor(
...     wave_form, sample_rate, effects, channels_first=True)
>>>
>>> # Check the result
>>> # The new waveform is sampling rate 8000, 1 second.
>>> # normalization and channel order are preserved
>>> waveform.shape
torch.Size([2, 8000])
>>> waveform
tensor([[ 0.5054, -0.5518, -0.4800,  ..., -0.0076,  0.0096, -0.0110],
        [ 0.1331,  0.0436, -0.3783,  ..., -0.0035,  0.0012,  0.0008]])
>>> sample_rate
8000

Example - Torchscript-able transform

>>>
>>> # Use `apply_effects_tensor` in `torch.nn.Module` and dump it to file,
>>> # then run sox effect via Torchscript runtime.
>>>
>>> class SoxEffectTransform(torch.nn.Module):
...     effects: List[List[str]]
...
...     def __init__(self, effects: List[List[str]]):
...         super().__init__()
...         self.effects = effects
...
...     def forward(self, tensor: torch.Tensor, sample_rate: int):
...         return sox_effects.apply_effects_tensor(
...             tensor, sample_rate, self.effects)
...
...
>>> # Create transform object
>>> effects = [
...     ["lowpass", "-1", "300"],  # apply single-pole lowpass filter
...     ["rate", "8000"],  # change sample rate to 8000
... ]
>>> transform = SoxEffectTensorTransform(effects, input_sample_rate)
>>>
>>> # Dump it to file and load
>>> path = 'sox_effect.zip'
>>> torch.jit.script(trans).save(path)
>>> transform = torch.jit.load(path)
>>>
>>>> # Run transform
>>> waveform, input_sample_rate = torchaudio.load("input.wav")
>>> waveform, sample_rate = transform(waveform, input_sample_rate)
>>> assert sample_rate == 8000

在文件上应用效果

torchaudio.sox_effects.apply_effects_file(path: str, effects: List[List[str]], normalize: bool = True, channels_first: bool = True, format: Optional[str] = None) → Tuple[torch.Tensor, int]

对音频文件应用 sox 效果，并将生成的数据加载为 Tensor

注意

此函数的运作方式与 sox 命令非常相似，但存在一些细微差别。例如，sox 命令会自动添加某些效果（例如在 speed 之后添加 rate 效果、pitch 等），而此函数仅应用给定的效果。因此，若要实际应用 speed 效果，您还需要提供具有所需采样率的 rate 效果，因为在内部，speed 效果仅更改采样率而不触碰样本。

Parameters

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

  音频数据的来源。当函数未通过 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 种类型。

  注意：此参数被故意标注为 str，仅为了与 TorchScript 编译器兼容。

• effects (List[List[str]]) – 效果列表。

• normalize (bool) – 当 True 时，此函数始终返回 float32，并且样本值被 归一化为 [-1.0, 1.0]。 如果输入文件是整数 WAV 格式，提供 False 将更改生成的张量类型为 整数类型。对于除整数 WAV 类型以外的格式，此参数没有效果。

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

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

Returns

结果张量和采样率。 如果 normalize=True，则结果张量始终为 float32 类型。 如果 normalize=False，且输入音频文件为整数WAV文件，则 结果张量具有相应的整数类型。（注意不支持24位整数类型） 如果 channels_first=True，则结果张量的维度为 [channel, time]， 否则为 [time, channel]。

Return type

Tuple[torch.Tensor, int]

Example - Basic usage

>>>
>>> # Defines the effects to apply
>>> effects = [
...     ['gain', '-n'],  # normalises to 0dB
...     ['pitch', '5'],  # 5 cent pitch shift
...     ['rate', '8000'],  # resample to 8000 Hz
... ]
>>>
>>> # Apply effects and load data with channels_first=True
>>> waveform, sample_rate = apply_effects_file("data.wav", effects, channels_first=True)
>>>
>>> # Check the result
>>> waveform.shape
torch.Size([2, 8000])
>>> waveform
tensor([[ 5.1151e-03,  1.8073e-02,  2.2188e-02,  ...,  1.0431e-07,
         -1.4761e-07,  1.8114e-07],
        [-2.6924e-03,  2.1860e-03,  1.0650e-02,  ...,  6.4122e-07,
         -5.6159e-07,  4.8103e-07]])
>>> sample_rate
8000

Example - Apply random speed perturbation to dataset

>>>
>>> # Load data from file, apply random speed perturbation
>>> class RandomPerturbationFile(torch.utils.data.Dataset):
...     """Given flist, apply random speed perturbation
...
...     Suppose all the input files are at least one second long.
...     """
...     def __init__(self, flist: List[str], sample_rate: int):
...         super().__init__()
...         self.flist = flist
...         self.sample_rate = sample_rate
...
...     def __getitem__(self, index):
...         speed = 0.5 + 1.5 * random.randn()
...         effects = [
...             ['gain', '-n', '-10'],  # apply 10 db attenuation
...             ['remix', '-'],  # merge all the channels
...             ['speed', f'{speed:.5f}'],  # duration is now 0.5 ~ 2.0 seconds.
...             ['rate', f'{self.sample_rate}'],
...             ['pad', '0', '1.5'],  # add 1.5 seconds silence at the end
...             ['trim', '0', '2'],  # get the first 2 seconds
...         ]
...         waveform, _ = torchaudio.sox_effects.apply_effects_file(
...             self.flist[index], effects)
...         return waveform
...
...     def __len__(self):
...         return len(self.flist)
...
>>> dataset = RandomPerturbationFile(file_list, sample_rate=8000)
>>> loader = torch.utils.data.DataLoader(dataset, batch_size=32)
>>> for batch in loader:
>>>     pass