返回技能市场
内容创作 安全

embedded-captions

@admin/embedded-captions

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

admin 热度 244v0.0.1
首先，让此 skill 保持最新——运行前请先征得用户确认： npx hyperframes skills update embedded-captions。当所有内容均为最新时，它会快速执行一次空操作；否则，在依赖这些内容前，它会更新此 skill 及其依赖的核心领域 skills。

嵌入式字幕

一个目录，预先选定（[CATALOG.md](CATALOG.md) — 35 种视觉标识；其背后的引擎属于后端细节）。标准模式（默认）构建一条简洁的逐字 字幕栏（承载大部分文本的下三分之一字幕）+ 一条在高潮处_融入_主体后方场景的 嵌入式 高潮字幕。电影感模式采用纯嵌入方式——没有字幕栏，每条字幕都合成在主体后方（以主视觉字体排印、累积和遮挡作为效果）。主题模式是一套完整的主题化规范体系——正文范式 × 主视觉场景装置 × 前景特效 × 原片响应，由注册表组合而成（[themes/README.md](themes/README.md)）：ordnance terminal neonsign stardust stomp。大多数解说 / 旁白采用 标准模式；嵌入是稀缺且需内容支撑的高潮——嵌入每个词是常见错误；主题模式适用于 VFX 级需求 ("炸", "特效", "像 AE 做的")。

---

操作流程（TL;DR）

经由 /hyperframes 路由后，意图层只确认输入（具体使用哪个片段），并告知用户视觉标识选择将延后询问——候选清单必须依据探查后的片段生成，因此仍留在下方步骤 1 处理；该层有关运行形态的问题不适用（素材保持原样，也没有分镜可供审阅）。若存在 BRIEF.md，其中会记录已确认的输入和所有用户备注——请先阅读。

下方的制作说明很长；但流水线本身很短——所有确定性内容都通过计算或编译生成，不得手写：

  1. 决策门禁（拒绝不合格的片段）→ 从 [CATALOG.md](CATALOG.md) 中选择一个视觉标识（35 种视觉标识；引擎/编译器通过查表确定——不得向用户提出模式/类别问题）
  2. hyperframes init（如果项目目录已存在且其中已有视频，则跳过此步骤——matte.cjs/transcribe.cjs 会将目录中的任意视频作为 source.mp4）→ bash scripts/prepare.sh <project>（抠像 ∥ 转写 ∥ 音频包络并行执行，随后基于场景调色板/光学特征/光照生成安全区 v2——一条命令，绝无遗漏）
  3. 编写一份包含创意选择的小型 JSON（先阅读 safe-zones.json）：电影感模式 → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs；主题模式 → theme.json → make-theme.cjs（字幕栏/面板/诗歌/接管范式；anchor 是低调字幕栏的默认选项）
  4. 视觉 QA：node scripts/preview-frames.cjs <project> → 约 2s/帧生成高保真合成预览（无需渲染）。在付出渲染成本前检查 § 视觉 QA。
  5. render-and-composite.sh → 门禁检查（时序 / 遮挡+主视觉 / 溢出 / 交接）→ final.mp4

人们容易忽略的关键规则：

  • 字幕栏（默认）+ 嵌入（提升）。 drop（填充语，不显示）/ rail（逐字下三分之一字幕，位于前景，承载大部分文本）/ embed（合成在主体后方的高潮词）。标准模式会同时实现两者，只嵌入高潮词。请参阅 § 字幕模型。
  • 视频交付时保持原样（标准/电影感；主题模式的 PLATE 预算是唯一获准的例外——每个主题 DNA 所定义、受风格类型限制的反应节拍（蓄力变暗、冲击、抖动、颗粒），会在遮罩合成之后应用，使主体、文字和底板作为同一帧一起运动）——唯一添加的内容是字幕；遮罩只用于让主体遮挡嵌入轨道。禁止对素材进行调色、重新着色或添加扫描线。
  • 两套规则手册：字幕栏 → [references/rail.md](references/rail.md)（精简），嵌入制作 → [references/composition-craft.md](references/composition-craft.md)（详尽，仅适用于嵌入）。按需浏览。

