Content & Media Creation · heygen-com/hyperframes
talking-head-recut
Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite 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
Positioned as "graphic packaging" rather than subtitling: the source footage plays fully without edits, while the agent composes card HTMLs (timing + content) card-by-card in the conversation, assembling them into a composite HTML rendered to MP4 via hyperframes; there is no fixed card-type roster, as cards are derived directly from the transcript.
skills/talking-head-recut/SKILL.md
Talking Head Recut takes a local video that **plays in full** and layers a sequence of timed, designed **graphic cards** onto it — titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to what's being said. The agent designs the cards (timing + content) and **writes each card's HTML directly in the conversation**, then assembles a single composition HTML and renders it to MP4 via `hyperframes`. There is no fixed archetype list and no prescribed card structure — the overlays emerge from what the transcript actually says.
What is happening here: Clearly distinguishes its division of labor from its sibling embedded-captions (which adds verbatim subtitles)—SKILL.md defines them as complementary ('Captions add the _spoken words_ as a readable subtitle; this adds _designed graphics_ on top of the playing video.') and provides reverse routing (Plain subtitles → embedded-captions).
Execution relies exclusively on this repository's CLI and system ffmpeg/ffprobe: transcription uses local Whisper, with no third-party services, API keys, proxies, or rate limits.
skills/talking-head-recut/SKILL.md
This skill runs entirely on the **hyperframes** CLI plus system `ffmpeg` / `ffprobe`. Transcription is local **Whisper** via `hyperframes transcribe` — no third-party service, API key, or rate-limited proxy.
What is happening here: Explicitly documented as a refactor outcome in NOTICE.md—the original project used the third-party `@notedit/vtake` CLI and `vtake.app` proxy for transcription; this repository replaced it with `hyperframes transcribe` (local Whisper) and removed the hardcoded branded outro. Therefore, this skill reads no credentials.
Steps 3-5 are purely local media processing: ffprobe extracts width/height/framerate/duration, ffmpeg extracts mp3, hyperframes transcribe outputs a **flat word array** transcript.json, and the agent corrects misheard words and segments sentences based on punctuation/pauses.
skills/talking-head-recut/SKILL.md
`transcript.json` is a **flat array of word objects** — `[{ "text": "...", "start": s, "end": s }, …]` (no `segments` array, no `words` wrapper; the per-word key is **`text`**). Read it and fix obvious ASR errors:
What is happening here: Hardcodes the "lack of segment structure" as a strict constraint (preventing models from searching for missing segments or words wrappers), requiring humans/models to correct homophones, product names, and terminology while **retaining original timestamps**; also applies a "clamp to media duration" rule to prevent trailing Whisper words from overshooting and causing a black tail.
The rendering strategy enforces an explicit one-time 4-question gate (aspect ratio / layout / style / card density) with precomputed recommendations (recommendedRatio from source aspect ratio, autoCount from video duration), accompanied by a 3-tier host fallback for user prompts.
skills/talking-head-recut/SKILL.md
**Environment compatibility — pick the best available question channel.** Not every runtime exposes the same structured-question tool. Apply this order: 1. **Native clarification tool** — use the structured 4-question call below. 2. **Other native clarification tool** (e.g. `ask_question`, `request_user_input`, IDE-specific prompt) — use that tool with the same 4 question texts and option lists. Preserve the recommendation markers and the precomputed values. 3. **No native tool** (Codex CLI, plain text-only runtimes) — **ask directly in normal conversation**.
What is happening here: Since different hosts (Claude Code / Codex CLI / IDE) provide different prompting tools, the skill defines a fallback sequence while keeping consistent options and recommendation tags; it also adheres to a global limit of '2–5 questions per round'. If the user pre-authorizes defaults or passes autonomous signals, it adopts recommendedRatio + layout=stack + neutral style + autoCount and notes this in the response.
The design space is decoupled into three orthogonal dimensions: 10 styles × 4 layouts × 3 framing options = 120 combinations, each defined as a self-contained HTML snippet (scoped <style>, no <script>, no external URLs, animations strictly via data-anim-*).
skills/talking-head-recut/references/DESIGN_INDEX.md
Style × Layout × VideoFrame (10) (4) (3) = 120 possible combinations
What is happening here: Structures design flexibility into a searchable reference library rather than having the model improvise. The document mandates that every reference snippet adheres to the card contract: 'scoped `<style>`, no `<script>`, no external URLs, animations only via `data-anim-*`'—which also explains why assets/vendor/gsap.min.js is bundled with the skill and copied to the working directory (ensuring offline usability).
Two strict rules during assembly: ① The input video must be re-encoded with dense keyframes (otherwise a sparse GOP causes the renderer to freeze on seek); ② The video is embedded as muted <video> while the root audio track #source-audio is linked to the same source, preserving original audio while enabling independent volume and ducking control.
skills/talking-head-recut/SKILL.md
ffmpeg -y -i "$VIDEO_PATH" -c:v libx264 -crf 18 -g 30 -keyint_min 30 \ -pix_fmt yuv420p -movflags +faststart -c:a aac "$WORK_DIR/public/input-video.mp4"
What is happening here: The annotations explain the rationale—'Sources with a sparse GOP (keyframe interval > ~1s) freeze on seek in the renderer (a frozen frame under the overlays)'. The reason for audio separation is: 'This uses a separate audio track rather than data-has-audio="true" so its volume and ducking remain independently controllable on the timeline.'
Includes a structural assertion test against the content of SKILL.md itself: verifies that the 'canonical composite' preserves the source video as muted video + source audio, and checks that both tracks match in src/data-start/data-duration while having distinct track indices.
skills/talking-head-recut/media-contract.test.mjs
assert.equal(readAttribute(audio, "src"), readAttribute(video, "src")); assert.equal(readAttribute(audio, "data-start"), readAttribute(video, "data-start")); assert.equal(readAttribute(audio, "data-duration"), readAttribute(video, "data-duration")); assert.notEqual( readAttribute(audio, "data-track-index"), readAttribute(video, "data-track-index"), );
What is happening here: This is the only executable code in the entire skill, and it tests the **documentation itself** (reading SKILL.md as text and asserting against property contracts in the sample composite). It functions as a documentation consistency regression test—preventing future edits to SKILL.md from breaking canonical examples.
2Core Capabilities
01Package existing talking-head / interview / podcast videos with timed design cards (kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture)
02Multi-aspect ratio output (16:9 / 9:16 / 4:5) with precalculated recommendations and rationales based on source dimensions
03Cross-host structured prompt fallback (native tool → alternate native tool → plain text 4-question gate) adhering to per-round question caps
04Local transcription and timeline alignment (flat word array + self-segmentation + ASR error correction + media duration clamping)
05Reference library of 120 style × layout × framing combinations (each a self-contained HTML snippet with no scripts or external URLs)
06Inlined HF layout/animation QA rules (static hero frame first, animate overlay only, lint constraints including data-track-index/data-duration, clip classes, and specific font names)
07Single-frame snapshot self-inspection and rendering (including macOS GPU rendering toggles)
08Delivery report specification + optional live preview (launched only upon user request and strictly post-render)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（doctor / transcribe / render / snapshot / preview / skills update） |
| cli | ffmpeg / ffprobe（系统依赖：取元数据、抽音频、重编码输入视频） |
| cli | 本地 Whisper（经 hyperframes transcribe，无 key/无代理） |
| package | GSAP 3.15.0（随包 vendored，复制进工作目录的 public/vendor/） |
| package | 随包字体（Inter / Caveat / Virgil / LXGWWenKaiTC，woff2） |
| network | hyperframes skills update（自刷新，需网络；本 skill 唯一需要联网的环节） |
| package | 上游开源项目（本 skill 卡片设计系统的来源，仅署名引用，非运行时依赖） |
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 scripts or commands: (No bundled production scripts) Workflow instructs the host to run: npx hyperframes doctor / transcribe / render / snapshot
- 本地工作目录: File I/O and artifact output: videos/<project>/metadata.json, audio.mp3, transcript.json, storyboard.json (ag
Audit Notes: Very restrained behavioral footprint: the only executable code in the entire directory is a test file (which only reads SKILL.md as text to run assertions), with zero production scripts; the workflow relies entirely on the repository's hyperframes CLI and system ffmpeg/ffprobe, executing fully locally; transcription runs on local Whisper (no keys, no proxies, no rate limits); no credential access, storage, or third-party API calls detected; GSAP and fonts are bundled locally, requiring no internet connection for rendering. The only network call is a self-refreshing `skills update`. It is not rated green purely because the workflow reads/writes local user videos and transcript files (persisted in the working directory without automatic cleanup), and outputs local HTML containing GSAP scripts.
5Second-Pass Verification
- [ok] 是否真的无凭证、无第三方 API（蓝档判定的关键） — 整目录 grep：(API_KEY|TOKEN|SECRET|\.env|keychain|Bearer|Authorization) 命中 15 处全为 'tokens' 子串误配（设计 token 语境）；heygen/OPENAI/ANTHROPIC 0 命中；process.env 0 命中；fetch 0 命中。SKILL.md 与 NOTICE.md 双重声明转录为本地 Whisper。结论成立。
- [ok] 『无脚本』是否属实（有没有隐藏的执行体） — 全量清单中 .mjs 仅 1 个且为测试；无 .sh/.py/.cjs。流程里的命令是文档中给宿主执行的 ffmpeg/CLI 调用，不是随包脚本。『runs entirely on the hyperframes CLI plus system ffmpeg/ffprobe』表述与文件构成一致。
- [ok] 『外部资源』逐条回查调用点 — npx hyperframes doctor/transcribe/render/snapshot/preview 均在 SKILL.md 原文；ffprobe/ffmpeg 两条命令在 Step 3 原文、重编码命令在 Step 9 原文；随包字体与 gsap 的复制命令在 Step 9 原文；上游仓库链接在 NOTICE.md 原文。无推测项。
- [discrepancy] 转录模型选择与同批 skill 的口径差异 — 本 skill 硬编码 `--model small.en`（Step 4 原文），而同仓 embedded-captions 的 transcribe.cjs 明确**禁止**默认 small.en（注释：'Default = multilingual `small`, NOT `small.en`. Per media-use: ".en models mistranslate non-English and mis-handle accented speech"'，并记录了曾被 small.en 在重口音说话人上产出错误转录的实例）。本 skill 在 description 中虽未宣称多语种，但也没有对非英语素材给出提示。这是**同一仓库内两个 skill 对同一问题给出相反默认**的真实出入，对非英语/重口音素材的使用者有实际影响（本 skill 使用者也可能会中同样的坑）。
- [ok] vendored GSAP 的许可约束是否被标注 — assets/vendor/gsap.min.js 文件头写明 'GSAP 3.15.0 … @license Copyright 2026, GreenSock. All rights reserved. Subject to the terms at https://gsap.com/standard-license.'；随包分发即意味着产出物沿用该许可约束（同批其它 skill 走 CDN 引用、许可披露方式不同）。已在 meta.license 与 risks 中记录。
- [unlocatable] 验证：渲染/预览类声明是否可在源码内证实其行为 — SKILL.md 描述的行为（稀疏 GOP 导致渲染器 seek 卡帧、单帧 snapshot 的位置与命名、`--at` 单值会忽略 --out）需要实际运行 hyperframes render/snapshot 才能证实；本次为只读侦查且不得运行构建/渲染，故记为无法在源码内定位，不作为已验证事实。
6Verdict & Scenarios
Best for: Ideal for users with existing talking-head, interview, or podcast footage who want to "package" it without trimming or color-grading the original: adding kinetic titles, lower-thirds, data callouts, quote cards, sidebars, and PiP while tailoring to platform formats (16:9 / 9:16 / 4:5). Also ideal for privacy-focused and offline workflows—featuring local Whisper transcription, zero API keys/proxies, and dependencies that are entirely bundled or rely on system tools, making it the most self-contained skill in the triad. Design-wise, it provides 10 styles (including Xiaohongshu-tailored Chinese aesthetics) and bundled Chinese KaiTi fonts.
Not for: Not suitable for: ① Users who only want verbatim subtitles (use /embedded-captions instead; description explicitly notes 'Not plain subtitles'); ② Generating videos from scratch (use generative workflows like product-launch-video or faceless-explainer); ③ Standalone standalone motion graphic clips (use /motion-graphics); ④ Trimming or rearranging footage—this skill requires the source video to play **fully untouched** without timeline cuts; ⑤ Non-English or heavily accented media where users are unwilling to adjust the transcription model (the default small.en poses known risks); ⑥ In-process visual reviews (preview is not opened during execution, only on demand post-render); ⑦ Confidential media requiring immediate trace cleanup (the working directory retains source copies and transcripts by default).
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload talking-head-recut.tar.gz
sha256:
Option B · Copy Guide for Agentff96f4df7b933a0f…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.