launch-video

把一个开源项目的核心价值压成约 30 秒的视频：观众看完知道它解决什么问题、怎么做到、凭什么信、怎么开始。画面由 HTML 动画按时间逐帧渲染，所以文字清晰、可反复修改、可重新生成。风格可以随项目变化，证据不能变：无论选哪种风格，真实素材和可核实数字都是同一套。

prompt 只占成片质量的一成，其余九成是流程：先拆参考、写方向文件、把字号和 UI 倍数定成数字，渲染后看自己的帧打分再改。跳过这些步骤的产出是"居中文字、渐变底、全部淡入"的通用片。做新片把模型 effort 调到最高两档，小修用默认档。

同系列：readme-craft 写仓库首页。视频里的定位句、证据与安装命令应和 README 一致；README 过时或无法走通时先修 README。

0. 检查依赖（任一缺失即停止并告知）

node --version && ffmpeg -version | head -1 && python3 --version

在工作目录安装渲染依赖（只装一次）；3D 风格再装 three：

npm i -D playwright && npx playwright install chromium
npm i three   # 仅 3D 或着色器风格需要

已有 Chromium 时可设置 CHROMIUM_PATH 复用，免下载。

1. 取证：先找证据幕

读 README、包元数据、发布记录、源码入口、测试与已有案例，确定：

• 观众与痛点：谁在什么场景遇到什么代价。
• 一句承诺：项目名后面那一句，只强调一个词。
• 证据：可复现的量化结果 > 真实产物 > 真实操作对比。证据与数字只取自可核实来源，并记下来源、版本、条件。
• 安装命令：从 README 或发布页逐字复制，并核对当前发布版本（如 npm view <pkg> version）。
• 真实素材：已有录屏、截图、导出文件；缺素材时实际运行项目录制（无头或离屏，不弹前台窗口），不画假界面。截图里的会话名、路径、数据必须是公开示例数据，不带用户隐私。
• 机制隐喻：用一个动词概括”原理”幕（组装、流转、过滤、监控、转换、一步到位……），第 2 步按它匹配风格。
• 参考：用户给了参考视频就按 references/references.md 的方法拆；没给就从该文件的七支参考里挑一支结构最接近的拆，结论写进 DIRECTION.md 第 1 节。

没有任何可信证据时，明确告诉用户：视频只能展示真实操作过程，或建议先产出证据。不编数字。

2. 定方向与风格：DIRECTION.md → 候选 → 试样 → 选定

在工作目录写 DIRECTION.md，结构见 references/direction.md 第一节：参考拆解、产品气质、三个方向（即下面的三候选）、本片专属手法（"因为产品有 X，所以用 Y"）、点名的禁用清单、带数字的画面规范（主标题 ≥ 画面高 1/6，UI 正文 ≥ 22 px，UI 占宽 45–70%，明暗分段）。风格选定后再补第 7 节镜头表。没有 DIRECTION.md 不写全片。

读 references/styles.md，按其中的选型流程：

1. 整理信号：渠道与画幅、证据类型、机制隐喻、受众调性、品牌资产、用户点名的风格。
2. 用硬约束排除：素材承载力、画幅、语言文化、可行性。

3. 选 3 个差异明显、至少覆盖两个家族的候选：稳妥 / 契合 / 大胆。每个写清以下内容：

   • 理由（引用项目事实）
   • 签名镜头
   • 五幕各一句
   • 配乐 mood
   • 成本

   最后标出推荐项。

4. 读候选所在的配方文件（references/styles/*.md），为每个候选写一个 3–4 秒的试样页 probe-<id>.html：项目名 + 承诺句 + 一张嵌入真实素材的原理画面，用 engine.js 搭（第 3 步的目录结构）。渲染并拼成对比图：

for id in <id1> <id2> <id3>; do node <skill>/scripts/render.mjs --html probe-$id.html --stills 1.2,3.2 --out out/probes/$id; done
ffmpeg -v error -y -pattern_type glob -i 'out/probes/*/t*.png' -vf "scale=960:-1,tile=2x3" -frames:v 1 out/candidates.jpg

对比图每行一个候选（按 id 字母序），左右两列是同一候选的两张静帧。自己先看对比图：试样质感不达标的候选（3D 发灰、粒子不成形、文字溢出）先修或换掉，不把半成品交给用户比较。然后把候选说明和 out/candidates.jpg 交给用户选。

• 用户已点名风格：只做该风格的试样，确认可行后继续。
• 用户要求直接出片或无人值守：取推荐项继续，交付时说明理由和其余候选。

3. 分镜

按 references/storyboard.md 的五幕结构写分镜表（即 DIRECTION.md 第 7 节镜头表）：镜头起止拍、标题、一句解释、画面素材及其来源、真实性标签、主角位置、声音。再加上所选风格配方里的五幕映射、原生转场和签名镜头。用户未指定时默认：英文、16:9、30 秒、强调色取自产品主色。9:16 渠道按竖屏重新排版，不裁切横屏画面。

分镜必须满足，否则重排：

