# AI Handover: Local Cinematic Highlight PoC

Last updated: 2026-07-23 (Europe/Berlin). **This file goes stale — verify before trusting it.**

## FIRST: check for staleness (prevents the 2026-07-23 stale-session incident)

This handover was once resumed from an old commit while the repo had advanced 2 days on another
branch/agent, wasting a whole session re-deriving already-built work. Do NOT let that happen:

```bash
git rev-parse --short HEAD          # compare to "Recorded HEAD" below
git log -8 --oneline --decorate
git status --short                  # uncommitted work may be the real current state
```

- **Recorded HEAD when this was written: `8b68116`**, plus uncommitted working-tree changes (portrait +
  audio-mix + unbounded-duration fixes, see below).
- If HEAD is newer than `8b68116`, or there are unfamiliar commits/uncommitted files, **this file is behind
  the repo**. The authoritative live state is: the git log, `git status`, and
  `docs/cinematic-highlight-poc-plan.md` (milestone log at its tail). Trust those over this file.
- If a `claude agents` background session is still "running" for this repo, only one agent should mutate the
  repo at a time (renders/commits/state). Confirm the others are stopped.

## What exists NOW (built, not aspirational)

The full local single-source cinematic-highlight pipeline is implemented and working end-to-end:
analysis → candidates/category → (manual) director plan → local asset generation → cinematic FFmpeg render
→ QA. Models are provisioned and proven (Piper voice, MusicGen music, AudioLDM2 SFX) — see
[[local-model-runtime-intel-mac]]. The user authorized model downloads on 2026-07-21 (this **reversed** the
earlier no-download stance; that reversal is real and current).

To run source → final render, follow [[highlight-e2e-render-runbook]] — do not re-derive it.

## Fixes applied 2026-07-23 (whole service, not just PoC) — uncommitted in working tree

1. **Portrait/orientation**: `FfmpegClipInspector` now reads rotation side-data/`rotate` tag and stores the
   EFFECTIVE (display) width/height. `HighlightFfmpegRenderer.outputGeometry()` renders portrait sources to a
   portrait frame and skips the 2.39 letterbox (landscape unchanged). Fixes portrait phone footage being
   stretched into landscape.
2. **Audio mix**: source audio (`[0:a]`) is now ducked (-20 dB, or -24 with narration) so the generated score
   leads instead of being buried; montage music cue raised to -9 dB. In `HighlightFfmpegRenderer.audioMixCommand`
   + the montage cue in `HighlightDirectorFlowService`.
3. **Duration constraint removed**: `HighlightDirectorPlanValidator` no longer enforces min/max highlight
   duration (only positive/finite + sane playback speed + candidate containment). Config defaults relaxed
   (min 2 / max 3600 as soft candidate hints only). A highlight can be as long as the story needs. Montage path
   was already unconstrained.

`mvn -o verify`: 254 tests, 0 failures (JaCoCo gate passes). 6 new tests cover the above. NOT yet committed —
the user has not asked to commit.

## Still open / next levers (from docs/cinematic-highlight-poc-plan.md Phase 5)

- Source footage quality is the ceiling (e.g. 576p phone clips upscale soft). Biggest lever.
- No resident local **director** — plans are hand-authored (`montage.json`). P5.2/P5.5.
- Bigger/continuous music (musicgen-medium is slow on CPU) — P5.3.
- In-shot `zoompan` push-in, beat-synced cut lengths — P5.4.
- Licensing: MusicGen CC-BY-NC, AudioLDM2 CC-BY-NC-SA, YOLOv8 AGPL → non-commercial. Production needs
  commercially-licensed models — P5.7.
- Production hardening (security, CI/CD, containers, PostgreSQL, no-egress cert) deferred until quality passes.

## Non-negotiables still in force (except downloads, which the user authorized)

No external AI services in the media path; no unlicensed assets shipped as production; no placeholder
silence/tones as success; no rendering without explicit approval; record license/provenance for every model.
Manual approval is fine for the PoC. Do not commit unless the user asks.