嵌入式字幕

一个目录，前端选取 ([CATALOG.md](CATALOG.md) — 17 种身份；三个引擎为后端细节）。标准模式（默认）生成干净的原文直出轨道字幕（位于画面下半部分，承载大部分文本）+ 一个在主体后方峰值处合成的嵌入式高潮。电影模式为纯嵌入式——无轨道字幕，所有字幕均合成于主体之后（英雄字体、累积效果、遮挡作为视觉重点）。主题模式是完整的主题化设定——主体范式 × 英雄场景 × 前置特效 × 画面反应，由注册表组合而成（[themes/README.md](themes/README.md)）：ordnance terminal neonsign stardust stomp。大多数解说或旁白使用标准模式；嵌入式字幕是稀有且值得期待的高潮点——将每个词都嵌入是常见错误；主题模式适用于 VFX 级别需求（如“爆炸”、“特效”、“像 AE 制作的”）。

操作流程（速览）

下方的创作说明较长；但流程本身很短——所有确定性步骤均由计算或编译完成，从不手动编写：

1. 决策门（拒绝无效片段）→ 从 [CATALOG.md](CATALOG.md) 中选取唯一一种身份（17 种身份；引擎/编译器通过查表确定——绝不暴露“模式/类别”选择问题）
2. hyperframes init（若项目目录已存在视频，则跳过此步——matte.cjs/transcribe.cjs 会自动以目录内视频作为 source.mp4）→ **bash scripts/prepare.sh <project>**（并行执行 matte / transcribe / 音频包络，随后进行安全区域 v2 处理，结合场景调色/光学/光照——一条命令，无遗漏）
3. 撰写少量创意选择的 JSON（请先阅读 safe-zones.json）：

- 电影模式 → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs

- 主题模式 → theme.json → make-theme.cjs（轨道/面板/诗体/接管范式；anchor 为默认静默轨道）

1. 视觉质检：node scripts/preview-frames.cjs <project> → 每帧约 2 秒生成忠实合成预览（无需渲染）。在支付渲染费用前务必检查 § 视觉质检。
2. render-and-composite.sh → 门控检测（时间 / 遮挡+英雄 / 溢出 / 交接）→ final.mp4

人们常忽略的关键规则：

• 轨道（默认） + 嵌入（提升）。drop（填充词，不显示） / rail（原文下部轨道字幕，置于前景，可读性强） / embed（关键词合成于主体背后）。标准模式同时包含两者，仅对峰值词进行嵌入。详见 § 字幕模型。
• 视频交付时保持原样（标准/电影模式）；主题模式的画板预算为唯一被允许的例外——注册表控制的反应节奏（充电变暗、击打、震动、颗粒感）按主题 DNA 定义，并在 matte 合成后应用，确保主体+字幕+画板作为一个整体运动。仅添加字幕；matte 仅用于让主体遮挡嵌入轨道。绝不进行调色/重新着色/扫描线处理。
• 两本规则手册：轨道 → [references/rail.md](references/rail.md)（简明），嵌入工艺 → [references/composition-craft.md](references/composition-craft.md)（详实，仅限嵌入）。按需浏览。

字幕模型 — 轨道 + 嵌入

每一段口语内容属于以下三类之一：

轨道承载大部分文本；嵌入是稀有且值得期待的高潮点。稀缺性是按节拍/段落计算，而非按片段：每段最多一个英雄词（思想单元），绝不会出现两个可见重叠，英雄窗口之间至少保留一拍空隙（编译器在间隔小于 0.6 秒时会发出警告）。短片段通常为 1–2 个；长篇解说约为每节一个。多个英雄词中，最大作者指定者为 APEX（仅它获得完整锁定嵌入 + 宽度适配抬升）；较小者为次要高峰，以放大强调线形式沿列呈现（前景、阻尼运动）——并非每个节拍都需要 matte 展示，这正是让 APEX 成为事件的原因。将每个词都嵌入仍是常见错误。

轨道表面身份严格实现此结构（轨道 = rail.html，嵌入 = index.html 中的高潮部分）。列流身份则省略轨道，全部采用嵌入风格——仅推荐用于氛围优先于可读性的需求，绝不用于解说或旁白，因为文字必须清晰可读（CATALOG.md 在每种身份中已编码此信息）。

第零步 — 从目录中选取唯一一种身份

一个前端，三个后端引擎。用户从 [CATALOG.md](CATALOG.md) 中选取一种身份（共 17 项：12 种经典 + 5 种主题）；引擎、编译器和作者文件通过目录行查表自动确定。绝不将“标准 vs 电影 vs 主题”作为用户选择问题暴露——这些仅为后端名称（产品即使有多个引擎，也只有一个用户体验）。目录中已编码所有路由所需信息：阅读表面、语音风格、推荐用途、场景需求、真实相近组合的邻接备注（如 loud↔ordnance, neon↔neonsign, cream↔stardust）。

技能：嵌入字幕（Embedded Captions）

版本：1.0.0

分块：2/7

操作流程

1. 探测视频片段 → 从目录中筛选 2–3 个身份（identity）→ 推荐其中一个，并附上一句推荐理由 → 由用户选择 → 根据用户选定的身份生成对应文件。

身份为引擎锁定状态（不可跨组合使用；打开一个身份即触发验证事件 — 参见 dna/README.md）。

始终在生成前呈现推荐结果，让用户做出选择。不得自动默认。

（完整的身份表位于 [CATALOG.md](CATALOG.md) — 是路由的唯一权威来源。以下引擎文档描述了各后端的生成契约。）

推荐策略

使用 [CATALOG.md](CATALOG.md) 中的“筛选启发式规则”——这些规则是针对具体身份的（例如：“炸”会筛选 ordnance/stomp/terminal/loud 等身份，并根据“应爆炸的内容”进行选择），而非类别级。不确定时，请使用 anchor。

• Cinematic 模式 → 编写 plan.json，由 make-composition.cjs 编译。
• Theme 模式 → 阅读 [themes/README.md](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，否则拒绝处理（一段伪造词语的逐字记录比无字幕更糟糕）
• 手持拍摄且运动过快（导致遮罩闪烁）

预飞行探测（零成本，可防止最严重失败）

1. 镜头切割探测：在 20%、50%、80% 处采样帧。若出现不同主体或场景，请在切割点前裁剪片段。
2. 画幅黑边探测：首帧是否有黑边？计算安全内容区域，并将字幕放置于该区域内。
3. 亮度探测：采样字幕区域的平均亮度 —

- 低于 60 → 使用浅色文字，无需调整

- 60–180 → 添加字形遮罩（scrim）

- 180 以上 → 使用深色文字 + 遮罩（禁止裸露浅色文字）

**Cinematic 模板默认为奶油色 + screen 混合模式，且为锁定状态 — 此探测仅用于选择合适身份**（明亮场景选 ink 或不透明轨道的 anchor），绝不可用于修改已有模板颜色。

1. 按语气推荐身份（你提出建议，用户做选择 — 参见步骤 0 与 CATALOG.md）

- 解说 / 采访 / 重点信息 → 选用轨道/面板表面类身份

- 诗意 / 社交 / “电影感” → 按风格选择列流类身份

- “炸” / 特效 / VFX / 命名世界 → 选用主题化身份

不确定时 → 使用 anchor（文字可读，场景安全）——但必须提供短名单，由用户决定。

工作流 — 5 个步骤

1. hyperframes init <project> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <project>       # 遮罩 ∥ 转录（并行） → 安全区。单命令完成
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [AGENT 步骤 — 唯一创造性步骤] 编写小量 JSON；根据模式不同，详见下方说明
   Cinematic: author plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     author 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/ 快照
   (Theme 模式：跳过步骤 3b/5 — render-theme.sh 已完成编译 + 渲染 + 板材反应
    + _postfx.sh；交付物为 final_fx.mp4，final.mp4 为板材反应前版本)

步骤 1 的 init 会检查本地安装的技能与 GitHub 上最新版本是否一致，如有差异则自动更新全局技能集。

步骤 3 的操作方式依模式而异：

步骤 3 — Cinematic 模式（纯嵌入）

（待续）

Skill: 嵌入式字幕

Version: 1.0.0

Chunk: 3/7

1. **首先读取 safe-zones.json。旁白区域应放置在 zones.hugLeft / zones.hugRight** —— 这些是紧贴轮廓的干净条带（文字远离主体时会显得悬浮，而非嵌入；远角仅为后备选项，非默认）。主角默认使用 heroAnchor / heroBands.best（居中于主体，约 30–55% 被遮挡）。recommendation:"fg" 表示将旁白置于前景以提升可读性；**只要 heroBands.feasible 成立，主角始终保持嵌入状态**——主角前景模式仅作为最后手段。

1. DNA 即你在步骤 0 中选择的身份（来自 CATALOG.md）——此处不再重新选择。请根据场景对所选 DNA 进行合理性校验（高亮度主角带亮度 > 150 时建议使用 ink 模式）。完整的选择指引位于目录中，涵盖全部十种风格，包括霓虹、故障、金属、动态等。请说明你的选择及理由，由用户最终决定。DNA 锁定类型 / 色彩方案 / 混合方式 / 动画效果 + 主角三幕结构；安全区域 v2（palette / optics / lighting）将自动将其参数化适配当前场景。

1. **编写 <project>/cinematic.json** —— 包含 "dna": "<name>"，并使用思想块（thought-BLOCKS）而非原始分组：每个块包含若干行文字（按从句边界分组，每组 2–5 行），指定其堆叠平面，以及每行的 css（仅限大小 / 粗细 / 风格，不包含位置信息），最多只有一行标记为 "hero": true（被突出显示的词语；"text" 用于显示形式）。格式参考 scripts/make-cinematic.cjs 的头部定义。

1. 编译：运行 node scripts/make-cinematic.cjs <project> —— 将块结构转换为 plan.json，再生成 index.html。自动生成内容包括：按台词序列的时间轴、块内累积、块间翻页、主角锁定机制（主角块的前文上下文、主角本身与后文上下文合并为一个中心对齐的组合体——阅读顺序从上到下即实际发音顺序；上下文浮于前景，主角嵌于背景 = 深度夹层结构；整体规则确保主角主导其上下文）、主次主角分离、按构造确定的阅读顺序、基于安全区域的前景回退策略。随后常规流程继续执行。（手动编写 plan.json 仍支持，适用于块结构无法表达的设计——此时需自行运行 fill-timings.cjs + fit-fonts.cjs + make-composition.cjs。）

步骤 3 —— 主题模式（主题宪章）

请先阅读 [themes/README.md](themes/README.md) —— 包含范式 / 场景库、关联关系、硬性规则及精确的 theme.json 格式定义。

1. 根据内容注册表选择主题 DNA（每个 themes/<name>.json 文件包含 voice 与 when）。说明你的选择及理由，由用户决定。
2. 编写 <project>/theme.json —— 包含 dna、lines（原文保留，按台词顺序排列；每行 1–5 个词——takeover 每行对应一张卡片）、minors（强调词）、hero:{match}（高潮词或短语；嵌入式场景中应从 lines 中移除，内联式或面板+删减场景中则保留在 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](references/reference-bar.md) 中列出的 5 项正面检查（海报测试 · 谨慎测试 · 一眼层级 · 场景呼应 · 静默审计）——失败清单防止渲染结果崩溃；正面清单使作品真正具备设计感。两项均通过后方可发布。

建议进行“陌生眼审查”（尤其适用于面向用户的项目）：你对自身布局存在确认偏误。若可创建子代理，仅提供预览图与本清单，要求其逐帧判断 “PASS” 或 “FIX”（“请根据五点清单审查这些字幕预览，每帧回答 PASS 或具体修复建议”）。在 plan.json / theme.json 中修正问题，重新编译、重新预览——每次循环耗时仅数秒。待预览通过后，再进行一次完整渲染。

技能：嵌入式字幕

版本：1.0.0

分块：4/7

按 safe-zones.json 中的判断条件（heroAnchor.bandLuma, palette.temperature） × 内容选择。

注册名 — [dna/README.md](dna/README.md) 提供决策规则。创作时：

cinematic.json 使用 "dna": "<名称>"。

引擎会根据 DNA 自动生成 主角三幕结构（无需手动创作）：

可见字幕变暗（铺垫）→ 按字母逐个进入，幅度与发音音量成正比（冲击）→ 呼吸 + 发光直至退出（余晖）。

（旧版：plan.template:"cinematic-cream" 会自动映射至 dna:"cream"。

已弃用的 54 模板库位于外部路径 ~/Downloads/embedded-captions-archive/standard-templates-54/；

_motion.md 仍保留在本技能内，作为动作动词参考目录。）

审美决策 — 气氛 × 镜头 × 平台（输入到目录短名单，非二次路由）

从三个维度对视频进行分类，并将结果输入至 [CATALOG.md](CATALOG.md) 的短名单筛选流程 — 此部分不独立决定模式或引擎：

气氛（内容的整体感觉？）

• documentary | conversational | energetic | poetic | keynote | investigative | music-video

镜头（画面构图？）

• close-up（头部+肩部） | mid-shot（躯干以上） | wide（全身及以上） | cut-montage（多镜头混合）

平台（将在何处播放？）

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

参考 [references/direction-catalog.md § 分类矩阵](references/direction-catalog.md) 获取方向语言描述 — 然后返回 [CATALOG.md](CATALOG.md) 进行身份短名单筛选（该矩阵仅用于指导短名单，实际路由由目录文件决定）。

布局技巧（嵌入轨道）—— 嵌入前必读

完整的 嵌入轨道 操作手册详见 [references/composition-craft.md](references/composition-craft.md)：

包括转录角色标注、短语分组、层级与安全区锚定、区域一致性、高潮爆发与可读性、边缘呼吸处理、遮挡三步评估，以及累积与持久性控制。

它决定了一个被突出的短语如何自然融入画面 —— 在编写任何嵌入内容（Cinematic plan.json 或 Standard index.html）前请务必阅读。

默认的 轨道 轨道拥有更简单的规范 → [references/rail.md](references/rail.md)。

共享知识

请优先阅读美学原则和方向目录。 其余内容均为实现细节。

不可妥协项

• 面部不得持续100%被遮挡 — 每0.3秒窗口内，面部边界框必须至少有30%未被遮挡。
• WCAG对比度要求 — 最终渲染需通过lint检查；若不达标，需调整配色方案。
• 确定性 — 禁用 Math.random()、Date.now() 和 repeat:-1。
• 绝不对视频进行评分或重新着色。原始素材保持原样，仅添加字幕。禁止全帧扫描线、双色调、暗化、晕影等处理。赛博朋克/CRT纹理应存在于字幕元素内部，而非覆盖整个画面。
• 以轨道（rail）优先原则处理对话型/解说类内容。不要嵌入完整文稿——大部分文本属于轨道；仅嵌入关键点。嵌入全部内容是默认的常见错误。
• 嵌入内容稀疏且间隔合理 — 每句/每拍最多一个嵌入，禁止相邻或共显，至少间隔一拍，最多一个 apex。高潮应为每拍的峰值，而非“整段视频唯一的高潮点”。
• **前景蒙版 = 人物（使用 hyperframes remove-background、u2net_human_seg，Apache-2.0 许可）**。人体分割基于意图，但非手术级精确：细小物体（如麦克风支架）通常排除在外——字幕会覆盖其上，位于人物之后；而靠近主体的显著物体（如望远镜、工作台设备）可能渗入蒙版并遮挡字幕。主体持有的物品（产品、手机）可能偶尔消失，使字幕短暂显现于前。切勿假设：在放置主视觉前，应在2-3个时间戳处采样 frames_fg/；优先选择无泄漏家具干扰的位置（heroAnchor 可能受泄漏影响偏移，需与 frames_bg 对比验证）。
• 安全区域（safe-zones）为“道具盲区”——需人工逐条检查所用带区。区域/主视觉带仅评估主体遮挡和亮度：若麦克风、望远镜或屏幕位于“干净”区域中，它们对区域检测不可见（而道具渗入蒙版会导致 heroAnchor.centerXPct 偏离人物）。创作前，请提取每个目标带区的一帧；若存在道具，测量其边界框并移动或缩小平面。已有两个真实案例因执行此操作而成功交付。自动道具显著性识别仍为已知缺陷；区域的 peakLuma 仅捕捉运动中的亮物。
• 字幕必须始终在画面内。电影模式强制禁止画面外溢出；标准模式运行 check-overflow.cjs 作为警告（故意溢出是唯一例外——请阅读警告说明）。
• 每个字幕在屏幕上停留时间 ≥ 0.5秒 — 更短则无法阅读。
• **字幕时间必须与 transcript.json 匹配，误差 ≤80ms** — 字幕提前或延后500ms将破坏场景沉浸感。电影模式在渲染前通过 render-and-composite.sh 执行 check-timing.cjs --strict；主题模式在编译时强制相同时间对齐（由 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亮度值）下失效。电影模板 使用奶油色 + screen 混合，此设计锁定不可更改 → 在明亮背景下会褪色，因此应选用 ink（专为明亮表面设计的压印字体）或 anchor 主题（不透明轨道面），而非强行覆盖外观。
• **禁止对文字进入动画使用 letter-spacing 或 filter:blur** — 内联块级元素重排会导致行跳动。
• 核心模型（CoreML）禁用于抠图 — onnxruntime CoreML EP 的混合精度分区曾导致人脸透明通道损坏（此前 RVM 引擎已观测到此问题；请勿重复尝试）。抠图仅限 CPU 处理（1080p 下约2fps ≈ 每10秒耗时2-3分钟；长片段需预留预算）。

依赖项

• hyperframes，构建产物位于 packages/cli/dist/cli.js。脚本会自动解析检出路径：若此技能内置于 hyperframes 中，则使用 HYPERFRAMES_ROOT 环境变量指向仓库根目录；否则默认为 ~/Downloads/hyperframes。通过 bun install && bun run build 进行构建。
• **以 Node 为核心；仅通过 uvx 调用 Python 两次（无需手动安装）**：语音转录通过 uvx 执行 WhisperX（支持词级时间戳与对齐；降级逻辑见 SKILL §transcription），Theme 的 drawon 组件在编译时调用 python3 scripts/gen-stroke-path.py。其余所有功能均基于 hyperframes 已内置的工具链运行：背景去除使用 hyperframes CLI 的 **remove-background**（基于 u2net_human_seg 模型；权重首次自动下载约 168 MB，存于 ~/.cache/hyperframes/），图像/透明度运算使用 **sharp，布局/遮挡/溢出处理使用 puppeteer，视频处理使用 ffmpeg**。所有依赖项均由 hyperframes 检出目录自动解析，无需额外安装。
• **语音转录 = 通过 uvx 调用 WhisperX**（支持词级时间戳与对齐；无需手动安装 — transcribe.cjs 驱动 uvx whisperx）。若存在已有的词级 transcript.json 文件，则直接使用，不重新生成。
• 源视频 — matte.cjs 与 transcribe.cjs 会自动解析 source.mp4（或匹配片段文件名、读取 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/。在全新机器上首次准备时需联网完成此次下载。

若发现任何硬依赖缺失，请立即停止并提示用户 —— 不得静默跳过步骤。