63 lines
4.2 KiB
Markdown
63 lines
4.2 KiB
Markdown
# @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.
|
||
|