口播成片

官方来源

本 Skill 由 chengfeng / AI产品自由 原创并维护。

https://github.com/Agentchengfeng/chengfeng-videocut-skills

官方账号：GitHub @Agentchengfeng；X @chengfeng240928；小红书 / 公众号 / B站 / 抖音 / 视频号 AI产品自由。

核心流程

这个 Skill 只解决一件事：把一条口播视频做成完整成片；成片比例和动画风格由用户配置决定。

+-----------------------------+
|  输入                         |
|  视频 + 字幕 + 可选素材         |
+--------------+--------------+
               |
               v
+-----------------------------+
|  1. 分镜稿                    |
|  概念分段 + 类型判定 + 画面来源  |
+--------------+--------------+
               |
               v
+-----------------------------+
|  2. 时间线预览                 |
|  原视频/截图/HTML 与口播对齐    |
+--------------+--------------+
               |
               v
+-----------------------------+
|  3. 合成                       |
|  按用户配置比例导出最终 MP4       |
+--------------+--------------+
               |
               v
+-----------------------------+
|  验收                         |
|  ffprobe + 抽关键帧检查         |
+-----------------------------+

不要把 cue 表、HTML 模块、review player、final player、导出脚本单独讲成用户流程。它们只是“时间线预览”和“合成”里的实现细节。

用户配置

每次执行本 Skill，先读取：

用户配置/default.json

配置项只负责定义用户当前选择：

{
  "aspectRatio": "3:4",
  "animationStyle": "xiaohei"
}

支持值：

• 3:4：默认竖屏高清，逻辑画布 1080x1440，默认用 DPR 1.5 导出 1620x2160。
• 16:9：横屏，逻辑画布和导出画布 1920x1080。
• 4:3：横屏，逻辑画布和导出画布 1440x1080。
• animationStyle：默认 xiaohei，可选项来自 动画/styles.json。

命令行参数优先级高于用户配置；没有显式参数时，导出脚本读取 aspectRatio，动画脚本读取 animationStyle。比例临时覆盖可用：

--config /path/to/config.json
--ratio 16:9
--aspect-ratio 16:9
--width 1920 --height 1080
--dpr 1.5

不要把视觉偏好、模板、编码质量、输出目录、字幕边距等七七八八的设置写进 用户配置/default.json。用户配置只放当前选择；动画目录只放可选项注册表和具体风格实现。

动画风格

动画风格的当前选择放在 用户配置/default.json：

animationStyle

动画目录只注册可选项：

动画/styles.json

xiaohei 对应：

动画/ian-xiaohei-svg-motion/

当分镜或 HTML 模块需要做解释动画、流程动画、手绘感高亮时，默认先用小黑漫画感 SVG 动效。除非用户明确指定其他动画风格，否则不要临时发明新风格。

输入

先定位这些文件：

• 主视频：source_cut.mp4、*_cut.mp4 或用户指定的剪后视频。
• 字幕：subtitles.srt、video.srt 或 subtitles_with_time.json。
• 可选文稿：文章、口播稿、正文草稿，只用于理解意图。
• 可选素材：assets/ 里的截图、产品页、评论图、结果页、证明页。
• 项目规则：如果当前项目有 AGENTS.md 或 README.md，先读。

真相源优先级：

实际音频 / 字幕 > 剪后视频画面 > 素材文件 > 文稿草稿

如果文稿和实际字幕不一致，以字幕和音频为准。

第 1 步：分镜稿

默认先做 HTML 分镜核对页，不先写 Markdown 表格。

分镜的前置流程必须按这个顺序执行：

1. 先按口播语义分段：把讲同一个概念、同一个动作、同一个证据的一句、两句或三句合成一段；不要按字幕编号机械切分。
2. 再判断每段的画面任务：这是操作演示、原图讲解、结果证明、概念梳理，还是纯文字表达。
3. 再决定画面来源：能用真实录屏、原始截图、原始图片证明的段落，优先用原素材；只有概念性讲解且当前屏幕主要是文字、空白或弱相关画面时，才设计 HTML / 小黑动画。
4. 最后才进入具体视觉设计：每个 HTML / 小黑动画段都要先写清它的独立隐喻和动作，再实现模块。

常见路径：

review/storyboard-audit-vN.html

默认基于这个模板：

templates/storyboard-audit.html

分镜稿要让用户回答：

这句话说到这里，观众眼前该看到什么？

每段至少写清楚：

• 时间范围
• 字幕编号
• 完整口播
• 语义分段依据
• 画面任务
• 画面类型：原视频、操作录屏、原始截图、原始图片、信息图聚焦、HTML 动画、文字 + 动画
• 素材来源
• 镜头动作

画面选择规则：

