# Music System Composer Integration Guide

## Source Of Truth

This guide completes `TODOS.phase-72.72.22.1.15` and is bound by
`V2/ue/Content/V2/Audio/MusicSystemComposerGuide_V2_Contract.json`.

The V2 launch music runtime remains MetaSounds plus AudioModulation. Optional
Wwise and FMOD mappings are documented for partner studios, but the composer
handoff must still preserve the native fallback path.

Primary source docs:

- `adaptive-music-state-machine.md`
- `horizontal-music-resequencing.md`
- `vertical-music-layering.md`
- `beat-synchronized-transitions.md`
- `tempo-beat-tracking.md`
- `music-intensity-curves.md`
- `music-stingers.md`
- `cross-fade-transition-effects.md`
- `music-memory-management.md`
- `music-ducking.md`
- `music-playlist.md`
- `music-authoring-interface.md`
- `audio-middleware-backend.md`
- `music-debug-overlay.md`

Contract dependencies:

- `AdaptiveMusicStateMachine_V2_Contract.json`
- `HorizontalMusicResequencing_V2_Contract.json`
- `VerticalMusicLayering_V2_Contract.json`
- `BeatSynchronizedTransitions_V2_Contract.json`
- `TempoBeatTracking_V2_Contract.json`
- `MusicIntensityCurves_V2_Contract.json`
- `MusicStingers_V2_Contract.json`
- `CrossFadeTransitionEffects_V2_Contract.json`
- `MusicMemoryManagement_V2_Contract.json`
- `MusicDucking_V2_Contract.json`
- `MusicPlaylist_V2_Contract.json`
- `MusicAuthoringInterface_V2_Contract.json`
- `AudioMiddlewareBackend_V2_Contract.json`
- `MusicDebugOverlay_V2_Contract.json`

## System Map

The composer-facing music graph starts with `EV2AdaptiveMusicState` and
substates such as `Music.State.Tension.Suspense`. Horizontal re-sequencing maps
each state to verse, chorus, and bridge sections, while vertical layering adds
or removes stems such as `Music.Layer.Tension.Strings.Sunset` from the current
state and context tags.

Beat synchronization supplies BPM, bars, phrases, and downbeat alignment for
section changes such as
`BeatSync.Bar.Music.Section.Tension.VerseToMusic.Section.Tension.Chorus`.
Intensity curves map normalized gameplay pressure into state, section, and stem
choices. Stingers, crossfade effects, ducking, playlists, and memory management
then constrain how the authored music behaves during gameplay.

## Composer Deliverables

Each delivered cue or stem must include:

- adaptive state and substate naming, using the `Music.State.*` contract;
- horizontal verse chorus bridge sections with loop points and tail policy;
- vertical stem and context-tag delivery, including required tags like
  `Context.Sunset`;
- beat grid BPM, beats per bar, bars per phrase, and downbeat timestamp;
- intensity curve mapping for low, mid, and high gameplay pressure;
- stinger and crossfade rules, including musical boundary and fallback cue;
- dialogue ducking behavior and memory budget classification;
- playlist metadata, composer credit, license tier, and avoid-repeat policy;
- optional Wwise FMOD event names only when an ADR approves middleware use.

Deliverables are rejected when they omit a native MetaSounds path, lack beat
metadata, use state names outside the contract, or require external middleware
banks for the default cook.

## Authoring Workflow

1. Author the state and substate targets first in the music authoring interface.
   Use `Tool.MusicAuthoring` to inspect state rows, transition rows, layer
   assignment rows, and simulation output.
2. Add horizontal sections for verse, chorus, and bridge before tuning layer
   stems. Section ids must stay stable across revisions so beat-sync and
   playlist entries can keep references.
3. Deliver vertical stems with context tags and normalized intensity ranges.
   Combat drums and sunset strings remain required reference checks.
4. Run tempo beat tracking and beat-synchronized transition validation before
   final mix review. The beat grid is the source of truth for quantized
   transitions and debug overlay counters.
5. Add stingers, ducking, playlist entries, and memory priorities only after the
   core state/section/layer graph validates.

## Runtime Integration

The runtime loads the default catalogs through `UV2AudioConfigAsset` and
registers them on `UV2AudioSubsystem`. The subsystem evaluates adaptive state,
horizontal section, vertical layers, beat-synchronized transitions, stingers,
ducking, playlist selection, and memory priorities using the same contracts
linked above.

Native MetaSounds plus AudioModulation remains the shipping path. Wwise FMOD
handoff data may mirror the adaptive music state machine through
`AudioMiddlewareBackend_V2_Contract.json`, but middleware profiles are disabled
by default, ADR-gated, licensing-gated, and cook-safe without external banks.

## Debugging And Signoff

Composer signoff must include:

- `Tool.MusicAuthoring` simulation evidence for the target state transition;
- `Tool.MusicDebugOverlay` evidence showing current state, active layers,
  upcoming transition, and beat counter;
- a runtime snapshot confirming music playlist, ducking, memory, beat-sync, and
  middleware fallback registration;
- checked documentation links for every affected state, section, stem, stinger,
  playlist, and middleware event;
- validation logs for the focused checker and adjacent music gates.

The canonical debug frame uses `Music.State.Tension`,
`Music.Layer.Tension.Strings.Sunset`,
`BeatSync.Bar.Music.Section.Tension.VerseToMusic.Section.Tension.Chorus`, and
`Editor.MusicDebugOverlay.Accepted.RuntimeFrame`.

## Validation Commands

Run the guide checker and adjacent music gates:

```bash
python3 V2/ue/Tools/check-v2-music-system-composer-guide.py
python3 V2/ue/Tools/check-v2-music-authoring-interface.py
python3 V2/ue/Tools/check-v2-music-debug-overlay.py
python3 V2/ue/Tools/check-v2-audio-middleware-backend.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/ue/Tools/check-v2-buildgraph.py
python3 V2/tools/validate-v2-docs.py
python3 -m json.tool V2/ue/Content/V2/Audio/MusicSystemComposerGuide_V2_Contract.json
```