Add 'Manual' auto align mode with persistent per-source compare offsets

[adam-ealovega]

TL;DR: compare sources get individual frame offsets that survive selection and compare-mode changes, via a new "Manual" auto align mode. Small diff, reuses the existing retime engine, no behavior change to any existing align mode, validated on production media on v1.3.0 and develop Windows builds.

Implements the API/persistence layer described in #314 (and long wished for in #93 / #166): per-source frame offsets for compare modes, driven through the engine that already exists in the codebase.

What this adds

• AAM_ALIGN_MANUAL ("Manual") auto align mode. In this mode align_clip_frame_numbers() applies user-set offsets instead of computing them from timecode or zeroing them. Offsets are remembered per media uuid inside PlayheadActor and re-applied on every selection rebuild — so they survive selection changes, compare-mode changes, and bare-pair sub-selections of a larger lineup (the current behavior recomputes or zeroes offsets on every such change).
• New PlayheadActor handlers (media::source_offset_frames_atom, <media uuid | selection index>, offset) so ANY compared source can be offset, not just the hero sub-playhead (the existing "Source Offset Frames" attribute remains hero-only and untouched in behavior).
• "Source Alignment Frames" is now writable while in Manual mode, and live-updates in all modes to reflect the offsets actually applied. Manual offsets restore correctly from serialised sessions.
• Python: Playhead.auto_align_mode, Playhead.source_alignment_frames, Playhead.set_source_offset_frames(media|uuid|index, offset).

Sign convention follows the existing engine: positive offset plays the source earlier.

What this deliberately does not add

No UI — the #93 Compare Settings Bar can layer on top of this. The change is confined to the playhead module + one pybind enum value + the Python wrapper; no behavior change for any existing align mode ("Off", "On", "On (Trim)" are untouched paths).

Validation

Behaviorally validated on production review media (multi-source render/plate/reference lineups, EXR/JPEG sequences and QuickTimes) on Windows builds of both v1.3.0 and this develop-based branch:

• per-source offsets apply frame-accurately (delayed sources hold their first frame through the head, then map position - delay, matching the engine's existing held-frame retime behavior);
• offsets persist through every 2-combination bare-pair reselection of a 4-source lineup and through reselect-all — the scenario that zeroes offsets today;
• sub_playhead.cpp (the retimer) is untouched by this PR and identical between v1.3.0 and develop, so retime behavior is inherited, not re-implemented.

We run this patch in production at our facility as the engine behind our review tooling's aligned-compare feature.

Portions of this change were developed with AI assistance (Anthropic's Claude); the approach, code, and behavior were reviewed and validated by the submitting engineer on production media.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: adam-ealovega / name: Adam Ealovega (0fad669)