Redesign as a complete STFT/ISTFT toolkit (0.4, breaking)

[sunsided]

Summary

Rebuilds ruststft from a single-file streaming STFT into a full short-time Fourier transform toolkit: forward and inverse transforms, a real window library, batch and streaming APIs, spectrum/decibel helpers, and optional mel spectrograms and MFCCs. The public API is now encapsulated behind builders instead of exposing struct internals.

Why now

The 0.3 API hard-codes two spectral bugs into its contract and exposes every field as pub, so neither could be fixed without breaking changes. This release takes the break deliberately, bumps to 0.4, and sets up a path to a stable 1.0.

Key changes

• FFT backend → realfft (real-input only): roughly 2x faster and half the memory of the previous full complex FFT on real data.
• Bug fixes baked into the old API: bin count is now fft_size/2 + 1 (the Nyquist bin was previously dropped), and bin frequencies are now k*fs/fft_size (previously off).
• Stft / StftBuilder: streaming (append/ready/process_into/step/columns) plus one-shot spectrogram() with centered framing (reflect/edge/zero padding) and optional rayon parallelism.
• Istft / IstftBuilder: weighted overlap-add inverse for perfect reconstruction; Stft::inverse() mirrors a forward transform.
• Window library: Window / WindowFunction / Symmetry covering 14 families in periodic and symmetric variants.
• mel feature: mel filterbank, mel scales and an orthonormal DCT-II for MFCCs with librosa-compatible defaults, no extra dependencies.
• Cross-cutting: Scaling and PadMode, spectrum helpers (magnitude/power/phase/dB), optional ndarray/serde, no_std (with alloc) for the non-FFT math, and #![forbid(unsafe_code)].
• Project hygiene: new CI (fmt, clippy, MSRV, no_std build, docs, cargo-deny, coverage), deny.toml, rustfmt.toml, CHANGELOG.md, dependabot; removed the dead Travis config; README rewritten with a 0.3 migration table.

Risks / notes

• Breaking: the old STFT type, WindowType, FromF64 and log10_positive are removed. Existing users must migrate; the README has a mapping table.
• no_std is partial: the FFT processors require the default std feature because the backend needs std. The window, spectrum and mel math build without it.
• librosa/scipy parity rests on periodic windows and Slaney area-normalized mel filters; these are the defaults and are locked by tests.

How to review

Start at src/lib.rs for the module map and feature gating. Read src/stft.rs (the forward transform and builder) then src/istft.rs (overlap-add inverse) - those two carry the core algorithm and the reconstruction math. Check src/batch.rs for centering/padding and the parallel frame path. Skim src/window/ and src/mel.rs as mostly self-contained math. tests/lib.rs and tests/proptests.rs show the intended usage and the correctness contracts (Nyquist bin, frequency mapping, round-trip reconstruction, linearity).

[Copilot]

Pull request overview

This PR redesigns ruststft into a broader STFT/ISTFT toolkit with builder-based APIs, real-FFT-backed processing, window/spectrum/mel helpers, no-std-compatible math modules, and expanded project automation.

Changes:

• Replaces the legacy STFT API with Stft, Istft, Spectrogram, builders, scaling, padding, and error types.
• Adds window generation, spectrum utilities, optional mel/MFCC support, examples, benches, and expanded tests.
• Updates package metadata, README, changelog, CI/dependabot/cargo-deny/task runner configuration, and removes Travis CI.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
Cargo.toml	Updates crate metadata, features, dependencies, lints, examples, and version.
src/lib.rs	Rebuilds crate root, feature gates, docs, and public re-exports.
src/config.rs	Adds Scaling and PadMode configuration enums.
src/error.rs	Adds StftError and display/error implementations.
src/sample.rs	Adds shared sample trait abstraction and casting helper.
src/spectrum.rs	Adds magnitude, power, phase, and dB conversion helpers.
src/stft.rs	Adds forward STFT builder and streaming processor.
src/batch.rs	Adds one-shot spectrogram generation and Spectrogram container.
src/istft.rs	Adds inverse STFT builder, WOLA reconstruction, and Stft::inverse.
src/mel.rs	Adds mel scale/filterbank and DCT-II support behind the mel feature.
src/window/mod.rs	Adds typed window API and window family definitions.
src/window/functions.rs	Adds raw f64 window coefficient generators.
tests/lib.rs	Rewrites integration tests for the new public API.
tests/proptests.rs	Adds property tests for STFT linearity and round-trip reconstruction.
examples/spectrogram.rs	Adds spectrogram/chirp example.
examples/roundtrip.rs	Adds STFT→ISTFT reconstruction example.
examples/mfcc.rs	Adds mel/MFCC example.
benches/lib.rs	Rewrites Criterion benchmarks for the new API.
README.md	Rewrites user-facing documentation and migration guide.
CHANGELOG.md	Adds 0.4.0 changelog entry.
Taskfile.dist.yaml	Adds common development, test, build, docs, and CI tasks.
rustfmt.toml	Adds rustfmt edition configuration.
deny.toml	Adds cargo-deny policy configuration.
.github/workflows/ci.yml	Adds expanded GitHub Actions CI workflow.
.github/dependabot.yml	Adds Dependabot configuration.
.travis.yml	Removes obsolete Travis CI configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.