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`
pip install video-cook[subtitle]   # word-boundary cutting in `cook subtitles`

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 (199 as of this writing) cover every subcommand whose correctness is non-obvious:

• verify-align (DP alignment edge cases), verify-shipment (file-presence checks), the cloud-srt copy logic (the fix for the split leak), and the width-based length gate;
• the dub pipeline: synth band split + worker orchestration (--workers/--stagger), atomic cue publishing (two concurrent writers of the same sent_NNNN.wav never expose a partial file), dub merge lockstep invariants, measure-rate/gate (measured-rate contract), and the retime chain (char alignment, the two-pass rewrite incl. the negative-anchor clamp, assemble auto-retime markers);
• packaging contracts: stage scripts resolve package-internally and never fall back to installed skill copies (ADR 0001).

No network, no ffmpeg, no whisperx — all tests use temp dirs and fake files.

License

AGPL-3.0-only · Copyright (c) 2026 ChHsiching —— 见 LICENSE。

• 使用（含公司内部使用）、修改、分发均免费；但分发或以本代码提供网络服务时，衍生作品须以 AGPL-3.0 开源。
• 闭源商用须另行获取商业授权：hsichingchang@gmail.com

贡献条款

提交 PR 即表示你同意以 AGPL-3.0 授权你的贡献，并授予维护者在 AGPL 之外另行提供商业授权的权利（你的贡献始终以 AGPL 对所有人开放）。