skills/plugins/document-navigator/docs/media/audio/audio-analysis-spectrum

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

Documentation tree

• dct — The DCT-II module is the cepstral projection step of the MFCC pipeline: it takes the log mel-spectrum of one frame and…
• fft — The FFT module is the numerical core every analyzer in this package depends on. It runs an in-place Cooley–Tukey radix-…
• mel-scale — The mel-scale module provides the perceptual frequency warp used by MFCC and any caller that wants a psychoacoustically…
• window — Window functions taper the endpoints of each analysis frame so the FFT sees a periodic-looking signal rather than the a…
• dsp — The dsp module is the per-frame DSP toolbox every analyzer in this package leans on. It owns the document→mono read pat…
• mfcc — MFCC is the speech/music feature extractor of this package: per frame it builds the magnitude spectrum, applies a tri…
• runtime — The runtime module is the shared spine for SpectrumAnalyzer, Spectrogram, and MFCC. It owns option parsing throug…
• spectrogram — Spectrogram produces the ordered list of per-frame magnitude spectra for a document, slicing by the same frameSize/…
• spectrum-analyzer — SpectrumAnalyzer is the workhorse analysis op of this package: it slices an AudioDocument into overlapping frames,…
• error-codes — The error-codes module owns the stable AUDIO_ANALYSIS_SPECTRUM.* code registry used by every analyzer in this package…
  • error-codes — The error-codes module owns the stable AUDIO_ANALYSIS_SPECTRUM.* code registry used by every analyzer in this package…

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

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.