Talking Head Recut

**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update talking-head-recut`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.

# Talking Head Recut

Talking Head Recut takes a local video that **plays in full** and layers a sequence of timed, designed **graphic cards** onto it — titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to what's being said. The agent designs the cards (timing + content) and **writes each card's HTML directly in the conversation**, then assembles a single composition HTML and renders it to MP4 via `hyperframes`. There is no fixed archetype list and no prescribed card structure — the overlays emerge from what the transcript actually says.

> **The front door is `/hyperframes`.** This skill packages an **existing talking-head clip** with **designed graphic cards** (titles, lower-thirds, data callouts, quotes, side panels, PiP) — not plain captions (the spoken words as text). **The clip plays untouched.** Any other intent — plain subtitles, a standalone graphic, a from-scratch video — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.

> **Graphic-packaging sibling of `embedded-captions`.** Captions add the _spoken words_ > as a readable subtitle; this adds _designed graphics_ on top of the playing video. > Plain subtitles → `embedded-captions`. Build a video from scratch → the creation > workflows (`product-launch-video` / `faceless-explainer` / …).

Routed through `/hyperframes`, the intent layer confirms only the input (which clip) and **announces** the render-strategy questions as deferred asks — aspect, layout, style group, and card count stay at Step 7, where the probed footage and transcript ground the recommendations; the layer's run-shape questions don't apply. A `BRIEF.md`, when present, carries the confirmed input and any user notes — read it first.

Inspectable intermediate files in the work directory:

- `metadata.json` — duration / width / height / fps - `audio.mp3` — extracted audio - `transcript.json` — a flat **word array** `[{ text, start, end }, …]` (Whisper; no `segments`, no `words` wrapper) - `storyboard.json` — lightweight card outline (the agent's plan) - `public/cards/card-XX.html` — one HTML fragment per card - `public/index.html` — final assembled composition - `output.mp4` — rendered video

## CLI Resolution

```bash # hyperframes — transcription (local Whisper) + rendering the assembled HTML to MP4 npx hyperframes --help ```

This skill runs entirely on the **hyperframes** CLI plus system `ffmpeg` / `ffprobe`. Transcription is local **Whisper** via `hyperframes transcribe` — no third-party service, API key, or rate-limited proxy.

## Workflow

### 1. Check Environment

```bash npx hyperframes doctor # ffmpeg, headless browser, render deps # confirm bundled assets: ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js" ```

Required:

- `ffmpeg` / `ffprobe` (system) - `<SKILL_DIR>/assets/fonts/*.woff2`, `<SKILL_DIR>/assets/vendor/gsap.min.js` (bundled inside this skill, staged to work dir in Step 9)

Transcription needs no key — `hyperframes transcribe` runs Whisper locally (Step 4).

Strongly recommended on macOS for `hyperframes render`:

```bash export PRODUCER_BROWSER_GPU_MODE=hardware ```

### 2. Create a Work Directory

All artifacts live under `videos/<project-name>/` — the same convention as the other video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video`). Keep the cwd at the workspace root; everything below writes under this one subdirectory.

```bash VIDEO_PATH="/absolute/path/input.mp4" WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')" mkdir -p "$WORK_DIR" ```

### 3. Extract Audio and Metadata

```bash # metadata — duration / width / height / fps ffprobe -v error -select_streams v:0 \ -show_entries stream=width,height,r_frame_rate \ -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json" # audio ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3" ```

Outputs: `metadata.json` (read `width`/`height`/`duration`; fps = the `r_frame_rate` fraction evaluated, e.g. `30000/1001 → 29.97`) + `audio.mp3`.

### 4. Transcribe

```bash npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en ```

Local **Whisper** — no API key, no proxy, no rate limit. Writes a word-level `transcript.json` into the work dir (word `text` + `start` / `end` timestamps). Read it for the word / sentence timings that drive card timing in Step 6; group words into sentences yours