embedded-captions

Embedded Captions

统一风格目录，预先选定（CATALOG.md —— 包含 17 种视觉风格；底层驱动的三大引擎属于后端实现细节）。Standard（标准模式，默认）构建一条干净清晰的逐字轨字幕（rail）（位于底部三分之一的常规字幕，承载绝大部分文本）+ 在高潮时刻合成到人像后方场景中的嵌入字幕（embed）。Cinematic（电影感模式）则是纯嵌入式 —— 无轨字幕，每条字幕均合成在人像后方（以主视觉排版、文本积聚和遮罩遮挡作为核心视觉效果）。Theme（主题模式）则是完整的主题宪章体系 —— 主体范式 × 高光重磅场景 × 前景特效 × 背景反应，由注册表（themes/README.md）组合而成：ordnance terminal neonsign stardust stomp。大多数知识解说/配音解说视频适用 Standard 模式；嵌入特效是极其珍贵的高潮节点，需要“赚取”才能出现 —— 把每一个字都做成嵌入特效是新手最常犯的错误；Theme 模式则专为 VFX 级的高要求而生（如“炸”、“特效”、“像 AE 做的”）。

---

Operational flow (TL;DR)

下文的工艺细则虽然较长，但管线本身其实非常精简 —— 所有确定的步骤均由计算或编译完成，无需手写：

1. 决策门禁（Decision gate）（直接拒绝不合规的剪辑素材）→ 从 CATALOG.md 中挑选 1 种视觉风格（identity）（共 17 种；引擎与编译器通过字典查表自动获取 —— 绝不要向用户询问模式/分类）
2. hyperframes init（若项目目录已存在且内含视频则可跳过 —— matte.cjs/transcribe.cjs 会自动将目录内的任意视频作为 source.mp4）→ bash scripts/prepare.sh <project>（并行执行 扣像 ∥ 语音转写 ∥ 音频包络，随后结合场景调色板/光学/灯光生成 safe-zones v2 —— 一条命令搞定，无一遗漏）
3. 编写包含创意选项的精简 JSON（先阅读 safe-zones.json）：
   Cinematic 模式 → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs；
   Theme 模式 → theme.json → make-theme.cjs（包含 rail/panel/poem/takeover 等范式；anchor 为默认安静的轨字幕）
4. 视觉质检（Visual QA）：node scripts/preview-frames.cjs <project> → 单帧约 2s 快速生成高保真合成预览（无需完整渲染）。付费渲染前务必检查 § Visual QA 章节。
5. render-and-composite.sh → 校验门禁（时间轴 / 遮挡+高光 / 溢出 / 交付）→ final.mp4

最容易被忽视的关键规则：

• 轨字幕 rail（默认）+ 嵌入字幕 embed（晋升高光）。 drop（废词语气词，不显示）/ rail（底部三分之一逐字字幕，置顶前置，承载绝大多数文本）/ embed（合成在人像后方的高潮节点词）。Standard 模式两者兼用，仅把高潮词升格为嵌入字幕。详见 § Caption model。
• 原始视频保持原汁原味（Standard/Cinematic 模式；Theme 模式的 PLATE 背景动画预算是唯一的特许例外 —— 根据主题 DNA 定义的注册表级别反应节奏（蓄力暗转、冲击、震动、噪点），在遮罩合成后统一应用，使主体+字幕+背景板作为一个整体帧联动）—— 除了添加字幕外不做任何修改，扣像遮罩仅用于让人像遮挡嵌入字幕轨道。切勿对原视频做调色、重新配色或添加扫描线。
• 规范手册分两本：轨字幕 → references/rail.md（精简），嵌入字幕工艺 → references/composition-craft.md（丰富，仅针对嵌入）。按需查阅。

---

Caption model — rail + embed

每一句说出的台词都归为以下三类之一：

	类别	展现形式
drop	废词 —— 呃/啊、口吃、自我修正	不显示
rail	默认类别 —— 常规口播内容（逐字呈现）	干净清晰的底部三分之一字幕，置于最前层，确保易读。重点词可包含行内 emphasis 高亮（点缀色 / 当前高亮词弹出效果）—— 但依然停留在轨字幕上。
embed	晋升的高光 —— 核心亮点节奏	巨幅单词，合成在人像后方（通过遮罩形成遮挡），配有精心设计的入场和出场动画。

轨字幕承载大部分文本；嵌入字幕则是稀缺且“赚取”的高潮节点。 这种稀缺性是按节奏点/语意块计算，而非按整段视频计算：每个语意块（独立观点）最多包含 1 个 hero（主视觉词），绝对不能同时出现两个，且两个 hero 窗口之间至少保留一个拍子的停顿气口（编译器会在间隔小于 0.6 秒时发出警告）。短视频素材 → 通常 1~2 个；长篇讲解视频 → 每个章节约 1 个。在多个 hero 中，字号最大的那个是顶点高潮 APEX（唯有它独占完整排版嵌入 + 宽度适配抬升）；较小的则是次级高光 MINOR peaks，它们作为超大强调行停留在列中（前景层，带阻尼运动）—— 并不是每个节奏点都需要遮罩展示，而这正是让顶点高潮具备冲击力的关键。把每一个字都做成嵌入特效依然是新手最常犯的错误。

轨字幕表层风格（Rail-surface identities）正是基于此构建（轨字幕 = rail.html，高潮嵌入 = index.html）。而列流风格（Column-flow identities）则丢弃了轨字幕，将所有文本均设为嵌入样式 —— 仅在用户追求氛围感胜于逐字阅读时推荐使用，绝不能用于必须保证文字清晰可读的知识解说/口播解说视频（CATALOG.md 中为每种风格都标注了此项属性）。

---

Step 0 — pick ONE identity from the CATALOG

