hyperframes 嵌入式字幕反模式全解从布局、排版到抠像的 20 个坑与正确做法【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本指南以 hyperframes 仓库中embedded-captions技能的反模式清单skills/embedded-captions/references/anti-patterns.md为核心骨架逐条拆解为单主体访谈视频添加嵌入式字幕时最容易犯的错误并给出对应源码与配置层面的修正方案。读完你将掌握字幕平面caption plane定位的数学公式、按列宽缩放字号的查表方法、混合模式与场景亮度匹配规则、只动 opacity/transform 的动画纪律、基于 Whisper 词级时间戳的 80ms 对拍门禁以及「克隆再微调」替代预设的进阶工作流——每一步都有仓库内可验证的脚本与配置支撑。为什么需要一份反模式清单embedded-captions是一条完整的本地端到端管线对一段单一主体的访谈/讲话视频在不改动原始素材的前提下把逐字verbatim字幕以「下三分之一 rail 高潮 embed」两种形态叠加进画面并让人物本体遮挡部分嵌入文字产生文字在人身后的场景里的纵深感。整条管线从决策门禁、预处理抠像/转写/音频包络并行、创作 JSON、编译、预览到渲染全部由确定性脚本驱动见 skills/embedded-captions/SKILL.md 的 5 步管线。正因为这条管线足够成熟绝大多数失败都不是引擎问题而是创作层的默认习惯。anti-patterns.md正是为 Agent 准备的犯错预登记册——作者原话是我们看着 Agent 犯过 10 遍同样的错。本文把所有条目按 7 个主题域整理并逐一补上仓库内源码、脚本和参考文档作为修正依据。一、布局Layout文字落在哪里是数学题不是感觉题布局反模式的共同根源是把模板默认值或上一次视频的坐标当成了通用真理。字幕平面caption plane是文字唯一可感知的空间——它错了后面所有排版都白做。1.1 别默认居中crown标题字.crown-plane { left: 0; right: 0; text-align: center }是模板默认值但居中 crown 只有在三个几何条件同时成立时才成立详见 skills/embedded-captions/references/layout-heuristics.md § Crown placement主体距画面中心 10% 以内|body_center_x − frame_width/2| frame_width × 0.10两侧干净区 ≥ 15%body_x_min frame_width × 0.15且body_x_max frame_width × 0.85crown 宽度 主体宽度 400pxcrown_width ≈ F × 0.55 × char_count反例主体偏右如 Jobs 的 60 Minutes 访谈主体中心约在 1920 帧的 x1100居中 crown 会被主体吃掉中间 60%THE BEATLES 变成 THE ___ S。任一条件不满足就把 crown 移到较大的干净区用更窄的容器和更小的字号。1.2 文本最左点按对齐方式换公式很多人把plane_left padding当成万能左边界但这只对左对齐成立。模板主列是右对齐、crown 是居中对齐真实的最左点取决于词宽对齐方式leftmost_x公式左对齐plane_left padding_left右对齐plane_right − padding_right − longest_line_width居中对齐plane_center − longest_line_width / 2关键细节宽度必须按换行后最长的那一行计算而不是整句话。four very talented guys 换行成 3 行最宽的是 talented约 8 字符不是整句 23 字符。layout-heuristics.md 里还记录过一个真实 bugplane_left180 右对齐 字号 108px 时正确算出来leftmost 180 700 − 36 − 468 376恰好越过 pillarbox 边界——因为按整句宽度算会得出错误结论。1.3plane_left不是文本左边缘平面 box 只定义坐标系文本在 box 内部按对齐方式定位。left: 180px 右对齐 468px 的词文本起点会落在plane_left之前 104px相对 plane但实际仍在平面内。判断依据是编译产物index.html的实际渲染结果而不是 plan.json 里的 plane 属性。1.4 对偏置主体别对着画面中心对齐看主体的身体中心不是画面中心。Jobs 在 1920 帧中位于 x1100场景重心是 1100 而非 960。对 960 居中对齐等于对左侧 1/3 空画面居中对齐。scene-types.md的决策流程和 layout-heuristics.md 的更大的干净区优先规则left_clean_width body_x_min − safe_left_marginvsright_clean_width safe_right_margin − body_x_max才是正道。1.5 坐标记忆搬家每次换视频都要重新跑 6 项检查top: 40, right: 30, width: 720, rotateY: -13在 1280×720 的吸音泡沫墙场景成立不代表在 1920×1080 书架背景成立。复用任何数字前对新视频跑 skills/embedded-captions/references/scene-types.md 的 6 项 checklist是否有占据 ≥30% 画面的单一表面表面是否相对平整非弯曲、非 3D 层架表面与镜头夹角 5–20°非完全平行、非畸变表面是否中亮度非近黑书架、非近白窗户表面是否无印刷/装饰元素与文字竞争表面是否在 3 个采样帧中都可见主体未遮挡6 项全 YES 才能用wall-embed任一 NO 就降级到corner-column-crown或portrait-header。二、排版Typography预设是脚手架不是天花板2.1 字号必须随列宽缩放模板默认字号 66/78/92/140 是针对约 560px 列宽调校的。平面放大到 700px 后字号不跟着动字幕就会漂在负空间里显单薄。查 skills/embedded-captions/references/typography-presets.md 的Font-size × column-width 矩阵平面宽度introphraseemphdreamcrown居中全幅crown仅干净区460–580px紧66789282140n/a600–760px中78108128100220118780px宽90128150116260140700px 列对应 78/108/128/220——整体上调 30–40%。加完字号要复查 pillarbox 安全更大的右对齐文本会向左延伸得更远layout-heuristics.md 记录84→104px 的字号提升会把右对齐文本左移约 30px预算吃紧时直接穿破黑边。另外若平面rotateY 8°可见宽度收缩字号需再放大约 10%。2.2 首条字幕别默认introintro 斜体、小号、沉思感适合填充性话语标记You know,, So,, Well,。但当首句其实是论点句如 Ive had this kind of upbringing时用intro就压错了重心。按语义读词不要按位置选样式。2.3 每条都干净 没有层次一个没有emph或 crown 的视频在排版上是平的观众感受不到渐强crescendo。每个视频至少保留一个emph给最落地的那句只有真正单调的内容政策声明、警告才豁免。2.4 别给每个 group 都配一种样式样式的意义是表达层级。15 秒短片里intro/phrase/emph/dream/crown全用上等于什么都没表达。短片段最多选 2–3 种样式遵循soft 开场 → present 推进 → emph 峰值 →可选crown 高潮的故事弧。2.5style字段接受任意字符串——position-indexed 是正解intro/phrase/emph/dream/crown是脚手架而非封闭集合。canonical 的 skills/embedded-captions/references/example-renders/memory-wall.html 用的是cap-1 / cap-2 / cap-3 / cap-4——按位置索引、每个位置独立排版从而实现了高潮处 3 行右对齐级联。plan.json 的style字段会变成classcap-string用custom_css定义类即可custom_css: .cap-1 { font-size: 78px; ... } .cap-2 { padding-right: 44px; }, groups: [{id: cg-0, style: 1, ...}]像position 2 的悬挂缩进这种诉求style: dream永远表达不了详见 skills/embedded-captions/references/bespoke-vs-presets.md。2.6 有 canonical 样例时克隆而不是重新推导当场景构图与memory-wall.html或champion.html接近时直接把那个 HTML 复制为project/index.html只替换 GROUPS 数组不要从预设重新推导设计——否则会丢失经过多轮迭代验证的逐位置排版。这正是bespoke-vs-presets.md的clone-and-tweak 工作流# 1. 脚手架 hyperframes init project --non-interactive --video video.mp4 --skillembedded-captions # 2. 抠像 转写 node skills/embedded-captions/scripts/matte.cjs project node skills/embedded-captions/scripts/transcribe.cjs project # 3. 克隆 canonical HTML 而不是写 plan.json cp skills/embedded-captions/references/example-renders/memory-wall.html project/index.html # 4. 手工替换 GROUPS 数组含词级时间戳 # 5. 跳过 make-composition.cjs 直接渲染 bash skills/embedded-captions/scripts/render-and-composite.sh project注意主体位置、场景亮度/混合需求差异显著或想试验新排版时不要克隆改回 plan.json custom_css 路线。三、混合Blendingblend mode 的选择依赖区域亮度3.1mix-blend-mode: overlay只对中亮度表面成立Overlay 在**中亮度60–180 亮度**背景上正确工作在暗书架60上会把白色文字渲成黑色在亮背景180上则过曝。先在采样帧里测字幕区域的实际亮度再选模式中亮度表面60–180→overlay暗表面60→screen亮表面180→normal 不透明文字这与 SKILL.md 的亮度探测under 60 / 60–180 / 180和 scene-types.md 的 wall-embed 条件 3 完全一致。3.2 永远不要动画letter-spacing打字机呼吸效果看起来很美但letterSpacing的每次变化都会触发 inline-block 回流 → 整行 line box 重算 → 字幕在行间肉眼可见地跳动memory-wall 的 Some → line 2 bug。只动画opacity和transform想要呼吸感就用scale或y。四、动画Animation双层淡入是指数曲线4.1 别同时淡入容器和每个词容器淡入 × 词淡入 非线性叠加progress 40% 时合成不透明度只有 16%0.4²观感是字幕到一半突然蹦出来。正确做法进入时用tl.set把容器 opacity 置 1只淡入词——单层 opacity 才是线性感知淡入。4.2 flex column 堆放字幕会掉进手势区flex-direction: column 在源码里很整齐但运行时visibility: hidden的隐藏字幕仍占据 flex 空间新进入的字幕会落在列底部而非设计位置——正好掉进手势区被裁掉。两个已发布的模板都用position: absolute定位每个.cap隐藏的不占布局。需要累积效果memory-wall 的诗页式堆叠时才用 custom_css 覆写为 flex columnbespoke-vs-presets.md§ Caps should accumulate 给出了完整 CSS。4.3 时间线别从 t0 开始t0 的字幕像视频开始前就存在。开场偏移 0.1–0.3shyperframes 的 motion-principles 也认同最后一条字幕也要在画面淡出前先退场。五、场景准入Scene admission开工前先看完整素材5.1 看起来一个人 ≠ 全程一个人电视档案片段会在句中切 B-roll访谈会插入采访者的 cutaway。只看了第一帧就渲染字幕会横跨镜头切换——为 A 设计的字幕在半个渲染里按 B 的位置或空画面摆放。规划前在 20%/50%/80% 采样帧SKILL.md 的 shot-cut probe场景变了就裁剪到最大的单主体片段。5.2 别无视烧录字幕 / 黑边 / 水印两侧黑边不计算安全区字幕就会横跨 pillarbox源素材已有烧录字幕还再加字幕就是两套字幕系统抢注意力。先跑 letterbox probe计算安全内容矩形源已带字幕就直接拒绝source already captioned, adding more would conflict.SKILL.md 决策门禁还要求用 1fps contact sheet 检查中途出现的烧录文字不要只信 3 个采样帧。5.3 Whisper 词级时间戳不是免检品转写走transcribe.cjsWhisperX via uvx无需 API key词级时间戳质量好但不是万无一失可能产生近零时长的词或错拍的时间戳。本技能要求 verbatim 对拍所以 check-timing.cjs 的--strict80ms 容差是门禁而非建议——渲染前在 plan.json 修好漂移。源码里的DRIFT_TOL 0.08就是这条规则const DRIFT_TOL 0.08; // 词级时间戳漂移超过 80ms → 输出 issuestrict 模式下以非 0 退出码拦截渲染绝不能把两个转写词打包进一个带时间戳的词条——第二个词会继承第一个的时间戳提前触发。check-timing.cjs对这类 packed 条目会直接报错packed with ... transcript... but entry has no distinct timing — split into separate word entries。合法的创造性替换如 15% 替代 fifteen percent要登记进脚本的CREATIVE_SUBS表。六、抠像Matting为字幕分层选模型不为保真选模型6.1 CoreML 在抠像 ONNX 上是禁用项直觉上 Apple 的 CoreML 执行器更快。不要。CoreML 会把 ONNX 图按 provider 分区混合精度边界曾在旧 RVM 引擎上造成面部 alpha30 而背景正确为 0——字幕从脸上透出来。只钉 CPU 执行器onnxruntime-node仓库的 matte.cjs 已经这么做了别优化回去。SKILL.md 的依赖说明给出了成本参考CPU 约 1080p ~2fps10s 片段约 2–3 分钟长片要预留预算。6.2 模型选择在 2026-06-12 已翻转u2net_human_seg 而非通用 vs 人像经过 5 模型 × 6 场景的 A/B 测试结论是这里抠像的目的是字幕分层caption layering不是道具保真。u2net_human_seg经 hyperframes 的remove-background调用Apache-2.0模型约 168MB 首次自动下载通常会把细的偏置家具麦克风吊杆臂排除在 matte 之外——文字不再被吊杆切割胜过 PP-MattingV2 的道具保留行为。但它不精细主体附近的大显著物望远镜架仍可能漏进 matte——永远采样frames_fg/验证。已知代价手持物品可能间歇性掉出字幕从前面穿过——产品演示类高潮要避开手持物路线。isnet-general-use在背光发丝场景彻底失败birefnet-portraitMIT 协议语义上最佳既保留手持物又剔除家具但 928MB / 每帧约 7sCPU是未来的高质量档位不是当前默认。顺带一提matte.cjs在实现层还处理了两个工程坑VFR 源先归一化为 CFRremove-background信任时间戳VFR 会产出帧数错位的双主体鬼影以及fg/bg 帧数对齐通过线性重映射或补齐容忍度 1%。这些是读取该脚本时值得注意的实现事实。七、分组Grouping你是排版师不是法庭记录员7.1 别给每个词都上字幕you know, um, I, I mean, you know 一拍里 5 个词全上屏幕会塞满画面、打断阅读节奏。编辑性删减填充词规则在 caption-grouping.md合并短片段、删重复话语标记、保语义、去噪音。每组 1 个视觉短语 ≈ 1 个逗号分句或 1 次呼吸。7.2 别按固定词数分组永远是 3 个词一条会让每条字幕长得一样违背说话的自然节奏。按句子边界、250ms 停顿和语义单元切分组大小在 2–5 词之间自然浮动才是对的。分组边界优先级≥500ms 停顿 → 句号/问号/叹号 → 强逗号≥250ms 停顿 → 话语重置词but/so/and then/you know→ 6 词或 2.5 秒上限。硬约束每组 ≥2 词单例外感叹词 Wait. 与 crown 行、屏上 ≥0.5s、组间不重叠。分组时间计算caption-grouping.md有完整公式in 首词.start − 0.08out min(下一组.in − 0.05, 末词.end 0.6)尾组可延伸到视频结束。同时注意 SKILL.md 的组窗口门禁group.in ≤ min(word.start)且group.out ≥ max(word.end)——check-timing.cjs的校验逻辑里对group.in晚于词起点的情况会报 word delayed对group.out早于词终点报 word clipped。八、元反模式先读完整个参考文档集再写 plan.json最大的反模式是只读一份文档就开工。本清单引用的概念定义在layout-heuristics.md、typography-presets.md、scene-types.md里——没读它们这里的修正建议就落不了地。新视频的标准阅读顺序SKILL.md 与 anti-patterns.md 一致SKILL.md——决策门禁 管线 预检探测bespoke-vs-presets.md——先查 canonical 样例是否匹配匹配就克隆scene-types.md——模板选择wall-embed 全 4 条件layout-heuristics.md——位置、侧面、crown、字号缩放、pillarbox 公式typography-presets.md——字号 × 列宽表、起点值caption-grouping.md——词 → 组本清单最后读——提交 plan.json 前自查一遍时间再紧也要读完这份反模式清单——它标记了你即将犯的错。完整文档索引见 SKILL.md 的 Shared knowledge 表含 rail.md、composition-craft.md、aesthetic-principles.md、failure-modes.md 等。自查清单提交 plan.json / theme.json 前过一遍把全文压缩成可执行清单同时对应 Visual QA 的 5 项人工检查与几何门禁crown 三条件都满足才居中否则移入较大干净区leftmost_x按对齐方式与最长换行行计算且 ≥ pillarbox 边 10–20px主体偏置时以身体中心而非画面中心对齐新视频重新跑 scene-types 6 项检查不搬旧坐标列宽 ≥700px 时字号按矩阵上调 30–40% 并复查黑边每条视频至少 1 个 emph短片样式 ≤3 种crown 全片 ≤1 个需要逐位排版时用cap-1..N自定义类不硬套预设有 canonical 样例就克隆换词不重推设计blend mode 按区域亮度选60 screen / 60–180 overlay / 180 normal不动画 letter-spacing 与 filter:blur只动 opacity/transform容器 opacity 进入即置 1只淡入词每个.cap用 absolute 定位首尾字幕偏移 0.1–0.3s不在 t0 抢跑20/50/80% 采样帧确认无镜头切换letterbox/烧录字幕已探测check-timing.cjs --strict80ms 容差通过无打包词条组窗口包住词时间matte 只走 CPU 执行器hero 位置已对照 frames_fg/ 排除漏入道具以上每一项都能在 skills/embedded-captions/references/anti-patterns.md 找到原始出处修正逻辑则分布在前述各参考文档与 scripts/ 下的check-timing.cjs、matte.cjs、transcribe.cjs、prepare.sh、render-and-composite.sh等脚本中——阅读顺序表就是这份技能最可靠的作战地图。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考