video-cook

Deterministic executor for the video-cooking skill pipeline. Wraps yt-dlp, whisperX, and ffmpeg into subcommands that assemble correctly every time — so the skill docs can stay short and the agent never hand-assembles a long command.

This is the hands, not the brain. Skills decide what to do, when, and handle creative work (translation, copywriting). cook only executes the deterministic parts and verifies the expected outputs exist.

Why

The video-cooking / video-download / video-subtitle skill trio started as natural-language docs that told the agent which yt-dlp / ffmpeg / whisperx commands to run. Three classes of bugs kept recurring:

1. Shell escaping traps — Windows paths with C: break ffmpeg's ass filter; backslashes get eaten by PowerShell; stdout redirects silently swallow downloads.
2. Hand-assembly drift — the agent forgets a flag (--convert-thumbnails jpg), picks the wrong template variable, renames the wrong file.
3. No mechanical completion check — "the agent feels done" is not a Done criterion. Real runs shipped without cover.jpg, without cloud-srt/, with translation drift the agent couldn't see.

cook fixes all three by being the single place where the commands are assembled. The skill docs shrink to a pipeline skeleton; the completion criteria become "cook exit 0".

Install

Option 1: One-liner via uv (recommended — uv handles Python interpreter + isolated env + PATH wiring automatically, no pip/venv knowledge needed):

# Linux / macOS
curl -LsSf https://github.com/ChHsiching/video-cook/releases/latest/download/install.sh | sh
# Windows (PowerShell)
irm https://github.com/ChHsiching/video-cook/releases/latest/download/install.ps1 | iex

The installer uses uv to install video-cook[all] as an isolated tool (~2GB — pulls whisperx + torch). After install, open a new shell and run cook doctor.

Option 2: pip directly:

pip install video-cook[all]       # yt-dlp + whisperx + cook itself
# or pick what you need:
pip install video-cook[download]   # for `cook download`
pip install video-cook[transcribe] # for `cook transcribe`

ffmpeg and Node.js must be on PATH separately (cook can't pip-install those).

Subcommands

Every command prints a JSON object on stdout (machine-readable; agents parse this) and human-readable progress on stderr. Exit codes are meaningful: 0 = done criterion passed, non-zero = it didn't.

How skills use cook

cook is the deterministic executor for the video-cooking skill pipeline. Skills call cook as a subprocess and branch on its exit code; the router (video-cooking) calls cook verify-shipment as the final gate. The pipeline steps — which cook subcommand runs when, what the agent does in between, the ASR/translation quality gates — live in each skill's SKILL.md, not here. This README covers cook itself: what it is, how to install it, what each subcommand does.

Bugs that cook fixes

Development

git clone https://github.com/ChHsiching/video-cook
cd video-cook
pip install -e .[dev]
pytest test_cook.py -v

Tests cover the subcommands whose correctness is non-obvious: verify-align (DP alignment edge cases), verify-shipment (file-presence checks), and the cloud-srt copy logic (the fix for the split leak). No network, no ffmpeg, no whisperx — all tests use temp dirs and fake files.

License

MIT