• 操作演示：使用原视频 / 原录屏，不要改成抽象动画。
• 讲图片内容、图表内容、报错截图、产品截图：直接用原始图片或原始截图，动画只做圈选、标注、局部聚焦。
• 真实操作、证明页、结果页、需要可信度的片段：保留原视频或原始截图。
• 录屏 / 原视频片段默认按原画面展示；只有明确需要避开后续统一字幕时，才把该段标记为录屏小窗，并在底部留出字幕安全区。不要把小窗规则批量套到所有录屏段。
• 概念梳理、机制关系、系统分工、观点归纳，并且当前屏幕主要是文字、空白或弱相关画面：做 HTML / 小黑动画。
• 可以用简短文字辅助理解的抽象段：使用文字 + 动画；文字负责命名，动画负责关系和动作。
• 已有截图或信息图：优先复用，不要重画。
• 同一张图多次出现时，每次必须承担不同任务：全貌、局部聚焦、对比、结果复看。
• 不要把所有动画做成同一套动态。每个动画段必须先单独设计动作隐喻，再实现。

分镜设计硬标准：

• 一页只讲一个概念、一个动作或一个案例。同一段口播里如果出现两个独立案例，必须拆成两个页面；不要为了少做页面把两个案例挤进同一张表或同一个动画。
• 每个 HTML / 小黑动画段必须先写清楚“这句话说到这里，画面发生什么变化”，再实现。动作要绑定具体口播句或字幕，不要把同一套入场 / 闪烁 / 放大平均套给所有段落。
• 讲原图、截图、结果页时，主视觉必须是原素材。HTML 只负责裁切、放大、圈选、标注和焦点切换；不要用录屏抽帧或重画图替代原图。
• 长图和网页结果页默认裁掉无信息的空白区域，优先露出观众正在听到的区域；口播说到对应对象时，可以放大对应图片或局部，其余内容退后。
• 视频画面里不要出现素材路径、内部说明、动作解释或“原图素材 · img/xxx.png”这类工作台文字。分镜稿可以写来源，成片画面只保留观众需要看的内容。
• 没有必要的标题就不放标题。结果页、表格页、原图对比页优先让主视觉自己说话，只保留短标签、模型名、指标名或必要的标注。
• 数据对比页优先用清晰的表格、列对齐、短标签和少量高亮。字号要服务阅读，不要把字塞进小方块；能用简单表格讲清楚，就不要做复杂卡片堆叠。
• 竖屏短视频里的表格不能只做成中间一条横向小表。数据阶段要把表格作为主视觉，占据主要安全区；前置任务说明、案例标签、总结句只在对应口播阶段出现，进入最终数据对比阶段后要消失或退到不占空间的位置。
• 评价词只写口播明确说到或剪辑需要强调的正向 / 中性结果。对照项可以留空或只展示数据；不要额外加“慢且贵”等负面用词，除非口播原句就是这个判断。
• 图标必须从动画库索引里找。ChatGPT、Claude、Flash 闪电、Step、DeepSeek、Qwen 等已有图标不得用抽象形状替代；新增用户给的 SVG，要先存入动画库并更新索引。

分镜方向确认前，不要进入时间线预览。

第 2 步：时间线预览

分镜方向确认后，再做时间线预览。

常见路径：

review/timeline-preview.html

默认基于这个模板：

templates/timeline-preview.html

时间线预览要检查：

• 画面切换是否跟口播句子对齐。
• 原视频有没有被误换成 HTML。
• 被标记为录屏小窗的段落是否避开底部字幕安全区；未标记的录屏段不要被自动缩窗。
• 截图、页面、证明素材有没有用错。
• 图片素材默认保留左右边距，不要贴满当前画面；需要强调完整截图时再单独缩小。
• 画面有没有挡字、裁切、留黑边。
• HTML 模块单独看没问题，但放进整条时间线后是否仍然成立。

预览页里有源视频时，必须用支持 HTTP Range 的服务打开页面，否则浏览器不能随机 seek，进度条会被拉回开头。不要用普通 python -m http.server 预览 MP4 时间线。默认使用：

node ~/.Codex/skills/chengfeng-videocut-skills/口播成片/scripts/serve_range_preview.cjs \
  --project-dir /absolute/path/to/project \
  --port 8767

必要时生成：

docs/08-动画cue表-vN.md
html-modules/module-*.html
html-modules/xiaohei-*.html

如果要新做解释动画，先读 用户配置/default.json 的 animationStyle，再到 动画/styles.json 找对应的动画子 Skill。

每个动画动作必须绑定到具体口播句，不要平均分配时间。多阶段 HTML 动画必须显式管理显隐状态：下一阶段出现时，上一阶段不再承担信息任务的说明卡、标签和注释要隐藏；不要让前一阶段继续占用主视觉空间，尤其是竖屏数据表、截图聚焦和结果页。

第 3 步：合成

只有用户确认时间线预览后，才能合成。

合成前创建或确认：

final-player.html

新写 final-player.html 或 HTML 模块前，读取：

references/artifact-contracts.md

如果项目里有 HTML 模块，先注入 render mode：

