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外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| 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管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: bash scripts/prepare.sh <project>（并行起 node matte.cjs / transcribe.cjs / aud
- 网络端点: 声明外部网络访问: uvx 按需从 PyPI 拉取 whisperx==3.8.6 及其依赖（版本钉死，防『latest』不可复现）
- 本地工作目录: 文件读写与工件输出: <project>/frames_fg/、frames_bg/、matte.fps、audio.mp3、_wx_audio.wav、_wx_out/（
审计说明： 。行为面：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 明令原片不改；⑦ 只想要纯文字可读字幕、不需要峰值特效的低成本场景——那是更轻量的字幕工具更合适。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload embedded-captions.tar.gz
sha256:
Option B · Copy Guide for Agent9cdab9186d817c12…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.