Quick start

Do the smoke test first. It needs no API keys and no judge subscription, so it proves the install works before anything is spent.

1. Install

Install the system tools for your platform first: see Requirements.

git clone https://github.com/Sipty/talkinghead.git
cd talkinghead
uv sync          # on Linux and WSL2: uv sync --python 3.12
uv run talkinghead --help

talkinghead is not a pip package. Run every command in this README from the clone, with uv run.

2. Smoke test (offline, a few minutes)

This makes a 30 second synthetic clip with macOS say (espeak-ng on Linux), then cuts it with the dry-run judge and the Whisper transcriber. The dry-run judge answers every prompt with the most conservative answer and calls no model. The first run downloads the Whisper model (about 1.5 GB) from Hugging Face.

mkdir -p /tmp/talkinghead-smoke
scripts/make_demo_clip.sh /tmp/talkinghead-smoke/demo.mp4
TALKINGHEAD_JUDGE='shell:python3 -m talkinghead.dryrun_judge' \
TALKINGHEAD_TRANSCRIBER=whisper \
uv run talkinghead run /tmp/talkinghead-smoke/demo.mp4 --no-visuals

When it finishes it prints two paths and exits 0:

final: /tmp/talkinghead-smoke/demo.talkinghead/final.mp4
report: /tmp/talkinghead-smoke/demo.talkinghead/report.md

Open demo.talkinghead/final.mp4 and demo.talkinghead/report.md. The report status should say OK. The output is about 16 seconds, not 30. The dry-run judge keeps the last sentence, which ends near 18.5 s, and cuts the silence after it. Pauses between sentences are trimmed as well.

3. A real run

Choose a judge and a transcriber (see Configuration) and set them in your shell. For example, Claude Code as the judge and Scribe v2 for transcription:

export TALKINGHEAD_JUDGE=claude
export TALKINGHEAD_TRANSCRIBER=scribe
export OPENROUTER_API_KEY=...
uv run talkinghead run ~/Movies/talk.mov --audio ~/Movies/mic.wav --topic "one line about the video"

--audio is optional. Use it when a separate microphone recording exists (see Two inputs). --topic is one line about the video. It goes into every judgment prompt, and it is the cheapest way to improve the judge’s answers.

The run directory is talk.talkinghead/, next to talk.mov.

--plan-only stops after plan.json: no render, verification or visuals. It rebuilds the plan from the run directory’s stage memos and cached transcript, so every memo must hit (a miss fails, rather than calling a judge). Point --out-dir at a scratch copy to experiment without touching a finished cook. Open talk.talkinghead/final.mp4 and talk.talkinghead/report.md.

To preview a long recording first, add --demo 6. That renders only the first 6 minutes at draft quality, and its files are prefixed demo-.