# Music Debug Overlay

## Source Of Truth

Task `TODOS.phase-72.72.22.1.14` adds a V2Editor diagnostics overlay for
adaptive music runtime inspection. The contract is
`V2/ue/Content/V2/Audio/MusicDebugOverlay_V2_Contract.json`, with focused
automation in `V2.Editor.Music.DebugOverlay` and module coverage in
`V2.Editor.Module`.

## Overlay Surface

`Tool.MusicDebugOverlay` targets `EV2EditorToolSurface::MusicDebugOverlay`.
`FV2MusicDebugOverlayWidgetSpec` keeps the overlay compact and operational:
current state, active layers, upcoming transition, beat counter, pinned PIE
follow, and a warning strip are mandatory panes.

The runtime-facing model is built from:

- `FV2MusicDebugOverlayRequest`
- `FV2MusicDebugOverlayActiveLayerRow`
- `FV2MusicDebugOverlayTransitionPreview`
- `FV2MusicDebugOverlayBeatCounter`
- `FV2MusicDebugOverlayFrame`

Blueprint helpers:

- `BuildMusicDebugOverlayWidgetSpec`
- `BuildMusicDebugOverlayRequest`
- `BuildMusicDebugOverlayFrame`

## Runtime Frame

The default verification frame shows `Music.State.Tension`, active layer
`Music.Layer.Tension.Strings.Sunset`, upcoming beat-synchronized transition
`BeatSync.Bar.Music.Section.Tension.VerseToMusic.Section.Tension.Chorus`, and
reason tag `Editor.MusicDebugOverlay.Accepted.RuntimeFrame`.

The frame is valid only when all four diagnostics panes are present: current
adaptive state, active vertical music layers, queued upcoming transition, and
beat counter.

## Validation Commands

Run the focused and adjacent checks:

```bash
python3 V2/ue/Tools/check-v2-music-debug-overlay.py
python3 V2/ue/Tools/check-v2-music-authoring-interface.py
python3 V2/ue/Tools/check-v2-editor-module.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m json.tool V2/ue/Content/V2/Audio/MusicDebugOverlay_V2_Contract.json
```