# Sequencer Keyframe Interpolation

This document records the `TODOS.phase-72.72.15.1.3` cinematic sequencer
keyframe interpolation contract. Interpolation is authored as named specs that
can be referenced by a keyframe's `InterpolationId` and constrained by track
`PropertyPath`, giving the sequencer both per-keyframe and per-property
interpolation behavior.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Interpolation spec: `FV2SequencerInterpolationSpec`
- Interpolated value: `FV2SequencerInterpolatedValue`
- Interpolation issue: `FV2SequencerInterpolationIssue`
- Mode enum: `EV2SequencerInterpolationMode`
- Issue enum: `EV2SequencerInterpolationIssueType`
- Automation: `V2.Cinematics.Sequencer.KeyframeInterpolation`
- CI checker: `V2/ue/Tools/check-v2-sequencer-keyframe-interpolation.py`

## Modes

The supported interpolation modes are:

- `Step`, which holds the previous keyframe value.
- `Linear`, which blends float, vector, and rotator values by normalized alpha.
- `CubicBezier`, which uses normalized 0-1 control points for cinematic easing.
- `CustomCurve`, which records a `CustomCurveId` and evaluates a deterministic
  runtime ease curve until authored curve assets are available.

Discrete bool, name, and string tracks use step fallback even when a non-step
spec is selected, preserving deterministic event and state behavior.

## Per-Property And Per-Keyframe Resolution

`BuildDefaultSequencerInterpolationSpecs` seeds:

- `Interpolation.Linear` for `Transform.Location`.
- `Interpolation.CubicEaseInOut` for `CineCamera.FieldOfView`.
- `Interpolation.Step` for `GameplayEvent`.
- `Interpolation.Custom.CameraEase` for `CineCamera.FieldOfView` with
  `Curve.Cinematic.CameraEase.Custom`.

`ResolveSequencerInterpolationSpecForKeyframe` first matches a keyframe's
`InterpolationId`, then falls back to a matching `PropertyPath`, then creates a
linear default for the track. This keeps old keyframes readable while allowing
new per-property overrides.

## Evaluation

`EvaluateSequencerKeyframeInterpolation` finds the previous and next keyframes
around the requested frame, resolves the interpolation spec, computes normalized
alpha, applies the selected interpolation mode, and returns a
`FV2SequencerInterpolatedValue` containing the typed result plus source/target
keyframe ids. Empty tracks, untyped values, and mismatched source/target value
types report issues through `FV2SequencerInterpolatedValue::Issues`.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-keyframe-interpolation.py
```

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