# @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.