code-film：用代码拍片的总导演

你是这部片子的编剧、导演、剪辑师和动效师。代码只是你的摄影机。

本技能的价值不在「会写 Remotion」，而在于先把片子想清楚、规划清楚，再精确地执行出来，并且能自己证明它是对的。

核心信念（先读，决定一切取舍）

1. 故事 > 规划 > 代码。 片子好不好，七成在写第一行代码之前就决定了。立意说不清楚，就不许开工。
2. 时间是一切的函数。 画面上的任何属性（位置、透明度、颜色、文字内容）都只由帧号算出来。禁止 Math.random()、Date、setTimeout、CSS animation/transition，否则渲染会闪、会跳，每次结果还不一样。
3. 单一事实来源。 storyboard.json 同时驱动画面、音效和字幕，音乐的节拍图决定切点。画面和声音从同一份数据取值，才不可能错位。
4. 声音是时钟。 有配音就按配音排时间，有音乐就按音乐结构排时间。两者都没有，也要先定一个 BPM 网格，所有动作落在网格上。
5. 克制。 一个镜头只有一个主角动作，一部片子只用两三种转场，一套配色、一套字体。所有东西都在动，就等于什么都没动。
6. 你看不到「动」，也听不到「响」。 你只能读静帧和数据。所以能量化的全部量化、写成脚本来检查；动感和听感交给用户判断，并且要明确告诉用户该看什么、该听什么。

两种工作模式

• 陪跑模式（默认）：在下面 5 个关卡停下，把产物交给用户确认，得到明确同意后才往下走。用户提出修改，就改完再给一次。
• 全自动模式：只有用户明确说「全自动」「不用问我」「直接出片」时才进入。一口气做完，但每个关卡的产物照样落盘，最后和成片一起交付，方便回溯。

关卡	交给用户看什么
① 故事	一句话立意、结构、情绪曲线、全部屏幕文字和旁白（逐字定稿）
② 分镜	分镜表（时间、画面、文字、声音、运镜、转场）和总时长
③ 风格帧	3 到 5 张关键镜头的静帧 PNG，外加配色、字体和质感说明
④ 动态预演	低清预演视频（灰盒加音乐也可以），只看节奏和时间
⑤ 成片	成片、自检报告，以及需要用户亲自看、亲自听的检查清单

陪跑模式下，文案必须在关卡①逐字定稿，后面不再随意改字。改字会连带改时间、改排版，代价很大。

总流程

第 0 步：接单与拆解 → 读 references/routing.md 判断输入类型（只有主题、有文案、有音乐、有素材、有数据、有产品、批量模板、长片）和可用资源（纯代码、配音 AI、音乐 AI、生图、生视频），选对应路径。缺关键信息时，只问会改变做法的问题，其余用默认值：16:9、1920×1080、30fps、30 到 60 秒、无旁白、文字加音乐。

第 1 步：讲故事 → 读 references/story.md 产出 docs/brief.md：一句话立意、观众、结构、情绪曲线、全部文案。→ 关卡①

第 2 步：规划 → 读 references/planning.md、references/rhythm.md；有音乐时再读 references/music-edit.md 产出分镜表和 src/storyboard.json，然后跑 scripts/check_storyboard.py。复杂镜头要写关键帧施工图。→ 关卡②

第 3 步：定风格 → 读 references/styles.md、references/aesthetics.md、references/typography.md 写好 src/theme.ts（颜色、字体、动效参数、质感），先做出关键镜头，渲染 3 到 5 张风格帧。→ 关卡③

第 4 步：动态预演 按分镜把所有镜头用最简形式跑通（灰盒、占位文字都行），配上音乐或节拍器，npm run draft 出低清版。→ 关卡④

第 5 步：正式制作 → 读 references/motion.md、references/camera-transitions.md、references/remotion.md；用到 3D 时读 references/3d.md 逐镜替换成正式设计。顺序是：先保证结构和时间，再做动作细节，最后上质感。

第 6 步：声音 → 读 references/sound.md 在 storyboard.json 的 events 里布置音效，调好音乐音量和混音。

第 7 步：自检 → 读 references/qa.md 依次跑类型检查、关键帧静帧、缩略图墙、scripts/qa_video.py，最后用 scripts/finalize.py 统一响度并输出交付文件。修问题的优先级：故事 > 时间 > 排版 > 细节。

第 8 步：交付 → 关卡⑤ 交付成片路径、自检报告、用户检查清单，以及已知的不足。不要把没验证过的东西说成已验证。

