embedded-captions

插件安装： 在执行设置或检查更新命令前，如果此技能位于 HyperFrames 插件中，请遵循插件执行规则。独立安装请按下方的更新说明操作。

首先，保持此技能为最新版本——运行前请先征得用户同意： npx hyperframes skills update embedded-captions。如果所有内容都是最新版本，这会快速无操作地完成；否则会先更新此技能及其依赖的核心领域技能，再供你使用。

嵌入式字幕

先选定一个目录（CATALOG.md — 35 种身份；其背后的引擎属于后端细节）。标准（默认）模式会构建简洁的逐字字幕条（承载大部分文本的下三分之一字幕）+ 嵌入式高潮字幕，在峰值时合成到主体后方的场景中。电影感模式则纯粹使用嵌入式字幕——没有字幕条，每条字幕都合成到主体后方（英雄级排版、层层累积、遮挡即效果）。主题是一套完整的主题规则——主体范式 × 英雄级场景装置 × 前景特效 × 底板响应，组合自各类注册项（themes/README.md）：ordnance terminal neonsign stardust stomp。大多数讲解或旁白内容适合使用标准模式；嵌入式字幕是稀缺的、需要充分理由才使用的峰值效果——每个词都嵌入是常见错误；主题模式适用于对特效质量要求很高的需求（“炸”“特效”“像 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，其中会记录已确认的输入和用户备注——请先阅读。

下方的创作说明很长；流程本身很短——所有确定性内容都会通过计算或编译得出，绝不手写：

1. 决策关卡（拒绝不合格片段）→ 从 CATALOG.md 中选择一个身份（共 35 种身份；通过查找得出引擎／编译器——绝不提出模式／类别问题）
2. hyperframes init（如果项目目录已存在且视频已在其中，则跳过——matte.cjs/transcribe.cjs 会将目录中的任意视频作为 source.mp4）→ bash scripts/prepare.sh <project>（并行运行 matte ∥ transcribe ∥ audio-envelope，然后使用场景调色板／光学效果／光照生成 safe-zones v2——一条命令，不会遗漏任何步骤）
3. 编写一份简短的创意选择 JSON（先阅读 safe-zones.json）：Cinematic → cinematic.json → make-cinematic.cjs（推导出 plan.json 并编译）；Theme → theme.json → make-theme.cjs（rail/panel/poem/takeover 范式；anchor 是默认的静态 rail）
4. 视觉 QA：node scripts/preview-frames.cjs <project> → 生成忠实的合成预览，约需 2 秒／帧（无需渲染）。付费渲染前，请先查看 § Visual QA。
5. render-and-composite.sh → 关卡（时序／遮挡+主体／溢出／交接）→ final.mp4

容易忽略的重要规则：

• rail（默认）+ embed（强化）。 drop（填充内容，不显示）／rail（逐字呈现的下三分之一字幕，置于前景，承载大部分文本）／embed（合成到主体后方的峰值词语）。标准模式会同时使用两者，只将峰值词语嵌入。参见 § Caption model。
• **视频保持原样交付（Standard/Cinematic；Theme 模式的 PLATE 预算是唯一获准的例外——由主题 DNA 定义、经寄存器门控的反应节拍（亮度充能／变暗、冲击、抖动、颗粒），在 matte 合成后应用，使主体+文本+底板作为同一帧移动）——只添加字幕；matte 仅用于让主体遮挡 embed 轨道。绝不对素材进行调色／重新着色／添加扫描线。
• 两套规则：rail → references/rail.md（简明），embed 创作 → references/composition-craft.md（详尽，仅适用于 embed）。按需略读。

字幕模型 — 轨道 + 嵌入

每个口语短语都属于以下三种类型之一：

	内容	呈现方式
