first commit

docs/media/audio/audio-analysis-spectrum/README.md

@@ -0,0 +1,62 @@
+# @suaveplan/audio-analysis-spectrum - Universal spectral analysis: real FFT, Hann/Hamming/Blackman windows, mel filterbank, DCT-II, SpectrumAnalyzer/Spectrogram/MFCC analysis ops with OTel instrumentation. Zero browser or Node dependencies.
+
+Universal spectral analysis for the Suaveplan audio stack: real FFT, Hann/Hamming/Blackman windows, mel filterbank, DCT-II, and three high-level analyzers — `SpectrumAnalyzer`, `Spectrogram`, `MFCC`. Zero browser or Node-only dependencies.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [dct](./src/algorithms/dct.md) — The DCT-II module is the cepstral projection step of the MFCC pipeline: it takes the log mel-spectrum of one frame and…
+- [fft](./src/algorithms/fft.md) — The FFT module is the numerical core every analyzer in this package depends on. It runs an in-place Cooley–Tukey radix-…
+- [mel-scale](./src/algorithms/mel-scale.md) — The mel-scale module provides the perceptual frequency warp used by MFCC and any caller that wants a psychoacoustically…
+- [window](./src/algorithms/window.md) — Window functions taper the endpoints of each analysis frame so the FFT sees a periodic-looking signal rather than the a…
+- [dsp](./src/analyzer/dsp.md) — The dsp module is the per-frame DSP toolbox every analyzer in this package leans on. It owns the document→mono read pat…
+- [mfcc](./src/analyzer/mfcc.md) — `MFCC` is the speech/music feature extractor of this package: per frame it builds the magnitude spectrum, applies a tri…
+- [runtime](./src/analyzer/runtime.md) — The runtime module is the shared spine for `SpectrumAnalyzer`, `Spectrogram`, and `MFCC`. It owns option parsing throug…
+- [spectrogram](./src/analyzer/spectrogram.md) — `Spectrogram` produces the ordered list of per-frame magnitude spectra for a document, slicing by the same `frameSize`/…
+- [spectrum-analyzer](./src/analyzer/spectrum-analyzer.md) — `SpectrumAnalyzer` is the workhorse analysis op of this package: it slices an `AudioDocument` into overlapping frames,…
+- [error-codes](./src/error-codes/error-codes.md) — The error-codes module owns the stable `AUDIO_ANALYSIS_SPECTRUM.*` code registry used by every analyzer in this package…
+  - [error-codes](./src/error-codes/error-codes.md) — The error-codes module owns the stable `AUDIO_ANALYSIS_SPECTRUM.*` code registry used by every analyzer in this package…
+<!-- end:auto-docs -->
+
+## What's in the box
+
+- **Algorithms** (`./algorithms/*`)
+  - `fft` — Cooley–Tukey radix-2 real-input FFT for every power of two in `[256, 32768]`.
+  - `window` — Hann, Hamming, Blackman windows with per-`(name, size)` caching.
+  - `mel-scale` — Slaney/HTK hz↔mel mapping plus a cached triangular filterbank.
+  - `dct` — type-II DCT with cached kernel matrix.
+- **Analyzers** (`./analyzer/*`)
+  - `SpectrumAnalyzer` — magnitude spectrum + centroid/rolloff/flux, `analyze` / `analyzeStream` / `analyzeBlock`.
+  - `Spectrogram` — time-frequency magnitude matrix, `analyze` / `analyzeStream`.
+  - `MFCC` — 13-coefficient mel-frequency cepstral coefficients per frame.
+- **Error codes** (`./error-codes`) — `AUDIO_ANALYSIS_SPECTRUM.{INVALID_OPTIONS, INVALID_FRAME, ABORTED}` via `defineCodes`.
+- **OTel instrumentation** — `audio.analysis.runs_total`, `audio.analysis.duration_ms`, `audio.analysis.block_duration_ms` counters/histograms; a span per `analyze`/`analyzeStream` invocation. Inert without an exporter.
+
+## Quick start
+
+```ts
+import { SpectrumAnalyzer } from "@suaveplan/audio-analysis-spectrum";
+import { AudioDocument } from "@suaveplan/audio-core/document/document";
+
+const analyzer = new SpectrumAnalyzer();
+const result = await analyzer.analyze(doc, {
+  bins: 128,
+  frameSize: 2048,
+  hopSize: 512,
+  window: "hann",
+});
+
+console.log(result.centroid, result.rolloff, result.flux);
+```
+
+## Universal guarantees
+
+- Imports zero browser globals (`window`, `document`, `AudioContext`, `AnalyserNode`).
+- Imports zero Node-only modules (`node:fs`, `node:path`, `process`, `Buffer`).
+- Runtime deps: `@suaveplan/audio-core`, `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`.
+- Each analyzer is sidecar — analysis never mutates the source `AudioDocument`.
+
+## Status
+
+`0.1.0`. Pre-publish gate (lint + typecheck + test) and 100% coverage are required on every change.
+