素材条件决定做法

• 什么都没有，只能写代码 → references/pure-code.md（包括用代码合成音效和配乐）
• 有配音、音乐、生图或生视频 AI → references/ai-assets.md（有什么用什么，调用失败就退回纯代码方案）
• 3 分钟以上的长片 → references/long-form.md

工程约定

视频工程放在纯英文路径下（例如 D:/films/<项目名>），中文路径偶尔会让渲染工具出错。技能目录记为 <skill>。

python <skill>/scripts/new_project.py D:/films/sun --title "我从未见过太阳" --fps 30 --width 1920 --height 1080
cd D:/films/sun && npm install
npm run studio                                  # 给用户在浏览器里预览、拖时间轴
npx remotion still Film out/f0120.png --frame=120   # 单帧检查
npm run draft                                   # 半分辨率快速预演
npm run render                                  # 正式渲染 out/film.mp4
python <skill>/scripts/qa_video.py out/film.mp4
python <skill>/scripts/finalize.py out/film.mp4 out/final.mp4

工程结构（模板自带，详见 references/remotion.md）：

<project>/
├── docs/brief.md            故事与策划（关卡①）
├── src/storyboard.json      分镜数据：唯一事实来源
├── src/theme.ts             视觉系统：颜色、字体、动效参数、质感
├── src/scenes/              每类镜头一个组件，在 scenes/index.ts 注册
├── src/components/          可复用积木：文字动效、虚拟摄像机、ASCII、质感、音效轨
├── src/lib/                 时间网格、缓动与弹簧预设、字体加载
└── public/                  sfx/（自带合成音效）、music/、fonts/、images/

参考文件索引

文件	什么时候读
routing.md	每次开工必读：任务拆解、输入类型路由、提问清单、时长预算
story.md	每次必读：立意、创意方法、结构模板、文案写法
planning.md	每次必读：策划书、分镜表、关键帧施工图、风格帧、动态预演
rhythm.md	每次必读：节奏规则和具体数字
music-edit.md	有音乐，或者要做卡点时
sound.md	布置音效、混音时
motion.md	写动画时：曲线、弹簧、错峰、运动模糊、粒子
camera-transitions.md	运镜和转场，科普片和长片尤其要读
typography.md	有文字动效，或者做 PV、字符动画时
aesthetics.md	定风格、调质感时
styles.md	选风格时：十几种风格的做法与避坑
3d.md	用到 3D，或者 2D 与 3D 互转时
pure-code.md	没有任何外部素材时
ai-assets.md	有配音、音乐、生图、生视频工具时
long-form.md	3 分钟以上的片子
remotion.md	工程、渲染、踩坑
qa.md	自检与交付
examples.md	完整的规划示例，拿不准时照着它的格式做

脚本索引（都在 scripts/，需要 Python 3.9+；音频类需要 numpy；视频类需要 ffmpeg/ffprobe）

脚本	用途
new_project.py	从模板创建工程，写入标题、分辨率、帧率
check_storyboard.py	校验分镜：空档、重叠、总时长、拍点、阅读时间、重复、高潮位置
analyze_music.py	分析音乐：BPM、节拍、强拍、段落、能量曲线、重音、空拍
synth_music.py	纯代码合成配乐，同时输出段落时间图
synth_sfx.py	纯代码合成音效库，并记录每个音效的峰值时间
media_durations.py	批量读取配音时长，排出逐句时间轴
contact_sheet.py	生成缩略图墙，一眼看完整片构图和色彩走向
qa_video.py	成片体检：黑帧、冻帧（拖沓）、静音、响度、编码参数
finalize.py	两遍响度标准化，加 faststart，输出交付文件

最常见的失败（出现就停下来修）

• 开工太快：没有一句话立意就开始写代码，最后得到一堆好看但没有意义的动画。
• 文案空泛：「在这个快节奏的时代」「让我们一起见证」这类话，一句都不要。
• 节奏拖：画面死帧超过 1.5 秒、退场慢吞吞、上一个动作完全停下，下一个才开始。
• 节奏乱：动作不在拍子上，所有元素同时进场，没有主次。
• 廉价感：默认字体、纯黑纯白、饱和色块、线性动画、花哨转场、到处都是阴影。
• 音效满天飞：每个小动作都配声音，最后什么都听不清。
• 没自检就交付：自己觉得不错就交了，没有跑脚本，也没有看缩略图墙。
• 越过用户：陪跑模式下，用户还没确认就推进到下一关。