name: vid-wiz description: Create or remake narrated videos. One engine, one chunk model; each chunk’s pixels come from a source — drive a live app (app), pan tall content (scroll), a generated concept panel (infographic), or real recorded footage (clip). Chipp voice, word-synced captions/cursor, Remotion compositing, single final loudnorm. Presets mulligan (remake existing video) and hole-in-one (build from a live app) are thin front-ends over this. metadata: openclaw: emoji: “🎬” requires: bins: [“ffmpeg”, “node”]

vid-wiz — unified video engine

“Turn a list of chunks into a narrated, composited video — from a live app, a recording, or both.”

vid-wiz is the engine behind two front-ends: mulligan (re-voice an existing video) and hole-in-one (build a tutorial from a live app). Both are just presets — a locked config + a tailored intake — over the one pipeline here. Run vid-wiz directly for hybrid videos that mix sources.

Project root + source of truth: D:\GitHub\vid-wiz (its own git repo; symlinked into ~/.claude/skills/vid-wiz). Compositing backend: D:\GitHub\remotion.

Mental model

A video is an ordered list of chunks. The pipeline is fixed; only how a chunk produces its pixels (source) varies.

intake (mode) → chunk list → [per chunk:
    script → voice (chipp-speak) → align (WhisperX)
    → produce visual (by source) → build props → Remotion render
    → score (≥80, ≤3 iters) → log]
  → concat + single loudnorm → optional intro/outro → final.mp4

Read RUNBOOK.md first — it is the driver. It fixes the stage order, the orchestrator/producer/verifier role split, and the hard gates (scripts/gate.sh) that end every stage. Then references/CHUNK-MODEL.md + references/PIPELINE.md (the per-chunk contract) and the references/SOURCE-*.md for each source you use.

Sources (one per chunk)

source Pixels from Remotion comp Reference
app drive a live app via MCP (or HTTP bridge) → screenshot(s) TutorialChunk references/SOURCE-app.md
scroll frame burst pan of tall content TutorialScroll references/SOURCE-scroll.md
infographic generated concept panel + gliding highlight InfoPanel references/SOURCE-infographic.md
clip real recorded footage, ffmpeg-retimed Clip references/SOURCE-clip.md

Captions + title cards

  • captions — word-synced burned-in captions from words.json (per-chunk, default off). Built in (Captions).
  • title cards — not a special type: a title is a simple infographic chunk (heading + a few bullets, same theme). Insert as an opener/divider. The infographic skill’s optional top-right logo applies. See references/TITLING.md.

Config (presets lock these)

See references/CONFIG.md. Key fields: mode (remake/create/hybrid), interaction (interactive/autonomous), allowedSources, voice (chipp default), captions (per-chunk, default off), introOutro, fps (30).

Interaction modes

The engine never asks anything itself — the driver picks the policy (references/INTERACTION.md):

  • interactive (default) — ask intake questions, wait for script approval.
  • autonomous — /vid-wiz … --auto (or “autonomously/unattended”): infer config from the prompt + defaults, auto-approve, fail soft (skip+flag, never block), log every decision, report once at the end.

This lives in the front-end layer, so /vid-wiz, the presets, and any future orchestrator skill all get autonomous mode from the same contract.

Entry mode allowedSources
mulligan preset remake [clip, infographic]
hole-in-one preset create [app, scroll, infographic]
vid-wiz (this) hybrid all

Roles + stages (full detail: RUNBOOK.md — follow it exactly)

Three roles; the same context never plays two of them for one chunk:

  • Orchestrator (the driving conversation): intake, chunks.json, dispatch, read verdicts, demand iteration, assemble, report. Never renders; never verifies its own work.
  • Producer (sub-agent): per-chunk pipeline steps 1–6 (references/PIPELINE.md).
  • Verifier (separate fresh sub-agent): measures sync/quality per references/VERIFY.md, writes chunk_NN_verdict.json. Never fixes.

Stages, each ending in a hard gate (scripts/gate.sh <stage>):

  1. Preflight — doctor.sh.
  2. Intake (references/INTAKE.md) → chunks.json + evidence. For any clip chunk: timestamped transcript + visual inventory contact sheets (make-inventory.sh) + A/V drift check (av_drift.md) are mandatory, and every clip chunk carries a visually-verified sync block (references/CHUNK-MODEL.md) — validate-chunks.py rejects it otherwise. For frame-exact remakes ALSO run fresh span analysis per clip and author a stretch/freeze clip.timeline (references/CLIP-TIMELINE.md) — never reuse a prior run’s windows or trust the SRT for in-points.
  3. Produce ⇄ Verify loop — producer renders (timeline clips via build-clip-timeline.sh), verifier scores each chunk 0–100 against the voiceover at every word-beat (references/VERIFY.md); fail → orchestrator re-dispatches with the verdict’s requiredFix; ≤3 iterations, then flag. Gate: every chunk has mp4 + a passing (score ≥ 80, no “wrong” beat) or explicitly flagged verdict.
  4. Assemble + finish — scripts/build-final.sh (ONE entrypoint): body concat from chunks.json ids → assemble-chunks.sh (the only loudnorm) → optional silent-card top-and-tail, never re-normalized. Music intro/outro → run video-intro+exit on body_normalized.mp4 instead. shotswap/both output additionally uses scripts/build-shotswap.py (references/SHOTSWAP-EXPORT.md).
  5. Final verify + report — verifier checks the assembled output (final_verdict.json); report includes the per-chunk verdict table, every flagged chunk, every inferred decision.

Shared scripts (canonical, in scripts/)

Script Role
doctor.sh env preflight — verify ffmpeg/node/Remotion/venvs/synth before any work (run at intake)
gate.sh hard stage gates (intake/chunks/final) — artifact + verdict existence; a fail means STOP
validate-chunks.py chunks.json gate — schema/limits/allowedSources + clip sync provenance check before any render
make-inventory.sh timecode-burned contact sheets of a source video — the visual ground truth for clip cuts
build-clip-timeline.sh hybrid clip builder — stretch+freeze clip.timeline segments fit to NARR, frame-exact to the voiceover (references/CLIP-TIMELINE.md)
build-final.sh ONE assembly entrypoint: body concat → assemble-chunks (only loudnorm) → silent-card top-and-tail
generate-voiceover.sh per-chunk Chipp voice (calls chipp-speak synth by abs path; edge fallback)
align-words.py WhisperX forced alignment → words.json (caption + cursor-click timing)
score-chunk.sh extract 25/50/75/95% frames for QA
assemble-chunks.sh final concat + single loudnorm
capture-window.ps1 PowerShell window capture (fallback for app when no MCP)
build-shotswap.py emit an editable .shotswap v4 project (clean base + extracted overlays + audio track); see references/SHOTSWAP-EXPORT.md
hi_log.py structured run logging (run_log.jsonl / .md / summary)
check-presets.sh drift check: repo presets/*.SKILL.md must equal the live deployed skills

Voice synth itself is owned by the chipp-speak skill (single canonical copy).

Logging (always)

Use scripts/hi_log.py (Logger(WORK_DIR)) for every run: actions, captures, renders, scores, errors → run_log.jsonl, run_log.md, run_summary.md. Redirect ffmpeg/remotion output to logs; on error show only tail -8.

Status

Engine + clip/app paths built and tested 2026-06-07 (see logs/TEST-RESULTS.md). Cutover done 2026-06-08: /mulligan and /hole-in-one are now live thin presets over this engine; the originals are preserved as /mulligan-old and /hole-in-one-old. See MIGRATION.md.