node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/write_render_mode.cjs \
  --project-dir /absolute/path/to/project

时间线预览和最终导出必须使用同一套 HTML 渲染上下文。HTML 模块在预览页和 final-player.html 里都要带 ?timeline=1&render=1，预览页只负责把最终画布等比缩放进窗口，不能让模块按预览窗口重新响应式排版。

高清交付不能把 CSS 逻辑画布直接放大。默认 3:4 必须保持 1080x1440 逻辑画布，再用截图 DPR 1.5 输出 1620x2160；否则表格、CSS 卡片、截图标注会在导出里相对变小，和预览不一致。

如果预览和导出出现大小不一致，先检查 HTML 模块内部 CSS、render-mode.js 和导出 DPR，确认预览页与 final-player 的逻辑画布相同，不要先重导整条视频。常见原因是预览 iframe 较小，看起来正常；最终高清画布触发了 .photo-frame { max-width: ... }、.stage { width: min(...) }、.wrap { max-height: ... }、clamp(...) 这类预览尺寸上限，导致导出变成“小图”。修复顺序：

1. 用 write_render_mode.cjs 重新生成 html-modules/render-mode.js。
2. 在时间线预览里确认 HTML 模块 URL 已经变成 ?timeline=1&render=1。
3. 确认 export_final_video.cjs 的 viewport 是逻辑画布尺寸，dpr 才是高清倍数。
4. 用 final-player 在实际导出 viewport 下抽该模块的关键帧，必要时用 getBoundingClientRect() 对比主视觉容器尺寸。

竖屏里处理横向小黑 SVG / 16:9 SVG 模块时，禁止用 .wrap { transform: scale(...) } 这类整体放大来解决“小横条”问题。整体缩放会在 3:4 画布里裁掉左右边缘，尤其是左右分布的模型卡、箭头、说明标签。要么重排成竖屏构图，要么保持完整安全区；改完必须抽该模块的左右边界帧检查，不能只看中心关键帧。

导出最终视频：

node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
  --project-dir /absolute/path/to/project \
  --input-video /absolute/path/to/source_cut.mp4 \
  --duration 173.03

默认按高清交付导出：无损 PNG 中间帧、H.264 crf=14、preset=slow。这样可以避免浏览器预览清楚、导出后小字和细线发软：

node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
  --project-dir /absolute/path/to/project \
  --input-video /absolute/path/to/source_cut.mp4 \
  --duration 173.03 \
  --frame-format png \
  --crf 14 \
  --preset slow

只有临时看节奏、需要快速出草稿时，才显式降级：

node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
  --project-dir /absolute/path/to/project \
  --input-video /absolute/path/to/source_cut.mp4 \
  --duration 173.03 \
  --frame-format jpeg \
  --quality 92 \
  --crf 18 \
  --preset medium

比例读取规则见“用户配置”。项目与用户配置不同时，可传：

--config
--ratio
--aspect-ratio
--fps
--player
--stage
--frames-dir
--width
--height
--frame-format png|jpeg
--quality 100
--crf 14
--dpr 1.5
--device-scale-factor 1.5

验收

导出成功不等于成片正确。必须做两步：

1. 用 ffprobe 检查分辨率、帧率、时长和音频。
2. 抽 3 张以上关键帧，人工看画面是否正确。
3. 对每个 HTML 模块，至少抽 1 张对应口播时间点的 final-player 帧，和时间线预览的同一时间点对照；大小、位置、裁切和显隐必须一致，不能只用 ffprobe 作为完成依据。

按当前比例检查分辨率，其他期望来自脚本默认值和项目实际输入。当前默认配置为：

1620x2160
逻辑画布 1080x1440，DPR 1.5
3:4
30fps
时长和剪后源视频一致
有音频
无 HUD、按钮、审核时间线、浏览器 UI

边界

适合：

• 中文口播
• 教程、产品演示、结果展示、知识讲解
• 已有剪后视频和字幕，素材可后补
• 原视频 + 截图 + HTML 解释画面混合成片

不优先解决：

• 没有视频，直接凭文稿生成成片
• 复杂多机位真人剪辑
• 需要剪辑软件工程文件的精细调色和多轨混音
• 用户没看分镜稿和时间线预览就直接要求最终发布

项目卫生

如果在用户写作工作区内新增或修改文件，必须同步更新项目 README 索引。

本地活动日志统一放在：

log/

log/ 只记录本机试验、用户偏好、临时结论和未发布的工作过程，禁止上传 GitHub。该目录已被 .claude/skills/.gitignore 忽略。

不要在这个 Skill 目录里新增 README。这个 Skill 的核心文件只保留：

SKILL.md
templates/
references/
scripts/
用户配置/
动画/

动画/ 用于沉淀口播成片可复用的 HTML/SVG/GSAP 动画子 Skill、模板和规则；可选风格见 动画/styles.json，当前选择见 用户配置/default.json。