specux 0.0.0__tar.gz → 0.1.0.dev1__tar.gz

specux-0.1.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Kiers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specux-0.1.0.dev1/MANIFEST.in

@@ -0,0 +1,12 @@
+# The sdist must carry everything a source build compiles against: setuptools
+# auto-includes ext_modules sources but not headers, platform-conditional
+# sources, or the vendored metal-cpp.
+recursive-include src *.h *.hpp *.c *.cpp *.mm
+recursive-include src/third_party/metal-cpp *
+# vendored license texts (extensionless / non-source), so the sdist carries
+# every third-party notice (soxr LGPL LICENCE, DLPack + minimp3 dedications)
+recursive-include src/third_party *LICENSE *LICENCE *COPYING
+include NOTICE
+include scripts/build.ps1
+prune build
+prune dist

specux-0.1.0.dev1/NOTICE

@@ -0,0 +1,123 @@
+specux third-party notices
+===========================
+
+specux itself is licensed under the MIT License (see LICENSE). All GPU kernels
+are generated by its own C++ codegen (src/codegen.h) and compiled at runtime;
+no third-party FFT library is linked into them.
+
+
+=======================================================================
+Vendored source
+=======================================================================
+
+DLPack (Apache-2.0)
+    https://github.com/dmlc/dlpack
+    src/third_party/dlpack.h, the tensor-exchange header used by the Metal
+    resident paths. Full license text in src/third_party/dlpack-LICENSE.
+
+metal-cpp (Apache-2.0, Apple)
+    src/third_party/metal-cpp, C++ bindings for the Metal API, used by the
+    specux._metal extension on macOS. License in metal-cpp/LICENSE.txt.
+
+
+=======================================================================
+Build / runtime dependencies (not vendored)
+=======================================================================
+
+pybind11 (BSD-3)
+    Extension bindings, build-time.
+
+NVIDIA CUDA / NVRTC (NVIDIA SLA)
+    Loaded at runtime by specux._cuda from a toolkit install or the nvidia-*
+    pip wheels.
+
+PyTorch (BSD-3)
+    Optional; enables the resident-tensor and autograd paths.
+
+
+=======================================================================
+Audio module: vendored (compiled into specux._audio)
+=======================================================================
+
+soxr (dofuuz fork)
+    src/third_party/soxr/
+    Sample-rate conversion (all quality= resampling). Fork of the SoX
+    Resampler Library with PFFFT and NEON/SIMD paths.
+    License: LGPL-2.1-or-later (see src/third_party/soxr/LICENCE).
+    Upstream: https://github.com/dofuuz/soxr
+    (fork of https://sourceforge.net/projects/soxr/).
+
+    LGPL compliance: soxr is built as its own shared library
+    (libspecux_soxr.dylib/.so, shipped next to the extension and resolved via
+    @loader_path / $ORIGIN), so users can replace or relink it as LGPL-2.1
+    section 6 requires. SPECUX_SOXR_STATIC=1 compiles it into the extension
+    instead, a dev-only convenience; wheels must not be built that way. This
+    does not affect the MIT licensing of specux's own code.
+
+    The soxr tree includes PFFFT (Julien Pommier; BSD-like FFTPACK license),
+    compiled as part of the fork. It also includes the Ooura FFT and Bessel
+    routines (soxr/fft4g64.c, fft4g32.c, dbesi0.c; Copyright Takuya Ooura
+    1996-2001), which carry a permissive "use freely" notice in their file
+    headers.
+
+dr_wav
+    src/third_party/dr_wav.h
+    WAV/PCM decode and encode by David Reid. Public domain (Unlicense) or
+    MIT-0, at your choice. Upstream: https://github.com/mackron/dr_libs
+
+dr_mp3
+    src/third_party/dr_mp3.h
+    MP3 decoder by David Reid, built on the minimp3 engine by lieff. Public
+    domain (Unlicense) or MIT-0, at your choice.
+    Upstream: https://github.com/mackron/dr_libs
+
+dr_flac
+    src/third_party/dr_flac.h
+    FLAC decoder by David Reid. Public domain (Unlicense) or MIT-0, at your
+    choice. Upstream: https://github.com/mackron/dr_libs
+
+minimp3 / minimp3_ex
+    src/third_party/minimp3.h, minimp3_ex.h
+    MP3 decoder with sample-accurate seeking (used for windowed MP3 reads),
+    by lieff. CC0-1.0 (public domain; see src/third_party/minimp3-LICENSE).
+    Upstream: https://github.com/lieff/minimp3
+
+
+=======================================================================
+Audio module: dynamically linked (bundled as shared libraries in wheels)
+=======================================================================
+
+TagLib (libtag)
+    Metadata read and write (tags, write_tags, cover, write_cover): ID3v1/v2,
+    Vorbis comments, MP4 atoms, and APE, parsed uniformly across formats.
+    Dual-licensed LGPL-2.1 / MPL-1.1. Where specux links TagLib statically
+    (the Windows dev build from scripts/get_taglib.ps1, unmodified sources,
+    zlib disabled), the MPL-1.1 license is elected: MPL is file-scoped and
+    permits static combination, requiring only that the covered files remain
+    available under MPL, which upstream provides. A dynamically linked build
+    satisfies either license. Optional at build time: without TagLib the tag
+    functions raise and everything else works. Upstream: https://taglib.org
+
+FFmpeg (libavformat, libavcodec, libavutil, libswresample)
+    Used for FLAC/OGG/MP4-AAC and other container decode, all compressed
+    encoding (save to flac/mp3/ogg/m4a), and sample-format conversion inside
+    those paths (libswresample converts codec sample formats to float; it does
+    not do rate conversion, that is soxr, above).
+    LGPL-2.1-or-later when built without GPL/nonfree components
+    (--disable-gpl --disable-nonfree, which is how release wheels must be
+    built). FFmpeg is linked dynamically; the shared libraries are bundled in
+    the wheel (delocate/auditwheel) and remain replaceable, satisfying the
+    LGPL. License and source: https://ffmpeg.org and
+    https://github.com/FFmpeg/FFmpeg.
+
+    The minimal FFmpeg (scripts/get_ffmpeg.sh on macOS, the BtbN lgpl-shared
+    build on Windows) enables no GPL or nonfree encoders. The external codec
+    libraries it links:
+      libmp3lame  LGPL-2.1-or-later  MP3 encode      https://lame.sourceforge.io
+      libvorbis   BSD-3-Clause       Ogg Vorbis      https://xiph.org/vorbis
+      libogg      BSD-3-Clause       Ogg container   https://xiph.org/ogg
+      libopus     BSD-3-Clause       Opus            https://opus-codec.org
+    libmp3lame (LGPL) is built as its own shared library and linked
+    dynamically, so it stays replaceable for the same section-6 reason as
+    FFmpeg itself; the BSD codecs fold in statically and carry attribution
+    only.

specux-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: specux
+Version: 0.1.0.dev1
+Summary: Differentiable audio DSP for Python: fast, fused kernels on GPU and CPU
+Author-email: Peter Kiers <pkiers.1983@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://specux.com
+Project-URL: Documentation, https://specux.com
+Project-URL: Repository, https://github.com/auvux/specux
+Project-URL: Issues, https://github.com/auvux/specux/issues
+Keywords: stft,istft,spectrogram,mel,fft,dsp,audio,cuda,metal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C++
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.22
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Provides-Extra: cuda
+Requires-Dist: nvidia-cuda-nvrtc-cu12; extra == "cuda"
+Requires-Dist: nvidia-cuda-runtime-cu12; extra == "cuda"
+Provides-Extra: cuda12
+Requires-Dist: nvidia-cuda-nvrtc-cu12; extra == "cuda12"
+Requires-Dist: nvidia-cuda-runtime-cu12; extra == "cuda12"
+Provides-Extra: cuda13
+Requires-Dist: nvidia-cuda-nvrtc<14,>=13; extra == "cuda13"
+Requires-Dist: nvidia-cuda-runtime<14,>=13; extra == "cuda13"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: torch; extra == "test"
+Provides-Extra: wheeltest
+Requires-Dist: pytest; extra == "wheeltest"
+Dynamic: license-file
+
+# specux
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Differentiable audio DSP for Python: fast, fused kernels on GPU and CPU.
+
+Spectral transforms, an FFT family, and audio I/O, on numpy, torch, and cupy
+arrays alike.
+
+Documentation: <https://specux.com>
+
+```python
+import specux
+
+y, sr = specux.audio.load("song.flac", sr=16000, mono=True)
+M = specux.melspectrogram(y, sr=sr, n_fft=1024, n_mels=80)
+
+import torch
+x = torch.randn(8, 32768, device="cuda", requires_grad=True)
+S = specux.stft(x, n_fft=1024, output="power")   # stays on the GPU
+S.sum().backward()                                # native adjoint kernels
+```
+
+Arrays go in and come out in their own library: numpy in, numpy out; torch in,
+torch out (resident on its device, differentiable); cupy in, cupy out. The GPU
+kernels are generated in C++ and compiled at runtime (NVRTC for CUDA, MSL for
+Metal), so one build covers every size, precision, and output mode; the CPU
+backend carries the same transforms and adjoints, so training works without
+a GPU.
+
+## What's in the box
+
+- **Spectral transforms**: `stft` / `istft`, `melspectrogram`, `mfcc`, `lfcc`,
+  `cqt` / `vqt` / `chroma`, with output modes `complex` / `magnitude` /
+  `power` / `db` and configured class twins (`specux.STFT`, `specux.MFCC`,
+  ...). `specux.transforms` adds torch `nn.Module` wrappers with
+  torchaudio-shaped defaults.
+- **FFT family**: `fft` / `ifft` / `rfft` / `irfft` at any length (powers of
+  two, smooth sizes, primes) and precision (float32, float64, and float16
+  storage with float32 compute), plus reusable plans (`fft_plan`,
+  `stft_plan` with optional autotuning).
+- **Audio I/O** (`specux.audio`): decode and encode WAV/FLAC/MP3/OGG/MP4,
+  frame-accurate `offset`/`duration`, batch `load_many`/`save_many`,
+  streaming readers and writers for multi-hour files, resampling, loudness /
+  true-peak / loudness-range metering, and tags/cover metadata.
+- **torch integration**: every entry point is a `torch.library` custom op, so
+  `torch.compile(fullgraph=True)` traces without graph breaks and
+  `torch.autocast` computes in float32. torch stays optional: without it,
+  numpy arrays run on the CPU engine or the torch-free CUDA runtime.
+- **Runtime options**: `specux.deterministic(True)` switches overlap-adds to
+  bitwise-reproducible kernels (and follows
+  `torch.use_deterministic_algorithms`); `specux.benchmark(True)` autotunes
+  new configurations once and caches the result on disk.
+
+## Install
+
+```bash
+pip install specux              # CPU everywhere; CUDA/Metal where the wheel includes them
+pip install specux[cuda12]      # + NVRTC and CUDA headers from NVIDIA's pip wheels
+pip install specux[cuda13]      # the same for CUDA 13
+pip install specux[torch]       # torch bundles its own CUDA, nothing extra needed
+```
+
+Or from source, in the environment you plan to use it in:
+
+```bash
+pip install -e .
+```
+
+The build is torch-free (no libtorch anywhere), so one build serves numpy,
+cupy, and whichever torch is installed at runtime. Python >= 3.10,
+numpy >= 1.22; torch optional (>= 2.4 for autograd and `torch.compile`,
+>= 2.7 for resident Metal).
+
+- **CUDA**: builds when a toolkit is found (`SPECUX_CUDA_HOME` overrides);
+  running needs an NVIDIA driver plus NVRTC from a toolkit, torch, or the
+  `nvidia-*` pip wheels. Skipped with a notice otherwise.
+- **CPU**: always builds. `SPECUX_CPU_ONLY=1` forces a CPU-only build.
+- **macOS**: builds the CPU and Metal extensions out of the box (metal-cpp is
+  vendored).
+- **Audio I/O**: needs FFmpeg dev libraries; on Windows,
+  `scripts/get_ffmpeg.ps1` fetches a self-contained LGPL build and
+  `scripts/get_taglib.ps1` adds tag/cover support. Without FFmpeg the audio
+  module is skipped and everything else works.
+- **Windows**: `./scripts/build.ps1` imports the MSVC environment and builds
+  in place.
+
+## Usage
+
+```python
+import numpy as np
+import specux
+
+x = np.random.randn(8, 32768).astype(np.float32)
+
+# functional, any array library
+S = specux.stft(x, n_fft=1024, hop_length=256, output="power")
+y = specux.istft(specux.stft(x, 1024), 1024, length=x.shape[-1])
+C = specux.mfcc(x, sr=16000, n_mfcc=20)
+
+# configured twins: construct once, call with (..., time)
+t = specux.MelSpectrogram(sr=44100, n_fft=1024, n_mels=80)
+M = t(x)
+
+# pick a backend explicitly (default follows the input)
+S = specux.stft(x, n_fft=1024, backend="cpu")
+```
+
+```python
+import torch
+
+xt = torch.randn(8, 32768, device="cuda")
+
+# torch.compile and autocast
+f = torch.compile(lambda v: specux.stft(v, 1024, output="power"), fullgraph=True)
+with torch.autocast("cuda", torch.float16):
+    S = specux.stft(xt, 1024)          # computes in float32
+
+# reusable plan; tuning knobs live only here
+plan = specux.stft_plan(n_fft=1024, hop_length=256, output="power", device="cuda")
+plan = specux.autotune(xt, plan)       # optional, cached on disk
+S = plan(xt)
+```
+
+```python
+# audio: read, meter, transform, write
+y, sr = specux.audio.load("take.wav", sr=16000, mono=True)
+lufs = specux.audio.loudness(y, sr)
+y = specux.audio.normalize(y, mode="lufs", target_db=-14.0, sr=sr)
+specux.audio.save("out.flac", y, sr)
+
+for block in specux.audio.blocks("4hours.flac", 30 * sr, sr=sr, mono=True):
+    M = specux.melspectrogram(block, sr=sr)     # constant memory
+```
+
+## Design
+
+A transform is one fused kernel. The C++ codegen (`src/codegen/`) assembles
+each kernel from three parts:
+
+- a **prologue** that frames, reflect-pads, and windows the signal,
+- an FFT **core** picked by size and precision,
+- an **epilogue** that finishes the op in the same pass: the Hermitian
+  recombine, then the output mode (`complex` / `magnitude` / `power` / `db`),
+  a filterbank reduce for mel, a wavelet-basis reduce for the CQT family, or
+  the spectrum product for convolution.
+
+The spectrum never round-trips through memory between those stages: a dB mel
+spectrogram is one kernel, and features like MFCC or chroma are short chains
+of them. Every backward pass is the analytic adjoint of the same chain,
+generated the same way. Op, direction, and mode select the prologue and
+epilogue, precision is a type parameter, and size is a plan, so adding a
+size or mode never adds a hand-written kernel. Lengths past a GPU block's
+shared memory decompose into a two-kernel four-step pipeline, and large
+prime factors take a chirp-z (Bluestein) route through the same machinery.
+
+The same sources emit the CUDA and Metal dialects, and the CPU engine
+(`src/cpu/`) implements the same transforms and adjoints. `src/README.md`
+describes the native layout and layering rules.
+
+Tests cover correctness, autograd, `torch.compile`, autocast, and audio;
+every numerical tolerance lives in `tests/_tol.py` with its derivation.
+
+```bash
+python -m pytest tests        # correctness, autograd, compile, autocast, audio
+python bench/bench_matrix.py  # timing matrix on your own hardware
+```
+
+## License
+
+MIT. Vendored third-party components and their licenses are listed in
+[NOTICE](NOTICE).

specux-0.1.0.dev1/README.md

@@ -0,0 +1,172 @@
+# specux
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Differentiable audio DSP for Python: fast, fused kernels on GPU and CPU.
+
+Spectral transforms, an FFT family, and audio I/O, on numpy, torch, and cupy
+arrays alike.
+
+Documentation: <https://specux.com>
+
+```python
+import specux
+
+y, sr = specux.audio.load("song.flac", sr=16000, mono=True)
+M = specux.melspectrogram(y, sr=sr, n_fft=1024, n_mels=80)
+
+import torch
+x = torch.randn(8, 32768, device="cuda", requires_grad=True)
+S = specux.stft(x, n_fft=1024, output="power")   # stays on the GPU
+S.sum().backward()                                # native adjoint kernels
+```
+
+Arrays go in and come out in their own library: numpy in, numpy out; torch in,
+torch out (resident on its device, differentiable); cupy in, cupy out. The GPU
+kernels are generated in C++ and compiled at runtime (NVRTC for CUDA, MSL for
+Metal), so one build covers every size, precision, and output mode; the CPU
+backend carries the same transforms and adjoints, so training works without
+a GPU.
+
+## What's in the box
+
+- **Spectral transforms**: `stft` / `istft`, `melspectrogram`, `mfcc`, `lfcc`,
+  `cqt` / `vqt` / `chroma`, with output modes `complex` / `magnitude` /
+  `power` / `db` and configured class twins (`specux.STFT`, `specux.MFCC`,
+  ...). `specux.transforms` adds torch `nn.Module` wrappers with
+  torchaudio-shaped defaults.
+- **FFT family**: `fft` / `ifft` / `rfft` / `irfft` at any length (powers of
+  two, smooth sizes, primes) and precision (float32, float64, and float16
+  storage with float32 compute), plus reusable plans (`fft_plan`,
+  `stft_plan` with optional autotuning).
+- **Audio I/O** (`specux.audio`): decode and encode WAV/FLAC/MP3/OGG/MP4,
+  frame-accurate `offset`/`duration`, batch `load_many`/`save_many`,
+  streaming readers and writers for multi-hour files, resampling, loudness /
+  true-peak / loudness-range metering, and tags/cover metadata.
+- **torch integration**: every entry point is a `torch.library` custom op, so
+  `torch.compile(fullgraph=True)` traces without graph breaks and
+  `torch.autocast` computes in float32. torch stays optional: without it,
+  numpy arrays run on the CPU engine or the torch-free CUDA runtime.
+- **Runtime options**: `specux.deterministic(True)` switches overlap-adds to
+  bitwise-reproducible kernels (and follows
+  `torch.use_deterministic_algorithms`); `specux.benchmark(True)` autotunes
+  new configurations once and caches the result on disk.
+
+## Install
+
+```bash
+pip install specux              # CPU everywhere; CUDA/Metal where the wheel includes them
+pip install specux[cuda12]      # + NVRTC and CUDA headers from NVIDIA's pip wheels
+pip install specux[cuda13]      # the same for CUDA 13
+pip install specux[torch]       # torch bundles its own CUDA, nothing extra needed
+```
+
+Or from source, in the environment you plan to use it in:
+
+```bash
+pip install -e .
+```
+
+The build is torch-free (no libtorch anywhere), so one build serves numpy,
+cupy, and whichever torch is installed at runtime. Python >= 3.10,
+numpy >= 1.22; torch optional (>= 2.4 for autograd and `torch.compile`,
+>= 2.7 for resident Metal).
+
+- **CUDA**: builds when a toolkit is found (`SPECUX_CUDA_HOME` overrides);
+  running needs an NVIDIA driver plus NVRTC from a toolkit, torch, or the
+  `nvidia-*` pip wheels. Skipped with a notice otherwise.
+- **CPU**: always builds. `SPECUX_CPU_ONLY=1` forces a CPU-only build.
+- **macOS**: builds the CPU and Metal extensions out of the box (metal-cpp is
+  vendored).
+- **Audio I/O**: needs FFmpeg dev libraries; on Windows,
+  `scripts/get_ffmpeg.ps1` fetches a self-contained LGPL build and
+  `scripts/get_taglib.ps1` adds tag/cover support. Without FFmpeg the audio
+  module is skipped and everything else works.
+- **Windows**: `./scripts/build.ps1` imports the MSVC environment and builds
+  in place.
+
+## Usage
+
+```python
+import numpy as np
+import specux
+
+x = np.random.randn(8, 32768).astype(np.float32)
+
+# functional, any array library
+S = specux.stft(x, n_fft=1024, hop_length=256, output="power")
+y = specux.istft(specux.stft(x, 1024), 1024, length=x.shape[-1])
+C = specux.mfcc(x, sr=16000, n_mfcc=20)
+
+# configured twins: construct once, call with (..., time)
+t = specux.MelSpectrogram(sr=44100, n_fft=1024, n_mels=80)
+M = t(x)
+
+# pick a backend explicitly (default follows the input)
+S = specux.stft(x, n_fft=1024, backend="cpu")
+```
+
+```python
+import torch
+
+xt = torch.randn(8, 32768, device="cuda")
+
+# torch.compile and autocast
+f = torch.compile(lambda v: specux.stft(v, 1024, output="power"), fullgraph=True)
+with torch.autocast("cuda", torch.float16):
+    S = specux.stft(xt, 1024)          # computes in float32
+
+# reusable plan; tuning knobs live only here
+plan = specux.stft_plan(n_fft=1024, hop_length=256, output="power", device="cuda")
+plan = specux.autotune(xt, plan)       # optional, cached on disk
+S = plan(xt)
+```
+
+```python
+# audio: read, meter, transform, write
+y, sr = specux.audio.load("take.wav", sr=16000, mono=True)
+lufs = specux.audio.loudness(y, sr)
+y = specux.audio.normalize(y, mode="lufs", target_db=-14.0, sr=sr)
+specux.audio.save("out.flac", y, sr)
+
+for block in specux.audio.blocks("4hours.flac", 30 * sr, sr=sr, mono=True):
+    M = specux.melspectrogram(block, sr=sr)     # constant memory
+```
+
+## Design
+
+A transform is one fused kernel. The C++ codegen (`src/codegen/`) assembles
+each kernel from three parts:
+
+- a **prologue** that frames, reflect-pads, and windows the signal,
+- an FFT **core** picked by size and precision,
+- an **epilogue** that finishes the op in the same pass: the Hermitian
+  recombine, then the output mode (`complex` / `magnitude` / `power` / `db`),
+  a filterbank reduce for mel, a wavelet-basis reduce for the CQT family, or
+  the spectrum product for convolution.
+
+The spectrum never round-trips through memory between those stages: a dB mel
+spectrogram is one kernel, and features like MFCC or chroma are short chains
+of them. Every backward pass is the analytic adjoint of the same chain,
+generated the same way. Op, direction, and mode select the prologue and
+epilogue, precision is a type parameter, and size is a plan, so adding a
+size or mode never adds a hand-written kernel. Lengths past a GPU block's
+shared memory decompose into a two-kernel four-step pipeline, and large
+prime factors take a chirp-z (Bluestein) route through the same machinery.
+
+The same sources emit the CUDA and Metal dialects, and the CPU engine
+(`src/cpu/`) implements the same transforms and adjoints. `src/README.md`
+describes the native layout and layering rules.
+
+Tests cover correctness, autograd, `torch.compile`, autocast, and audio;
+every numerical tolerance lives in `tests/_tol.py` with its derivation.
+
+```bash
+python -m pytest tests        # correctness, autograd, compile, autocast, audio
+python bench/bench_matrix.py  # timing matrix on your own hardware
+```
+
+## License
+
+MIT. Vendored third-party components and their licenses are listed in
+[NOTICE](NOTICE).