Content & Media Creation · heygen-com/hyperframes
faceless-explainer
Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The core premise is 'no assets to capture': deliberately avoid running capture, creating asset-descriptions.md, or populating capture/assets/; all visuals are invented downstream (typography, abstract graphics, diagrams, data visualizations).
skills/faceless-explainer/SKILL.md
Do **not** run `npx hyperframes capture` (there is no URL). Do not create `asset-descriptions.md` or populate `capture/assets/` — faceless visuals are invented in Steps 4-5, not captured.
What is happening here: It shares the same six-step pipeline with product-launch-video from the same batch (identical Step 0/3/6 user gates and script names), but replaces Step 1's capture with 'saving raw user text into visible-text.txt + manually crafting a tokens.json'. The Quick Reference explicitly lists four key differences under 'Faceless deltas vs a captured-asset workflow'.
The design system does not rely on hand-crafted color palettes: after selecting a shipped frame preset, build-frame.mjs remaps the preset's FRAME.md into the project's frame.md and generates the caption skin; if no brand color is provided, the preset's full palette is retained.
skills/faceless-explainer/SKILL.md
A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors/fonts empty) → the script keeps the preset's own palette, a complete shippable design.
What is happening here: The 'design system' is reduced to a single selection (picking a preset) plus a deterministic command with 'no hand-editing of the spec'. The script exits with code 1 if self-validation fails.
Story ordering stems from narrative design rather than the paragraph sequence of the input text: explicitly requires reordering, merging, omitting, and compressing, while selecting candidate shot shapes for each beat from a 'role → blueprint' menu—without inventing beats merely to fit shapes.
skills/faceless-explainer/SKILL.md
The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress.
What is happening here: When the source material is an article or unstructured notes, the laziest approach is illustrating paragraph by paragraph. Step 3 explicitly forbids this and dictates that blueprints serve only as soft guidelines ('Teaching truth still decides which beats exist — never force a beat to fit a blueprint').
Voiceovers and music are handled via media-side scripts: voice/provider can be specified, default voices are hardcoded in the workflow (HeyGen Marcia / Kokoro am_michael), and a standardized marker combination is defined for 'completely muted'.
skills/faceless-explainer/SKILL.md
The pipeline default is otherwise **Marcia (female)** on HeyGen / `am_michael` on Kokoro — so a request like "a male voice" is silently ignored unless you pass the flag.
What is happening here: Silent mismatches (e.g., user requested a male voice but the default is female) are treated with explicit warnings, requiring provider resolution before obtaining the voice ID. The mute marker is `music: none` (YAML at top of STORYBOARD) plus no SCRIPT.md. Once detected, audio.mjs purges stale audio_meta.json (absent = mute), skipping both Step 5 duration sync and fetch-sfx.
One sub-agent per frame during construction: the packet builder inlines 'the frame's storyboard block + blueprint body + all referenced rules' into a bounded packet and composes the complete worker role file _role.md; the worker only reads these two documents.
skills/faceless-explainer/SKILL.md
Workers read only their packet and `frame.md`; they never open `STORYBOARD.md` or the skill documents (the packet inlines what was selected upstream). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
What is happening here: Context isolation is enforced as a hard constraint—workers lack global visibility and cannot arbitrarily alter the storyboard. The orchestrator marks the frame as animated once the worker returns. Frame backgrounds (solid/gradient/grid) must be attached to the `class="clip"` layer rather than #root, because #root's background can be clipped to the frame window, potentially rendering dark content invisible against a black body.
Finalizing gates plus an explicitly documented known false positive: check may report a 1–4px text_box_overflow on caption words; the skill mandates ignoring it rather than papering over it with inflated line-height.
skills/faceless-explainer/SKILL.md
**Known false-positive — do not chase it.** `check` may report a handful of `text_box_overflow` findings of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`).
What is happening here: Criteria distinguishing 'tool noise vs. real defects' are built into the workflow (action is only required when pointing to frame elements `#el-NN-*`). It warns against masking issues with inflated line-height—codifying engineering experience into discipline to prevent agents from idling on false positives.
Review and render gates: inject/verify transitions, lint, check, and generate snapshot contact sheets first, pause for the user to review in Studio preview, and only then render MP4; lint/check/snapshot are not rerun after rendering.
skills/faceless-explainer/SKILL.md
**Gate:** `lint` and `check` passed and the snapshots were inspected before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states MP4 path and final duration.
What is happening here: Separates 'checks passed' and 'human reviewed' into distinct conditions. In autonomous mode, this collapses into a single reserved question: 'preview first or render directly?' (standard phrasing from brief-contract).
2Core Capabilities
01Arbitrary text → faceless explainer video (topic explainers, concept breakdowns, how-tos, listicles) with all visuals invented on the fly
02Synthetic input bundle: stores verbatim user text + crafts minimal tokens.json (title/description/optional brand colors and fonts), preserving user scripts (VO_MODE verbatim/restructured)
03Single-script design system: preset → frame.md + caption skin (including role-based brand token remapping and self-validation)
04Explainer structural design: hook strategies, value before proof, clarity techniques, emotional beats, archetype mapping, and VO_MODE
05Frame-by-frame visual design (timecoded shot sequences + inline Layout/motion vocabulary + video-level ## Video direction block), with concurrent audio track initiation
06Parallel frame-by-frame construction (one sub-agent per frame, packet + _role.md) and caption/assembly pipeline (background captions + assemble-index)
07Standardized handling of muted projects (combined semantics of `music: none` + no SCRIPT.md, including purging stale audio_meta.json)
08Draft storyboard (sketch pass) in collaboration mode: wireframes per frame first, prompts a single layout question once filled, and only modifies specified drafts
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（init / lint / check / snapshot / preview / render / skills update；注意本 skill 不调用 capture） |
| api | HeyGen（TTS 与音乐库检索；凭证 ~/.heygen，由媒体侧脚本使用） |
| api | 本地离线 TTS（Kokoro）作为无登录态降级路径 |
| cli | ffprobe / ffmpeg（装配期音频探测与补齐，由 assemble-index.mjs 调用） |
| network | GSAP CDN（写进装配产物 HTML，带 SRI 完整性校验） |
| cli | media-use 侧脚本（prefs.mjs 记偏好、recipe.mjs 应用配方、heygen-tts.mjs 列语音） |
| package | 兄弟 skill 依赖（/hyperframes 路由、/hyperframes-core、/hyperframes-creative 的 frame-presets、/hyperframes-animation 的 blueprints+rules、/media-use） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local script or command: node scripts/build-frame.mjs --preset <name> --hyperframes . (step 2 design system, writes frame.md)
- 网络端点: Declares external network access: HeyGen Audio API (TTS voice synthesis and music library search via media-side script/CLI, credentials in ~/.heygen)
- 本地工作目录: File I/O and artifact generation: videos/<project>/hyperframes.json, BRIEF.md, capture/extracted/visible-text.txt
Audit Notes: The orange rating is triggered by the **credential footprint**: audio steps use ~/.heygen credentials to call HeyGen (TTS synthesis + music catalog retrieval), falling back to local Kokoro only when unauthenticated; additionally, the process requires relaying output from `npx hyperframes auth status` directly to the user (exposing account state in conversation). Otherwise, behavioral footprint is clean: this skill does not scrape websites or probe visual keys (unlike product-launch-video), all 17 scripts make zero HTTP calls, and generated HTML references SRI-hashed CDN assets. It warrants orange rather than yellow because relying on external account credentials and third-party services for core functionality entails potential costs and cross-border data transfer that users must evaluate.
5Second-Pass Verification
- [ok] 『无抓取、无视觉 key』这一关键差异是否属实 — 整目录 grep GEMINI/GOOGLE_API_KEY/OpenRouter → 0 命中；SKILL.md 明确 'Do **not** run `npx hyperframes capture` (there is no URL).'；URL 扫描仅 2 处（同一 gsap CDN 字符串出现在 assemble-index.mjs 与 captions.mjs）。差异成立。
- [discrepancy] 是否与 product-launch-video 真正共享脚本（第一遍的资产描述是否正确） — 第一遍初稿把本 skill 写成『无 build-frame』——复核发现**错误**：Step 2 原文就是 `node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .`，scripts/ 下确有 build-frame.mjs。真实差异是：本 skill 无 capture（Step 1 改为手造输入包）、无 stage-assets（SKILL.md 写明 'There is **no asset-staging step**'），而 build-frame / audio / captions / transitions / frame-packets / assemble-index 六个脚本两家都有。已按源码更正 analysis 与 internal_assets 的表述。
- [ok] 『外部资源』逐条回查调用点 — hyperframes init/lint/check/snapshot/preview/render 均在 SKILL.md 出现；HeyGen 与 ~/.heygen 在 Step 3.1 原文；Kokoro 离线降级与 am_/bm_ 前缀在 Step 3.1 原文；prefs.mjs/recipe.mjs 在 Step 0 原文并定义了 <MEDIA_DIR>；ffprobe/ffmpeg 在 assemble-index.mjs 的 spawnSync 可验。
- [ok] 静音标记的实现语义是否与文档一致 — SKILL.md 规定 `music: none` + 无 SCRIPT.md = 全静音，且『audio.mjs recognizes it and generates nothing (it removes any stale audio_meta.json; an absent audio_meta.json is what assemble treats as silent)』；Step 5 的 sync-durations / fetch-sfx 在静音时跳过。语义自洽（以「文件不存在」作为静音的真值载体）。
- [unlocatable] 正文自述的已知假阳性是否真实存在于工具链 — SKILL.md 声称 `check` 会在 caption 高亮词上报 1–4px 的 text_box_overflow（选择器 `#caption-word-*` / `.caption-line`），且该 pill 的 snug line-height 由 scripts/captions.mjs 设定。caption pill 的 line-height 设定可在本 skill 的 captions.mjs 中定位，但『该假阳性确实会出现』这一行为需要实际跑 `npx hyperframes check` 才能证实——本任务为只读侦查，未执行构建/渲染（亦被任务书禁止）。故记为无法在源码内定位，不做进一步断言。
6Verdict & Scenarios
Best for: Ideal for talking-head/voiceover explainer videos where only raw text is available (articles, rough notes, a topic, or a brief) with zero existing assets or websites: concept breakdowns, how-tos, listicles, or compressing long-form content into a pedagogically paced short video. Also suitable for bilingual (Chinese/English) workflows—TTS powered by HeyGen or local Kokoro, with captions and storyboard formats consistent with other HyperFrames workflows (facilitating reused project directory habits).
Not for: Not suitable for: 1) Promo or product tour videos with existing websites or UI to show—use /product-launch-video (specified in description); 2) Short, voiceover-free, motion-centric pieces—use /motion-graphics; 3) Videos requiring real-world footage, live capture, or product screenshots—this skill explicitly avoids capturing or cataloging assets, with the sole exception of a single image placed manually in public/<basename>; 4) Completely offline environments refusing any external credentials/accounts (audio defaults to HeyGen, with partial fallback to Kokoro); 5) Direct unattended exports expecting zero approvals—Step 0/3/6 enforce user gates; 6) Workflows requiring strict 1:1 paragraph-by-paragraph illustration matching the source document order (this skill explicitly mandates reordering/merging/omitting).
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload faceless-explainer.tar.gz
sha256:
Option B · Copy Guide for Agent2b565aaa0ac76062…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.