/analyze-video

name: analyze-video
description: Internal sub-procedure (not a standalone entry point) — the shared footage-analysis pipeline that produces audio transcripts, contact sheets, and Sonnet-written summaries. Invoked end-to-end by the process-library and reprocess-with-contact-sheets skills; don't trigger it on its own.

Skill: Analyze Video (parent brief)

This is the main thread's playbook for the **Analyze Video** workflow step. Run it after library setup, before any cut work. It covers the three artifacts produced per clip: audio `transcript`, `contact_sheet`, and markdown `summary`. The roughcut agent reads dialogue on demand by running `script_extractor.rb` over the transcript JSON — no separate script artifact.

`SKILL.md` is the parent's dispatch brief. The sub-agent working prompt lives in `agent_prompt.md` — inline its contents when launching a Task agent. Don't pass `SKILL.md`.

Terminology

• **User-facing:** call it "footage analysis" or "analyzing footage."
• **Internal/file names:** "transcription" (library.yaml field `transcript`, etc.).

Prerequisites

• Library setup is complete (`library.yaml` exists, schema is current — run migrations from AGENTS.md if not).
• Read `libraries/settings.yaml` directly for `whisper_model`. For library fields, read the snapshot via `ruby lib/buttercut/library.rb <name> summary` and pull the values you need from the JSON — don't parse library.yaml inline.

At this point, create a todo list, visible to the user, with high-level, non-technical steps so they can follow the overall plan for processing the library. Include caffeination steps only if they've opted in. e.g.:

- [ ] Keep computer awake 
- [ ] Create transcripts (0/30)
- [ ] Analyze footage (0/30)
- [ ] Let computer sleep again 
- [ ] Review the footage together

These public todos map onto the steps below: "Keep computer awake" is Step 1 and "Let computer sleep again" is Step 6; "Create transcripts" covers the mechanical run in Step 2 plus the optional refinement pass in Step 3 (advance its count from Step 2's `[transcript …]` progress lines; hold it in-progress through Step 3 when refinement is on); "Analyze footage" tracks the summaries in Step 4 (advance its count as clips are summarized, *not* after contact sheets); "Review the footage together" is Step 5.

In the public chat, refer to these non-technical steps. Keep the technical work (WhisperX, contact-sheet generation, Sonnet summaries) behind the scenes.

Step 1 — Prevent sleep during processing

Before starting analysis, ask the user (via `AskUserQuestion`): "Processing can take a while — want me to keep your computer awake until it's done?" Options: "Yes (Recommended)" and "No".

If yes, start the platform's keep-awake helper in the background and store the PID — you'll kill it in Step 6 once analysis is finished. (Backup is handled by the calling skill — `process-library` — after this skill returns.)

macOS:

caffeinate -i -w $$ &
KEEPAWAKE_PID=$!

Windows (Git Bash):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!

Both prevent idle sleep while footage processes (the display may still turn off, which is fine).

Step 2 — Process footage (transcripts, then contact sheets)

(If you reached this skill directly rather than via `process-library`, first tell the user: "Found [N] videos ([total size]). Starting footage analysis...")

This is two mechanical commands you run **one after the other** — transcripts first, contact sheets second. **Never run them at once**: WhisperX is RAM-hungry, and overlapping the two is what we're avoiding. Don't hand-roll either with sub-agents; each runs identically every time, ~2 clips at a time, recording each clip into library.yaml the moment it finishes. Both are idempotent — they only touch clips still missing that artifact — so a re-run finishes only what's left. They will run in a minature Sidekiq-like job service. You'll run the command and then watch the log file that will be returned to watch progress.

**Step 2a — Transcripts.** If using Claude Code, run with `run_in_background: true` on the Bash tool. Otherwise use correct tool/argument to run in background.

ruby lib/buttercut/process_footage.rb transcripts <library-name>

Immediately after launching, set up a `Monitor` or equivalent on the log file to receive a notification for each completed or failed clip:

tail -f tmp/logs/processing/<library-name>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob  (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"

ruby lib/buttercut/library.rb <name> pending transcript   # JSON list; done = N − its length

Update "Create transcripts 5/20" ie, number_of_clips_complete/total_number_of_clips as clips finish so the user can see progress. When the background task completes it exits non-zero if any clip failed. On failure, re-run once. If it fails again, investigate and then either create a fix so we handle it elegantlyy or inform the user about the problem with the clip and potentially pull it from the library.

**Wait for 2a to finish before starting 2b.**

**Step 2b — Contact sheets.** Once transcripts are done, build the sheets (a fast ffmpeg pass — foreground is fine):

ruby lib/buttercut/process_footage.rb contact-sheets <library-name>

Contact sheets stay behind the scenes — don't surface them as a public count. Mark "Create transcripts" done once 2a has finished and any refinement (Step 3) is complete.

Tuning (optional): both steps read `parallel_jobs` from `libraries/settings.yaml` (default 2); override for one run with `--jobs N`. Each writes a timestamped log under `tmp/logs/processing/<library>/` for after-the-fact review.

**Reprocessing.** Each step skips clips that already have its artifact. To redo one — say a transcript that misheard a name — re-run that step with `--force --clips NAME.mov`. `--force` alone