dsp-audio-metrics

BS.1770-4 loudness metering and audio analysis — LUFS, LRA, true peak, spectral balance, stereo width. Zero runtime dependencies, works in Node and the browser.

📚 Full documentation: gtnorbeat.github.io/dsp‑audio‑metrics — getting started, CLI reference and API docs.

Why does this exist?

Measuring loudness correctly is hard to get right by hand. The BS.1770-4 standard mandates K-weighting, a two-stage gate and a mandatory 48 kHz measurement rate — feed it 44.1 kHz audio naively and your LUFS numbers are wrong. Most npm metering code is stale Web Audio plugin code with none of this.

This package implements the standard properly, in ~500 lines of dependency-free JavaScript that runs anywhere.

What it does

• Integrated loudness (LUFS) — BS.1770-4 two-stage gating, EBU R128 windows
• Loudness range (LRA) — 10th–95th percentile of gated short-term loudness
• True peak (dBTP) — oversampled to ≥ 192 kHz as the standard requires
• Spectral balance — sub / low / mid / high energy split of the mono mix
• Stereo width — mid/side ratio over sliding windows
• Levels — RMS, peak, crest factor
• CLI — dsp-audio-metrics file.wav → loudness table or JSON

Requirements

• Node.js >= 18 (browser/Deno/Bun: just import the ESM directly)

Quick start

npm install dsp-audio-metrics

Programmatic:

import { integratedLufs, measure } from "dsp-audio-metrics";

const sr = 44100;
const t = Float64Array.from({ length: sr * 5 }, (_, i) => i / sr);
const programme = t.map((x) => 0.5 * Math.sin(2 * Math.PI * 997 * x));

integratedLufs(programme, sr);      // ≈ -9.0 LUFS
measure(programme, sr);             // { integratedLufs, truePeakDb, loudnessRange, gainToTargetDb }

Mono (N), stereo (N×2) and multichannel (N×C) input all work — mono is measured as duplicated stereo, and everything resamples to 48 kHz internally.

CLI:

npx dsp-audio-metrics track.wav          # human table
npx dsp-audio-metrics --json track.wav   # machine-readable

Wait — there's more

The docs are hosted at gtnorbeat.github.io/dsp-audio-metrics and maintained on the dedicated docs branch:

• Guide
• CLI reference
• API reference
• Advanced

Contributing

PRs are welcome and appreciated. 🤝

• Read the Contributing Guidelines — setup, conventions and testing in one page
• Use the issue templates to file a bug report or feature request
• Keep PRs small, tested (npm test) and linted (npm run lint)
• Commit messages follow Conventional Commits (feat:, fix:, docs: …)

License

Apache-2.0 © astrocat86 — see LICENSE