1实现原理 · 为什么它能做到
定位是「图形包装」而不是字幕：原片完整播放不加剪辑，agent 在对话里逐张写卡片的 HTML（时间 + 内容），再组装成一个合成 HTML 交给 hyperframes 渲成 MP4；没有固定卡型清单，卡片由转录内容决定。
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.
这里在做什么：与同批 embedded-captions（加逐字字幕）明确分工——SKILL.md 把两者写成姊妹关系（'Captions add the _spoken words_ as a readable subtitle; this adds _designed graphics_ on top of the playing video.'），并给出反向路由（Plain subtitles → embedded-captions）。
执行面只有本仓 CLI 与系统 ffmpeg/ffprobe：转录走本地 Whisper，无第三方服务、无 API key、无代理、无速率限制。
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.
这里在做什么：这是 NOTICE.md 里明写的改造结果——原项目用第三方 `@notedit/vtake` CLI 与 `vtake.app` 代理做转录，本仓把它换成 `hyperframes transcribe`（本地 Whisper），并去掉固定品牌片尾。因此本 skill 无任何凭证读取。
步骤 3-5 是纯本地媒体处理：ffprobe 取宽高/帧率/时长、ffmpeg 抽 mp3、hyperframes transcribe 出**扁平词数组** transcript.json，然后 agent 自己改错词并自行按标点/停顿切句。
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:
这里在做什么：把「没有分段结构」这件事写成硬约束（模型容易去找 segments 或 words 包装），并要求人工/模型修正同音词、产品名、术语后**保留原时间戳**；另有『钳到媒体时长』的规则防 Whisper 末词越过片尾造成黑尾。
渲染策略是显式的一次性 4 问门禁（画幅 / 布局 / 风格 / 卡片密度），并预计算推荐值（按源片宽高比推 recommendedRatio、按视频时长推 autoCount），且给出跨宿主的三级问询通道降级。
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**.
这里在做什么：不同宿主（Claude Code / Codex CLI / IDE）的问询工具不同，skill 给出降级顺序并保持同样的选项与推荐标记；同时遵守『每轮最多 2–5 问』的全局上限。若用户已预先授权默认值或走自主信号，则直接采用 recommendedRatio + layout=stack + 中性风格 + autoCount 并在回复里说明。
设计维度被拆成正交三维：10 种风格 × 4 种布局 × 3 种画面框 = 120 种组合，每种是一个自包含 HTML 片段（作用域内 <style>、无 <script>、无外链、动画只走 data-anim-*）。
skills/talking-head-recut/references/DESIGN_INDEX.md
Style × Layout × VideoFrame (10) (4) (3) = 120 possible combinations
这里在做什么：把设计自由度做成可检索的资料库而不是让模型现编。同文件规定每个参考片段遵守卡片契约：'scoped `<style>`, no `<script>`, no external URLs, animations only via `data-anim-*`'——这也解释了 assets/vendor/gsap.min.js 为何由 skill 自带并复制到工作目录（保证离线可用）。
装配期两个硬规则：① 输入视频必须重编码成密集关键帧（否则稀疏 GOP 会让渲染器 seek 时卡帧）；② 画面用 muted <video>，同一源另挂根级 #source-audio 音轨，从而保住原声且音量/闪避可独立控制。
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"
这里在做什么：注释解释理由——'Sources with a sparse GOP (keyframe interval > ~1s) freeze on seek in the renderer (a frozen frame under the overlays)'。音频分离的理由是 'This uses a separate audio track rather than data-has-audio="true" so its volume and ducking remain independently controllable on the timeline.'
带一个针对 SKILL.md 自身内容的结构断言测试：校验「权威合成」确实把源视频以 muted video + 同源 audio 的形式保住，且两条轨道的 src/data-start/data-duration 一致、track 不同。
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"), );
这里在做什么：这是本 skill 唯一的可执行代码，且它测的是**文档本身**（读 SKILL.md 文本，断言其中示例合成的属性契约）。属于文档一致性回归测试——防止后人编辑 SKILL.md 时把权威示例改坏。
2核心能力
01用带时间的设计卡片包装既有口播/访谈/播客视频（动力标题、下三分之一、数据标注、引用、侧栏、画中画）
02多画幅输出（16:9 / 9:16 / 4:5），并按源片宽高比预计算推荐值与理由标签
03跨宿主的结构化提问降级（原生工具 → 其它原生工具 → 纯文本四问），并遵守每轮问数上限
04本地转录与时间轴对齐（扁平词数组 + 自行切句 + 修正 ASR 错误 + 钳到媒体时长）
05120 种风格×布局×画面框组合的参考库（每份为自包含、无脚本、无外链的 HTML 片段）
06HF 版面/动画 QA 规则内联（先做静态主帧、动画只动包装层、用 data-track-index/data-duration、clip 类与具体字体名等 lint 约束）
07单帧快照自检与渲染（含 macOS GPU 渲染开关）
08交付报告规范 + 可选实时预览（仅在用户要求时启动，且渲染后）
3外部依赖
| 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 卡片设计系统的来源，仅署名引用，非运行时依赖） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: (无自带生产脚本) 流程要求宿主执行：npx hyperframes doctor / transcribe / render / snapshot
- 本地工作目录: 文件读写与工件输出: videos/<project>/metadata.json、audio.mp3、transcript.json、storyboard.json（ag
审计说明： 。行为面非常克制：整目录只有一个测试文件是可执行代码（且只读 SKILL.md 文本做断言），没有生产脚本；流程依赖本仓 hyperframes CLI 与系统 ffmpeg/ffprobe，全部本地执行；转录用本地 Whisper（无 key、无代理、无速率限制）；未发现任何凭证读取、凭证存储或第三方 API 调用；GSAP 与字体随包分发，渲染不依赖外网。唯一网络动作是自刷新 `skills update`。之所以不落绿色：流程会读写用户本地视频与其转录文本（并落盘工作目录不自动清理），且产出物是含 GSAP 脚本的本地 HTML。
5第二遍独立确认
- [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 才能证实；本次为只读侦查且不得运行构建/渲染，故记为无法在源码内定位，不作为已验证事实。
6结论
适合： 适合已有口播/访谈/播客原片、想在不剪不调色原片的前提下「包装」成片的人：加动力标题、下三分之一、数据标注、引用卡、侧栏与画中画，并需要按平台选 16:9 / 9:16 / 4:5。也适合关注隐私与离线能力的用户——转录本地 Whisper、无 key 无代理、依赖全部随包或系统工具，是三件套里最『自包含』的一个；设计上还提供 10 种风格（含 xhs 中文平台风格）与中文楷体字体。
不适合： 不适合：① 只想要逐字字幕（应走 /embedded-captions，description 明确排除 'Not plain subtitles'）；② 需要从零做片子（应走 product-launch-video / faceless-explainer 等创建类 workflow）；③ 需要单人独立的动效短片（走 /motion-graphics）；④ 需要剪掉片段/重排素材的需求——本 skill 的前提是原片**完整播放**，不做时间线剪辑；⑤ 非英语或重口音素材且不愿手动调整转录模型的使用者（默认 small.en 有已知风险）；⑥ 期望流程内可视复核的用户（运行中不打开预览，只有渲染后按需预览）；⑦ 需要严格清理痕迹的涉密素材（工作目录默认保留原片副本与转录）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload talking-head-recut.tar.gz
sha256:
Option B · Copy Guide for Agentff96f4df7b933a0f…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.