# V2 Music Memory Management

## Source Of Truth

- Task: `TODOS.phase-72.72.22.1.9`
- Contract:
  [MusicMemoryManagement_V2_Contract.json](../../ue/Content/V2/Audio/MusicMemoryManagement_V2_Contract.json)
- Core types: `FV2MusicStreamingSectionSpec`, `FV2MusicMemoryManagementRequest`,
  `FV2ResolvedMusicMemoryManagementPlan`, and `FV2MusicMemoryManagementCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultMusicMemoryManagementCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateMusicMemoryManagementCatalog`
- Resolver: `UV2AudioBlueprintLibrary::ResolveMusicMemoryManagementPlan`
- Registrar: `UV2AudioSubsystem::RegisterMusicMemoryManagementCatalog`
- Scheduler: `UV2AudioSubsystem::ScheduleMusicMemoryManagement`

## Streaming And Preload Coverage

The default `MusicMemoryManagement.V2` catalog declares large music sections for
the launch adaptive-music states and keeps only the first streaming chunk
resident while the full file streams from disk:

- `Exploration`
- `Tension`
- `Combat`
- `Defeat`
- `Music.Section.Exploration.Verse`
- `Music.Section.Tension.Chorus`
- `Music.Section.Combat.Chorus`
- `Music.State.Defeat.KO`

Every `FV2MusicStreamingSectionSpec` must point at an authored `/Audio/Music/`
asset, exceed the large-file threshold, define multiple streaming chunks,
publish a preload lead time and priority, stream from disk, and mark the first
chunk resident. The launch catalog requires predicted preload coverage for
tension, combat, and defeat transitions.

## Runtime Behavior

`FV2MusicMemoryManagementCatalog::ResolveMemoryPlan` resolves the current
section, selects upcoming sections whose `EV2AdaptiveMusicState` matches the
prediction window, accounts for first-chunk resident memory, and rejects plans
that would exceed the configured music memory budget. Accepted plans report
`Audio.MusicMemory.Accepted.PredictedPreload`, include the current streaming
section, and list predicted preload sections separately.

`UV2AudioConfigAsset` owns the default catalog. `UV2AudioSubsystem` registers
it, schedules music-memory plans through `ScheduleMusicMemoryManagement`, and
exposes runtime snapshot evidence for section count, large-file streaming
coverage, predicted-preload coverage, last streaming/preload counts, and
resident MB.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-music-memory-management.py
python3 V2/ue/Tools/check-v2-cross-fade-transition-effects.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/MusicMemoryManagement_V2_Contract.json
```