插件安装： 在运行 setup 或 freshness 命令之前，如果此技能位于 HyperFrames 插件内，请遵循插件执行规则。独立安装则保留下面的更新说明。
首先，保持此技能最新——运行前请与用户确认：
npx hyperframes skills update embedded-captions。如果一切已是最新，执行速度很快（无操作）；否则，它会先刷新此技能及其依赖的核心领域技能，然后再供你使用。
嵌入式字幕
一个目录，在前端选取（CATALOG.md — 35 个身份；背后的引擎是后端细节）。标准（默认）会构建一条清晰的逐字 轨道（位于下部三分之一的副标题，承载大部分文本）+ 一个 嵌入 高潮，合成到场景中主体背后的峰值处。电影感 是纯嵌入——无轨道，每条字幕都合成在主体背后（主体字体、累积、遮挡作为效果）。主题 是一套完整的主题构成——主体范式 × 主角布景 × 前端特效 × 平板反应，由注册表组合而成（themes/README.md）：ordnance terminal neonsign stardust stomp。大多数解说/配音使用 标准；嵌入是稀缺且应得的峰值——对每个词都进行嵌入是常见错误；主题适用于 VFX 级别的需求（“炸”、“特效”、“像 AE 做的”）。
运行时前提条件
插件安装使用捆绑的、清单固定的 CLI 进行抠像、转录和渲染；无需源码检出。本地预览和字幕测量辅助工具还需要 Sharp、Puppeteer（含其 Chromium 浏览器）和 GSAP。请将这些安装在 字幕项目 中，而非只读插件内部：
npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]
保留项目的锁定文件。如果这些依赖已存在，请使用其锁定版本，不要覆盖。Bash 和 FFmpeg/ffprobe 必须在 PATH 中。抠像和转录可能在首次使用时下载各自的模型。
渲染等待 CLI 成功退出后才进行合成。旧的 HF_TIMEOUT_S shell 看门狗已不再使用：大而不完整的文件并不能证明渲染已完成。通过显式的构建检出参数或 HYPERFRAMES_ROOT 可选择贡献者 CLI 而非插件固定版本。通过 CLI/终端正常取消卡住的渲染；字幕辅助工具不会强制终止或从进程快照恢复渲染。
操作流程（快速概览）
通过 /hyperframes 路由，意图层仅确认输入（哪个片段）并将身份选择 宣布 为延迟询问——候选列表需要探测过的片段，因此它保持在下面的步骤 1；该层的运行形态问题不适用（素材未动，无需审查故事板）。如果存在 BRIEF.md，则包含已确认的输入和任何用户备注——请先阅读它。
下面的工艺文字较长；管道本身很短——所有确定性的内容都是计算或编译的，绝不是手写的：
- 决策门（拒绝不合格片段）→ 从 CATALOG.md中选择 一个身份（35 个身份；引擎/编译器通过查找推导——切勿提出模式/类别问题）
hyperframes init（如果项目目录已存在且包含视频，则跳过——matte.cjs/transcribe.cjs会将目录中的任何视频作为 source.mp4 采用）→bash scripts/prepare.sh <project>（同步并行执行 matte ∥ transcribe ∥ audio-envelope，然后执行 safe-zones v2 并包含场景调色板/光学/光照——一个命令，不会遗漏任何内容）- 编写一个小的 JSON 创意选择（先读取
safe-zones.json）：电影感 →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs；主题 →theme.json→make-theme.cjs（轨道/面板/诗意/接管范式；anchor是默认的静默轨道） - 视觉质量检查：
node scripts/preview-frames.cjs <project>→ 大约 2 秒/帧的忠实合成预览（无需渲染）。在支付渲染费用之前，请检查 § 视觉质量检查。 render-and-composite.sh→ 门控（时序 / 遮挡+主角 / 溢出 / 交接）→final.mp4
人们经常忽略的规则要点：
- 轨道（默认）+ 嵌入（提升）
drop（填充词，不显示）/rail（逐字的下部三分之一字幕，在前端，承载大部分文本）/embed（一个峰值词合成在主体后面）。标准模式两者都做，仅嵌入峰值。详见 § 字幕模型。 - 视频以原始状态交付（标准/电影感；主题模式的 PLATE 预算是唯一允许的例外——每个主题 DNA 定义的注册门控反应节拍（电荷变暗、重击、摇晃、颗粒感）在抠像合成之后应用，使主体+文本+平板作为一帧移动）——仅添加字幕；抠像仅让主体遮挡嵌入轨道。切勿对素材进行调色/重新着色/扫描线。
- 两本规则手册：轨道 → references/rail.md（简短），嵌入工艺 → references/composition-craft.md（丰富，纯嵌入）。根据需要浏览。
字幕模型——轨道 + 嵌入
每个口头的短语都是以下三种之一：
| 内容 | 显示方式 | |
|---|---|---|
| drop | 填充词——嗯/呃、口吃、自我修正 | 不显示 |
| rail | 默认值——普通口语内容（逐字） | 干净的下部三分之一字幕，在前端，可读。关键词可以获得内联 emphasis 高亮（强调色/动态词弹出）——它保持在轨道上。 |
| embed | 提升的峰值——头条节拍 | 一个合成在 主体后面（抠像遮挡）的大词，设计好的进入和退出 |
轨道承载大部分文本；嵌入是稀缺且应得的峰值。 稀缺性是 每个节拍/块，而非每个片段：每个块（想法）≤1 个主角，永远不能同时可见，主角窗口之间至少有一个节拍的空隙（编译器在低于 0.6 秒时会发出警告）。短片段 → 通常 1-2 个；长解说 → 每个部分大约一个。在多个主角中，最大的一个被编写为 APEX（它单独获得完整的锁定嵌入 + 宽度适配提升）；较小的主角是 次要峰值，它们作为加大的强调行在前景轨道上（阻尼运动）——并非每个节拍都需要抠像展示，这正是让 apex 成为事件的原因。嵌入每个词仍然是常见错误。
轨道表面身份正是这样构建的（轨道 = rail.html，嵌入 = index.html 中的高潮）。列流身份放弃轨道，使所有内容都像嵌入风格——仅推荐用于重氛围而非逐字清晰度的需求，切勿用于解说/配音（文字必须可读）（CATALOG.md 为每个身份编码了这一点）。
步骤 0 — 从 CATALOG 中选择一个身份
一个前端，三个引擎在后面。 用户从 CATALOG.md 中选择一个身份（35 个条目：10 个经典 + 25 个主题）；引擎、编译器和编写文件通过目录行查找推导。切勿将“标准与电影感与主题”作为问题提出——这些是后端名称（一个产品即使有多个引擎也有一个 UX）。目录编码了路由所需的一切：阅读表面、声音、推荐对象、场景需求、真正接近配对（loud↔ordnance, neon↔neonsign, cream↔stardust）的邻接说明。
身份选择是一个 偏好门（../hyperframes/references/brief-contract.md § 1）：在自主模式（“给我惊喜”/“你决定”）下，自行从你的候选列表中选择，并陈述一行原因，而不是询问。
流程：探测片段 → 从目录中筛选 2-3 个身份 → 推荐 一个 并附上一行理由 → 用户选择（自主模式：你选择，陈述理由）→ 编写该身份的文件。身份与引擎绑定（无交叉组合；打开一个身份是一个验证事件——参见 dna/README.md）。
始终提出你的推荐，并在你编写之前让用户选择。 不要默默默认。
（完整的身份表位于 CATALOG.md 中——路由的唯一真实来源。下面的引擎文档描述了每个后端的编写约定。）
CATALOG.md 是整个答案空间：此工作流不会搜索 HyperFrames 组件注册表。 组合工作流在编写命名外观之前运行 npx hyperframes catalog；此工作流禁止这样做。它的引擎是锁定的编译器，它们消费 cinematic.json/theme.json 并自行发出组合，因此注册表项——包括 caption-* 块——没有可挂载的内容。注册表块在设计好的画布上样式化文本；此技能通过抠像将字幕嵌入某人的素材中。当没有身份符合需求时，请说明并选择最接近的，而非在目录之外寻找。
推荐启发式：使用 CATALOG.md 中的“筛选启发式”——它们是身份级别的（例如“炸”会短列出 ordnance/stomp/terminal/loud 并根据 WHAT 应该爆炸来选择），绝不是类别级别的。不确定 → anchor。
- 电影感 → 为锁定模板编写
plan.json，由make-composition.cjs编译。 - 主题 → 阅读 themes/README.md，编写
theme.json，运行scripts/render-theme.sh（编译 + 渲染 + 平板反应 → final_fx.mp4）。
决策门——首先运行
在任一模式之前探测视频并分类场景。
ffprobe <video.mp4> # 规格
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # 在 20/50/80% 处
读取样本。如果出现以下情况，拒绝：
- 多个说话者 / 硬切（分割并渲染每个镜头，或拒绝）
- 无人类主体（此技能用于说话头部）
- 时长不足 3 秒、无语音，或面部从未清晰可见——
transcribe.cjs在音频接近静音时会发出警告（Whisper 会在静音上幻觉出“谢谢”之类的词）；注意警告并拒绝，而不是字幕编造的词 - 源素材已带有烧录字幕/副标题/大量文本图形——添加第二个字幕系统会冲突，且素材按原样交付（无覆盖/修复）。烧录文本通常仅在中段出现：采样一个 1fps 接触印样（
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png），不要相信 3 个随机帧。 - 转录结果是垃圾——非母语/重口音语音可能被转录成自信的胡言乱语。在编写之前通读
transcript.json；如果它无法解析为语言，尝试一次WHISPER_MODEL=medium，否则拒绝（编造词句的逐字轨道比无字幕更糟）。 - 手持拍摄，快速运动且抖动（抠像闪烁）
预飞探测（零成本，防止最严重的失败）
- 镜头切探测。在 20%、50%、80% 处采样帧。如果出现不同主体/场景，在切之前修剪片段。
- 宽高比黑边/柱框探测。第一帧上有黑条？计算安全内容矩形并限制字幕放置在其内。
- 亮度探测。采样字幕区域的平均亮度——
低于 60→ 浅色文本直接可读，60-180→ 添加字符遮罩，180+→ 不透明文本 + 遮罩（永远不要裸露浅色文本）。电影感模板是奶油色+screen且被锁定——使用此探测来 选择匹配的身份（亮场景 →ink，或不透明轨道anchor主题），切勿重新着色。 - 按语调的身份推荐（你推荐；用户选择——见步骤 0 + CATALOG.md）。解说/访谈/必须阅读文字 → 轨道/面板表面身份；诗意/社交/“电影感” → 按语域的列流身份；“炸/特效/VFX”/命名世界 → 主题身份。不确定时 →
anchor（文字可读，场景安全）——但提供候选列表让用户选择。
管道——5 个步骤
1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project> # matte ∥ transcribe（并行）→ safe-zones。一个命令。
# → frames_fg/ transcript.json safe-zones.json
3. [代理步骤——唯一的创意步骤] 编写一个小型 JSON；参见下面按模式
电影感：编写 plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
主题： 编写 theme.json → bash scripts/render-theme.sh <project> （编译 + 渲染 + 平板特效）
4. node scripts/preview-frames.cjs <project> # 约 2 秒/帧的合成预览 → § 视觉质量检查（在渲染之前）
5. bash scripts/render-and-composite.sh <project> # 门控 → final.mp4 + history/ 快照
（主题模式：跳过步骤 3b/5——render-theme.sh 已经运行编译 + render-and-composite
+ _postfx.sh；交付物是 final_fx.mp4，final.mp4 是预平板反应）
步骤 1 的 init 会检查已安装的技能与 GitHub 上的最新版本，如果有任何过时，会更新全局集合。
步骤 3 因模式而异：
步骤 3——电影感模式（纯嵌入）
- 先读取
safe-zones.json。 叙述平面放在zones.hugLeft/hugRight——紧贴轮廓的干净条带（文本远离主体会显得漂浮而非嵌入；远角是后备方案，非默认）。主角默认为heroAnchor/heroBands.best（居中对齐在主体上，大约 30-55% 被遮挡）。recommendation:"fg"将 NARRATION 移到前面以提高可读性；只要heroBands.feasible，主角就保持嵌入——主角-前景是最后的手段。 - **DNA 是你从 CATALOG 中选择的身份——
…
[因长度限制截断]