# Sequencer Camera Tracks

This document records the `TODOS.phase-72.72.15.1.8` cinematic sequencer camera
track contract. Camera tracks evaluate camera position, rotation, and FOV
keyframes, dispatch camera cuts between camera bindings, and expose rail cameras
for dolly-style movement.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Camera keyframe spec: `FV2SequencerCameraKeyframeSpec`
- Camera cut spec: `FV2SequencerCameraCutSpec`
- Rail camera spec: `FV2SequencerRailCameraSpec`
- Track evaluation: `FV2SequencerCameraTrackEvaluation`
- Issue enum: `EV2SequencerCameraTrackIssueType`
- Issue struct: `FV2SequencerCameraTrackIssue`
- Automation: `V2.Cinematics.Sequencer.CameraTracks`
- CI checker: `V2/ue/Tools/check-v2-sequencer-camera-tracks.py`

## Camera Model

`FV2SequencerCameraKeyframeSpec` stores camera position, rotation, FOV, frame,
time, interpolation id, and optional rail-lock metadata.
`FV2SequencerCameraCutSpec` stores camera cut timing, target camera binding,
hard-cut state, and blend frame metadata. `FV2SequencerRailCameraSpec` stores a
rail id, spline path id, active frame range, distance range, and rail
orientation flag.

`FV2SequencerTrackSpec` now carries `CameraKeyframes`, `CameraCuts`, and
`CameraRails` for `EV2SequencerTrackType::Camera` tracks. This keeps dedicated
camera sequencing beside the earlier generic camera FOV keyframe fixture used by
the data-model tests.

## Default Fixture

`BuildDefaultSequencerCameraTrack` creates `Track.Camera.CouncilTrial.Hero`,
bound to `Binding.Camera.Hero`. The track contains:

- Three transform/FOV keyframes at frames 0, 90, and 180.
- `Cut.Camera.HeroToCloseup`, cutting to `Binding.Camera.Closeup` at frame 90.
- `Cut.Camera.CloseupToRainWide`, cutting to `Binding.Camera.RainWide` at frame
  135 with a 12-frame blend metadata window.
- `Rail.CouncilTrial.Dolly`, using `Spline.CouncilTrial.JuryDolly` from frames
  60 to 150.

At frame 45, FOV interpolates to `43.5`. At frame 90, the closeup cut fires and
the dolly rail distance is `240`. At frame 120, the dolly rail distance is
`480`.

## Evaluation

`EvaluateSequencerCameraTrack` validates camera-track type, camera binding id,
camera keyframes, duplicate keyframe frames, camera cuts, and rail camera specs.
At a frame it returns the evaluated camera location, rotation, FOV,
interpolation alpha, active camera binding, camera cut fired this frame, active
cut id, active rail id, active rail spline path, rail alpha, and rail distance.

## Verification

Run:

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

Adjacent verification should include
`python3 V2/ue/Tools/check-v2-sequencer-event-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-audio-tracks.py`,
`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`.