统一前端入口，三大后端引擎驱动。 用户从 CATALOG.md 中选择一种视觉风格（IDENTITY）（共 17 个条目：12 个经典风格 + 5 个主题风格）；引擎、编译器及配置文件均通过查阅目录表格自动推导。切勿向用户提出“Standard vs Cinematic vs Theme”这种选择题 —— 那些都是后端名称（良好的产品体验即使包含多个底层引擎也应该具备统一的 UX）。目录中包含了路由所需的一切信息：阅读表层、基调声线、推荐场景、场景需求，以及极易混淆相似对的判别说明（如 loud↔ordnance、neon↔neonsign、cream↔stardust）。

流程：检测视频剪辑 → 从目录中筛选出 2~3 个候选视觉风格 → 推荐其中 1 个并附带一句话理由 → 由用户做最终选择 → 编写对应视觉风格的文件。视觉风格与引擎强绑定（不可跨引擎组合；尝试开启跨引擎组合会触发校验报错 —— 详见 dna/README.md）。

必须先向用户展示你的推荐方案，待用户确认后再开始编写代码/配置文件。 严禁悄悄使用默认值。

（完整的视觉风格清单见 CATALOG.md —— 这是路由分发的唯一事实来源。下文的引擎文档描述了各个后端的编写规范。）

推荐启发式规则：参考 CATALOG.md 中的“候选筛选启发规则” —— 筛选是基于具体风格维度的（例如提到“炸”时，候选清单包含 ordnance/stomp/terminal/loud，并根据“具体要炸什么”来进行选择），绝非基于粗粒度分类。拿不准时 → 选 anchor。

• Cinematic → 编写 plan.json 指定锁定模板，由 make-composition.cjs 进行编译。
• Theme → 阅读 themes/README.md，编写 theme.json，运行 scripts/render-theme.sh（自动完成编译 + 渲染 + 背景板特效 → 生成 final_fx.mp4）。

---

Decision gate — RUN FIRST

在进入任何模式之前，先探测视频并对场景进行分类。

ffprobe <video.mp4>                    # 检查参数信息
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # 在 20%/50%/80% 时间点采样

检查采样帧。若存在以下情况，请直接拒绝处理：

• 多人说话 / 硬切镜（拆分并单独渲染每个镜头，或者直接拒绝）
• 无真人主体（本 skill 专门针对单人口播）
• 短于 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 重新转写一次，若依然异常则拒绝处理（满屏胡编乱造的逐字字幕比没有字幕更糟糕）
• 镜头剧烈晃动手持拍摄（抠图遮罩会发生频闪）

Pre-flight probes（零成本预检，规避致命失败）

1. 分镜切镜探测。 在 20%、50%、80% 处采样帧。若出现了不同的主体或场景，在切镜位置前裁剪视频。
2. 黑边/柱状黑边探测。 首帧是否有黑边？计算安全内容矩形区域（safe content rect），并将字幕位置约束在区域内部。
3. 亮度探测。 采样字幕区域的平均亮度 —— 小于 60 → 浅色文字直接显示，60-180 → 添加字符衬底遮罩（glyph scrim），180+ → 不透明文字 + 衬底遮罩（绝不要直接使用裸露的浅色文字）。Cinematic 模板采用 cream+screen 模式且属性锁定 —— 使用此探测器是为了_挑选契合的视觉风格_（明亮场景 → 选 ink，或使用带不透明轨字幕的 anchor 主题），而不是为了去改动模板配色。
4. 基于调性的视觉风格推荐（你提出推荐，用户做最终选择 —— 参见步骤 0 + CATALOG.md）。 知识解说 / 访谈 / 文字必须易读的场景 → 选轨字幕/面板表层风格；诗意 / 社交媒体 / “电影感” → 按基调调性选择列流风格；“炸 / 特效 / VFX” / 具象世界观 → 选择主题风格。拿不准时 → 选 anchor（字能看清，场景安全）—— 但务必列出候选清单供用户挑选。

---

Pipeline — 5 steps

1. hyperframes init <project> --non-interactive --video <video.mp4> --skip-skills
2. bash scripts/prepare.sh <project>       # 扣像 ∥ 语音转写（并行执行）→ safe-zones。一条命令搞定。
                                           #   → 生成 frames_fg/ transcript.json safe-zones.json
3. [AGENT 步骤 —— 唯一需要创意的步骤] 编写一份精简的 JSON 配置；不同模式对应格式如下：
   Cinematic 模式: 编写 plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme 模式:     编写 theme.json → bash scripts/render-theme.sh <project>   （自动完成编译 + 渲染 + 背景板特效）
4. node scripts/preview-frames.cjs <project>   # 单帧约 2s 生成合成预览图 → 参阅 § Visual QA（在渲染之前）
5. bash scripts/render-and-composite.sh <project>  # 校验门禁 → 生成 final.mp4 + history/ 历史快照
   （Theme 模式：跳过步骤 3b 与步骤 5 —— render-theme.sh 内部已包含编译 + 渲染合成
    + _postfx.sh 后处理；最终交付物为 final_fx.mp4，final.mp4 仅为应用背景板特效前的中间产物）

Step 3 differs by mode:

Step 3 — Cinematic mode (pure embed)

1. 务必先阅读 safe-zones.json。 旁白层文字应放置在 zones.hugLeft/hugRight 区域 —— 即贴合人像剪影的干净条带（文字如果离身体太远会显得飘浮悬空，缺乏融入感；边角区域是兜底退路，非默认首选）。Hero 高光词默认定位于 heroAnchor/heroBands.best（以人像为中心居中，约 30%~55% 被遮挡）。当 recommendation:"fg" 时，会把旁白文字提到前景层以确保可读性；但只要 `heroBands.feasi