video_editing_poc/docs
JSLMPR d89a28e084 refactor(director): decisive moment = measurement proposes, vision model judges
Choosing WHICH moment is the highlight is a question of meaning, not motion or
loudness, and there is no generic rule in measurement alone: on the real bowling
clip a camera turn-away has the highest motion AND is louder than the celebration.
Positional bands / thresholds only move which video breaks. So responsibilities
are now split, with zero per-video constants:

- HighlightMontageDirector.candidatePeaks: measurement PROPOSES the intensity
  (motion+audio) local maxima, strongest-first, min-separated. No opinion on which
  is the highlight; no band, no threshold.
- HighlightVisionDirector.rankDecisiveMoment: the vision model JUDGES each
  candidate by highlight-worthiness (a celebration/goal outranks a loud turn-away
  or an "about to..." build; anticipation is not the payoff). Highest score wins;
  falls back to the strongest peak only if the model declines.
- composeMontageAt: builds the action segment (measured onset -> chosen peak ->
  measured resolution that sweeps in the outcome+reaction) around the choice.
- MomentChooser interface makes the judge a drop-in: a stronger local VLM plugs in
  with no director changes.

Removes the previous positional-band / semantic-weight heuristics.

Honest, verified ceiling (documented in R15): the judge is only as good as its
eyes. moondream2 perceives some actions (soccer: "kicking a soccer ball" -> the
goal is chosen correctly) but not others -- on distant portrait bowling footage it
describes every frame as "standing"/"walking" and never sees the celebration
(a posture prompt collapsed to a constant "Standing still"). When it can't
discriminate, candidates tie and it falls back to the loudest peak. This is a
model-capability limit, not a design flaw; the fix is a stronger VLM (drop-in).

mvn verify: 293 tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-25 18:37:38 +02:00
..
LOCAL-MODELS.md docs: portable e2e runbook + local-models reference (any-AI usable) 2026-07-24 15:47:45 +02:00
RUNBOOK-highlight-e2e.md docs: portable e2e runbook + local-models reference (any-AI usable) 2026-07-24 15:47:45 +02:00
alerts.md Added the next operational-readiness artifact in docs/alerts.md and marked Alerts complete in docs/video-clipping-service-implementation-plan.md:722. 2026-07-10 00:20:31 +02:00
autoscaling-policies.md • The next step is done and the plan is updated. Autoscaling policies is now marked complete in docs/video-clipping-service-implementation-plan.md:717. 2026-07-09 19:00:31 +02:00
backup-and-restore-validation.md • Added the backup/restore validation artifact at docs/backup-and-restore-validation.md and marked Backup and restore validation complete in docs/video-clipping-service-implementation-plan.md:724. 2026-07-10 00:27:26 +02:00
cinematic-editing-runbook.md - Implement end-to-end cinematic highlight rendering pipeline 2026-07-12 01:20:18 +02:00
cinematic-highlight-acceptance-review.md docs: add P3.6 acceptance review (frozen thresholds + rubric); Gate A measured PASS 2026-07-22 11:59:06 +02:00
cinematic-highlight-operator-checklist.md add asset generation 2026-07-21 10:03:27 +02:00
cinematic-highlight-poc-plan.md Automatic two-tier highlight director + source-adaptive rendering 2026-07-23 22:49:05 +02:00
cinematic-quality-rules.md refactor(director): decisive moment = measurement proposes, vision model judges 2026-07-25 18:37:38 +02:00
cinematic-video-editing-service-plan.md • working version but not cinematic 2026-07-11 00:32:46 +02:00
cost-model-by-video-minute.md I added a reproducible cost-model harness in src/test/java/org/example/videoclips/perf/CostModelBenchmarkHarness.java:1 that turns the checked-in FFmpeg and object-storage benchmark baselines into per-source-minute estimates 2026-07-09 19:04:23 +02:00
current_state.md feat(cinematic): R10–R14 grade/cadence/edit rules + 420p compat fix 2026-07-25 12:36:18 +02:00
dashboards.md Updated the prompt in docs/grafana-dashboard-creation-prompt.md so the VPS AI now has the full next-step instructions: generate the dashboard JSON, save it to dashboards/video-clipping-overview-grafana.json, and verify the 2026-07-10 00:17:51 +02:00
dlq-redrive-procedure.md • Added the DLQ redrive artifact at docs/dlq-redrive-procedure.md and marked DLQ redrive procedure complete in docs/video-clipping-service-implementation-plan.md:725. 2026-07-10 00:29:26 +02:00
ffmpeg-preset-benchmark-baseline.md • The next plan item is done and the plan is updated. Object-storage bandwidth tests is now marked complete in docs/video-clipping-service-implementation-plan.md:713. 2026-07-09 01:33:24 +02:00
gate-b-review-bowling.md feat(cinematic): R10–R14 grade/cadence/edit rules + 420p compat fix 2026-07-25 12:36:18 +02:00
grafana-dashboard-creation-prompt.md Updated the prompt in docs/grafana-dashboard-creation-prompt.md so the VPS AI now has the full next-step instructions: generate the dashboard JSON, save it to dashboards/video-clipping-overview-grafana.json, and verify the 2026-07-10 00:17:51 +02:00
highlight-rendering-gap-closure-plan.md Add highlight rendering gap closure plan 2026-07-11 17:26:36 +02:00
input-folder-scheduler-plan.md Configure folder scheduler in YAML 2026-07-10 12:24:16 +02:00
load-test-signoff.md • Added the signoff artifact at docs/load-test-signoff.md and marked Load-test signoff complete in docs/video-clipping-service-implementation-plan.md:726. 2026-07-10 00:30:56 +02:00
local-cinematic-asset-worker-prompt.md add asset generation 2026-07-21 10:03:27 +02:00
local-cv-visual-analysis-guide.md Add local CV worker readiness checks 2026-07-11 17:46:40 +02:00
object-storage-bandwidth-benchmark-baseline.md • The next plan item is done and the plan is updated. Object-storage bandwidth tests is now marked complete in docs/video-clipping-service-implementation-plan.md:713. 2026-07-09 01:33:24 +02:00
production-cinematic-ai-director-prompt.md - Implement end-to-end cinematic highlight rendering pipeline 2026-07-12 01:20:18 +02:00
production-cinematic-highlight-editing-plan.md - Implement end-to-end cinematic highlight rendering pipeline 2026-07-12 01:20:18 +02:00
queue-visibility-timeout-tuning.md • I completed the next plan item and updated the checklist. Queue visibility-timeout tuning is now marked done in docs/video-clipping-service-implementation-plan.md:716. 2026-07-09 18:37:57 +02:00
runbooks.md • Added the runbook artifact at docs/runbooks.md and marked Runbooks complete in docs/video-clipping-service-implementation-plan.md:723. 2026-07-10 00:22:35 +02:00
video-clipping-service-implementation-plan.md • clip video locally plan 2026-07-10 00:49:29 +02:00
video-clipping-service-planning-prompt.md initial 2026-07-08 17:00:58 +02:00
worker-cpu-disk-benchmark-baseline.md I continued with the next plan step and updated the plan. 2026-07-09 01:25:04 +02:00