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，將發出警告。在未來的版本中，此屬性將是必需的。當前不提供 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 必須是 1 維時間序列或 2 維批次時間序列。

• 如果 hop_length 為 None（預設值），則將其視為等於 floor(n_fft / 4)。

• 如果 win_length 為 None（預設值），則將其視為等於 n_fft。

• window 可以是大小為 win_length 的 1 維張量，例如透過 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（實數輸入的預設值），則僅返回範圍為 $\left[0, 1, 2, \dots, \left\lfloor \frac{\text{n\_fft}}{2} \right\rfloor + 1\right]$ 的 $\omega$ 對應值，因為實數到複數的傅立葉變換滿足共軛對稱性，即 $X[m, \omega] = X[m, \text{n\_fft} - \omega]^*$。請注意，如果 input 或 window 張量是複數，則無法進行 onesided 輸出。

• 如果 normalized 為 True（預設值為 False），則函式返回歸一化的 STFT 結果，即乘以 $(\text{frame\_length})^{-0.5}$。

• 如果 return_complex 為 True（如果 input 是複數，則為預設值），則返回 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 中更改了簽名。使用舊簽名呼叫可能會導致錯誤或返回不正確的結果。

引數

• input (Tensor) – 輸入張量，形狀為 (B?, L)，其中 B? 是可選的批次維度。

• n_fft (int) – 傅立葉變換大小

• hop_length (int, optional) – 相鄰滑動視窗幀之間的距離。預設值：None (被視為等於 floor(n_fft / 4))

• win_length (int, optional) – 視窗幀大小和 STFT 濾波器大小。預設值：None (被視為等於 n_fft)

• window (Tensor, optional) – 可選的視窗函式。形狀必須為一維且 <= n_fft。預設值：None (被視為全 $1$ 的視窗)

• center (bool, optional) – 是否在 input 兩側進行填充，以便第 $t$ 幀以時間點 $t \times \text{hop\_length}$ 為中心。預設值：True

• pad_mode (str, optional) – 控制當 center 為 True 時使用的填充方法。預設值："reflect"

• normalized (bool, optional) – 控制是否返回歸一化的 STFT 結果。預設值：False

• onesided (bool, optional) – 控制對於實數輸入是否返回一半結果以避免冗餘。預設值：對於實數 input 和 window 為 True，否則為 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 時存在。

返回型別

Tensor