# V2 Tempo Beat Tracking

Phase 72.22.1.5 adds deterministic tempo detection and beat-position tracking
for Maya adaptive music clips. It analyzes authored music clip metadata into
BPM, beat markers, and downbeat times that can feed beat-synchronized
transitions.

## Source Of Truth

- Contract:
  [TempoBeatTracking_V2_Contract.json](../../ue/Content/V2/Audio/TempoBeatTracking_V2_Contract.json)
- Runtime module: `V2Audio`
- Core types: `FV2TempoDetectionSourceClip`, `FV2DetectedBeatMarker`,
  `FV2TempoDetectionRequest`, `FV2TempoDetectionResult`, and
  `FV2TempoBeatTrackingCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultTempoBeatTrackingCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateTempoBeatTrackingCatalog`
- Analyzer: `UV2AudioBlueprintLibrary::AnalyzeTempoBeatTrackingClip`
- Registrar: `UV2AudioSubsystem::RegisterTempoBeatTrackingCatalog`
- Subsystem route: `UV2AudioSubsystem::AnalyzeTempoBeatTrackingClip`

## Clip Coverage

The default `TempoBeatTracking.V2` catalog validates the music clips needed by
horizontal re-sequencing, combat music, and beat-sync transition scheduling.

Required clip ids include:

- `Music.Section.Exploration.Verse`
- `Music.Section.Exploration.Chorus`
- `Music.Section.Combat.Chorus`
- `Music.State.Combat.Main`

## Beat Analysis

`FV2TempoBeatTrackingCatalog::AnalyzeClip` selects a candidate BPM when supplied
or falls back to the source clip's authored BPM. It converts duration to a beat
grid, emits ordered `BeatMarkers`, and records `DownbeatTimesSeconds` at the
configured bar interval. The accepted reason tag is
`Audio.TempoBeatTracking.Accepted.BpmAndBeatGrid`.

The default exploration verse analysis returns 120 BPM, more than sixty beat
markers over the authored clip duration, and downbeat times for bar-aligned
synchronization. Combat clips can provide a measured candidate BPM such as 132
for alternate analysis passes.

## Runtime Evidence

`UV2AudioConfigAsset` owns the default `FV2TempoBeatTrackingCatalog`.
`UV2AudioSubsystem` registers it, analyzes requested clips, stores the last
accepted result, and exposes catalog registration, BPM detection, beat-position
tracking, last clip id, last detected BPM, and last beat marker count through
`FV2AudioRuntimeSnapshot`.

The catalog is rollback-cosmetic: tempo and beat-grid evidence drives audio
scheduling only and does not change gameplay simulation state.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-tempo-beat-tracking.py
python3 V2/ue/Tools/check-v2-beat-synchronized-transitions.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 -m json.tool V2/ue/Content/V2/Audio/TempoBeatTracking_V2_Contract.json
python3 V2/tools/validate-v2-docs.py
```