This release is a pre-release and may not be stable for production use.
specux
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
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 modescomplex/magnitude/power/dband configured class twins (specux.STFT,specux.MFCC, ...).specux.transformsadds torchnn.Modulewrappers with torchaudio-shaped defaults. - FFT family:
fft/ifft/rfft/irfftat any length (powers of two, smooth sizes, primes) and precision (float32, float64, and float16 storage with float32 compute), plus reusable plans (fft_plan,stft_planwith optional autotuning). - Audio I/O (
specux.audio): decode and encode WAV/FLAC/MP3/OGG/MP4, frame-accurateoffset/duration, batchload_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.librarycustom op, sotorch.compile(fullgraph=True)traces without graph breaks andtorch.autocastcomputes 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 followstorch.use_deterministic_algorithms);specux.benchmark(True)autotunes new configurations once and caches the result on disk.
Install
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:
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_HOMEoverrides); running needs an NVIDIA driver plus NVRTC from a toolkit, torch, or thenvidia-*pip wheels. Skipped with a notice otherwise. - CPU: always builds.
SPECUX_CPU_ONLY=1forces 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.ps1fetches a self-contained LGPL build andscripts/get_taglib.ps1adds tag/cover support. Without FFmpeg the audio module is skipped and everything else works. - Windows:
./scripts/build.ps1imports the MSVC environment and builds in place.
Usage
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")
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)
# 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.
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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file specux-0.1.0.dev1.tar.gz.
File metadata
- Download URL: specux-0.1.0.dev1.tar.gz
- Upload date:
- Size: 837.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4375df25a97e13ecd6b400b5e784ad4be0c27f6f0e3f694c655a5478ee590106
|
|
| MD5 |
700cfa25d4bce87c1d62ac4667219530
|
|
| BLAKE2b-256 |
88ca7689fcdfd8b0d480057b45e5cceb413780ac4fed8de8035715f1c1c3ba58
|
File details
Details for the file specux-0.1.0.dev1-cp313-cp313-win_amd64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp313-cp313-win_amd64.whl
- Upload date:
- Size: 42.7 MB
- Tags: CPython 3.13, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a5f460129792c1dc82f9c4276325d7788434eeb4056b71b1bb6ca43c50f6700d
|
|
| MD5 |
afc956781809accaeaf4e45efcba12a0
|
|
| BLAKE2b-256 |
eedf3ad6bc2286964d928a31ce8ccbdac2842e34e2f41dbb305c5f3971bb6cb3
|
File details
Details for the file specux-0.1.0.dev1-cp313-cp313-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp313-cp313-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 34.6 MB
- Tags: CPython 3.13, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f374e744a1f3e3d1f230ec4f9974d960ad694e6881be075ce3f6a1151638ef12
|
|
| MD5 |
ecf536368e817958e89dc1215cd8dafb
|
|
| BLAKE2b-256 |
2061c28d1f37b8f628bfca878cfc30058204ce90f5dacbe83c271d533f48a5a1
|
File details
Details for the file specux-0.1.0.dev1-cp313-cp313-macosx_11_0_arm64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp313-cp313-macosx_11_0_arm64.whl
- Upload date:
- Size: 3.7 MB
- Tags: CPython 3.13, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9b314d1de4cf329a3ba281bc46bb3b1a32eadb3aa9089e51e3c27296e9b0a530
|
|
| MD5 |
696816e3d9edbef9721f24c2b7216f40
|
|
| BLAKE2b-256 |
80954b44fa768cc232c2a0ae11d56058f26543dd9b78dcf97d67b1f31fb6f8c8
|
File details
Details for the file specux-0.1.0.dev1-cp312-cp312-win_amd64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp312-cp312-win_amd64.whl
- Upload date:
- Size: 42.7 MB
- Tags: CPython 3.12, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c6915611daea31d6d1c861fcc8047ab43cdc019666f46f5e6689df71cf77078b
|
|
| MD5 |
3952245c4bc51d9971062dcfbc9d1c4a
|
|
| BLAKE2b-256 |
e7caea5293497e3dea451cadacd58109d5da80a04326740849bf5bb6b9541711
|
File details
Details for the file specux-0.1.0.dev1-cp312-cp312-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp312-cp312-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 34.5 MB
- Tags: CPython 3.12, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1b9012a3cd6bddbcecc33a596b788d83e752bc5d862e78029acc8f72d0db7caa
|
|
| MD5 |
21d2edb91b685583158879c4fdf0aa76
|
|
| BLAKE2b-256 |
2a0516f55887f4b24e5634b72a8ec80dd045cb19995846f5f26c841e78fbbc2b
|
File details
Details for the file specux-0.1.0.dev1-cp312-cp312-macosx_11_0_arm64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp312-cp312-macosx_11_0_arm64.whl
- Upload date:
- Size: 3.7 MB
- Tags: CPython 3.12, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d55de2ec7e03e6cf390bf4fc9c1a8b03878d00cee944b479bf547a615215bd87
|
|
| MD5 |
88297bc471f34204b5c4437c4b82638b
|
|
| BLAKE2b-256 |
813b7209c998e00d267ce9f5a22b2592463ecd2ec1553164d1de9bc463c70a14
|
File details
Details for the file specux-0.1.0.dev1-cp311-cp311-win_amd64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 42.7 MB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6df0254fedb41becba2fc086d7c680d428d75f53f9b5085c8d55b8f94215c047
|
|
| MD5 |
626a40935a9187d06d3236804399413f
|
|
| BLAKE2b-256 |
a441c2c5c78defa8b10e850c86d81ddb3f4d6517790e68cf15cfea79366c7eaf
|
File details
Details for the file specux-0.1.0.dev1-cp311-cp311-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp311-cp311-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 34.4 MB
- Tags: CPython 3.11, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
10130211b105887fc614c3ebc7ca6ac13a41bbc4e95ac75c7c6f7d4db7acd99a
|
|
| MD5 |
725a2179a547d1edfd0d47dc053c83a7
|
|
| BLAKE2b-256 |
b989bb16b01bf382099d3dd7f8ccfcf774c811bc60c8679a91348e5f61e82594
|
File details
Details for the file specux-0.1.0.dev1-cp311-cp311-macosx_11_0_arm64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp311-cp311-macosx_11_0_arm64.whl
- Upload date:
- Size: 3.7 MB
- Tags: CPython 3.11, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6ccee7e0ba3dacf12ed6406baaeb1844cafe72d6dadce2dfbc2226bd008d5e7d
|
|
| MD5 |
bb247563fdcd0d5280ae55bcfedd6807
|
|
| BLAKE2b-256 |
e540b650a8010e0f36652f9d2ff067f5b276bd0e0b35df02a0fbe69efac9295c
|
File details
Details for the file specux-0.1.0.dev1-cp310-cp310-win_amd64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp310-cp310-win_amd64.whl
- Upload date:
- Size: 42.7 MB
- Tags: CPython 3.10, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
399c00586aa7ed38aab5cb8125f3629bd6101614d89f48c9abe5d0692ac87fc7
|
|
| MD5 |
fce03eeb1e675813d79bb618c5fc6068
|
|
| BLAKE2b-256 |
8566e0417eeccb22244f9fbb811f340364f7ae9cfa2dfa5f37d12e7d7be1fb00
|
File details
Details for the file specux-0.1.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 34.2 MB
- Tags: CPython 3.10, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d14429c87aad0be6206f998c89660a26cfa0316bc3600c43b1060d918d05138d
|
|
| MD5 |
e71ce9b366cd4fea35c99694042aef16
|
|
| BLAKE2b-256 |
24be4dd88577aee89869413c9a316b9ed4e9f10ff611aaf3183a96e925fe66a3
|
File details
Details for the file specux-0.1.0.dev1-cp310-cp310-macosx_11_0_arm64.whl.
File metadata
- Download URL: specux-0.1.0.dev1-cp310-cp310-macosx_11_0_arm64.whl
- Upload date:
- Size: 3.7 MB
- Tags: CPython 3.10, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
46762c174373a5de7573363c36be612b5381a63a73965169c7c3a53cb269cb77
|
|
| MD5 |
f5d651c713e597c0bbc6b3a7050d6500
|
|
| BLAKE2b-256 |
1a295d3c393e9095706501fee8d5713dd30922e4af6d65afa2afecaf6eb30253
|