drop	填充词——嗯、呃、口吃、自我纠正	不显示
rail	默认类型——普通口语内容（逐字呈现）	简洁的下三分之一字幕，位于前景，易于阅读。重点词可以加上行内 emphasis 高亮（强调色 / 当前词弹出）——仍显示在轨道上。
embed	提升后的峰值——标题节拍	一个大字合成在主体后方（遮罩遮挡），带有精心设计的入场和退场动画

轨道承载大部分文本；嵌入是稀缺且来之不易的峰值。 稀缺性按节拍 / 区块计算，而非按片段计算：每个区块（一个想法）最多 1 个主视觉词，绝不同时出现两个主视觉词，主视觉词窗口之间至少留出一个节拍的空隙（编译器会对间隔小于 0.6 秒发出警告）。短片通常用 1–2 个；长篇解说通常每个章节用一个。在多个主视觉词中，作者设定的最大字号那个是 APEX（只有它会获得完整的锁定组合嵌入效果 + 宽度适配放大）；较小的则是次级峰值，沿其所在列以超大强调行呈现（前景色，减弱动画）——并非每个节拍都需要遮罩展示，这正是 APEX 能成为事件的原因。把每个词都嵌入仍是常见错误。

轨道表面风格会准确地构建这一效果（轨道 = rail.html，嵌入 = index.html 中的高潮部分）。列流风格会去掉轨道，让所有内容都采用嵌入式样式——仅建议用于重氛围、轻逐字呈现的需求，切勿用于必须让文字清晰可读的解说 / 旁白（CATALOG.md 会针对每种风格说明这一点）。

---

第 0 步 — 从 CATALOG 中选择一个身份

一个前端，三个后端引擎。 用户从 CATALOG.md 中选择一个身份（35 个条目：10 个经典风格 + 25 个主题风格）；引擎、编译器和创作文件根据目录条目查找得出。绝不要把“Standard、Cinematic 还是 Theme”当作问题抛给用户——这些是后端名称（即使产品有多个引擎，用户体验也只有一种）。目录包含路由所需的所有信息：阅读界面、语气、推荐用途、场景需求，以及真正相近的风格组合的邻近关系说明（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 中的“Shortlisting heuristics”——这些启发式针对身份级别（例如，“炸”会筛选出 ordnance/stomp/terminal/loud，再根据应该炸掉的内容来选择），而不是类别级别。不确定时 → anchor。

• Cinematic → 为锁定模板编写 cinematic.json，由 make-cinematic.cjs 编译。
• Theme → 阅读 themes/README.md，创作 theme.json，运行 scripts/render-theme.sh（编译 + 渲染 + 底板反应 → final_fx.mp4）。

---

决策门槛 — 首先运行

检查视频并对场景分类，然后再选择任一模式。

ffprobe <video.mp4>                    # specs
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # at 20/50/80%

查看样本。如果符合以下任一情况，则拒绝：

• 多位说话者 / 硬切镜头（拆分并分别渲染每个镜头，或拒绝）
• 没有人物主体（此技能用于谈话类视频）
• 时长不足 3 秒、没有语音，或从未清晰看到人脸——transcribe.cjs 会在音频几乎无声时发出警告（Whisper 可能会在静音上幻听出“Thank you.”之类的词）；请注意警告并拒绝，而不是为捏造的词语添加字幕
• 源视频已带有烧录字幕 / 字幕轨或大量文字图形——添加第二套字幕系统会产生冲突，且视频素材会原样输出（不会遮盖或修补）。烧录文字往往只在片段中段出现：请制作 1fps 联系表（ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png），不要只相信 3 帧抽样。
• 转录内容不成句——非母语或口音很重的语音可能会被转录成看似可信的乱码。创作前请仔细检查 transcript.json；如果内容无法解析为语言，尝试一次 WHISPER_MODEL=medium，否则拒绝（逐字显示捏造词语的轨道比没有字幕更糟）。
• 手持拍摄且画面繁杂、运动快速（遮罩会闪烁）

预检探测（零成本，避免最糟糕的失败）

