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 вычисляет преобразование Фурье для коротких перекрывающихся окон входного сигнала. В результате получаются частотные компоненты сигнала и их изменения во времени. Интерфейс этой функции разработан по образцу функции stft из библиотеки librosa (но не является её прямой заменой).

Если не учитывать необязательное измерение пакета, этот метод вычисляет следующее выражение:

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

где $m$ — индекс скользящего окна, а $\omega$ — частота $0 \leq \omega < \text{n\_fft}$ для onesided=False или $0 \leq \omega < \lfloor \text{n\_fft} / 2 \rfloor + 1$ для onesided=True.

• 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 задаёт способ дополнения, используемый для input, когда center равно True. Все доступные варианты см. в 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 имеет значение true, или вещественный тензор размера $(* \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, необязательно) – определяет, возвращать ли половину результатов во избежание избыточности для вещественных входных данных. Значение по умолчанию: True для вещественных input и window, в противном случае — False.

• return_complex (bool, необязательно) –

  возвращать ли комплексный тензор или вещественный тензор с дополнительным последним измерением для вещественной и мнимой частей.

  Изменено в версии 2.0: return_complex теперь является обязательным аргументом для вещественных входных данных, поскольку значение по умолчанию переводится на True.

  Устарело с версии 2.0: return_complex=False считается устаревшим; вместо него используйте return_complex=True. Обратите внимание: вызов torch.view_as_real() для выходных данных восстановит устаревший формат результата.

Возвращает:

A tensor containing the STFT result with shape (B?, N, T, C?) where

• B? — необязательное измерение пакета из входных данных.
• N — число частотных отсчётов: (n_fft // 2) + 1 для onesided=True или n_fft в противном случае.
• T — число кадров: 1 + L // hop_length для center=True или 1 + (L - n_fft) // hop_length в противном случае.
• C? — необязательное измерение длины 2 для вещественной и мнимой частей; присутствует при return_complex=False.

Тип возвращаемого значения:

Tensor