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
infographicchunk (heading + a few bullets, same theme). Insert as an opener/divider. The infographic skill’s optional top-right logo applies. Seereferences/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, writeschunk_NN_verdict.json. Never fixes.
Stages, each ending in a hard gate (scripts/gate.sh <stage>):
-
Preflight —
doctor.sh. -
Intake (
references/INTAKE.md) →chunks.json+ evidence. For anyclipchunk: 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-verifiedsyncblock (references/CHUNK-MODEL.md) —validate-chunks.pyrejects it otherwise. For frame-exact remakes ALSO run fresh span analysis per clip and author a stretch/freezeclip.timeline(references/CLIP-TIMELINE.md) — never reuse a prior run’s windows or trust the SRT for in-points. -
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’srequiredFix; ≤3 iterations, then flag. Gate: every chunk has mp4 + a passing (score ≥ 80, no “wrong” beat) or explicitly flagged verdict. -
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 → runvideo-intro+exitonbody_normalized.mp4instead.shotswap/bothoutput additionally usesscripts/build-shotswap.py(references/SHOTSWAP-EXPORT.md). -
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.