suaveplan/openspec/archive/2026-05-23-enterprise-audio-analysis-loudness/tasks.md

Tasks: enterprise-audio-analysis-loudness

Change ID: enterprise-audio-analysis-loudness Package: @suaveplan/audio-analysis-loudness Target path: packages/media/audio/audio-analysis-loudness Prerequisite packages on Verdaccio: @suaveplan/audio-core, @suaveplan/error, @suaveplan/types

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory packages/media/audio/audio-analysis-loudness/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/audio-core workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/opentelemetry workspace:^, zod catalog:forms.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/error-codes.ts — LOUDNESSErrorCode, AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA, registerAudioAnalysisErrorCodes().
• Write Zod schemas: LoudnessMeterOptionsSchema, LoudnessResultSchema.

---

3. Filters + algorithms

• Implement k-weighting.ts — ITU-R BS.1770 K-weighting filter (high-shelf + high-pass).
• Write k-weighting.test.ts and k-weighting.md (≥200 words).
• Implement lufs.ts — momentary/short-term/integrated loudness with gating.
• Write lufs.test.ts and lufs.md (≥200 words).
• Implement true-peak.ts — 4x oversampled true peak detection.
• Write true-peak.test.ts and true-peak.md (≥200 words).
• Implement loudness-range.ts — EBU Tech 3342 statistical loudness range.
• Write loudness-range.test.ts and loudness-range.md (≥200 words).

---

4. LoudnessMeter

• Implement LoudnessMeter class:
  • analyze() — full-document BS.1770-4 measurement
  • analyzeStream() — running integrated loudness as blocks arrive
  • analyzeBlock() — momentary loudness for real-time meters
• Wire OTel: span audio.analysis.loudness, counter, histogram.
• Write loudness-meter.test.ts (≤500 lines): reference signal → known LUFS, silence → graceful, true peak > sample peak.
• Write loudness-meter.md (≥200 words).

---

5. Benchmarks

• Write src/__benchmarks__/loudness.bench.ts — meter 1-minute track, meter 10-minute track.

---

6. Tests

• Write tests/integration.test.ts — full loudness measurement round-trip on real audio fixture.
• Write tests/property.test.ts (fast-check) — LUFS monotonic with gain, true peak ≥ sample peak.

---

7. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/audio-analysis-loudness — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-analysis-loudness — 100%.
• bun scripts/publish.ts --package @suaveplan/audio-analysis-loudness.
• Fold specs/audio-analysis-loudness/spec.md into openspec/specs/audio-analysis-loudness/spec.md.
• Archive to openspec/archive/2026-05-14-enterprise-audio-analysis-loudness/.