• 有一个贯穿主角（圆点、消息卡、光标、一条线……）从第一幕活到最后一幕，每次换幕由它的位移、变形或放大完成；不靠淡入淡出切换。
• 第 3 幕先演机制：用风格的原生动作把产品机制演出来，真实截图在机制讲完后作证据停 ≥ 2 秒。界面本身就是产品价值时才以截图为主。
• 陌生人看得懂，节奏由理解决定（references/direction.md 第 7 节与"陌生人测试"）：观众是第一次听说这个项目的人，不会暂停。镜头分两类：展示型（logo、大字、砸屏）1–2.5 秒；讲解型（机制、证据）每镜只引入一个新概念，概念先用一句话命名再使用，停留 = 字幕阅读时间 + 动作时间，通常 4–6 秒。每个讲解型镜头底部有一行解说字幕，用观众的话说"此刻发生了什么"。总时长由镜头表倒推，30–60 秒都可以；宁可 50 秒看懂，不要 30 秒看不懂。
• 仍要像爆款不像幻灯片（references/references.md 共性）：前 3 秒有钩子（产品真实交互、痛点可视化或主角出生，不从 logo 开始）；每屏 ≤ 6 词的大字 + 一行字幕；镜头之间靠主角位移或变形衔接；首帧是完整画面、末帧停在 logo + 命令的完成态且停 ≥ 4 秒。

方向或素材存在重大不确定（选哪个项目、面向哪个渠道、证据是否可用）时，先向用户确认；其余按默认推进。

4. 搭建工作目录

工作目录放在用户指定位置；未指定时放在项目仓库之外的运营/素材目录，或仓库内 docs/media/launch-video/。源 HTML 是视频的“源码”，与成片放在一起；node_modules/ 与 out/ 不入库。

mkdir -p <work>/assets && cd <work>
cp <skill>/assets/engine.js .
cp <skill>/assets/template.html promo.html         # editorial 风格
cp <skill>/assets/three-starter.html promo.html    # 3D / 着色器风格（二选一）
python3 <skill>/scripts/fetch_fonts.py --out fonts "Instrument Serif:ital@0;1" "Inter Tight:wght@400;500;600" "JetBrains Mono:wght@400;600"
python3 <skill>/scripts/fetch_fonts.py --out fonts-cjk --text-from promo.html "Ma Shan Zheng"   # 中文字体只取用到的字

<skill> 指本 SKILL.md 所在目录。其他 2D 风格从空白页开始：<div id="stage"> 加各幕 <section class="scene">，引入 engine.js，调用 LV.start(...)（用法见 engine.js 文件头）。字体按配方选用 Google Fonts 上的 OFL 字体。中文文案改动后，重跑带 --text-from 的抓取。

素材处理：

• 录屏转帧：ffmpeg -i rec.mp4 -vf "fps=15,crop=W:H:X:Y" -q:v 3 assets/rec/%03d.jpg，用 setFrame / preloadFrames 播放。先抽一帧确认裁剪去掉了字幕条、系统信息与隐私内容。
• 截图与导出图复制进 assets/，文件名写清来源。

5. 写动画

按分镜和风格配方实现每一幕：

• render(t) 必须是纯函数：DOM 样式、Canvas 像素、3D 姿态全部由 t 算出；随机数只用 rng(seed)；运动用闭式函数，不逐帧积分。一个值改了几次目标（光标、容器宽、半径）用 springTrack，不重启缓动。
• 按 DIRECTION.md 的画面规范排版：主标题 ≥ 画面高 1/6，UI 正文 ≥ 22 px，截图放大到占宽 45–70%，完整窗口只作建立镜头；截图里要动的部分拆成组件单独动（按钮、候选行、光标），不整张滑入。
• 明暗分段与全屏色块按 DIRECTION.md 执行；相邻镜头换取景（全景 ↔ 特写 ↔ 大字）或换明暗；同一种入场不连用三次，同一种转场不连用三次以上。
• 禁用清单里点名的模式一个都不出现。
• 时间写在拍网格上：const B = beats(bpm)（bpm 取 mood 默认或 cues.json 里的值），幕切换、落定、锁定、cue 全部写成 B(n) 或 B(n) + 小偏移。
• 用 engine.js 的运动词汇，不只用 rise：落定用 spring / squash，标题用 riseChars 逐字从遮罩升起，数字用 counter，主角用 travel 沿路径走、morphRect 放大成下一幕的元素，连接器用 dashFlow，决策用 reel。rise 只给次要文字。
• 幕间切换由主角或风格原生转场完成，LV.start({ transition: 'none' })；只有 editorial 的浅底对浅底切换允许 'fade'。
• 代码、字段名、输出格式照源码写；示意值要在画面上标注。
• 一幕一件事，标题 ≤ 8 个词。文字停留时间按 references/styles.md 的阅读时间规则计算。
• 动效与转场遵循所选风格的配方（editorial 用 expoOut 快起慢收、不回弹；扁平和粘土用 backOut / squash；像素和拼贴用 12fps 步进）。全片只用一套转场语法。
• 音画同步：每个音效所在的帧，对应画面必须已经开始动。分组元素按音效节拍逐个出现，不整块同时出现。

动手前读 references/pitfalls.md。

