vs-explain-video

Files (53)

• LICENSE.anidoodle
• LICENSE.take-one
• NOTICE.anidoodle
• SKILL.md
• openai.yaml · agents/
• captions.js · assets/
• motion.js · assets/
• scenes.example.js · assets/
• script.example.json · assets/
• stage.html · assets/
• Cargo.toml · fframes/kit/
• lib.rs · fframes/kit/src/
• lint.rs · fframes/kit/src/
• motion.rs · fframes/kit/src/
• style.rs · fframes/kit/src/
• timeline.rs · fframes/kit/src/
• Cargo.lock · fframes/video/
• Cargo.toml · fframes/video/
• main.rs · fframes/video/src/
• captions.md · references/
• checks.md · references/
• fframes.md · references/
• motion-craft.md · references/
• reviewer-brief.md · references/
• scenarist.md · references/
• audio.mjs · scripts/
• captions.mjs · scripts/
• check.mjs · scripts/
• checks.mjs · scripts/
• diff.mjs · scripts/
• ffkit.mjs · scripts/
• fframes.mjs · scripts/
• init.mjs · scripts/
• media.mjs · scripts/
• narrate.mjs · scripts/
• pack.mjs · scripts/
• pieces.mjs · scripts/
• preflight.mjs · scripts/
• quiz.mjs · scripts/
• render.mjs · scripts/
• stage.mjs · scripts/
• verdict.mjs · scripts/
• audio-motion-speed.static.eval.ts · test/
• captions-sync.static.eval.ts · test/
• captions.static.eval.ts · test/
• checks.static.eval.ts · test/
• diff-first.eval.ts · test/
• diff-repo.ts · test/
• diff.static.eval.ts · test/
• explain-video-renderer.eval.ts · test/
• explain-video.static.eval.ts · test/
• fframes.static.eval.ts · test/
• run-dirs.ts · test/

SKILL.md (first lines)

# Explain video

Turn one question into a 60-120 second narrated motion video: one concrete
example moving through the system, each build landing on the sentence that
names it. The video is a disposable explainer artifact. Do not widen it into a
production pipeline, a reusable video framework, or a branded template.

One shot: the text checks run before the voice, then one narration, one
render, and one review whose score is reported. No step loops back.

## Flow Contract

- **Kind:** Building block
- **Inputs:** A topic, code path, or PR; for a branch or PR, its `base...head` diff
- **Outputs:** An mp4 with burned-in subtitles under
  `~/.vs/$PROJECT_ID/videos/<topic>/`, audited stills per beat, a fresh
  reviewer's score, and a 2-4 line chat TLDR
- **Status:** `VIDEO_READY` or `BLOCKED_TOOLING` (with the install step)
- **Consumers:** Direct user invocation; `/vs-show-me` or `/vs-eli5` pages
  whose visuals become scenes
- **Skip conditions:** A static page answers the question as well; use
  `/vs-show-me`. Motion must carry part of the explanation.

## How it works

```text
script.json (beats) --quiz (text, one fix)--> --narrate--> narration.wav + timeline.js
ff/src/main.rs (Rust scenes) --fframes.mjs check--> stills --render--> mp4 --pack.mjs--> reviewer
```

The default renderer is fframes (Rust and SVG, Skia on the CPU, no GPU), one
build shared per machine; Playwright (`scenes.js`) is the fallback. Each scene
is a function of time on a 1920x1080 stage, so every frame is exact. The kit
draws the chrome, dot field, handoffs, camera push, and captions
([references/captions.md](references/captions.md)); you write `script.json` and
the arms of `ff/src/main.rs` ([references/fframes.md](references/fframes.md)).

## 1. Check the tools

Run `node <skill-dir>/scripts/preflight.mjs [<work-dir>]`. It installs the
pinned `playwright-core` into `~/.vs/tooling/` when none resolves; do not ask
first. It prints JSON: `ttsEngine`, `renderer`, found tools, and an install
hint per missing one. Exit 2 means blocked: show `next`, offer the storyboard
as a `/vs-show-me` page, and stop. Do not install system tools (ffmpeg, voices,
Rust, dev libraries) without the user's consent. With `fframes.warmable`, run
`node <skill-dir>/scripts/fframes.mjs doctor --warm` once (about 5 minutes,
4 GB in `~/.cache`). When `renderer` is `playwright` or `--warm` fails, use the
fallback (`scenes.js`) and put the FALLBACK warning in the handoff. Never
switch renderers silently.

