# V2 Music Ducking

## Source Of Truth

- Task: `TODOS.phase-72.72.22.1.10`
- Contract:
  [MusicDucking_V2_Contract.json](../../ue/Content/V2/Audio/MusicDucking_V2_Contract.json)
- Core types: `EV2MusicDuckingTriggerKind`, `FV2MusicDuckingRule`,
  `FV2MusicDuckingRequest`, `FV2ResolvedMusicDucking`, and
  `FV2MusicDuckingCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultMusicDuckingCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateMusicDuckingCatalog`
- Resolver: `UV2AudioBlueprintLibrary::ResolveMusicDucking`
- Registrar: `UV2AudioSubsystem::RegisterMusicDuckingCatalog`
- Runtime controls: `UV2AudioSubsystem::ApplyMusicDucking` and
  `UV2AudioSubsystem::ClearMusicDucking`

## Trigger Coverage

The default `MusicDuckingSystem.V2` catalog reduces the dynamic music bus when
priority audio events need foreground space:

- `Dialogue` through `Audio.Event.Dialogue` and
  `Music.Ducking.Dialogue.Sidechain`
- `Explosion` through `Audio.Event.Explosion` and
  `Music.Ducking.Explosion.Sidechain`
- `ImportantSFX` through `Audio.Event.ImportantSFX` and
  `Music.Ducking.ImportantSFX.Sidechain`

Every rule must target `V2.DynamicMusic`, bind a `V2.*` sidechain bus, provide
attack/hold/release envelope timing, attenuate music below unity, and enable
sidechain compression with a threshold and compressor ratio.

## Runtime Behavior

`FV2MusicDuckingCatalog::ResolveDucking` validates the catalog, matches the
incoming `FV2MusicDuckingRequest` by `EV2MusicDuckingTriggerKind` and event tag,
and returns an accepted `FV2ResolvedMusicDucking` only when sidechain
compression is active. Accepted results publish trigger-specific reason tags for
dialogue, explosions, and important SFX.

`UV2AudioConfigAsset` owns the default catalog. `UV2AudioSubsystem` registers
it, applies accepted ducking results to the active mix by multiplying music
volume by the selected target gain, prioritizes voice during dialogue ducking,
and exposes runtime snapshot evidence for rule coverage, active sidechain
compression, last rule id, and last gain. `ClearMusicDucking` removes the active
ducking multiplier and refreshes the mix.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-music-ducking.py
python3 V2/ue/Tools/check-v2-music-memory-management.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/MusicDucking_V2_Contract.json
```