1. 镜头切换探测。 在 20%、50%、80% 处抽取帧。如果出现不同的主体／场景，请在切换前裁剪片段。
2. 信箱／柱箱探测。 第一帧有黑边？计算安全内容矩形，并将字幕限制在其中。
3. 亮度探测。 采样字幕区域的平均亮度——under 60 → 浅色文字可直接显示，60-180 → 添加字形底衬，180+ → 不透明文字 + 底衬（绝不单独使用浅色文字）。电影感模板为奶油色 + screen，且已锁定——使用此探测来 挑选合适的身份（明亮场景 → ink，或不透明轨道 anchor 主题），绝不要用它来重新着色。
4. 按基调推荐身份（由你推荐，用户选择——参见步骤 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 (parallel) → safe-zones. One command.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [AGENT STEP — the only creative step] author a small JSON; see below by mode
   Cinematic: author cinematic.json → node scripts/make-cinematic.cjs <project>
   Theme:     author theme.json → bash scripts/render-theme.sh <project>   (compiles + renders + plate fx)
4. node scripts/preview-frames.cjs <project>   # ~2s/frame composite previews → § Visual QA (BEFORE the render)
5. bash scripts/render-and-composite.sh <project>  # gates → final.mp4 + history/ snapshot
   (Theme mode: SKIP steps 3b/5 — render-theme.sh already runs compile + render-and-composite
    + _postfx.sh; the deliverable is final_fx.mp4, final.mp4 is pre-plate-reaction)

步骤 1 的 init 会将已安装的技能与 GitHub 上的最新版本进行检查，如有过期项，则更新全局集合。

步骤 3 因模式而异：

步骤 3——电影模式（纯嵌入）

1. 先读取 safe-zones.json。 旁白平面放在 zones.hugLeft/hugRight——紧贴剪影的干净条带（文字离人物太远会显得悬浮，而非嵌入；远处角落是备用方案，不是默认位置）。主视觉默认位于 heroAnchor/heroBands.best（以主体为中心，遮挡约 30–55%）。recommendation:"fg" 会将旁白移到前景以提高可读性；只要 heroBands.feasible，主视觉就保持嵌入状态——主视觉置于前景是最后手段。
2. DNA 就是你在步骤 0 选定的身份（CATALOG.md）——不要在此重新选择。根据场景做合理性检查（主视觉带亮度 > 150 时适合 ink；完整的选择指南见目录，涵盖全部十种，包括 neon / glitch / chrome / velocity）。说明你的选择及理由；由用户决定。DNA 会锁定字体／调色板／混合／动态效果 + 主视觉三幕结构；safe-zones v2（palette/optics/lighting）会自动针对 THIS 场景进行参数化。
3. 编写 <project>/cinematic.json——"dna": "<name>" + 思考块，而非原始分组：每个块 = 文字行（在分句边界处分组，每组 2–5 个）+ 该块堆叠所在的平面 + 每行的 css（仅大小／字重／样式——不含位置）+ 最多一行标记为 "hero": true（提升的词；"text" 用于显示形式）。架构见 scripts/make-cinematic.cjs 头部。
4. 编译：node scripts/make-cinematic.cjs <project>——将块转换为 plan.json → index.html。自动为你生成：按转录顺序排列的时间、块内累积显示、块间翻页、主视觉锁定组合（主视觉块的前置上下文、主视觉和后置上下文会堆叠成一个整体组合，以主体为中心——从上到下的阅读顺序天然对应口述顺序；上下文浮在前景，主视觉嵌入背景，形成深度夹层；体量规则确保主视觉压过上下文）、高潮／次要主视觉拆分、天然形成的阅读顺序、基于 safe-zones 的前景回退。随后照常运行各项门禁。(仍可直接手工编写 plan.json，以实现块结构无法表达的设计——然后自行运行 fill-timings.cjs + fit-fonts.cjs + make-composition.cjs。)

步骤 3 — 主题模式（主题化构成）

