first commit

docs/media/audio/audio-analysis-loudness/src/algorithms/lufs.md

@@ -0,0 +1,57 @@
+# lufs
+
+## Purpose
+
+`lufs` contains the kernel of BS.1770-4 loudness measurement: the per-block
+mean-square energy calculation, the BS.1770 channel-weighted summation, the
+energy-to-LUFS conversion, and the streaming `IntegratedLoudness` accumulator
+that implements the two-gate algorithm (absolute gate at −70 LUFS, then a
+relative gate 10 LU below the ungated mean of survivors). The kernels are
+document-agnostic — they consume `Float32Array[]` blocks and numbers — so a
+true-peak limiter can pull `momentaryLufs` without instantiating a meter.
+
+## Features
+
+- Pure functions: `blockMeanSquare`, `combineChannelEnergies`,
+  `energyToLufs`, `momentaryLufs`, `shortTermLufs`.
+- Streaming `IntegratedLoudness` class with two-gate integration.
+- BS.1770 channel weights — L/R/C at 1.0, surround at 1.41, LFE excluded.
+- Finite silence floor (`LUFS_SILENCE_FLOOR = -100`) instead of `-Infinity`.
+
+## Usage: Basic
+
+```ts
+import { momentaryLufs } from "@suaveplan/audio-analysis-loudness/algorithms/lufs";
+
+const lufs = momentaryLufs(kWeightedBlock);
+```
+
+## Usage: Advanced
+
+```ts
+import { IntegratedLoudness } from "@suaveplan/audio-analysis-loudness/algorithms/lufs";
+
+const integrator = new IntegratedLoudness(2);
+for (const block of kWeightedGatingBlocks) integrator.pushBlock(block);
+const integrated = integrator.integrated();
+console.log({ integrated, surviving: integrator.gatedBlockCount });
+```
+
+## API Reference
+
+- `LUFS_SILENCE_FLOOR`, `ABSOLUTE_GATE_LUFS`, `RELATIVE_GATE_OFFSET_LU`,
+  `CHANNEL_WEIGHTS_BS1770` — frozen constants.
+- `channelWeight(index)`, `blockMeanSquare(block)`,
+  `combineChannelEnergies(perChannel)`, `energyToLufs(weightedMS)`,
+  `momentaryLufs(block)`, `shortTermLufs(block)`.
+- `class IntegratedLoudness` — `pushBlock`, `integrated`, `reset`,
+  `gatedBlockCount`.
+
+## Implementation Notes
+
+The integrator stores the linear weighted mean-square values that survived
+the absolute gate rather than their LUFS counterparts, because the relative
+gate is itself derived from the linear mean. This avoids a second
+`Math.pow(10, …)` pass per block. The silence floor is the BS.1770-4 minimum
+reported value (−70 LUFS for "no programme") rounded down to −100 to give
+downstream UI meters a stable bottom.