Requirements

Run each check command in a terminal before you start. talkinghead runs on macOS on Apple Silicon, on Linux, and on Windows through WSL2 with Ubuntu. Native Windows is not supported.

Install the system tools

macOS (Apple Silicon, Homebrew)

brew install ffmpeg librsvg uv
swiftc --version || xcode-select --install   # for visuals; the installer opens a window

Linux (Ubuntu or Debian)

sudo apt-get update
sudo apt-get install -y git ffmpeg librsvg2-bin espeak-ng fonts-liberation curl ca-certificates
curl -LsSf https://astral.sh/uv/install.sh | sh
. "$HOME/.local/bin/env"

Ubuntu 24.04’s ffmpeg 6.1 is enough to run talkinghead, HDR sources included. Only the developer test suite needs ffmpeg 7.1 or newer, for its HDR test fixtures: install a newer static build if you run the tests (for example from https://github.com/BtbN/FFmpeg-Builds/releases).

Windows (WSL2)

1. In PowerShell as administrator, run wsl --install -d Ubuntu, then restart when asked.
2. Open the Ubuntu app and follow the Linux steps there.
3. Keep the clone in the Linux home (~/talkinghead). File access under /mnt/c is much slower.

The Linux steps were verified on Ubuntu 24.04 with its stock ffmpeg 6.1, on both x86_64 and arm64, in Docker. WSL2 runs the same Ubuntu, but WSL2 itself has not been run end to end yet.

Check the tools and requirements

requirement	needed	check command	notes
ffmpeg and ffprobe	always	ffmpeg -version | head -1 and ffprobe -version | head -1	7.1 or newer for the test suite
uv (Python project manager)	always	uv --version
Python 3.11 or newer	always	uv run python --version	on Linux and WSL2 use uv sync --python 3.12, since faster-whisper has no wheel for the newest Python releases
librsvg (rsvg-convert)	with visuals (the default)	rsvg-convert --version	brew install librsvg or apt install librsvg2-bin
swiftc	with visuals, macOS only	swiftc --version	xcode-select --install
fonts	with visuals, Linux only	fc-match "Liberation Sans"	apt install fonts-liberation
a judge	always	see Judge values	Claude Code, omp, or your own command
an OpenRouter key (OPENROUTER_API_KEY)	with --transcriber scribe	echo "${OPENROUTER_API_KEY:+openrouter set}" prints openrouter set when it is set	your OpenRouter account
Whisper model (about 1.5 GB)	with --transcriber whisper	downloaded on first use; macOS: du -sh ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-turbo; Linux and WSL2: du -sh ~/.cache/huggingface/hub/models--mobiuslabsgmbh--faster-whisper-large-v3-turbo	the model comes from Hugging Face
fluidaudiocli (Parakeet)	with --transcriber parakeet, macOS only	command -v fluidaudiocli or echo "$FLUIDAUDIO_BIN"	a macOS build of FluidAudio’s fluidaudiocli, on PATH or named in FLUIDAUDIO_BIN
Silero VAD (optional)	no	uv run python -c "import silero_vad"	uv sync --extra vad
10-bit HEVC encoder (for HDR sources)	only for 10-bit HLG or PQ sources	ffmpeg -hide_banner -encoders | grep -E "hevc_videotoolbox|libx265"	macOS uses hevc_videotoolbox; elsewhere libx265, which is slower
espeak-ng	only for scripts/make_demo_clip.sh on Linux	espeak-ng --version	apt install espeak-ng; macOS uses say

Off macOS these things differ:

• Whisper runs faster-whisper on the CPU with the same large-v3-turbo weights. Its transcripts carry a different version string, so the two engines never share a cache entry.
• HDR output is encoded in software with libx265. It keeps the same 10-bit HLG or PQ tags.
• The head-coverage check needs Apple Vision. Elsewhere it is skipped with a warning, so check the framing of overlays yourself.
• Parakeet runs on macOS only.

Without Silero VAD the mouth-noise pass falls back to envelope-only gap detection, and the run prints one stderr line that says so. That line is not an error.