请先阅读 themes/README.md — 范式／场景调度表、关联关系、硬性规则，以及精确的 theme.json 架构。

1. 选择主题 DNA，依据内容风格（每个 themes/<name>.json 都包含 voice 和 when）。说明你的选择及理由；由用户决定。
2. 编写 <project>/theme.json — dna、lines（逐字照录，按转录顺序；每行 1–5 个词——对于 takeover，每行就是一张 CARD）、minors（强调词）、hero:{match}（高潮词／短语；对于嵌入式场景调度，将其从 lines 中省略；对于行内场景调度和 panel+redact，则保留在 lines 中）。
3. 渲染：bash scripts/render-theme.sh <project> — 编译（编译时进行逐字完整性检查）、渲染两层、合成，并应用底板效果 → final_fx.mp4。请在编译和渲染之间使用 preview-frames.cjs 进行视觉质检。

---

视觉质检 — 渲染前先预览

node scripts/preview-frames.cjs <project> [t…] 会在每帧约 2 秒内合成忠实的预览帧（在指定时间点截取字幕图层 + 实际视频帧 + 遮罩遮挡 + 导轨叠加 = 该时刻最终合成画面的效果）。默认采样点 = 每个分组／高潮窗口。完整渲染需要几分钟——切勿用它来_发现_布局问题。

请将预览（<project>/preview/sheet.png）对照此清单检查——这些问题是几何检查无法发现的：

1. 褪色 — 浅色文字叠在明亮区域上（窗户／标牌／天空）：难以辨认 → 移动平面或更改 DNA／模式（明亮场景 → ink）。
2. 文字叠字 — 字幕覆盖场景自带的文字／图形，或两个字幕组互相碰撞。
3. 阅读顺序 — 屏幕上的垂直顺序必须与口播顺序一致；主视觉词不能排在后续文字下方。
4. 主视觉呈现 — 高潮内容应足够大，并明显位于主体后方（遮挡约 30–55%），而不是飘在边缘的标签。
5. 平衡 — 形成连贯的列／带，而不是散乱的碎片；留出舒展的边距；不得有内容被裁切。

然后检查 references/reference-bar.md 中的 5 项正向检查（海报测试 · timid 测试 · 一眼层级 · 场景呼应 · 空镜审查）——失败清单能防止渲染出错；正向清单则决定作品是否经过_精心设计_。两项都通过后即可交付。

**新鲜视角审查（建议用于所有面向用户的内容）：**你可能会对自己的布局产生确认偏误。如果可以启动子 Agent，只给它预览图表和这份清单，并要求它逐帧给出 PASS/FIX 结论（“请根据 5 项检查清单审查这些字幕预览；逐帧回答 PASS 或给出具体修改建议”）。在 cinematic.json / theme.json 中应用修改，重新编译并再次预览——每轮只需几秒。预览通过后再渲染一次。

DNA 注册表 — 十种视觉语言（取代模板目录）

两种模式都基于 dna/ — 十种由艺术指导设计的视觉语言，可按场景参数化（从画面素材中采样强调色、沿测得的光线方向添加接触阴影、匹配景深的模糊、与 RMS 耦合的主视觉振幅）：

DNA	风格定位	适用场景	风格
cream	高端暖调	暗调／中间调暖色场景	Inter + 暖奶油色 + 滤色；辉光显现式主视觉（cinematic-cream 的继任者）
ink	高端	明亮场景（亮度 > 150）	近黑色正片叠底 — 文字仿佛印在墙上；明亮场景的解决方案
editorial	编辑奢华	内省／时尚／诗意	Bodoni Moda、小写斜体主视觉 — 杂志般的优雅
keynote	科技高端	产品／发布	不透明白色 Inter 800，绝对居中、静止
documentary	正式	访谈／严肃	烧录式显现，无主视觉 — 庄重感就是风格
loud	张扬	炒热气氛／运动／社交	Anton + 从场景采样的强调色，单体重击 + 涟漪；正文在前方宣告（bodyLayer: fg）
neon	霓虹张扬	霓虹黑色电影／夜生活／科技黑色电影（暗调场景）	电光青色招牌、点火闪烁，主视觉像招牌一样通电亮起
glitch	霓虹张扬	数字／黑客／AI	RGB 分离的回声在落点时骤然合一；机器打击乐般的节奏
chrome	奢华张扬	Y2K／时尚科技／音乐	液态金属渐变主视觉 + 停留期间一道光泽扫过
velocity	运动张扬	运动／汽车／健身	每个词都沿其运动矢量进入（拖影 + 倾斜），主视觉掠过并带有速度轨迹

