# Sequencer Audio Tracks

This document records the `TODOS.phase-72.72.15.1.6` cinematic sequencer audio
track contract. Audio tracks bind timeline sound cue triggers to the cinematic
context, route them through a named audio bus, and evaluate volume automation
and pitch automation for active cues.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Cue spec: `FV2SequencerAudioCueSpec`
- Cue playback row: `FV2SequencerAudioCuePlayback`
- Track evaluation: `FV2SequencerAudioTrackEvaluation`
- Issue enum: `EV2SequencerAudioTrackIssueType`
- Issue struct: `FV2SequencerAudioTrackIssue`
- Automation: `V2.Cinematics.Sequencer.AudioTracks`
- CI checker: `V2/ue/Tools/check-v2-sequencer-audio-tracks.py`

## Cue Model

`FV2SequencerAudioCueSpec` stores a stable cue id, sound cue asset path, start
frame, duration frames, base volume, base pitch, volume automation keyframes,
pitch automation keyframes, looping state, and spatialization state. The cue
spec exposes helpers for end frame, frame containment, automation presence, and
validation.

`FV2SequencerTrackSpec` now carries `AudioBusId` and `AudioCues` for
`EV2SequencerTrackType::Audio` tracks. Automation keyframes reuse the sequencer
keyframe interpolation path through `Audio.Volume` and `Audio.Pitch` property
paths, so audio automation follows the same timeline interpolation rules as the
rest of the sequencer.

## Default Fixture

`BuildDefaultSequencerAudioTrack` creates `Track.Audio.CouncilTrial.Mix`, bound
to `Binding.Global.Cinematic` and routed to `Audio.Bus.Cinematic`. The track
contains:

- `Cue.CouncilTrial.OminousMusicSwell`, a looping cinematic bed starting at
  frame 0 with volume and pitch automation.
- `Cue.CouncilTrial.DecisionImpactSting`, a one-shot sting starting at frame 120
  with volume and pitch automation.

At frame 90 the music cue evaluates a volume of `0.6166667`. At frame 120 the
sting triggers with pitch `0.92`, and at frame 126 it evaluates volume `0.93`
and pitch `0.96`.

## Evaluation

`EvaluateSequencerAudioTrack` validates audio-track type, binding id, audio bus
id, cue inventory, cue ids, sound cue asset paths, frame ranges, base volume and
pitch, and automation keyframes. At a frame it returns active cue playback rows
with local frame, resolved volume, resolved pitch, sound cue path, audio bus,
trigger flag, looping state, and spatialization state.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-audio-tracks.py
```

Adjacent verification should include
`python3 V2/ue/Tools/check-v2-sequencer-animation-clip-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-property-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-keyframe-interpolation.py`,
`python3 V2/ue/Tools/check-v2-sequencer-timeline-playback.py`,
`python3 V2/ue/Tools/check-v2-sequencer-data-model.py`, and
`python3 V2/ue/Tools/check-v2-cinematics-module.py`.