[brand-header]
---
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`.