根据 safe-zones.json（heroAnchor.bandLuma、palette.temperature）× 内容风格定位进行选择 — dna/README.md 中有选择规则。创作时：cinematic.json 使用 "dna": "<name>"。

引擎会根据 DNA 生成主视觉的三幕式（无需创作配置）：同时可见的字幕变暗（铺垫）→ 逐字母进入，振幅与语音响度成正比（冲击）→ 呼吸式发光，直至退出（余辉）。

（旧版：plan.template:"cinematic-cream" 会自动映射为 dna:"cream"。已停用的 54 种模板库已归档在本仓库之外，不随此技能分发；_motion.md 仍保留在技能中，作为动作动词参考目录。）

---

美学决策 — 基调 × 镜头 × 平台（供目录筛选使用，而非第二套路由）

从 3 个维度对片段进行分类，并将结果用于 CATALOG.md 的筛选 — 本节本身不会选择模式或引擎：

基调（内容给人什么感觉？）

• 纪实 | 对话式 | 充满活力 | 诗意 | 主题演讲 | 调查式 | 音乐视频

镜头（采用什么取景方式？）

• 特写（头部和肩部） | 中景（躯干以上） | 远景（全身以上） | 剪辑蒙太奇（混合镜头）

平台（将在哪里播放？）

• 9:16 竖屏（TikTok/IG/Shorts） | 16:9 横屏（YouTube/网页） | 1:1 正方形 | 广播导出

请参阅 references/direction-catalog.md § Classification matrix 中的方向语言，然后返回 CATALOG.md 筛选风格方案（此矩阵为筛选提供参考；目录是唯一的路由入口）。

构图技巧（嵌入轨道）——嵌入前请阅读

完整的 embed-track 指南见 references/composition-craft.md：转录文本角色标注、短语分组、平面与净空区锚定、区域一致性、高潮突出与可读性、边缘留白、遮挡的 3 步判断，以及累积与持续性。它规定了_突出显示_的短语如何融入场景 — 编写任何嵌入内容前（Cinematic cinematic.json 或 Standard index.html），请先阅读。默认的 rail 轨道有自己的简单得多的规范 → references/rail.md。

---

共享知识

文档	内容
references/rail.md	轨道路径——标准下三分之一字幕规范（默认方案；承载大部分文本）。
references/composition-craft.md	嵌入轨道实战手册——分组、平面、高潮弹出、遮挡判断、累积／持续。嵌入前请阅读。
dna/README.md	DNA 注册表——十种按场景参数化的视觉语言；如何选择。
references/reference-bar.md	品味标准——各类风格的世界级参考＋5 项正向检查。
references/aesthetic-principles.md	**18 条规则。**在品味上胜过 Veed AI。请先阅读。
references/motion-vocabulary.md	10 种命名的运动原语＋语气→时序查找表
references/direction-catalog.md	10 种可直接交付的美学风格＋语气×镜头×平台矩阵
references/anti-patterns.md	已排除的缺陷（CoreML、字间距重排等）
references/scene-types.md	何时可使用墙面（4 个条件）
references/layout-heuristics.md	平面定位、干净区域选择、顶部区域 3 个条件、黑边计算
references/typography-presets.md	字号×栏宽矩阵（起始参考值）
references/caption-grouping.md	单词→分组规则（停顿、句子边界）
references/failure-modes.md	开发中易踩坑的长期问题
references/bespoke-vs-presets.md	预设有时为何会失效；克隆并调整的模式

