feat: initial clawaudio v1 -- STFT spectral encoder + WAV/FLAC/OGG decode

New sibling repo unblocking omni-cortex's two long-standing audio gaps
(README.md:570 there): "the production FFT-based encoder" and "the
format-decoding front end for arbitrary audio files".

Three crates, clawsync-style workspace conventions:

- clawaudio-dsp: pure spectral-analysis primitives (Hann window, STFT
  via rustfft, triangular mel filterbank, log-mel spectrogram). No I/O,
  no file formats, decoupled from any caller's types -- operates on
  &[f32] mono PCM + a sample rate. SpectrogramComputer::compute_aggregate
  is zero-alloc after construction (reused FFT/power scratch buffers),
  mirroring the hot-path contract omni-cortex's encoder traits require.

- clawaudio-decode: WAV (hound) / FLAC (claxon) / OGG-Vorbis (lewton)
  decode to interleaved f32 PCM, plus fixed-target-rate resampling
  (rubato). All pure Rust, no C bindings. Deliberately NOT symphonia --
  its MPL-2.0 license fails permissive-license-only allow-lists (e.g.
  omni-cortex's cargo-deny config already only allows MIT/Apache-2.0/
  BSD/etc). MP3 deferred -- no sufficiently mature pure-Rust decoder was
  vetted for this pass.

- clawaudio: facade re-exporting both, plus SpectrogramEncoder<const
  DIM: usize> -- the const-generic drop-in type a consumer's own
  encoder trait wraps. Final f32->fixed-point quantization is left to
  the caller, since that's a consumer-specific convention, not
  something a project-agnostic DSP library should own.

Verified end-to-end (56 tests, all passing, cargo fmt/clippy -D warnings
clean workspace-wide): decode -> resample -> spectrogram for real
ffmpeg-generated WAV/FLAC/OGG fixtures (tiny synthesized sine tones,
checked in as tests/fixtures/*, not real/copyrighted audio), plus the
correctness properties omni-cortex's existing GoertzelMelEncoder test
suite already established (distinct tones dissimilar, tone peaks in the
right mel band, silence near floor, deterministic). compute_aggregate
benchmarks at ~88us for a 500ms/16kHz/16-mel chunk on real hardware --
comfortably real-time.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

This commit is contained in:

Omar Sobh

2026-08-10 11:49:48 -07:00

co-authored by

Claude Sonnet 5

commit 1b76852ec7

29 changed files with 2482 additions and 0 deletions

crates/clawaudio-decode/tests/fixtures/tone_1000hz.flac

Vendored

BIN

View File

Binary file not shown.