/video-toolkit

name: video_toolkit
description: Make short explainer videos from a brief with claude-code-video-toolkit — submit a scene spec, poll a job, get a QC-checked MP4. Also covers the individual tools (AI voiceover, images, clips, music, talking heads) for custom work.
metadata:
  openclaw:
    emoji: "🎬"
    skillKey: "video-toolkit"
    os: ["darwin", "linux", "win32"]
    requires:
      bins: ["uv", "ffmpeg"]

Video Toolkit

Turn a brief into a finished MP4 with [claude-code-video-toolkit](https://github.com/digitalsamba/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..." }}}
  ]
}

• `format`: `9:16` (Shorts, Reels, TikTok) or `16:9` (YouTube, decks).
• `visual.kind`: `ltx` (5 s motion b-roll, prompt the motion and atmosphere, never on-screen text),

`text` (constructed: a generated background that drifts, with `headline` and optional `subline` animated in; about a cent), `ideogram` (a designed card with legible text: **always a `caption` object**, filled from the template below), `flux` (text-free generated background), `none` (placeholder, drafts only). A scene with no visual gets a generated background. Alternate motion and constructed scenes so there is a pattern interrupt every ~15 s.

• `voice`: a preset name (`"lugh"`, from `assets/voices/lugh.json`) or an object. The title animates

over the first scene and a soft music bed is mixed in by default; `"titleCard": false` and `"music": false` turn them off.

• **No JSON at all:** `--scene "narration :: ltx: motion prompt"` per scene, `--scene "narration ::

text: HEADLINE ; subline"`, `--title`, `--voice lugh`. See the docs page for the full flat form.

• Scene 1 must hook in one sentence. Scene N is the call to action. Captions are burned from the script text,

so write every scene exactly as it should appear.

• Optional: `"music": {"enabled": true, "prompt": "..."}` (off by default), `"brand": "digital-samba"`,

`"ideogram": {"speed": "TURBO"}` to halve image cost, `"captions": {"enabled": false}`.

• `uv run tools/video_job.py presets` prints the full price table, formats and an example spec.

The caption template (every `ideogram` scene)

Ideogram renders text reliably only from a structured JSON caption. A plain `prompt` works but adds small filler text to the card ("A REMINDER", a fake tagline), so fill this in instead. Replace the `<...>` placeholders and leave everything else. The headline is under 6 words, all caps. `bbox` is `[top, left, bottom, right]` on a 0 to 1000 grid, so the same numbers work for 9:16 and 16:9. `uv run tools/video_job.py presets --json` prints it as `ideogram_caption_template`.

{
  "high_level_description": "A <dark-navy poster> with the headline <HEADLINE>, showing <one simple diagram or icon>, with clear space in the bottom fifth of the frame.",
  "style_description": {
    "aesthetics": "clean, diagrammatic, modern explainer",
    "lighting": "flat even lighting, soft glow on the main object",
    "medium": "flat vector graphic design",
    "art_style": "minimalist infographic poster, generous negative space",
    "color_palette": ["#0A1428", "#4DA8FF", "#FFB347", "#FFFFFF"]
  },
  "compositional_deconstruction": {
    "background": "Deep navy gradient, faint tiny stars.",
    "elements": [
      {"type": "text", "bbox": [80, 80, 200, 920], "text": "<HEA