video_toolkit

Video Toolkit

Turn a brief into a finished MP4 with claude-code-video-toolkit. This skill is written for any agent runtime: Claude Code, OpenClaw, Codex, Hermes, a bare API loop with a run_tool call, or an MCP client. Nothing here depends on how your runtime backgrounds work, because the long work runs in a detached job you poll.

Where the toolkit is

Every command below runs from the toolkit root. Find it, in this order:

1. $VIDEO_TOOLKIT_ROOT if set (also honoured by the toolkit's own scripts);
2. $VIDEO_TOOLKIT_DIR (the name longarm uses);
3. a claude-code-video-toolkit/ directory under your workspace or home.

cd "${VIDEO_TOOLKIT_ROOT:-${VIDEO_TOOLKIT_DIR:-$HOME/claude-code-video-toolkit}}"
uv run tools/verify_setup.py --json     # prerequisites, keys and endpoints; [x] means ready

Never run a tool from inside a project directory: tools resolve paths relative to the toolkit root. If your runtime can't cd, pass --directory: uv run --directory /path/to/toolkit tools/video_job.py ....

No shell at all? Use the MCP server instead: uv run --directory /path/to/toolkit --extra mcp tools/video_mcp.py exposes video_estimate, video_submit, video_status, video_result and video_list_presets over stdio. Same flow as below, same JSON.

The quick path: estimate → submit → poll → result

tools/video_job.py is one async entrypoint. submit returns in seconds with a job id; a detached worker runs the whole pipeline (voiceover → visuals → captions → build → QC); every later call is short and reads state from disk. That is how it fits a per-call time limit, and it survives you going away between turns.

1. Write the spec (you are the LLM)

A spec is a list of scenes, each with narration text and one visual. Budget about 2.4 words a second of narration; a 45 s video is ~100 words in 3 to 5 scenes.

{
  "title": "Why do we have leap years?",
  "format": "9:16",
  "voice": {"provider": "qwen3", "speaker": "Ryan", "tone": "warm", "maxWpm": 165},
  "scenes": [
    {"slug": "hook",
     "text": "Every four years, February gets an extra day. Why? Because a year isn't 365 days long.",
     "visual": {"kind": "ltx", "prompt": "Slow orbital shot of Earth turning in space, sunlight sweeping the oceans, cinematic, no text"}},
    {"slug": "quarter",
     "text": "Earth takes about 365 and a quarter days to orbit the sun. Ignore the quarter and the calendar drifts.",
     "visual": {"kind": "ideogram", "caption": { "...filled from the caption template below..." }}},
    {"slug": "cta",
     "text": "So every fourth year we add one day back. Follow for one concept a week.",
     "visual": {"kind": "ideogram", "caption": { "...filled from the caption template below..." }}}
  ]
}