1实现原理 · 为什么它能做到
真正的选型面是一张 35 行的身份目录（10 classic DNA + 25 themed），引擎与作者文件由查表推导；SKILL.md 明确禁止把后端引擎名当作问题抛给用户。
skills/embedded-captions/SKILL.md
**Never surface "Standard vs Cinematic vs Theme" as a question** — those are backend names (a product has one UX even with several engines). The catalog encodes everything routing needs: reading surface, voice, recommend-for, scene needs, adjacency notes for the genuinely-close pairs (loud↔ordnance, neon↔neonsign, cream↔stardust).
注：这里在做什么：把「三套引擎」的复杂度关在产品内部。用户只选视觉身份（如 anchor/cream/ordnance），skill 用 CATALOG.md 的行推出作者文件与编译链。复核：CATALOG.md 实际有 35 个 `| \`` 开头的身份行；dna/ 下 10 个 json；themes/ 下 25 个 json——三者自洽。
字幕被建模成三态：drop（填充词，不显示）/ rail（逐字下三分之一字幕，在前，承载大部分文本）/ embed（被提升的高峰词，合成到主体背后，由抠像产生遮挡）。embed 被规定为稀缺品。
skills/embedded-captions/SKILL.md
| **rail** | the default — ordinary spoken content (verbatim) | clean lower-third subtitle, **in front**, readable. A punch word can get an inline `emphasis` highlight (accent colour / active-word pop) — it stays on the rail. | | **embed** | a promoted peak — the headline beat | one big word composited **behind the subject** (matte occlusion), designed entrance + exit |
注：这里在做什么：用「遮挡」当特效来源——先对视频做人物抠像，再把高峰词放在主体层之下，于是文字被人物挡住再露出。稀缺性是硬规则：'≤1 hero per block (thought), never two co-visible, ≥ a beat of air between hero windows (the compiler warns under 0.6s)'，并且多 hero 中只有最大的那个（APEX）享受完整 lockup。
预处理是一条并行命令：抠像 ∥ 转录 ∥ 音频包络 三路同时跑，再串行算 safe-zones——把「手跑三步容易漏」变成一次调用。
skills/embedded-captions/scripts/prepare.sh
# matte.cjs (CPU-heavy ONNX) ∥ transcribe.cjs (whisper) → then safe-zones.cjs # (matte and transcribe are independent; safe-zones needs the matte's frames_fg.) # Replaces hand-running steps 2 / 3 / 3b — one call, nothing forgotten, ~the cost # of the slower of the two instead of their sum.
注：这里在做什么：三条后台进程（matte/transcribe/audio-envelope）各自重定向日志后 wait，随后跑 safe-zones.cjs；失败时分别回显尾部日志并带非零码退出。产出 frames_fg/、frames_bg/、matte.fps、transcript.json、safe-zones.json——即后续作者步骤的全部输入。
转录走本地 WhisperX（经 uvx，版本钉死），以 wav2vec2 强制对齐换取词级时间戳，因为下游门禁是 80ms 严格对齐；失败再退到本仓 whisper.cpp。
skills/embedded-captions/scripts/transcribe.cjs
// Pin whisperx so `uvx` fetches a reproducible build instead of resolving // "latest" on every run (a supply-chain + determinism foot-gun). Override // with $WHISPERX_VERSION if you've validated a different release. const whisperxSpec = `whisperx==${process.env.WHISPERX_VERSION || "3.8.6"}`;
注：这里在做什么：把第三方包版本钉死（同时防供应链与防不可复现），调用形态是 `uvx --python 3.12 --from whisperx==3.8.6 whisperx <wav> --model small --device cpu --compute_type int8 --output_format json`；默认模型是 multilingual `small` 而不是 `small.en`，注释里给了理由（.en 模型会误译非英语与重口音语音）。
抠像不自带权重，而是 shell 本仓 CLI 的 remove-background（u2net_human_seg），首次运行联网下载约 168MB 到用户缓存目录；VFR 源会先归一化成 CFR 再抠。
skills/embedded-captions/scripts/matte.cjs
const r = cp.spawnSync("node", [hfCli(), "remove-background", matteSrc, "-o", mov], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", });
注：这里在做什么：把「模型资产」外包给 CLI 的缓存管理，脚本自己零捆绑权重。同文件注释记录了为什么：老实现内置 34MB PP-MattingV2 + onnxruntime 推理循环。VFR 归一化有实测依据（'observed: 2251 fg frames vs 902 bg on one clip'）。
合成阶段用 ffmpeg 把抠像当遮挡层：embed 走「先渲背景+字幕，再用人物 alpha 覆盖」；rail 走「渲成透明 WebM，再叠到最前」；帧率以 matte.fps 为唯一权威以保持帧对齐。
skills/embedded-captions/scripts/render-and-composite.sh
# FPS: matte.fps (written by matte.cjs at the source's NATIVE rate) is authoritative # so the matte overlay stays frame-aligned with the render. Falls back to plan.fps / # frame-count inference / 24. Warn if plan.json fps disagrees with the matte.
注：这里在做什么：渲染器用 plan.duration 而抠像帧率来自源视频原生帧率，两者不一致就会出现主体漂浮/尾巴黑帧；脚本还把输出长度钳到 min(matte 帧数/fps, 源时长)，并有 'Bug-1 guard' 防止只有前景的尾巴。同时把 index.html + plan.json 快照进 history/ 供回滚。
几何门禁靠 headless Chromium 的 DOM 矩形 × 抠像 alpha 做像素级判定（遮挡、出框、rail/climax 撞车），并用 --strict 卡 80ms 时间对齐；先出的预览帧只需 ~2s/帧，逼你在付渲染费之前发现版面问题。
skills/embedded-captions/SKILL.md
`node scripts/preview-frames.cjs <project> [t…]` composites **faithful preview frames in ~2s each** (caption layers screenshotted at seek-time + real video frame + matte occlusion + rail overlay = what the final composite will look like at that moment).
注：这里在做什么：把「渲染很贵 → 所以先便宜地看」做成流程纪律（'A full render costs minutes — never use it to _discover_ layout problems.'）。门禁清单：check-timing.cjs --strict（80ms）、check-occlusion + measure-layout（主体遮挡与出框）、check-overflow（warning only）、check-rail-climax（rail 与 climax 重复揭示，硬失败）。
2核心能力
01不剪原片的字幕叠加：Standard/rail + peak embed 双轨模型（drop/rail/embed 三态分配）
0235 身份视觉目录 + 场景参数化 DNA（accent 取色、接触阴影按光向、景深匹配模糊、hero 振幅随 RMS 语音响度）
03Cinematic 纯 embed 编译：作者只写 blocks（词行 + 平面 + css + 一个 hero），编译器自动生成时间轴、块内累积、块间翻页、hero 三幕与 apex/minor 分层
04Theme 模式：整套主题宪法（body 范式 × hero setpiece × front fx × plate 反应），编译即校验逐字完整性，渲染即产出 final_fx.mp4
05本地词级转录（WhisperX via uvx），带近静音守卫（防 Whisper 在静音上幻觉出词）与垃圾转录判退
06主体抠像与遮挡合成（CPU-only ONNX，约 2fps@1080p，权重自动下载）
07决策门禁：多说话人/硬切、无人物、短片/无语音/脸不可见、已有烧入字幕、手持抖动——逐条给出拒收或拆分处置
08便宜预览（~2s/帧）与两份 QA 清单：否定清单挡破版，正面的 5 条 reference-bar 检查决定「设计感」，并建议请 fresh-eyes 子代理盲评预览图
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | ffmpeg / ffprobe（系统） |
| cli | hyperframes CLI（init / remove-background / render / lint / check / snapshot / preview） |
| cli | uvx（Python 运行器，按需拉取 whisperx==3.8.6） |
| network | 抠像权重下载（u2net_human_seg.onnx，约 168MB，仅首次） |
| network | GSAP CDN（仅示例渲染与引擎模板 HTML 里引用） |
| package | sharp（图像/alpha 数学）与 puppeteer（版面度量、截图） |
| package | python3（Theme 的 drawon setpiece 在编译期调用 gen-stroke-path.py） |
| cli | hyperframes skills update（自刷新，需网络） |
4风险提醒 风险提醒：黄色 · 留意使用
风险提醒：黄色 · 留意使用
- 首次运行的供应链面：联网拉取第三方 Python 包与 ~168MB 模型权重 — uvx 从 PyPI 取 whisperx==3.8.6（版本已钉死，注释自述是为防供应链；但仍是运行期第三方包拉取），hyperframes CLI 首次下载 u2net_human_seg 权重到 ~/.cache。离线/受限网络环境会失败，需要预置缓存。
- 处理的是用户本地原始视频，抠像帧整段落盘 — prepare.sh 会把视频抽成 frames_fg/frames_bg 每帧 PNG（含人物影像）写入项目目录，并有 history/ 迭代快照与 _prepare_*.log。敏感素材需自行管理目录权限与事后清理（SKILL.md 未包含清理步骤）。
- 计算成本高且不可忽视（CPU-only 抠像约 2fps@1080p） — SKILL.md 明确 'budget for it on long clips'（10s 片约 2-3 分钟），渲染期还有 Chromium 挂起问题（脚本用 HF_TIMEOUT_S 与『输出已存在即视为成功』的僵尸进程处理兜底）——长片段会显著变慢，且这套兜底本身是启发式。
- 文档漂移：SKILL.md 仍以 Standard 为默认，引擎侧已宣告其退役 — 见 verification.second_pass 的 discrepancy 条：SKILL.md 与 scripts/render-and-composite.sh / dna/README.md 对『默认模式』说法互相矛盾（retired 2026-06-12），而脚本里 STANDARD 分支仍在。使用者应按 CATALOG.md 选 `anchor` 主题而不是照 SKILL.md 的 Standard 描述操作。
- 内容层提示注入面：转录文本逐词进入模型上下文 — 视频语音转成的 transcript 会被 agent 当长文细读（并判级 hero/rail/drop）；若素材含指令式语句，属于把不可信字符串喂进上下文。有『近静音幻觉』与『垃圾转录判退』两条守卫，但无隔离机制。
- 第三方依赖多且重（sharp/puppeteer/ffmpeg/uvx/python3） — 缺任一硬依赖时 SKILL.md 要求 STOP 并问用户而不是静默跳过；实际使用中容易在环境缺件上卡住（尤其 python3 与 uvx）。
风险提醒：黄色，留意使用。行为面：18 个 .cjs + 3 个 .sh + 1 个 .py 的本地执行链，大量本地文件读写与 ffmpeg/Chromium 调用；有网络外发但对象可预期且版本钉死——PyPI 上的 whisperx==3.8.6（uvx）、hyperframes CLI 自管的 u2net 抠像权重（~168MB，一次性）、jsdelivr 的 [email protected]，以及 `skills update` 自刷新。**未发现任何凭证/cookie/keychain 读取**（与同批依赖 HeyGen 的 skill 不同）；未发现 TLS 降级、反爬绕过或任意代码执行面（子进程调用均为固定二进制/固定脚本，参数来自本地文件）。因此不落橙色。需留意的是：① 首次运行会联网拉取第三方 Python 包与本仓模型权重（供应链面）；② 处理的是用户本地原始视频，抠像帧会整段落盘到项目目录（含人物影像），需注意目录权限与清理；③ 转录文本进入模型上下文，构成内容层面的提示注入面。
5第二遍独立确认
- [ok] 是否隐藏凭证读取（与同批 HeyGen 系 skill 的差异） — 对整目录 grep `\.heygen|HEYGEN|api[_-]?key|TOKEN|SECRET|keychain|Bearer|Authorization` → 0 命中；process.env 命中 12 处全部是 HYPERFRAMES_ROOT / WHISPER_MODEL / WHISPER_LANG / TRANSCRIBE_ENGINE / WHISPERX_VERSION 等行为开关。『全本地、无凭证』成立。
- [ok] 网络外发是否全部可预期 — 逐条回查：uvx 拉 whisperx（版本钉死 3.8.6，注释明说是为防供应链与不可复现）；模型下载由 hyperframes CLI 自管且路径固定在 ~/.cache/hyperframes/；CDN 引用仅在 engine.html / example-renders / _archive 模板内；无其它域名。未发现隐藏上报或遥测。
- [ok] 实现原理与功能声明是否相符 — 'runs locally end to end, including transcription and subject matting' 成立（本地 WhisperX + 本地 ONNX 抠像）；'without editing the footage' 成立（Standard/Cinematic 只叠加，脚本注释与 SKILL.md 均强调不调色/不覆盖）；唯一被允许改原片的是 Theme 的 PLATE 反应预算，SKILL.md 已显式标注为例外。
- [discrepancy] SKILL.md 的三引擎描述与脚本实际状态不一致（文档漂移） — SKILL.md 开篇仍把 Standard 描述为默认模式（'**Standard** (default) builds a clean verbatim **rail** … + an **embed** climax'），并在多处按 rail.html + index.html 描述两轨产出；但同 commit 的 scripts/render-and-composite.sh 第 35-37 行写着 'Standard mode retired 2026-06-12 — rail-surface needs are served by theme DNAs like "anchor"'，dna/README.md 第 15-16 行同样写 'Standard/rail mode was retired 2026-06-12'，make-composition.cjs 第 253-257 行则在检测到 standard 派生的 plan.json 时直接报错退出。然而 scripts/ 下仍保留完整的 STANDARD 合成分支（第 392 行起 'STANDARD mode (rail + embed) — detected by rail.html'）、modes/standard/ 目录与 44 个字体仍在包内。结论：**rail + peak embed 的实现仍在，但文档层（SKILL.md）已落后于引擎层（dna/README、render 脚本注释）**，两处关于『默认模式』的说法互相矛盾。这是对 pin commit 有效的真实出入，非第一遍误读。
- [ok] 『35 身份』等数量声明的准确性 — 实测 CATALOG.md 身份行 = 35；dna/*.json = 10（chrome/cream/documentary/editorial/glitch/ink/keynote/loud/neon/velocity）；themes/*.json = 25；references/*.md = 14。与 SKILL.md 自述一致。
- [ok] 门禁是否真的会执行（而非只写在文档里） — render-and-composite.sh 内确实依次调用 check-timing（plan+transcript 存在时）、measure-layout + check-occlusion（plan + frames_fg 存在时）、check-overflow（无 plan 的 custom 模式告警）、check-rail-climax（rail.html 存在时，支持 RAIL_CLIMAX_SKIP=1 覆盖），并把结果汇总进 _gates.txt；与 SKILL.md 的门禁描述对应。
6结论
适合：适合：已有一条单人讲述视频（口播/访谈/解释型），想在不剪不调色原片的前提下加成片级字幕的人；需要在「逐字下三分之一可读字幕」与「高峰词嵌到主体身后」之间做设计的创作者；以及想要成套视觉身份（35 种，从安静的 anchor 到 ordnance/terminal/vhs/arcade 等特效档）而不想自己写 CSS/GSAP 的团队。中文「炸/特效/酷炫字幕」在 description 里有显式触发词与选型启发式。
不适合：不适合：① 多说话人或含硬切的素材（SKILL.md 要求先切分或拒收）；② 非 talking-head（无人物主体）的视频；③ 少于 3 秒、无语音、脸始终不可见的片段；④ 原片已带烧入字幕/大量文字图形（不与第二套字幕系统叠）；⑤ 转录质量已崩坏（重口音/非母语导致 gibberish）且换 medium 模型仍不行——SKILL.md 要求拒收而不是交付假字幕；⑥ 想改变画面本身（调色/特效/裁切重构图）的需求——本 skill 明令原片不改；⑦ 只想要纯文字可读字幕、不需要峰值特效的低成本场景——那是更轻量的字幕工具更合适。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 embedded-captions.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent9cdab9186d817c12…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库heygen-com / heygen-com/hyperframes
原始 GitHubheygen-com/hyperframes ↗
Stars44283
最近推送2026-09-06
本 skill commit
b8328f9573许可Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；池内值亦为 Apache-2.0。注意：skill 内含的 u2net_human_seg 抠像权重亦为 Apache-2.0，且权重不随包分发）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。