# V2 Music Playlist

## Source Of Truth

- Task: `TODOS.phase-72.72.22.1.11`
- Contract:
  [MusicPlaylist_V2_Contract.json](../../ue/Content/V2/Audio/MusicPlaylist_V2_Contract.json)
- Core types: `EV2MusicPlaylistOrderMode`, `FV2MusicPlaylistTrack`,
  `FV2MusicPlaylist`, `FV2MusicPlaylistRequest`,
  `FV2ResolvedMusicPlaylistTrack`, and `FV2MusicPlaylistCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultMusicPlaylistCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateMusicPlaylistCatalog`
- Resolver: `UV2AudioBlueprintLibrary::ResolveMusicPlaylistTrack`
- Registrar: `UV2AudioSubsystem::RegisterMusicPlaylistCatalog`
- Runtime selector: `UV2AudioSubsystem::SelectMusicPlaylistTrack`

## State Coverage

The default `MusicPlaylistSystem.V2` catalog provides multiple authored tracks
for each launch adaptive state that needs rotating music:

- `Exploration`: `Music.Playlist.Exploration.Sequential` with
  `Music.Playlist.Track.Exploration.Market` and
  `Music.Playlist.Track.Exploration.Rooftops`
- `Tension`: `Music.Playlist.Tension.Shuffle` with
  `Music.Playlist.Track.Tension.Pulse` and
  `Music.Playlist.Track.Tension.Undercurrent`
- `Combat`: `Music.Playlist.Combat.Shuffle` with
  `Music.Playlist.Track.Combat.Drums` and `Music.Playlist.Track.Combat.Brass`

`Sequential` and `Shuffle` ordering are both authored, and every playlist keeps
repeat avoidance enabled.

## Runtime Behavior

`FV2MusicPlaylistCatalog::ResolveTrack` chooses the requested playlist or the
first playlist for the requested `EV2AdaptiveMusicState`. Sequential playlists
walk forward from `SequenceCursor`; shuffle playlists use a stable hash of
playlist id, state, cursor, and `ShuffleSeed`. When `LastTrackId` or
`RecentTrackIds` includes a candidate and another valid candidate exists, the
resolver filters the recent track and returns a non-repeat result.

`UV2AudioConfigAsset` owns the default catalog. `UV2AudioSubsystem` registers
it, exposes `SelectMusicPlaylistTrack`, stores the last accepted
`FV2ResolvedMusicPlaylistTrack`, and publishes snapshot evidence for track
count, playlist count, multiple-track coverage, shuffle/sequential coverage,
repeat avoidance, last playlist id, and last track id.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-music-playlist.py
python3 V2/ue/Tools/check-v2-music-ducking.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 V2/tools/validate-v2-docs.py
python3 -m json.tool V2/ue/Content/V2/Audio/MusicPlaylist_V2_Contract.json
```