API index

Every public name in specux 0.1.0, linked to its page.

Audio I/O

name	summary
`load(path, sr, offset, duration, mono, dtype, quality, backend, threads, mmap, track, strict)`	Decode `path` to a numpy array; returns (samples, samplerate)
`load_many(paths, workers, on_error, kwargs)`	Load several files in parallel; returns a list of `(samples, samplerate)`
`info(path, track)`	Return (frames, samplerate, channels, format, tracks) for one audio track
`save(path, y, sr, subtype, bitrate, compression_level)`	Write audio `y` (sample rate `sr`) to `path`; the format is chosen from the
`save_many(items, workers, on_error, kwargs)`	Save several `(path, y, sr)` items in parallel. `kwargs` are passed to
`save_bytes(y, sr, format, subtype, bitrate, compression_level)`	Encode `y` to an in-memory container and return the bytes; the mirror
`codec_roundtrip(y, sr, format, bitrate, compression_level)`	Encode+decode `y` through a lossy codec entirely in memory and return an
`audio.StreamReader`	Stateful streaming reader: open a file ONCE and pull it forward in blocks
`audio.StreamWriter`	Stateful streaming writer: open an output file ONCE and append blocks -
`blocks(path, block_frames, hop, mono, sr, quality, track)`	Stream `path` in blocks of `block_frames` output samples, yielding
`resample(y, orig_sr, target_sr, quality)`	Resample `y` from `orig_sr` to `target_sr` with the vendored soxr
`to_mono(y)`	Downmix `y` (channels, frames) to a single (frames,) channel by averaging
`to_stereo(y)`	Return a (2, frames) array. Stereo passes through; mono (or (1, frames)) is
`level(y)`	Peak and RMS of `y` as a Level (linear; .peak_db/.rms_db for dBFS)
`loudness(y, sr)`	Integrated loudness of `y` in LUFS per ITU-R BS.1770-4 / EBU R128:
`loudness_range(y, sr)`	Loudness range (LRA) of `y` in LU per EBU Tech 3342: the 10th..95th
`true_peak(y, sr)`	True peak of `y` in dBTP per ITU-R BS.1770-4 Annex 2: the sample peak
`normalize(y, mode, target_db, sr)`	Return `y` scaled so its peak (or RMS) hits `target_db` dBFS
`tags(path)`	All metadata tags of `path` (a path or bytes-like) as a {key: value}
`write_tags(path, tags)`	Merge `tags` into the file’s metadata and save, in place
`write_tags_bytes(data, tags)`	Bytes-in, bytes-out write_tags: return `data` (an in-memory audio file)
`cover(path)`	The embedded cover art of `path` (a path or bytes-like) as a
`write_cover(path, image, mime, description)`	Set (or remove, with image=None) the embedded front cover and save
`write_cover_bytes(data, image, mime, description)`	Bytes-in, bytes-out write_cover: return `data` (an in-memory audio file)
`audio.Info`
`audio.Level`	Peak and RMS of a signal (linear, from one fused measurement pass)
`audio.Cover`	Embedded cover art: raw image bytes + mime type (+ optional description)
`audio.Quality`
`audio.Subtype`
`audio.QUALITY`

FFT

