vs-explain-video
Make a short narrated motion explainer video about a topic, code path, or PR. Use when the user types /vs-explain-video or asks for an explainer video, animated walkthrough, or narrated video of how something works. Produces one mp4 outside the repo, with audited frame stills and a short TLDR.
- License 许可
- MIT
- 所属仓库
- vltansky/vs
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- vs-explain-video
- description
- Make a short narrated motion explainer video about a topic, code path, or PR. Use when the user types /vs-explain-video or asks for an explainer video, animated walkthrough, or narrated video of how something works. Produces one mp4 outside the repo, with audited frame stills and a short TLDR.
02 资源文件 52
- 参考文档agents/openai.yaml175 B
- 脚本assets/captions.js3.1 KB
- 脚本assets/motion.js20.9 KB
- 脚本assets/scenes.example.js3.1 KB
- 资产文件assets/script.example.json1.5 KB
- 资产文件assets/stage.html7.1 KB
- 其他fframes/kit/Cargo.toml1.0 KB
- 脚本fframes/kit/src/lib.rs42.4 KB
- 脚本fframes/kit/src/lint.rs1.5 KB
- 脚本fframes/kit/src/motion.rs6.8 KB
- 脚本fframes/kit/src/style.rs7.3 KB
- 脚本fframes/kit/src/timeline.rs4.1 KB
- 其他fframes/video/Cargo.lock70.9 KB
- 其他fframes/video/Cargo.toml766 B
- 脚本fframes/video/src/main.rs4.6 KB
- 许可证LICENSE.anidoodle11.1 KB
- 许可证LICENSE.take-one1.0 KB
- 其他NOTICE.anidoodle822 B
- 参考文档references/captions.md1.8 KB
- 参考文档references/checks.md1.8 KB
- 参考文档references/fframes.md11.0 KB
- 参考文档references/motion-craft.md6.4 KB
- 参考文档references/reviewer-brief.md4.0 KB
- 参考文档references/scenarist.md8.1 KB
- 脚本scripts/audio.mjs10.3 KB
- 脚本scripts/captions.mjs13.7 KB
- 脚本scripts/check.mjs11.9 KB
- 脚本scripts/checks.mjs14.6 KB
- 脚本scripts/diff.mjs18.4 KB
- 脚本scripts/ffkit.mjs7.7 KB
- 脚本scripts/fframes.mjs45.3 KB
- 脚本scripts/init.mjs3.1 KB
- 脚本scripts/media.mjs5.1 KB
- 脚本scripts/narrate.mjs17.8 KB
- 脚本scripts/pack.mjs6.6 KB
- 脚本scripts/pieces.mjs2.9 KB
- 脚本scripts/preflight.mjs5.0 KB
- 脚本scripts/quiz.mjs4.1 KB
- 脚本scripts/render.mjs14.0 KB
- 脚本scripts/stage.mjs2.3 KB
- 脚本scripts/verdict.mjs2.0 KB
- 脚本test/audio-motion-speed.static.eval.ts33.2 KB
- 脚本test/captions-sync.static.eval.ts9.8 KB
- 脚本test/captions.static.eval.ts16.9 KB
- 脚本test/checks.static.eval.ts44.2 KB
- 脚本test/diff-first.eval.ts3.9 KB
- 脚本test/diff-repo.ts3.8 KB
- 脚本test/diff.static.eval.ts28.2 KB
- 脚本test/explain-video-renderer.eval.ts11.8 KB
- 脚本test/explain-video.static.eval.ts13.7 KB
- 脚本test/fframes.static.eval.ts42.6 KB
- 脚本test/run-dirs.ts1.9 KB
03 SKILL.md 正文
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...headdiff - 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_READYorBLOCKED_TOOLING(with the install step) - Consumers: Direct user invocation;
/vs-show-meor/vs-eli5pages 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
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); you write script.json and
the arms of ff/src/main.rs (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). Other topics:
read the named code; set "diff": {"none": "<why>"}. Put the question and viewer in question and audience.
3. Scaffold
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; a subagent can take that
file alone. Beats are ASD-STE100-style plain English:
../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).
No state carries between frames. Fallback: scenes.js, one scene(id, build)
whose update(t, B, D) does the same. Never use timers, requestAnimationFrame,
or CSS animations. Moves spring (rise, pop, spring_to); never move anything linearly.
Hold each build for its settle plus readTime(text) (read_time) first.
Every sentence gets a visual change. Start the build for beat i at B[i] (or
up to a second after, on the word that names it). A beat with no build is a
slide; redraw it as the example moving through the system. Kit helpers,
layout grid, and the design rules: references/motion-craft.md.
Short form: fixed colors (accent = under discussion, red = broken or removed,
green = fixed or kept), type 20px or larger, staggered entrances, keep old
state dimmed rather than removed, at most three regions, bottom 150px clear.
7. Check, then render
node <skill-dir>/scripts/fframes.mjs check "$WORK" [--scene <id>]
node <skill-dir>/scripts/fframes.mjs render "$WORK" --out "$WORK/<topic>.mp4"
check builds the crate (fix a Rust error at its line), renders each beat end
and scene end to stills/ with fframes' frame command, and audits them:
overlap, safe area, chapter bar, subtitles, text past its card or clipped,
SMALL text, and a beat that changes under 0.5% of the frame (NO-BUILD). Exit 1: fix each issue in main.rs once
(references/checks.md) and rerun once; what still
fails goes in the handoff. Then open each still and look at it: the checks
catch geometry and timing, not meaning. A frame you did not look at is not
verified. render muxes narration.wav and checks the ffprobe duration
against the timeline; on a mismatch report it, do not narrate again.
Fallback (Playwright) only, the same checks on scenes.js:
node <skill-dir>/scripts/render.mjs "$WORK" --stills
node <skill-dir>/scripts/check.mjs "$WORK"
node <skill-dir>/scripts/render.mjs "$WORK" --out "$WORK/<topic>.mp4"
Subtitles are burned in only. Do not add a soft subtitle track or a sidecar
.srt. Do not add HyperFrames, Remotion, or Manim to a project for this video;
the fframes crate lives in the work dir, its build in ~/.cache.
8. Fresh review
node <skill-dir>/scripts/pack.mjs "$WORK" "$WORK/<topic>.mp4"
Give the printed BRIEF.md, and nothing else, to a new agent that has seen
none of the work. Save its reply as review/REPLY.md and run
verdict.mjs "$WORK": PASS needs 8 or more on every axis, by the scores;
anything less is BELOW. One review: its score and three problems go in the
handoff. Do not re-render or review again. Never report a pass that did not
happen. Rules: references/reviewer-brief.md.
9. Handoff
Give the mp4 path as a file:// link, the stills folder, and a 2-4 line
TLDR: the question, the answer, the voice, the renderer (and any FALLBACK),
the length, the review verdict with its scores (or "not reviewed by fresh eyes"),
and any open quiz gap, word flag, or check failure. Listen-check is not
possible for the agent; say so. Mark anything not checked as unverified.
Topic: $ARGUMENTS
Apply the shared output style to every user-facing message.
Workflow
Direct: emit Next only. Composed: return to caller.
Prev: user ask, or a /vs-show-me page that needs motion
Next: done
Relevant: /vs-explain-pr
04 同仓库更多 Skills
vs-write
Use when asked to write, rewrite, edit, tighten, simplify, or polish prose for clarity, or to put text in STE, ASD-STE100, or controlled language. Produces plain, direct, accessible copy without losing substance or precision.
vs-fake-verify
暂无简介
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.