---

字幕模型 — 字幕栏 + 嵌入

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

| | 内容 | 显示方式 | | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 丢弃 | 填充语 — 嗯/呃、磕巴、自我纠正 | 不显示 | | 字幕栏 | 默认类型 — 普通口述内容（逐字） | 简洁的下三分之一字幕，位于前景，清晰可读。可以用行内 emphasis 高亮突出一个有冲击力的词（强调色 / 当前词弹出效果）——该词仍位于字幕栏中。 | | 嵌入 | 经提升的高潮 — 标题式节拍 | 将一个大字号词合成在主体后方（抠像遮挡），并采用经过设计的入场 + 出场 |

字幕栏承载大部分文本；嵌入是稀缺且需内容支撑的高潮。 这种稀缺性按 每个节拍/区块，而非每个片段 计算：每个区块（意群）≤ 1 个主视觉，不得有两个同时可见，主视觉窗口之间的留白 ≥ 一个节拍（低于 0.6s时编译器会发出警告）。短片段 → 通常有 1–2 个；长篇解说 → 每个章节约一个。多个主视觉中，创作时尺寸最大的一个是 APEX（只有它会获得完整的锁定组合式嵌入 + 宽度适配放大）；较小的则是 MINOR 峰值，以超大强调行的形式沿各自列呈现（前景、阻尼运动）——并非每个节拍都需要抠像展示，这恰恰让顶峰保持事件感。嵌入每个词仍是常见错误。

以字幕栏为显示载体的视觉标识正是这样构建的（字幕栏 = rail.html，嵌入 = index.html 中的高潮）。纵列流式视觉标识会取消字幕栏，让所有内容都采用嵌入式呈现——仅在氛围优先于逐字呈现的需求中推荐，不得用于文字必须清晰可读的解说 / 旁白（CATALOG.md 为每个视觉标识记录了这一点）。

---

步骤 0——从目录中选择一种视觉风格

一套前端，后端三种引擎。 用户从 [CATALOG.md](CATALOG.md) 中选择一种视觉风格（共 35 项：10 项经典风格 + 25 项主题风格）；引擎、编译器和创作文件均通过查询对应的目录条目确定。禁止将“标准 vs 电影感 vs 主题”作为问题向用户提出——这些都是后端名称（即使有多种引擎，一个产品也只有一套 UX）。目录包含路由所需的一切信息：阅读载体、调性、推荐用途、场景要求，以及真正相近的风格对之间的相近项说明（loud↔ordnance、neon↔neonsign、cream↔stardust）。

视觉标识选择是一个偏好门禁（../hyperframes/references/brief-contract.md § 1）：在自主模式（“给我惊喜” / “替我决定”）下，自行从候选清单中选择，并用一行说明原因，而不是询问用户。

流程：探查片段 → 从目录中筛选 2–3 个视觉风格 → 推荐一个并用一句话说明理由 → 由用户选择（自主模式：由你选择并说明理由）→ 编写该视觉风格对应的文件。视觉风格与引擎锁定（不得跨引擎组合；打开其中一个即触发验证事件——参见 dna/README.md）。

始终先给出你的推荐，让用户选择后再编写。 不得静默使用默认项。

（完整的视觉风格表位于 [CATALOG.md](CATALOG.md)，它是路由的唯一事实来源。下方的引擎文档说明各后端的编写约定。）

CATALOG.md 涵盖了这里的全部答案空间：此工作流不搜索 HyperFrames 组件注册表。 合成工作流在编写有名称的视觉风格前会运行 npx hyperframes catalog；此工作流不得运行该命令。其引擎均为锁定的编译器，会使用 cinematic.json / theme.json 并自行生成合成，因此注册表项——包括 caption-* 块——没有可挂载的位置。注册表块用于在已设计的画布上设置文本样式；此 skill 则借助遮罩将字幕烧录到他人的视频素材中。当没有视觉风格符合需求时，应明确说明并选择最接近的一项，而不是超出目录范围寻找。