## 2. Read the diff, then state the question

Branch or PR: first run `node <skill-dir>/scripts/diff.mjs <work-dir>` (an empty diff blocks) and read each
file's diff; chat loses context, so it gives only the why. A behaviour change the chat never named gets a
beat; `skip` is only for edits that change no behaviour ([scenarist](references/scenarist.md)). Other topics:
read the named code; set `"diff": {"none": "<why>"}`. Put the question and viewer in `question` and `audience`.

## 3. Scaffold

```bash
PROJECT_ID=$(git config --get remote.origin.url 2>/dev/null \
  | sed -E 's#\.git$##; s#.*[:/]([^/]+/[^/]+)$#\1#; s#/#-#g')
[ -z "$PROJECT_ID" ] && PROJECT_ID=$(basename "$PWD")
WORK="$HOME/.vs/$PROJECT_ID/videos/<topic>"
node <skill-dir>/scripts/init.mjs "$WORK"
node <skill-dir>/scripts/fframes.mjs init "$WORK"
```

`init.mjs` copies fonts, a script, and the fallback stage; `fframes.mjs init`
writes the crate `$WORK/ff/` (read the example it names) and `renderer.json`.
If fframes fails later, run `fframes.mjs fallback "$WORK" --reason "<why>"`
first; a fallback sticks (only `init --fframes` undoes it). Never commit videos, audio, or frames, or write them into the project.

## 4. Write the beats

Write `script.json` (beats, `pronounce`, `quiz`) with
[references/scenarist.md](references/scenarist.md); a subagent can take that
file alone. Beats are ASD-STE100-style plain English:
[../vs-internal-shared/references/ste-writing.md](../vs-internal-shared/references/ste-writing.md).
Pointer only; do not copy those rules here. Open slowly: scene one says how
this area works today, what is wrong, and the question, before any example
(motion-craft rule 0). Carry one concrete example through every scene.
Ground every claim in the code, PR, or source you read.

`pronounce` changes only what the voice says, not subtitles or the screen:
add each letter-by-letter acronym (`"AICM": "A I C M"`) and each name the voice
gets wrong. Run `node <skill-dir>/scripts/narrate.mjs "$WORK/script.json" --dry-run`. It
writes `narration.md` and estimates the length. Run
`node <skill-dir>/../vs-write/scripts/check-ste.mjs narration.md` on it. Exit
1: rewrite the flagged beats once; do not rerun it. Exit 2 means not
checked, not a pass.

Run `node <skill-dir>/scripts/quiz.mjs "$WORK"` and give the printed
`BRIEF.md`, and nothing else, to a new agent: it answers the three `quiz`
questions from the beats alone. A wrong answer or "not said" means a beat is
missing: add it once. The quiz never runs twice.

## 5. Narrate

Run `narrate.mjs` without `--dry-run`. It picks ElevenLabs when
`ELEVENLABS_API_KEY` is set in the environment, else a free local voice:
kokoro, then piper, then macOS `say`. It speaks each beat separately (cached,
so a rerun only speaks changed beats), then writes `narration.wav` and
`timeline.js`. It prints each scene's `cues`: `B[i] = <seconds>` per beat.
When the user cares about the voice, let them pick from 4-6 voices on one beat
(`KOKORO_VOICE=am_michael`; default `af_heart`). It then checks without ears
(`narration-check.json`). With whisper installed, it transcribes each beat; a
flagged beat lost or gained words: report it in the handoff and do not narrate again.
Without whisper it says the words were not checked; report that
(`--require-word-check` exits 2). It levels the track to -16 LUFS.
The API key is a secret. Never print, log, echo, or write the key, and never
put it in a command line. Never ask the user to paste it into chat; ask them
to export it in their shell. Report only whether it is set.

## 6. Write the scenes

In `ff/src/main.rs`, one `match` arm per script scene id draws the scene at
time `s.t` from the beat starts `s.b` (`B` in the craft notes) with the kit's
helpers (`s.words`, `s.card`, `s.row`, `s.terminal`, `s.still`, `s.clip`).

From vltansky/vs, MIT.

More from vltansky/vs