nnAudio2 Migration Summary

May 2, 2026 · View on GitHub

This document describes what changed between nnAudio (≤ 0.3.x) and nnAudio2 (2.0.0), why each change was made, and how to verify the results.

For the full per-batch development log, see MIGRATION_LOG.md.

Verified environment

Problem: torch.jit.script(STFT(...)) and torch.jit.script(iSTFT(...)) both failed.

Root causes:

STFT.forward() assigned self.num_samples dynamically — TorchScript does not allow setting undeclared attributes.
STFT.forward() constructed nn.ConstantPad1d / nn.ReflectionPad1d at runtime — TorchScript does not allow dynamic module construction inside forward.
iSTFT used refresh_win == None-style control flow that TorchScript could not type-infer correctly.

Fixes:

Replaced dynamic attribute assignment with local variables.
Replaced runtime-constructed padding modules with functional padding calls (F.pad).
Tightened optional-argument handling in STFT.forward, STFT.inverse, and iSTFT.forward.
Updated inverse_stft to use local tensors for window normalisation under scripting, while preserving the eager-mode cache.

Result: STFT and iSTFT now compile with torch.jit.script.

Problem: Calling inverse STFT with freq_scale='linear' or freq_scale='log' silently returned severely degraded audio:

The reconstruction was not just noisy — it was essentially wrong — but no error was raised.

Fix:

Added self.supports_inverse tracking per frequency scale.
STFTBase now raises RuntimeError on any inverse call when freq_scale != 'no'.
Initialization emits a warning when an inverse-capable object is created with a non-uniform scale.

Result:

freq_scale='no': inverse still works (MSE ~4 × 10⁻¹⁴).
freq_scale='linear' / 'log' / 'log2': raises a clear RuntimeError instead of returning bad audio.

Problem: After the stft.py fixes, TorchScript compilation moved on to fail in the helper functions used by iSTFT.

Fixes:

Added explicit type annotations to torch_window_sumsquare and overlap_add.
Changed fold(..., stride=...) calls to pass stride as a 2-element tuple rather than a bare integer, matching current TorchScript type expectations.

Problem: scipy.signal.blackmanharris was removed from the top-level scipy.signal namespace in modern SciPy.

Fix: changed both Combined_Frequency_Periodicity and CFP to use scipy.signal.windows.blackmanharris.

Problem: VQT(gamma=0) should reduce to CQT, but showed a meaningful numerical mismatch against CQT1992v2 (max absolute error ~0.089).

Fix: when gamma == 0, VQT.__init__ now creates an internal CQT1992v2 module and VQT.forward delegates to it.

Added import-time citation reminder so users who install the package are prompted to cite the paper.

cd Installation
pytest -q

To run only STFT/iSTFT tests:

pytest tests/test_stft.py -q

To verify the citation reminder:

python -c "import nnAudio2"
# suppress with: NNAUDIO_DISABLE_CITATION_REMINDER=1 python -c "import nnAudio2"

The following warnings appear in the test suite but do not cause failures:

These are reasonable cleanup targets for a future maintenance pass.