**请先阅读美学原则和方向目录。**其他内容都是实现细节。

---

不容妥协的要求

• 不得连续完全遮挡面部——在每个 0.3s 窗口内，面部边界框至少有 30% 不被遮挡。
• 符合 WCAG 对比度要求——最终渲染会进行检查；如果不通过，请修正配色。
• 结果确定——不得使用 Math.random()、Date.now() 或 repeat:-1。
• **绝不对视频调色或重新着色。**素材保持原样——只添加字幕。不得在 A-roll 上叠加全画面扫描线／双色调／变暗／暗角效果。霓虹黑色电影／CRT 纹理应放在字幕元素 内部，而不是覆盖整个画面。
• **对于访谈／讲解类视频，优先使用侧栏。**不要嵌入完整转录文本——大部分文本放在侧栏；只嵌入重点内容。把所有内容都嵌进去是最常见的错误。
• **嵌入内容应少而分散。**每个句子／节拍最多 1 处嵌入，绝不连续出现两个，也不得同时可见；间隔至少一个节拍；apex 最多使用一次。高潮 = 每个节拍的重点，不是“整个片段唯一的核心亮点”。
• 遮罩 = 人物（hyperframes remove-background，u2net_human_seg，Apache-2.0）。按设计进行人物分割，但不会精细到外科手术级别：细长的偏移家具（麦克风悬臂）通常会被排除——字幕会渲染在它们上方、人物后方；而靠近主体的大型显眼物体（望远镜、桌面设备）仍可能混入遮罩并遮挡字幕。人物手持的物体（产品、手机）可能会间歇性消失，让字幕显示在它们前方。**绝不要想当然：**放置主视觉元素之前，先在 2-3 个时间点检查 frames_fg/，并优先选择没有家具泄漏的位置（泄漏可能导致 heroAnchor 偏移——请对照 frames_bg 交叉核验）。
• **safe-zones 不识别道具——使用的每个区域都要亲自检查。**区域／heroBands 只评估人物遮挡和亮度：落在“干净”区域内的麦克风、望远镜或屏幕对它们不可见（道具混入遮罩还会使 heroAnchor.centerXPct 偏离人物）。开始制作前，提取计划使用的每个区域各一帧；如果那里有道具，请测量其边界框并移动／缩小平面。有两个实际案例之所以干净交付，正是因为 Agent 做了这一步。（自动识别道具显著性是已知不足；区域的 peakLuma 只能捕捉_移动中_的亮物体。）
• **字幕必须保持在画面内。**电影模式会严格阻止画面溢出；标准模式则运行 check-overflow.cjs 并发出警告（有意溢出是唯一例外——请阅读警告）。
• 每条字幕至少在屏幕上显示 0.5s——时间更短就无法读清。
• 词语时间必须与 transcript.json 相差不超过 80ms——字幕晚 500ms 入点会破坏场景错觉。电影模式会在渲染前（通过 render-and-composite.sh）运行 check-timing.cjs --strict。THEME 模式则在编译时强制执行相同的时间要求（make-theme 的顺序转录匹配器和逐字完整性检查——时间偏差会导致编译错误）。不得把多个转录词塞进一个条目（例如 "FUTURE OF"，或将 IT + 换行 + ALL 堆叠在一起并共用一个起止时间）——第二个词会继承第一个词的时间戳，提前显示。应将它们拆成单独的词条并分别设置时间，即使你希望它们显示在同一行（请用 CSS white-space／自然换行代替 <br>）。支持创意替换字幕文本≠转录文本的情况（例如用 "15%" 替换 "fifteen percent"）——请在 check-timing.cjs 中的 CREATIVE_SUBS 里登记。
• 组窗口必须覆盖其词语的时间范围——对于每个组，group.in ≤ min(word.start) 且 group.out ≥ max(word.end)。如果 group.in 晚于某个词的开始时间，该词会被延迟到容器挂载后才显示（我们曾上线过延迟 800ms 的故障）。验证器会强制检查这一点。
• 两个字幕组不得同时在时间和屏幕区域上重叠——时间重叠的字幕会造成文字堆叠。可选方案：（a）空间分离——将每组放在互不重叠的垂直区域，使其可以同时显示（记忆墙式层叠）；（b）交接——将前一组的 out 设为 ≤ 下一组的 in，确保屏幕上始终只有一组；（c）刻意叠加排版——在其中一组添加 "allow_overlap": true，以关闭验证器警告。验证器会根据每组的 CSS 估算垂直边界框并标记碰撞。默认选择（a）——这正是 cinematic-cream 营造诗意层层累积感，而非让字幕轨不断替换自身的关键。
• 亮背景（亮度 >180）上使用屏幕混合会失效。Cinematic 模板使用奶油色 + screen，且其设计风格已锁定（方案无法更改其配色）→ 在明亮背景上会泛白，因此请选择 ink（专为明亮表面打造的活版印刷效果）或 anchor 主题（不透明的侧栏表面），而不是覆盖原有风格。
• 词语入场时不要动画处理 letter-spacing 或 filter:blur——inline-block 重排会导致行跳动。
• 禁止使用 CoreML 进行遮罩处理——onnxruntime CoreML EP 的混合精度分区会破坏面部 alpha（此前使用 RVM 引擎时已观察到；不要再次尝试）。遮罩处理仅使用 CPU（1080p 时约 2 fps；每 10s 片段约需 2-3 分钟；处理长片段时请预留时间）。

