Initial Commit

packages/media/audio/audio-analysis-spectrum/src/algorithms/window.md

@@ -0,0 +1,56 @@
+# `window` — discrete window functions
+
+## Purpose
+
+Window functions taper the endpoints of each analysis frame so the FFT sees a periodic-looking signal rather than the abrupt discontinuities created by a rectangular slice. Tapering reduces spectral leakage at the cost of a small main-lobe widening, which is the standard trade-off used by every spectral analyzer in this package.
+
+The module exposes three closed-form windows — Hann, Hamming, and Blackman — selectable by the `window` option of `SpectrumAnalyzerOptions`. Vectors are cached per `(name, size)` so the spectrum, spectrogram, and MFCC analyzers share a single allocation across every frame of the same shape.
+
+## Features
+
+- Hann, Hamming, Blackman generators producing `Float32Array` vectors.
+- Cached per `(name, size)` to avoid re-allocation on every frame.
+- `applyWindow` for in-place multiplication into a caller-provided buffer.
+- `clearWindowCache` for benchmarks measuring cold-start cost.
+
+## Usage: Basic
+
+```ts
+import {
+  applyWindow,
+  getWindow,
+} from "@suaveplan/audio-analysis-spectrum/algorithms/window";
+
+const w = getWindow("hann", 2048);
+const frame = new Float32Array(2048);
+const out = new Float32Array(2048);
+applyWindow(frame, w, out);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+  clearWindowCache,
+  getWindow,
+} from "@suaveplan/audio-analysis-spectrum/algorithms/window";
+
+// Pre-warm the cache for the working set.
+for (const name of ["hann", "hamming", "blackman"] as const) {
+  for (const size of [1024, 2048, 4096]) getWindow(name, size);
+}
+
+// Later, before a benchmark, evict every vector.
+clearWindowCache();
+```
+
+## API Reference
+
+- `getWindow(name, size): Float32Array` — cached window vector.
+- `applyWindow(frame, window, out): void` — element-wise multiply.
+- `clearWindowCache(): void` — drop every cached vector.
+- `WindowName = "hann" | "hamming" | "blackman"`.
+
+## Implementation Notes
+
+Each closed form is the standard periodic definition with `N - 1` in the denominator, so the endpoints of Hann and Blackman are exact zeros and the centre is exactly `1`. Hamming uses the `(0.54, 0.46)` coefficients from Hamming's 1989 paper. The cache key is `${name}:${size}`; since both inputs are tightly constrained by the analyzer layer the key set is small.