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}} \text{window}[k]\ \text{input}[m \times \text{hop\_length} + k]\ \exp\left(- j \frac{2 \pi \cdot \omega k}{\text{n\_fft}}\right),$$

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

• input 必须是 1 维时间序列或 2 维时间序列的批量。

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

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

• window 可以是一个大小为 win_length 的 1-D 张量，例如来自 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 确定在 input 上使用 center 时的填充方法。有关所有可用选项，请参阅 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 维度的实数张量，其中最后一个维度表示实部和虚部。

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

警告

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

参数:

• 输入（张量）- 形状为（B？, L）的输入张量，其中 B？是可选的批次维度

• n_fft（整数）- 傅里叶变换的大小

• hop_length（整数，可选）- 相邻滑动窗口帧之间的距离。默认： None （视为等于 floor(n_fft / 4) ）

• win_length（int，可选）- 窗口帧大小和 STFT 滤波器的大小。默认： None （视为等于 n_fft ）

• window（Tensor，可选）- 可选的窗口函数。形状必须为 1 维且小于等于 n_fft。默认： None （视为所有 $1$ 的窗口）

• center（bool，可选）- 是否在两侧填充 input ，使得第 $t$ 帧在时间 $t \times \text{hop\_length}$ 处居中。默认： True

• pad_mode（str，可选）- 控制当 center 为 True 时使用的填充方法。默认： "reflect"

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

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

• return_complex (bool, optional) –

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

  版本 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 时存在。

返回类型:

张量