---

依赖项

• HyperFrames CLI： 插件安装会使用随附且固定清单版本的启动器。源码贡献者可以通过 HYPERFRAMES_ROOT 使用构建好的检出版本（packages/cli/dist/cli.js）、技能的源码树或 ~/Downloads/hyperframes。
• 以 Node 为主；通过 uvx 调用两处 Python（无需手动安装）： 转录通过 uvx 运行 WhisperX（提供词级时间戳；如果已有词级 transcript.json，则回退使用该文件），Theme 的 drawon 场景组件会在编译时调用 python3 scripts/gen-stroke-path.py。其他所有操作都使用 hyperframes 已提供的工具链：通过 hyperframes CLI 的 remove-background 进行抠像（u2net_human_seg；权重会自动下载一次，约 168 MB，保存到 ~/.cache/hyperframes/）、通过 sharp 处理图像和 Alpha 通道、通过 puppeteer 处理布局、遮挡和溢出问题，另需 ffmpeg。请按照上文 运行时先决条件 中的说明，在字幕项目中安装 Sharp、Puppeteer 和 GSAP。辅助工具会先检查该项目，并保留为源码贡献者查找检出版本依赖的功能。
• 转录 = 通过 uvx 运行 WhisperX（词级时间戳和对齐；无需手动安装——transcribe.cjs 会调用 uvx whisperx）。如果存在词级 transcript.json，则回退使用该文件。
• 源视频 — matte.cjs / transcribe.cjs 会自动解析 source.mp4（或通过 glob 查找片段 / 读取 hyperframes.json），因此 hyperframes init --video X.mp4 无需手动重命名。
• fps — matte.cjs 会按源视频的原生帧率提取，并记录到 matte.fps；render-and-composite.sh 会使用该值，确保遮罩与帧保持同步。
• 抠像权重不会随附：matte.cjs 会调用 hyperframes CLI 的 remove-background，该工具会将 u2net_human_seg（约 168 MB，Apache-2.0）下载一次到 ~/.cache/hyperframes/background-removal/models/。首次在新设备上准备时，需要联网完成这次下载。

如果缺少硬性依赖，请停止并询问用户，不要悄悄跳过步骤。