# V2 Beat-Synchronized Transitions

Phase 72.22.1.4 adds beat-synchronized transition scheduling for Maya adaptive
music. It waits until the next authored beat, bar, or phrase boundary before a
music segment switch is allowed.

## Source Of Truth

- Contract:
  [BeatSynchronizedTransitions_V2_Contract.json](../../ue/Content/V2/Audio/BeatSynchronizedTransitions_V2_Contract.json)
- Runtime module: `V2Audio`
- Core types: `EV2MusicSyncBoundary`, `FV2BeatSynchronizedTransitionRule`,
  `FV2BeatSynchronizedTransitionRequest`,
  `FV2ResolvedBeatSynchronizedTransition`, and
  `FV2BeatSynchronizedTransitionPlan`
- Builder:
  `UV2AudioBlueprintLibrary::BuildDefaultBeatSynchronizedTransitionPlan`
- Validator: `UV2AudioBlueprintLibrary::ValidateBeatSynchronizedTransitionPlan`
- Resolver: `UV2AudioBlueprintLibrary::ResolveBeatSynchronizedTransition`
- Registrar: `UV2AudioSubsystem::RegisterBeatSynchronizedTransitionPlan`
- Subsystem route: `UV2AudioSubsystem::ScheduleBeatSynchronizedTransition`

## Boundary Rules

The default plan validates `Beat`, `Bar`, and `Phrase` boundaries. Rules are
authored against segment ids used by the horizontal re-sequencing and adaptive
state tasks.

| Boundary | Example transition                                                       |
| -------- | ------------------------------------------------------------------------ |
| Beat     | `Music.State.Combat.Main` to `Music.State.Defeat.KO`                     |
| Bar      | `Music.Section.Exploration.Verse` to `Music.Section.Exploration.Chorus`  |
| Phrase   | `Music.Section.Exploration.Chorus` to `Music.Section.Exploration.Bridge` |

Required rule ids include:

- `Music.Section.Exploration.Verse->Music.Section.Exploration.Chorus`
- `Music.Section.Exploration.Chorus->Music.Section.Exploration.Bridge`
- `Music.State.Combat.Main->Music.State.Defeat.KO`

## Wait Math

`FV2BeatSynchronizedTransitionPlan::ResolveTransition` converts playback time to
beats using BPM, finds the next boundary period, and returns `WaitSeconds`,
`TargetBeatIndex`, `TargetBarIndex`, and `TargetPhraseIndex`. This task owns the
boundary scheduler only; later tempo-detection work can feed measured BPM into
the same request through `OverrideBpm`.

## Runtime Evidence

`UV2AudioConfigAsset` owns the default `FV2BeatSynchronizedTransitionPlan`.
`UV2AudioSubsystem` registers it, schedules transitions, stores the last
accepted transition, and exposes rule count, beat coverage, bar coverage, phrase
coverage, target segment, and wait time through `FV2AudioRuntimeSnapshot`.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-beat-synchronized-transitions.py
python3 V2/ue/Tools/check-v2-vertical-music-layering.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 -m json.tool V2/ue/Content/V2/Audio/BeatSynchronizedTransitions_V2_Contract.json
python3 V2/tools/validate-v2-docs.py
```