推荐启发式规则：使用 [CATALOG.md](CATALOG.md) 中的“候选筛选启发式规则”——这些规则针对具体视觉风格（例如，"炸" 会将 ordnance/stomp/terminal/loud 列入候选，并根据究竟应让什么爆炸来选择），绝不在类别层级上进行。拿不准 → anchor。

  • 电影感模式 → 为锁定模板编写 plan.json，并由 make-composition.cjs 编译。
  • 主题模式 → 阅读 [themes/README.md](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%

查看样本。遇到以下情况时拒绝：

  • 多位说话者 / 硬切（拆分并分别渲染每个镜头，否则拒绝）
  • 没有人物主体（此 skill 适用于人物口播视频）
  • 片段短于 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. 亮度探测。 对字幕区域的平均亮度进行采样——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 plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   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 会将已安装的 skills 与 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）会自动针对当前场景对其进行参数化。
  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。系统会自动生成：按转录顺序编排的时间、块内累积、块间翻页、主视觉锁定组合（主视觉块的前置上下文、主视觉和后置上下文堆叠成一个以主体为中心的紧密构图——通过结构保证从上到下的阅读顺序 = 口述顺序；上下文浮于前景，而主视觉嵌入后方 = 深度三明治；视觉体量规则确保主视觉在上下文中占据主导）、顶峰/次级主视觉拆分、通过结构保证的阅读顺序，以及根据安全区域设置的前景后备方案。随后照常运行各检查关卡。_(对于块无法表达的设计，仍可直接手工编写 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；对于行内重头场景和面板+遮盖，则将其保留在其中）。
  3. 渲染：bash scripts/render-theme.sh <project> — 编译（在编译时执行逐字内容完整性门禁）、渲染两个图层、合成并应用底板反应效果 → final_fx.mp4。在编译与渲染之间使用 preview-frames.cjs 进行视觉 QA。

---

视觉 QA — 在渲染之前预览

node scripts/preview-frames.cjs <project> [t…] 会合成每帧约 2s 的高保真预览帧（在跳转时间点截取的字幕层 + 真实视频帧 + 蒙版遮挡 + 字幕轨叠加 = 该时刻最终合成的实际效果）。默认采样点 = 每个组/高潮窗口。完整渲染需要数分钟 — 禁止用它来_发现_布局问题。

依据此列表检查预览（<project>/preview/sheet.png）— 以下问题是几何门禁无法捕获的：

  1. 泛白 — 浅色文字覆盖在明亮区域（窗户/标牌/天空）上：无法阅读 → 移动平面或更改 DNA/模式（明亮场景 → ink）。
  2. 文字叠文字 — 字幕覆盖场景本身的文字/图形，或两个字幕组相互碰撞。
  3. 阅读顺序 — 屏幕上的垂直顺序必须与说话顺序一致；主视觉文字不得位于后说内容的下方。
  4. 主视觉存在感——高潮内容应该足够大，并明显位于主体之后（约有 30–55% 被遮挡），而不是悬浮在边缘空白处的标签。
  5. 平衡 — 形成一个连贯统一的纵栏/横带，而非散落的碎片；边距留有呼吸空间；不得有任何内容被裁切。

然后执行 [references/reference-bar.md](references/reference-bar.md) 中的 5 项正向检查（海报测试 · 怯弱测试 · 一眼可辨的层级 · 场景契合 · 冷场审查）— 问题列表可避免渲染结果出错；正向列表则让它真正具有_设计感_。两者都通过后再交付。

全新视角审查（建议所有面向用户的内容都执行）：你对自己的布局存在确认偏误。如果可以启动子 agent，仅向其提供预览表 + 此检查清单，并要求其逐帧给出 PASS/修复结论（“按照这份 5 点检查清单审查这些字幕预览；逐帧回答 PASS 或具体修复方案”）。在 plan.json / theme.json 中应用修复，重新编译并重新预览 — 每次迭代只需数秒。预览通过后只渲染一次。

---

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

两种模式均使用 [dna/](dna/README.md) — 十种由艺术指导设计且按场景参数化的视觉语言（从素材采样强调色、沿测得光线方向生成接触阴影、深度匹配模糊、与 RMS 耦合的主视觉振幅）：

| DNA | 风格调性 | 适用场景 | 风格表达 | | --------------- | -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- | | cream | premium-warm | 暗色/中等亮度的暖色场景 | Inter + 暖奶油色 + 滤色；发光浮现的主视觉（电影感奶油风的后继方案） | | ink | 高端 | 明亮场景（亮度 > 150） | 近黑色正片叠底 — 文字仿佛印在墙面上；明亮场景的解决方案 | | editorial | editorial-luxe | introspective / fashion / poetic | Bodoni Moda、小写斜体主视觉 — 杂志般的优雅 | | keynote | tech-premium | product / launch | 不透明的白色 Inter 800，正中央的静止感 | | documentary | 正式 | interview / serious | 灼刻式显现，无主视觉 — 庄重感本身就是风格 | | loud | 张扬 | hype / sport / social | Anton + 从场景采样的强调色，整体猛击 + 涟漪；正文在前景中高调宣告（bodyLayer: fg） | | neon | loud-neon | 霓虹黑色电影 / 夜生活 / 科技黑色电影（暗色场景） | 电光青色标牌、点亮闪烁，主视觉像标牌一样通电亮起 | | glitch | loud-neon | digital / hacker / AI | RGB 分离重影在落点瞬间合拢；机械打击乐式节奏 | | chrome | loud-luxe | Y2K / fashion-tech / music | 液态金属渐变主视觉 + 停留期间的一次光泽扫过 | | velocity | loud-sport | sport / auto / fitness | 每个词都沿其运动矢量入场（拖影+倾斜），主视觉掠过并带有速度轨迹 |

根据 safe-zones.json（heroAnchor.bandLuma、palette.temperature）× 内容调性进行选择 — [dna/README.md](dna/README.md) 中提供了决策规则。创作方式：cinematic.json 接受 "dna": "<name>"。

引擎根据 DNA 生成主视觉三幕式效果（无需创作）：同屏字幕变暗（铺垫）→ 逐字母入场，振幅 ∝ 说话响度（冲击）→ 呼吸并发光直至退场（余韵）。

（旧版：plan.template:"cinematic-cream" 会自动映射到 dna:"cream"。已弃用的 54 模板库存档于此仓库之外，且不随此 skill 分发；_motion.md 仍保留在 skill 内，作为动作动词参考目录。）

---

审美决策 — 调性 × 镜头 × 平台（目录候选列表的输入，而非第二套路由）

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

调性（内容呈现什么感觉？）

  • 纪录片式 | 对话感 | 动感 | 诗意 | 主题演讲 | 调查式 | 音乐视频

镜头（采用什么构图？）

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

平台（将在哪里播放？）

  • 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)：转录角色标注、短语分组、平面与干净区域锚定、区域一致性、高潮弹出效果与可读性、边缘留白、遮挡的 3 步判断，以及累积/持续显示。它规定了被提升的短语如何融入场景——在编写任何嵌入内容之前，请先阅读该指南（电影感模式的 plan.json 或标准模式的 index.html）。默认的字幕条轨道有自己独立且简单得多的规范 → [references/rail.md](references/rail.md)。

---

共享知识

| 文档 | 内容 | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | [references/rail.md](references/rail.md) | 字幕条轨道——标准的画面下三分之一字幕规范（默认设置；承载大部分文本）。 | | [references/composition-craft.md](references/composition-craft.md) | 嵌入轨道实践指南——分组、平面、高潮凸显、遮挡判断、累积/持续显示。嵌入前请先阅读。 | | [dna/README.md](dna/README.md) | DNA 注册表——十种根据场景参数化的视觉语言及其选择方法。 | | [references/reference-bar.md](references/reference-bar.md) | 审美标杆——各风格语域对应的世界级参考 + 5 项正向检查。 | | [references/aesthetic-principles.md](references/aesthetic-principles.md) | 18 条规则。 在审美上胜过 Veed AI。请先阅读。 | | [references/motion-vocabulary.md](references/motion-vocabulary.md) | 10 个命名动效基元 + 基调→时序对照表 | | [references/direction-catalog.md](references/direction-catalog.md) | 10 套可直接交付的美学风格 + 基调×镜头×平台矩阵 | | [references/anti-patterns.md](references/anti-patterns.md) | 已被杜绝的问题（CoreML、字间距变化导致的重排等） | | [references/scene-types.md](references/scene-types.md) | 墙面何时可用（4 项条件） | | [references/layout-heuristics.md](references/layout-heuristics.md) | 平面定位、净区选择、顶部区域的 3 项条件、左右黑边计算 | | [references/typography-presets.md](references/typography-presets.md) | 字号 × 栏宽矩阵（初始参考值） | | [references/caption-grouping.md](references/caption-grouping.md) | 单词 → 字幕组规则（停顿、句子边界） | | [references/failure-modes.md](references/failure-modes.md) | 开发中的长尾陷阱 | | [references/bespoke-vs-presets.md](references/bespoke-vs-presets.md) | 预设有时失效的原因；克隆并微调模式 |

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

---

不可妥协的要求

  • 严禁持续 100% 遮挡面部——在每个 0.3s窗口内，面部边界框必须有 ≥ 30% 的区域未被遮挡。
  • WCAG 对比度——最终渲染会执行校验；若未通过，请修正调色板。
  • 确定性——不得使用 Math.random()、Date.now() 或 repeat:-1。
  • 禁止对视频进行调色/重新着色。 原始视频必须不经改动地交付——字幕是唯一新增内容。不得在主镜头上叠加全画面扫描线 / 双色调 / 压暗 / 晕影。霓虹黑色电影 / CRT 纹理应置于字幕元素 _内部_，不得覆盖整个画面。
  • 口播人物视频 / 解说视频以字幕条为先。 不要嵌入整段转写文本——大部分文本应由字幕条承载；仅嵌入高峰内容。嵌入全部内容是默认情况下最常犯的错误。
  • 嵌入内容应稀少且彼此留有间隔。 每个句子/节拍的嵌入内容必须 ≤ 1 个；禁止两个嵌入内容相邻或同时可见；间隔必须 ≥ 一个节拍；且最多只能有一个 apex。高潮 = 每个节拍的高峰，而不是“整段视频唯一的最终爆点”。
  • 遮罩 = 人物（hyperframes remove-background、u2net_human_seg、Apache-2.0）。 其目标是人物分割，但精细度并非外科手术般精准：细长且偏离主体的物件（麦克风悬臂）通常不会纳入遮罩——字幕会渲染在这些物件之上、人物之后——而主体附近的大型显眼物体（望远镜、桌面设备）仍可能误入遮罩并遮挡字幕。主体手持的物体（产品、手机）可能间歇性地未被纳入遮罩，导致字幕显示在其前方。禁止想当然：放置主视觉前，必须从 frames_fg/ 中抽查 2–3 个时间点，并优先将主视觉放在避开所有误入遮罩物件的位置（heroAnchor 可能被误入物件带偏——请与 frames_bg 交叉核对）。
  • 安全区域无法识别道具——目视检查使用的每个带区。 区域/heroBands 只对_主体_遮挡和亮度评分：位于“干净”区域内的麦克风、望远镜或屏幕不会被识别（误入遮罩的道具还会使 heroAnchor.centerXPct 偏离人物）。编写前，从计划使用的每个带区中提取一帧；如果其中有道具，请测量其边界框并移动/缩小平面。两个真实案例之所以能够无问题交付，完全是因为 agent 严格执行了这一步。（自动道具显著性检测是一个已知缺口；区域的 peakLuma 只能捕捉_移动的_明亮物体。）
  • 字幕必须保持在画面内。 电影感模式会对画面溢出执行硬门禁；标准模式会运行 check-overflow.cjs，但仅发出警告（有意出血是唯一例外——请阅读该警告）。
  • 每条字幕在屏幕上的显示时间必须 ≥ 0.5s——否则会因过短而无法阅读。
  • 单词时间必须与 transcript.json 保持一致，误差不超过 80ms——字幕出现时间偏离节拍 500ms 会破坏场景幻觉。电影感模式会在渲染前运行 check-timing.cjs --strict（通过 render-and-composite.sh）；THEME 模式则在编译时强制执行相同的时间要求（主题生成器的顺序转写匹配器 + 逐字完整性门禁——时间漂移会导致编译错误）。禁止将多个转写单词塞入同一个条目（例如 "FUTURE OF"，或将 IT + 换行 + ALL 堆叠但仅使用一组开始/结束时间）——第二个单词会继承第一个单词的时间戳并提前触发。即使希望它们位于同一视觉行，也要将其拆分为各自具有独立时间的单词条目（使用 CSS white-space / 自然换行，而非 <br>）。支持字幕文本 ≠ 转写文本的创意替换（例如用 "15%" 替换 "fifteen percent"）——请在 CREATIVE_SUBS（位于 check-timing.cjs 内）中注册。
  • 组时间窗口必须覆盖其中所有单词的完整时间范围——每个组都必须满足 group.in ≤ min(word.start) 和 group.out ≥ max(word.end)。如果 group.in 晚于某个单词的开始时间，该单词会被无提示地延迟到容器挂载时才显示（我们曾因此交付过带有 800ms 延迟缺陷的成品）。验证器会强制执行此要求。
  • 任意两个字幕组均不得在时间和屏幕区域上同时重叠——时间重叠的字幕会造成文本相互堆叠。选项：(a) 空间分离——将各组放置在互不重叠的垂直区域带中，使其可以共存（记忆墙瀑布式风格）；(b) 交接——将前一组的 out 设置为 ≤ 后一组的 in，确保屏幕上只有一组；(c) 有意分层排版——在其中一个组上添加 "allow_overlap": true，使验证器不再对此报错。验证器根据每个组的 CSS 估算其垂直边界框并标记碰撞。默认选择 (a)——正是这种方式让电影感奶油风呈现诗句逐步累积的感觉，而不是让字幕轨道不断自我替换。
  • 滤色混合在明亮背景（亮度 >180）上会失效。 电影感模板采用奶油色 + screen，且该 DNA 已锁定（方案无法改变其颜色）→ 在明亮背景上会泛白，因此应选择 ink（专为明亮表面打造的活版印刷风格）或 anchor 主题（不透明字幕条呈现面），而不要强行覆盖视觉风格设置。
  • 禁止在单词入场时对 letter-spacing 或 filter:blur 制作动画——inline-block 重排会导致行跳动。
  • 抠像禁止使用 CoreML——onnxruntime CoreML EP 的混合精度分区破坏了人脸 alpha（在之前的 RVM 引擎中观察到；禁止再次尝试）。抠像仅使用 CPU（在 1080p 下约 2 fps ≈ 每段 10s 素材耗时 2-3 min；长素材需预留相应预算）。

---

依赖

  • 已构建的 hyperframes（packages/cli/dist/cli.js）。脚本自动解析检出目录：HYPERFRAMES_ROOT 环境变量 → 若此 skill 随 hyperframes _内部_ 分发则使用仓库根目录 → ~/Downloads/hyperframes。使用 bun install && bun run build 构建。
  • 以 Node 为主；通过 uvx 提供两个 Python 调用点（无需手动安装）：转录通过 uvx 运行 WhisperX（单词级时间信息；按 SKILL §transcription 回退），Theme 的 drawon 场景片段在编译时通过 Shell 调用 python3 scripts/gen-stroke-path.py。其他部分均在 hyperframes 已附带的工具链上运行：抠像使用 hyperframes CLI 中的 remove-background（u2net_human_seg；权重自动下载一次，约 168 MB，存放于 ~/.cache/hyperframes/），图像/alpha 运算使用 sharp，布局/遮挡/溢出使用 puppeteer，另有 ffmpeg。脚本自动从 hyperframes 检出目录解析这些依赖——无需额外安装。
  • 转录 = 通过 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 通过 Shell 调用 hyperframes CLI 中的 remove-background，后者将 u2net_human_seg（约 168 MB，Apache-2.0）下载一次到 ~/.cache/hyperframes/background-removal/models/。新机器首次准备时需联网完成这一次下载。

若缺少硬性依赖，必须停止并询问用户——禁止默默跳过步骤。

qianwen skills install @admin/embedded-captions