# 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/`.