# Project health review

[中文](../zh/HEALTH.md)

## Assessment

The project has a useful research implementation and a now-verified core pipeline, rather than broad external numerical certification. The initial source checkout had 105 passing tests on WASM and JS, but short-window alignment, arbitrary complex FFTs, streaming windows/hops and error envelopes were not covered. Five failing regressions were reproduced; the arbitrary complex path could hang, and was interrupted before repair. The default Windows MSVC installation could not compile because its configured headers were missing. That environmental failure is distinct from a source defect.

Current evidence includes four-target tests, a reproducible one-second example, 31 source/runtime packages plus the example package, dependency direction checks, fresh generated browser bindings, scoped eight-case external numerical validation and browser flow verification. CI configuration now covers compiler minimum, check, build, tests, example and demo; remote completion must be checked on GitHub, not inferred from this document.

## Package review coverage

| Area | Files/behavior examined | Improvement or explicit boundary |
| --- | --- | --- |
| core/types | All audio/config/error/matrix/complex contracts | Split by responsibility; finite config/PCM and reusable matrix validation; public raw matrices keep indexing preconditions |
| dsp/window | All window and reflect helpers | Retained tested O(1) reflect indexing; documented reflect vs default librosa padding |
| dsp/framing + stft | Preparation, short/full/odd windows, STFT/ISTFT | Shared centered window offsets; exact arbitrary FFT grid; odd Hermitian reconstruction; full-frame synthesis; reusable FFT buffers |
| dsp/fft | Radix-2, padding, Bluestein, dispatch | Checked dispatcher, unsafe raw-kernel guard; radix-2 APIs retain their original size contract |
| dsp/filter | Pre/de-emphasis and in-place variant | Retained tested recurrences; no cosmetic rewrite |
| dsp/resample | Linear, sinc, polyphase, length conversion | Correct fractional-phase direction and source-grid anti-alias cutoff; reject nonpositive filters; no SciPy-default-filter equivalence claim |
| codec/wav | Headers, chunks, layout, samples | Bounded arithmetic before access; reject hostile lengths/missing formats/incomplete PCM; duplicate policy explicit |
| mel + mfcc | Scale/filterbank/projection/log/DCT | Reusable matrix stages, sparse zero-weight skip, cached per-matrix DCT basis; preserve eight-case external evidence |
| energy + spectral | Frame sums/RMS, centroid/rolloff/flatness/ZCR | Reuse energy for RMS; avoid single-sample ZCR divide-by-zero; configurable spectral-power conventions explicit |
| streaming + multichannel | Buffer consumption, outputs, per-channel/ILD/IPD paths | Shared framing/FFT, gap cursor and config-respecting MFCC; streaming allocation/batch clipping limits explicit; validate channel lengths and metadata/config rates, use power for ILD regardless of display power; external spatial reference validation remains limited |
| delta + chroma + cqt | Derivatives, projection/normalization, direct kernels | Ragged-shape checks, invalid dimension guards, CQT Nyquist validation; direct/HTK conventions stated rather than inventing librosa parity |
| hpss + contrast | Median masks/margins, band quantiles | Margin suppression and residual fixed; contrast dB and linear-difference units fixed; median/quantile conventions are not a whole-library parity claim |
| onset + tempo | Flux, SuperFlux, peaks, lag scoring | Silence/empty envelopes yield no detected tempo; onset is a local-threshold implementation, not independently proven equivalent to librosa |
| lpc + pitch + formant | Recurrences, YIN differences, root solving | Guard negative/invalid parameters; correct predictor-to-polynomial sign; known all-pole formant frequency/bandwidth regression |
| loudness + effects | K-weighting, gates, oversampling, phase/length paths | Relative LRA gate, invalid rate/step guards, phase-vocoder phase ordering and tail interpolation; effect/true-peak compliance still needs broader reference signals |
| pipeline + facade + bindings | Every exposed adapter and transport | Separate orchestration/ergonomics/JSON; one shared STFT; truthful failure envelopes; generated compiler interfaces |
| cmd + tools + playground | Examples, reference generation, build sync, all UI modules | Runnable minimal example; full-matrix checks vs old spot values; worker, AudioWorklet, decoded-audio reuse, stale-load protection, actual report rendering |

## Correctness changes that callers should notice

Short windows now analyze the center of the complete FFT frame. Arbitrary STFT sizes preserve their actual bin spacing. Formants use the denominator of the positive predictor coefficients. Spectral contrast's logarithmic result is dB and its linear result is peak-minus-valley. Larger HPSS margins suppress components and can leave residuals. Silence has no detected BPM. ILD remains a power ratio even with magnitude display configuration; malformed or rate-mismatched channel metadata returns errors. The phase vocoder advances phase after emitting each synthesis step and interpolates its tail toward zero. Streaming honors configuration and preserves large-hop gaps. Polyphase fractional phases no longer interpolate toward the wrong side.

These fix incorrect results and therefore can change numeric output. They are covered by dedicated regressions; preserving the old incorrect values is not a compatibility objective.

## Remaining limits

The eight-case comparison checks the core numerical pipeline only. Advanced algorithms need broader reference datasets and perceptual/compliance checks before production or standards claims. Direct CQT and YIN are computationally heavier than FFT-only core features. Raw constructors/arrays and low-level numerical helpers have preconditions; checked high-level boundaries do not imply every raw helper handles arbitrary malformed state. Streaming allocates and clips dB per emitted matrix. The browser microphone is a rolling offline preview. Mooncakes publication is deferred; GitHub write access and remote CI results are external acceptance state, not numerical health.

No comparable-device competitor benchmark has been run. Current-browser timing includes feature computation, JSON serialization/parsing and worker-side preparation; it excludes startup and transfer/render time.