name	summary
`fft(x, backend, out)`	Full FFT: (…, n) real or complex -> (…, n) complex
`ifft(X, backend, out)`	Inverse FFT: (…, n) complex -> (…, n) complex, scaled by 1/n
`rfft(x, backend, out)`	Onesided FFT of real input: (…, n) -> (…, n // 2 + 1) complex
`irfft(X, n, backend, out)`	Inverse of `rfft`: (…, n // 2 + 1) complex -> (…, n) real
`fftconvolve(a, b, mode, backend)`	Convolve two signals along the last axis via the FFT
`fft_plan(n, real, backend)`	Build a reusable `FFTPlan` for length-`n` transforms
`FFTPlan`	A reusable FFT configuration bound to a length and backend, so repeated
`FFT`	Configured full complex FFT (`specux.fft` as an object)
`IFFT`	Configured inverse FFT (`specux.ifft` as an object), scaled by 1/n
`RFFT`	Configured onesided FFT of real input (`specux.rfft` as an object)
`IRFFT`	Configured inverse of `RFFT` (`specux.irfft` as an object)
`FFTConvolve`	Configured FFT convolution (`specux.fftconvolve`): holds the mode,

Spectral analysis

name	summary
`stft(x, plan, n_fft, hop_length, win_length, window, center, output, eps, backend)`	Short-Time Fourier Transform
`istft(Z, n_fft, hop_length, win_length, window, center, length, backend)`	Inverse Short-Time Fourier Transform
`melspectrogram(x, sr, n_fft, hop_length, win_length, window, center, n_mels, fmin, fmax, mel_scale, norm, power, output, eps, backend)`	Mel spectrogram: “mel_filterbank @
`cqt(x, sr, hop_length, fmin, n_bins, bins_per_octave, filter_scale, sparsity, tuning, output, eps, backend)`	Constant-Q transform: `specux.vqt` at `gamma=0`
`vqt(x, sr, hop_length, fmin, n_bins, bins_per_octave, gamma, filter_scale, sparsity, tuning, output, eps, backend)`	Variable-Q transform via recursive octave decimation
`chroma(x, sr, hop_length, n_chroma, bins_per_octave, n_octaves, fmin, tuning, backend)`	Chromagram: CQT magnitudes folded onto pitch classes
`mfcc(x, sr, n_mfcc, n_fft, hop_length, win_length, window, center, n_mels, fmin, fmax, mel_scale, norm, lifter, top_db, eps, backend)`	Mel-frequency cepstral coefficients: DCT-II of the dB mel spectrogram
`lfcc(x, sr, n_lfcc, n_filter, n_fft, hop_length, win_length, window, center, fmin, fmax, lifter, top_db, eps, backend)`	Linear-frequency cepstral coefficients: DCT-II of the dB spectrogram

Configured transforms

name	summary
`STFT`	Configured Short-Time Fourier Transform
`ISTFT`	Configured inverse Short-Time Fourier Transform
`MelSpectrogram`	Configured mel spectrogram: “mel_filterbank @
`CQT`	Configured Constant-Q transform: `specux.VQT` pinned at `gamma=0`
`VQT`	Configured Variable-Q transform
`Chroma`	Configured chromagram: CQT magnitudes folded onto pitch classes
`MFCC`	Configured mel-frequency cepstral coefficients (`specux.mfcc`)
`LFCC`	Configured linear-frequency cepstral coefficients (`specux.lfcc`)
`Transform`	Base of the configured transform classes
`transforms`	specux transforms: torch nn.Module wrappers over the functional API

Plans & tuning

name	summary
`stft_plan(n_fft, hop_length, win_length, window, center, output, out_dtype, eps, dtype, device, ept, fpb, tpf, core, tune)`	Build a reusable, tunable STFT plan for the CUDA backend
`autotune(x, plan, iters, warmup)`	Autotune a plan on a sample input
`STFTPlan`	A compiled, reusable STFT configuration bound to a CUDA device

Runtime options

name	summary
`deterministic`
`benchmark`
`set_deterministic(flag)`	Deterministic overlap-add for istft and the training backwards: per-frame
`set_benchmark(on)`	Enable lazy autotune-and-cache on first use
`set_num_threads(n)`	CPU backend thread count (0 = auto, resolving to the physical cores)
`get_num_threads()`	Configured CPU backend thread count (0 = auto)
`clear_cache()`	Drop cached plans, filterbanks, twiddle tables, and idle CPU/GPU pool

Helpers

name	summary
`mel_filterbank`
`hz_to_mel`
`mel_to_hz`