# Beat annotations
Ground-truth beat/downbeat annotations for the BPM accuracy harness
(`qa/bpm_accuracy.rs`), one JSON per manifest track id:
```json
{"beats": [secs...], "downbeats": [secs...], "meta": {...}}
```
`beats`/`downbeats` are what the harness scores against (F-measure ±70 ms,
CMLt/AMLt). `meta` is provenance only and ignored by the harness.
## Provenance
Generated by `examples/annotate_rigid_grid.rs`: a rigid constant-tempo grid
locked to the manifest's independently verified BPM, phase-fitted by
maximizing kick-band (≤150 Hz) onset energy at the grid points, downbeat
phase picked from 4 rotations by kick-band accent. The method shares no code
with the production detector. It is only valid for DAW-produced
constant-tempo material.
Trust levels, per `meta`:
- **Beat positions** are reliable where `phase_lock` is healthy (≥ ~0.3) or
the fitted BPM lands exactly on the integer label. Both held for every
annotated track.
- **Downbeat rotation** is a weak heuristic (four-on-the-floor kicks land on
every beat), reflected in mostly small `downbeat_margin` values. Treat
`downbeat_f` as provisional until a track's `verified_by_ear` is flipped to
`true` after listening to a click preview
(`cargo run --release --example annotate_rigid_grid -- --clicks <dir>`;
high tick = downbeat, low tick = beat).
`interplanetary-criminal-saucers` (swung UKG) has no annotation: the rigid
fit cannot lock onto its 2-step kick pattern. Annotate it manually (tap) if
beat-level coverage of swung material is wanted.
Regenerating overwrites the JSONs — re-verify by ear afterwards or restore
`verified_by_ear` flags from git.