6. 静帧检查 → 全片渲染

node <skill>/scripts/render.mjs --html promo.html --stills 1,3.5,6,9,13,17,22,29.9
node <skill>/scripts/render.mjs --html promo.html --out out/silent.mp4

画布尺寸取页面的 LV.start({ width, height })，竖屏无需额外参数。逐张查看静帧：残影、溢出、占位符、文字可读性、风格签名是否成立、真实素材是否看得清。render.mjs 报页面错误时必须修复，不能忽略。

静帧看不出“动得够不够”，再做运动检查：

python3 <skill>/scripts/motion_check.py --video out/silent.mp4 --scenes <各幕起点，逗号分隔>
ffmpeg -v error -y -ss <幕起点-0.5> -t 1 -i out/silent.mp4 -vf "fps=10,scale=480:-1,tile=5x2" -frames:v 1 out/cut-<n>.jpg

motion_check.py 列出每秒运动量、≥ 2 秒的静止段（STILL）和不在切点上的单帧跳变（POP）；静止段要么补主角动作、pulse 或 dashFlow，要么确认是刻意停留给人读；POP 抽帧条看，多半是闪白、漏出一帧或图片晚一帧换。每个幕边界抽一条 10fps 帧条看一眼：应当看到主角位移或元素变形跨过边界，而不是一边淡出一边淡入。

然后按 references/direction.md 第二节审片打分：2 fps 联系表 + 每个转场的 10 fps 帧条 + 信息密集镜头的全尺寸静帧，用 Read 看图，每幕六个维度各打 1–10 分，列出最差 3 个问题，改完重渲重打，直到全部 ≥ 8。最少两轮；每轮分数与问题记在 DIRECTION.md 末尾。第一次导出是草稿，不是交付。

交付渲染加 --subframes 3 得到真实运动模糊（3 倍耗时，迭代时不加）：

node <skill>/scripts/render.mjs --html promo.html --subframes 3 --out out/silent.mp4

7. 配乐与音效

在工作目录写 cues.json。mood 取所选风格在总表里的 mood，bpm 可省略（用该 mood 的默认速度）。音效对齐到画面节点（点击、亮相、转场、状态出现、打字）；工具演示每 10 秒约 3–5 个，宁少勿密：

{"mood": "synthwave", "bgm_gain": 0.5, "cues": [{"t": 4.6, "sfx": "reveal", "gain": 0.6}, {"t": 13.0, "sfx": "chime", "gain": 0.5}]}

mood：calm bright synthwave chiptune pentatonic pulse。内置音效：click tick pop chime snap whoosh reveal type thud blip glitch drop。

python3 <skill>/scripts/check_sync.py --video out/silent.mp4 --cues cues.json
python3 <skill>/scripts/mix.py --video out/silent.mp4 --cues cues.json --out out/<project>-launch.mp4

check_sync.py 会列出画面晚于音效的点：LATE 表示画面起动晚，SLOW 表示画面变化峰值晚超过 0.2s。这些只是嫌疑点，逐条用 ffmpeg -ss <t-0.1> -i out/silent.mp4 -vf "fps=10,scale=480:-1,tile=4x2" -frames:v 1 cue.jpg 看帧确认。真问题就改 HTML 或 cue 时间。持续运动的风格（网格滚动、粒子漂浮、背景流动）会让变化峰值不明显；细线描边、小图标这类小面积变化可能低于检测阈值；同一窗口里更大的场景变化也会盖住小元素。看帧确认画面已按时起动的，记为误报并在交付时注明。

用户有授权明确的音乐时用 --music <file> 替换；不要使用来源或授权不明的音频。

8. 验证

ffprobe -v error -show_entries stream=codec_type,width,height,r_frame_rate:format=duration -of compact out/<project>-launch.mp4
ffmpeg -v error -y -i out/<project>-launch.mp4 -vf "fps=1,scale=480:-1,tile=6x5" -frames:v 1 out/sheet.jpg

确认：有视频流和音频流，时长和画幅正确，每秒抽帧无残影与空白，首帧是完整画面（不是空底色），末帧停在 logo + 安装命令的完成态。按 references/pitfalls.md 的自检清单逐条核对。音频的主观听感无法由脚本判断，交付时请用户试听。

ffmpeg -v error -y -i out/<project>-launch.mp4 -vf "select='eq(n,0)'" -frames:v 1 out/poster-first.png
ffmpeg -v error -y -sseof -0.1 -i out/<project>-launch.mp4 -frames:v 1 out/poster-last.png

输出

交付以下内容：

• 成片路径，首帧与末帧海报图
• DIRECTION.md：方向与理由（以及未选的候选和 out/candidates.jpg）、专属手法、禁用清单、镜头表、每轮审片分数
• 源 HTML 与 cues.json
• 分镜摘要：每幕内容、素材来源、主角在这一幕的位置
• 真实性说明：哪些是真实录屏，哪些是示意
• 验证结果
• 修改方式：改 HTML 或 cues 后重跑第 6、7 步；换风格就回到第 2 步

发布到 X、社区、README 或任何对外渠道，都需要用户对具体平台和内容的授权；未授权时只交付成片和建议文案。