vox-explainer
Create a 60–90 second, collage-style HyperFrames explainer from a hiding-in-plain-sight topic or supplied documents and links. Use for requests such as 'make a plain-sight explainer', 'Vox-style history of X', 'why is X everywhere?', or 'turn this document into an explainer'. Covers topic or source routing, research, script, static design approval, voiceover timing, motion continuity, build, and numeric quality gates.
1How It Works & Mechanism
Both entry modes share a single gate: In topic mode, the four-question filter is used only for topic selection and trade-offs, and must never reject a user-specified topic (explain where it falls short, what is lost, and provide alternatives); in source mode, the filter is completely inapplicable, switching instead to reading all user materials and running the "storyline vein"—treating source material as a mine rather than an outline, extracting five elements: on-ramp / tension / turn / mechanism / receipts. For multi-source, multi-thread content, only one backbone is selected, and the rest are demoted to receipts.
- **Topic mode** (the user names a subject, or asks for ideas): the four-part filter governs IDEATION and tie-breaking only.
The structural backbone serves as an authoritative weighting table: FAMILIAR 15% → DIG (name specific person + date) 5% → STORY 15% → ARTIFACT 10% → MECHANISM (instantly verifiable on-screen by the audience) 20% → SECOND WIND 15% → THESIS (yellow circle) 10% → CLOSE 10%; THE FAMILY belongs to the latter half of FAMILIAR rather than being a new beat.
FAMILIAR 15% → DIG (person + date named) 5% → STORY 15% → THE ARTIFACT BEAT 10% → MECHANISM the viewer verifies on screen 20% → SECOND WIND (a technology removes a constraint) 15% → THESIS in the yellow circle 10% → CLOSE mirrors the open 10%.
The design pass first delivers a contact sheet (one frame per beat, 960×540 tile, HTML → headless Chrome screenshot) and conducts a LOOK GATE self-inspection prior to delivery: The palette must strictly use officially measured colors (ink #1a1a1a / yellow #FFE619 / process blue #66CFFF / specimen blue #58BCEC / greys / ground #fbfaf8), titles use Archivo Black, every frame must be a named recipe, and the yellow circle serves as a recurring visual motif; iterating here is 10x cheaper than making changes at the finished video stage. There is also an anti-contamination rule: do not inherit brand styling when source documents carry their own brand identity system (brand-faithful is a separate workflow).
Iterate here — it is 10x cheaper than comp notes.
Audio clock: VO is recorded first or generated via TTS (TTS input written as a pronunciation script: spell out numbers in full, write names phonetically), followed by transcription to extract word-level timestamps; thereafter, every cut, pop-up, and highlight is aligned to word timings—changing a VO track requires retiming the entire video. Subtitles transcribe "what was actually spoken" rather than the script file.
Transcribe the result for word timestamps — audio is the clock; every cut, pop, and highlight keys to a word time.
Seams are the core mechanism of this skill, functioning as a "generate + verify" two-piece suite: First write ledger.json (one line per seam: cut seconds, exit/entry axis+dir, motion-carrying selector, technique), use seam-stamp.mjs to stamp master seam code into index.html (replacing the // <seams:auto> block), and then numerically verify via seam-gate.mjs—ledger row consistency, exit still in motion at the cut point, entry must not start from a standstill, measured direction matches ledger, entry/exit velocity matches (WARN), zero-overlap (only one side visible in the same frame, no crossfades), Z-sign (scale change directions match on both sides, scanning if the incoming scene's own entry reverses sign), and carrier bounding box continuity (including ancestor scale, with a 12px/5% tolerance).
The script (usage + ledger schema: [seam-gate.md](seam-gate.md)) numerically enforces, per seam: ledger-row consistency, exit still moving at the cut, entry mid-flight (never from rest), measured direction = ledger direction, entry/exit speed match (WARN), **zero overlap** (one side visible per frame — the cut is not a dissolve), the **Z sign** rule
Anti-slide floor and technical declarations: Each beat must explicitly **declare** its layout recipe and motion technique during the beat map stage (no improvisation during assembly). The entire video must clear the minimum thresholds (≥1 zoom-isolation driving into and punching through the carrier for a scene transition, ≥1 inverse zoom-through for payoff, ≥2 drive-past/scale traversals ending in full-bleed framing, ≥1 background-stripped cutout performing motion impossible on flat cards, ≥1 newsprint layering with circle reveal), backed by hard upper limits (static cards/side-by-sides ≤ 1 per 3 beats; adjacent beats cannot share the same recipe and technique).
- CAPS: static-card / side-by-side layouts ≤ one third of beats; no two consecutive beats share the same layout recipe or the same treatment.
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | HyperFrames 预览服务（版本钉在脚本常量里：0.8.14；--project 模式下由 npx 拉起，未缓存时会从 npm 下载；可改用 --url 复用已在跑的服务） |
| cli | 上游脚手架/技能安装：npx skills add heygen-com/hyperframes、npx hyperframes init |
| cli | Node 22+ 与本地 Chrome/chrome-headless-shell（verifier 自找 Puppeteer 缓存或系统 Chrome，用隔离临时 profile） |
| network | source 模式会抓公开引用与公共领域/开放许可资产（最多一跳公开引用），资产来源为 Wikimedia Commons API、LOC 等声明的来源 |
| api | 可选的第三方 TTS / 转写 API（须先向用户说明 provider、数据、所需凭据与可能成本并获得批准） |
| network | 预览期仍可能加载构图自身声明的远端资产（verifier 只把 --url/--comp-url 限制为 localhost，不限制页面内的远端引用） |
4Recommended Governance & Evidence
- scripts/: Executes local script or command: node <SKILL_DIR>/scripts/seam-stamp.mjs --ledger ledger.json --write index.
- 网络端点: Declares external network access: registry.npmjs.org: In --project mode, uses npx to spin up pinned HyperFrames preview service (downloads when not cached); npx ski
- 本地工作目录: File read/write and artifact output: Within user project directory: index.html (replaces only // <seams:auto> block), project source code, downloaded assets, audio/, contact sheet, r
5Second-Pass Verification
- [ok] 『--url/--comp-url 只接受 localhost』是否真在代码里 — seam-gate.mjs 有 localUrl(value, label) 校验函数，非 localhost 直接报错；--project 模式自己 spawn 预览服务后拼 http://localhost:<port> 再连。文档声明与实现一致。
- [ok] seam-gate 到底验什么（本题重点） — 逐 seam 的报告行对应规则：ledger（plan 层 exit/entry 向量一致）、exit-moving / entry-moving（规则1/3：不许静止退出、不许从静止入场）、exit-direction / entry-direction（实测符号 = ledger 符号）、speed-match（law §3 速度匹配，仅 WARN）、zero-overlap（规则6：同帧只有一侧可见，切口不是叠化）、z-sign-scan（规则7：incoming 场景自身入场不得与 Z 符号打架）、carrier-*（规则3/4：carrier 矩形连续性，含祖先 scale，12px/5% 容差）。速度不匹配只是警告，不是失败——使用者需自己看警告与渲染帧对。
- [ok] 子进程环境是否被显式过滤 — previewEnv() 只取 15 个白名单系统变量 + npm_config_audit/fund，不用 process.env 整包；另单独读 CHROME_PATH 找浏览器。
- [ok] stamp 的写入边界 — seam-stamp.mjs 的 --write 目标 resolve 后必须落在当前项目目录内，且拒绝符号链接（lstatSync 判定）——降低借 ledger 写项目外文件的面。
- [ok] 文档量化门禁是否都有出处 — 色值/字体/recipe 命名在 vox-collage-layout.md 与 SKILL.md 的 LOOK GATE；运动法则与反模式表在 motion-continuity.md；转场代码与占位符在 velocity-matched-transitions-gsap.md；ledger schema 与容差在 seam-gate.md。引用链完整。
- [unlocatable] 『Grammar measured from Vox's Cooper Black film』所述测量过程与样本 — 该测量（以及 motion 的 frame-by-frame calibration）的过程与数据不在本 skill 目录内，无测量脚本或样本文件；只作为文档声明记录，本次只读侦查未运行 verifier 或渲染，故不作为已核事实使用。
6Verdict & Scenarios
e75b209b1949465d…