Overview

talkinghead turns one talking-head recording into a finished cut and a report that says why each cut was made. It removes material: warmup, retakes, digressions, long pauses and filler words. It does not write, re-record or reorder anything. An LLM judge that you choose makes the editorial calls, and every call is recorded with its vote count. The cutting, mastering and checks all run on your own machine.

Runs on macOS, Linux and Windows (WSL2). Point your AI coding agent at this README and it can set everything up.

What you get

Every run writes a run directory next to the source video, named <video stem>.talkinghead/.

file	what it is
final.mp4	the cut. Shippable on its own
final-visuals.mp4	the same cut with the overlay pass applied (quote cards, screenshots, chapter roadmap)
plan.json	the edit decision list: every cut with its reason, the kept segments, and the config that produced them
report.md	the decisions with their vote counts, every cut, the verification table, and the render command

An excerpt of report.md from the smoke test in Quick start (a 30 second synthetic clip):

# talkinghead report

- status: **OK**
- source duration: 30.00s; output: 16.40s; removed: 13.60s in 4 cuts
- transcript: whisper (46 words)

## Decisions

- outro: S0004 (votes: S0004=5)
    - dry run: keep to the last sentence

## Verification

- duration: OK: 16.40s rendered vs 16.40s planned (delta +0.00s, tol 0.50s)
- loudness: OK: -16.1 LUFS (target -16 +-1)
- cold_open: OK: first word ' This' at 0.00s (<= 0.5s required)
- joins: OK: 3/3 joins clean
- resolution: OK: render 1280x720 vs source 1280x720 as displayed

The smoke test used the offline dry-run judge, so its cuts are mechanical. A real judge makes the editorial cuts.