torch.stft

torch.stft(input, n_fft, hop_length=None, win_length=None, window=None, center=True, pad_mode='reflect', normalized=False, onesided=None, return_complex=None, align_to_window=None)

短时傅里叶变换 (STFT)。

警告

从 1.8.0 版本开始，对于实数输入必须始终明确指定 return_complex，并且 return_complex=False 已被弃用。强烈建议使用 return_complex=True，因为在未来的 PyTorch 版本中，此函数将只返回复数张量。

请注意，torch.view_as_real() 可用于恢复一个带有额外最后一个维度表示实部和虚部的实数张量。

警告

从 2.1 版本开始，如果未指定 window，将会发出警告。在未来的版本中，此属性将是必需的。目前不提供窗口默认为使用矩形窗，这可能会导致不理想的伪影。考虑使用锥形窗，例如 torch.hann_window()。

STFT 计算输入的短重叠窗口的傅里叶变换。这给出了信号的频率分量随时间变化的情况。此函数的接口仿照了 librosa 的 stft 函数（但并不是一个直接的替代品）。

忽略可选的批处理维度，此方法计算以下表达式：

$$X[\omega, m] = \sum_{k = 0}^{\text{win\_length-1}}$$

其中 $m$ 是滑动窗口的索引，$\omega$ 是频率。当 onesided=False 时，$0 \leq \omega < \text{n\_fft}$；当 onesided=True 时，$0 \leq \omega < \lfloor \text{n\_fft} / 2 \rfloor + 1$。

• input 必须是一维时间序列或二维时间序列批次。

• 如果 hop_length 是 None（默认值），则它被视为等于 floor(n_fft / 4)。

• 如果 win_length 是 None（默认值），则它被视为等于 n_fft。

• window 可以是一个大小为 win_length 的一维张量，例如，来自 torch.hann_window()。如果 window 是 None（默认值），则它被视为在窗口中所有位置都为 $1$。如果 $\text{win\_length} < \text{n\_fft}$，则在应用之前，window 将在两侧填充到长度 n_fft。

• 如果 center 是 True（默认值），input 将在两侧进行填充，以便第 $t$ 帧以时间 $t \times \text{hop\_length}$ 为中心。否则，第 $t$ 帧从时间 $t \times \text{hop\_length}$ 开始。

• pad_mode 决定了当 center 为 True 时用于 input 的填充方法。有关所有可用选项，请参阅 torch.nn.functional.pad()。默认值为 "reflect"。

• 如果 onesided 是 True（对于实数输入的默认值），则仅返回 $\omega$ 在 $\left[0, 1, 2, \dots, \left\lfloor \frac{\text{n\_fft}}{2} \right\rfloor + 1\right]$ 中的值，因为实数到复数的傅里叶变换满足共轭对称性，即 $X[m, \omega] = X[m, \text{n\_fft} - \omega]^*$。注意，如果输入或窗口张量是复数，则无法进行 onesided 输出。

• 如果 normalized 是 True（默认为 False），函数将返回归一化的 STFT 结果，即乘以 $(\text{frame\_length})^{-0.5}$。

• 如果 return_complex 是 True（如果输入是复数，则为默认值），返回值是一个 input.dim() + 1 维的复数张量。如果为 False，输出是一个 input.dim() + 2 维的实数张量，其中最后一个维度表示实部和虚部。

如果 return_complex 为 true，则返回一个大小为 $(* \times N \times T)$ 的复数张量，或者一个大小为 $(* \times N \times T \times 2)$ 的实数张量。其中 $*$ 是 input 的可选批次大小，$N$ 是应用 STFT 的频率数，$T$ 是使用的总帧数。

警告

此函数在 0.4.1 版本中更改了签名。使用先前的签名调用可能会导致错误或返回不正确的结果。

参数

• input (Tensor) – 输入张量，形状为 (B?, L)，其中 B? 是一个可选的批次维度

• n_fft (int) – 傅里叶变换的大小

• hop_length (int, 可选) – 相邻滑动窗口帧之间的距离。默认值：None (被视为等于 floor(n_fft / 4))

• win_length (int, 可选) – 窗口帧和 STFT 滤波器的大小。默认值：None (被视为等于 n_fft)

• window (Tensor, 可选) – 可选的窗口函数。形状必须是一维且 <= n_fft。默认值：None (被视为一个全为 $1$ 的窗口)

• center (bool, 可选) – 是否在两侧填充 input，以使第 $t$ 帧以时间 $t \times \text{hop\_length}$ 为中心。默认值：True

• pad_mode (str, 可选) – 控制当 center 为 True 时使用的填充方法。默认值："reflect"

• normalized (bool, 可选) – 控制是否返回归一化的 STFT 结果。默认值：False

• onesided (bool, 可选) – 控制是否为实数输入返回一半结果以避免冗余。默认值：对于实数 input 和 window 为 True，否则为 False。

• return_complex (bool, 可选) –

  是否返回一个复数张量，或一个带有额外最后一个维度表示实部和虚部的实数张量。

  在 2.0 版本中更改: 对于实数输入，return_complex 现在是一个必需参数，因为默认值正在过渡到 True。

  从 2.0 版本开始弃用: return_complex=False 已被弃用，请改用 return_complex=True。请注意，在输出上调用 torch.view_as_real() 将恢复已弃用的输出格式。

返回

一个包含 STFT 结果的张量，形状为 (B?, N, T, C?)，其中

• B? 是来自输入的可选批次维度。

• N 是频率样本数，对于 onesided=True 是 (n_fft // 2) + 1，否则是 n_fft。

• T 是帧数，对于 center=True 是 1 + L // hop_length，否则是 1 + (L - n_fft) // hop_length。

• C? 是一个可选的长度为 2 的维度，表示实部和虚部，当 return_complex=False 时存在。

返回类型

张量