80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# Tasks: enterprise-audio-analysis-beat
|
|
|
|
**Change ID**: enterprise-audio-analysis-beat
|
|
**Package**: `@suaveplan/audio-analysis-beat`
|
|
**Target path**: `packages/media/audio/audio-analysis-beat`
|
|
**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-beat/` 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` — `BEATErrorCode`, `AUDIO_ANALYSIS_BEAT_ERROR_METADATA`, `registerAudioAnalysisErrorCodes()`.
|
|
- [ ] Write Zod schemas: `BeatDetectorOptionsSchema`, `BeatResultSchema`.
|
|
|
|
---
|
|
|
|
## 3. Algorithms
|
|
|
|
- [ ] Implement `energy-odf.ts` — positive first-differences of energy block stats; `processBlock()` returns ODF value.
|
|
- [ ] Write `energy-odf.test.ts` and `energy-odf.md` (≥200 words).
|
|
- [ ] Implement `spectral-flux.ts` — FFT-based onset detection with magnitude spectrum differences.
|
|
- [ ] Write `spectral-flux.test.ts` and `spectral-flux.md` (≥200 words).
|
|
- [ ] Implement `comb-tempo.ts` — autocorrelation / comb-filter tempo estimation.
|
|
- [ ] Write `comb-tempo.test.ts` and `comb-tempo.md` (≥200 words).
|
|
- [ ] Implement `beat-grid.ts` — phase-align onsets to regular grid given BPM.
|
|
- [ ] Write `beat-grid.test.ts` and `beat-grid.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 4. BeatDetector
|
|
|
|
- [ ] Implement `BeatDetector` class:
|
|
- `analyze()` — full-document scan, returns `BeatResult`
|
|
- `analyzeStream()` — `AsyncGenerator<BeatResult>` that refines as more audio arrives
|
|
- `analyzeBlock()` — real-time per-block onset detection
|
|
- [ ] Wire OTel: span `audio.analysis.beat`, counter, histogram.
|
|
- [ ] Write `beat-detector.test.ts` (≤500 lines): synthetic metronome → exact BPM, silence → no beats, confidence bounds.
|
|
- [ ] Write `beat-detector.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 5. Benchmarks
|
|
|
|
- [ ] Write `src/__benchmarks__/beat.bench.ts` — analyze 1-minute track, analyze 10-minute track.
|
|
|
|
---
|
|
|
|
## 6. Tests
|
|
|
|
- [ ] Write `tests/integration.test.ts` — full analyze round-trip on real audio fixture.
|
|
- [ ] Write `tests/property.test.ts` (fast-check) — BPM in range, beats monotonically increasing, confidence in [0,1].
|
|
|
|
---
|
|
|
|
## 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-beat` — green.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-analysis-beat` — 100%.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/audio-analysis-beat`.
|
|
- [ ] Fold `specs/audio-analysis-beat/spec.md` into `openspec/specs/audio-analysis-beat/spec.md`.
|
|
- [ ] Archive to `openspec/archive/2026-05-14-enterprise-audio-analysis-beat/`.
|