Code film(代码电影)
这里的“电影”是一个网页,它能按需绘制任意时刻的画面(window.renderAt(t))。一个小型工具在 headless Chromium 中对每一帧进行 GPU 渲染,然后 ffmpeg 将这些帧与音轨合成为视频。整个过程不涉及实际拍摄或生成视频,因此画面完全由代码决定,无论何种分辨率,每次渲染结果都一致。
本文件夹中的工具包已在 "Dial-A-Dev 98"(Builder Wars 每周主题“1998 年发布”,2026 年 11 月)中验证:时长 44 秒,分辨率 1920x1080,共 11 个镜头,约 1326 帧,渲染耗时约 45 秒。该电影的完整源代码位于 examples/dial-a-dev-98/ 中。开发模式遵循 github.com/Vincentwei1021/mg-styles-15(MIT 许可),该仓库也是动态设计风格的优秀入门指南。
启动电影项目
bash ~/.claude/skills/code-film/new-film.sh ~/Work/<电影文件夹> # 复制工具包,安装两个本地包
cd ~/Work/<电影文件夹>
# 声音需要 ElevenLabs 密钥:用户需自行在 ./.env 中保存 ELEVENLABS_API_KEY=...(切勿在聊天中索取)
node harness/render.mjs film --stills 0,1,2 # 导出 PNG 静态帧 → film/out/stills/
bash tools/build.sh v1 # 生成提示列表、混音、渲染、X 编码 → film/out/<电影名称>_v1.mp4
将电影项目保存在独立文件夹中,不要放在任何产品仓库内。在安装任何全局工具前请先询问。
工作流程
- 简报。 产品、受众、发布渠道、时长、画面比例(16:9、9:16、1:1)。如果用于 Builder Wars,调用
get_video_guide并遵循其规则(优先级高于本文档)。 - 创意方案。 一个核心创意:前 0.5 秒内设置钩子、逐步升级、在影片时长约 60-75% 处呈现一个高光时刻、以及一个精心设计的结束画面。选择一种风格,并将其标志性特征以可测试的语句记录下来。
- 先写提示表(
film/cues.json)。将旁白脚本按行书写,并附带预估时长。镜头与台词、词语绑定,而非硬编码的秒数,因此更换语音录制时,整个电影的时间线会自动调整。 - 动画前先确定静态帧。 先构建两到三个最难画面的视觉效果,并以完整尺寸审视它们。不要对尚未达到海报级别的帧进行动画。
- 镜头。 每个镜头一个模块(合约见下文)。使用静态帧和小样片检查每个镜头。
- 配音。 试听(库存语音及三种定制语音),逐行录制并获取单词时间戳,然后让提示表调整剪辑点:
node tools/vo.mjs --voice <id>,随后使用--reuse --tempo 1.12收紧朗读节奏。 - 音效和音乐。 在
audio/sfx.json和audio/music.json中列出,使用node tools/sfx.mjs --music生成。每个镜头声明自己的音效提示,确保音效与画面精准同步。 - 构建(
tools/build.sh),然后自行观看样片并修复发现的问题。 - 评审。 向独立代理提供
rubric.md、视频文件和简报。该代理未参与制作,负责评分并返回有序的修改意见。应用修改后重新构建,然后才能展示给用户。如果时间允许,进行两轮评审。 - 完成并交付。
tools/finish.sh对 X 进行编码,并生成海报和样片。运行目标平台的检查工具。由用户自行发布,切勿代为发布。
页面合约
window.FILM = { width, height, fps, duration, shots, lines, sfx },window.renderAt = async (t) => {...},然后window.__ready = true。- 每一帧都是
t的纯函数:仅使用确定性随机数,无时钟、无 CSS 过渡、无帧间状态传递。工具包可能以任意顺序、同时在多个浏览器上请求帧。 - 一个镜头定义为
{ name, samples(lt), render(lt, post, renderer), overlay(g, lt), look(lt), sfx: [...] }:render将线性 HDR 绘制到post.scene;overlay在 1920x1080 的画布上绘制二维叠加层(若绘制则返回 true);samples是该时刻的运动模糊采样数量(静止时 3,快速运动时 12-20);look返回后期处理设置(辉光、闪光、胶片效果、故障效果);sfx列出{ t, s, g, a, len }:本地时间、声音名称、增益、a: 'peak'表示将声音的最强点对准提示点、以及可选的剪辑长度。
film/js/film.js将镜头名称映射到工厂函数,并绘制所有镜头之上的通用元素。- 查询开关用于外观开发:
?clean(无胶片后期)、?nocc(无字幕)、?mb=1、?rs=0.5。 render还接收当前渲染通道编号和总数(render(lt, post, renderer, i, K))。镜头可设置shutter: 0。无运动模糊时,K 个通道可用于其他用途:移动镜头以实现景深、调整主光以实现柔化阴影、移动像素网格以实现抗锯齿(参见故事书中的rig.js)。look()可返回paper: true以替代胶片后期,实现干净效果(色彩准确的色调曲线、颗粒感、暗角)。film.js可导出loadFonts(必须在首帧前完成的所有异步操作)、buildCaptions和caption。
本机配置(2026-11-11 检查)
- Chromium 155(路径
/usr/bin/chromium),RTX 4070 Ti SUPER。硬件 WebGL2 需要--use-gl=angle --use-angle=gl-egl(工具包会自动传递这些参数,若回退到软件渲染会发出警告)。WebGPU 会回退到软件渲染:请使用 WebGL2。 - ffmpeg 9(含 libx264 和 NVENC);ImageMagick 用于生成样片;无 Blender,虚拟环境外无 numpy。
- 完整 1080p 渲染:使用三个工作线程时,每帧约 0.03 秒。
ElevenLabs 注意事项(2026-11-11 检查)
- 密钥存放在电影文件夹的
.env文件中。某些密钥可能缺少user_read权限,导致无法读取套餐信息和剩余额度;请如实说明,不要猜测。 - 当前套餐最高支持
mp3_44100_128(更高格式需要 Creator 套餐)。语音模型eleven_v4工作正常,并支持音频标签如[excited];这些标签会在对齐结果中保留,由vo.mjs自动清理。 - 库存语音在强推销场景下朗读偏慢。使用定制语音(
eleven.mjs design,然后voice-save.mjs,会占用一个语音槽位)加上--tempo 1.12可实现电视购物般的节奏。speed设置对时长的改变微乎其微。 - 音效音量差异极大,甚至有静音文件:
mix.mjs会对每个文件进行峰值归一化,跳过接近静音的文件并给出提示。使用更简单的提示词重新生成这些音效(例如“一声响亮的手掌拍击”能达到效果,而描述拍板的声音可能三次返回静音)。 - 故事讲述者语音朗读较慢:库存语音 George 的速度为每秒 2.25 个单词。
--tempo 1.25可提升至 2.7,达到普通语速。时长应根据录制后的台词确定,而非单词计数。 - 生成的音乐在指定时长之前就已结束。
mix.mjs会检测音量的实际结束点,并与电影结尾对齐。 - 角色语音(例如儿童电视节目吉祥物)会根据描述中的语速朗读:同样的文本,描述为“对幼儿说话缓慢”时耗时 31 秒,描述为“活泼、明快”时耗时 24 秒。将语速写入描述,设计两到三个描述(每个预览三次),使用
tools/audition-stats.mjs测量(时长、中位音高、音高范围),并预期需要--tempo 1.3。描述类型而非具体名称,切勿使用真实角色或人名。 - 用户从试听中选择的语音在电影中可能听上去音调更高,尽管测量的音高和亮度相同:模型朗读单句的速度大约比朗读长段落快 1.3 倍,再加上
--tempo会使语音听上去更高、更细。使用vo.mjs --reuse --tempo 1.38 --pitch -2可在相同速度下降低音调(时间线不变,因此只需重新混音并在原母版上运行finish.sh,无需重新渲染)。生成 0、-1、-2、-3 半音的比较片段供用户试听,之后重新检查语音轨电平(mix.vo)。 voice-save.mjs <生成的 id> "<名称>" "<描述>"将预览保存到账户中(占用一个语音槽位)。录制新语音前,请保留之前的配音文件(cp -r audio/vo audio/vo_<名称>)。- 免费计划不适用于商业发布。如果套餐类型未知,请告知用户。
常见问题总结,避免重复发生
画面与代码:
- 根据文本位置估算单词发音时间误差可达 1 秒(例如“98”发音为“ninety-eight”)。请使用录制后的单词时间戳(
mark(line, word))。 - Three.js 渲染的挤出文本尺寸比标称尺寸大。需要将文字适配到目标宽度,切勿信任数字。
- 平面镜面在方向光照射下会呈现均匀白色。为圆盘和铬面物体添加点光源或多样化环境,使高光呈现为光斑。
- 重叠的倾斜圆盘会相互交叉。按深度排列它们并限制倾斜角度。
- 模糊的地面反射会将背景闪光点转换为点阵:在镜面反射通道中关闭闪光点。
- 伪粗体位图文字(将文字绘制两次,相差一个像素)会导致 W 和 M 被填充。
ui98.js仅在到下一笔画间距足够大时加粗笔画。 - 顶部颜色与背景相近的 Logo 会消失。为挤出字母添加深色边线(
makeLetters中的outline),并保持侧面近乎黑色。 - 胶片噪点编码成本高昂。使用无损渲染(
--lossless),然后以比特率限制进行一次编码。
首次评审发现的问题(我以为电影完成时,得分约 6/10):
- 产品名称必须在约 2 秒内出现在屏幕上,且第 0 帧应为缩略图。从第一帧开始显示静止的下三分之一标题栏,可同时解决这两个问题。
- 叠加层和字幕遮挡了最佳笑点。放置任何叠加层后,请查看其下方的画面。
- 镜头推进后,文字超出安全标题区域。检查每次推进的最后一帧,而非第一帧。
- 每个剪辑点都使用相同的白色闪光和故障效果,显得模板化;四个镜头共用同一个背景和五个相同的星爆效果也是如此。让它们多样化;将大闪光留给一两个关键点。
- 在 1080p 下看起来正常的字幕在手机上显得过小:字母高度应约为 40 像素,并放置在独立区域中。
- 前提未得到兑现。例如电影说“除非有人接电话”,那么必须有这样一个人出现。
- 音效落在单词发音处会听不见。将音效移至单词之后并提高音量。
在纸质故事书电影的两轮评审中发现的问题(得分约 6/10,然后约 7/10):
- 真实产品屏幕全屏显示时看起来像屏幕录制,破坏了世界氛围。将其限制在场景内(例如场景中的笔记本电脑),以两个大裁剪区域配合大字号显示,使用至少 16 帧的世界内过渡切换。裁剪掉所有边框,使屏幕两侧无缝;标注游戏内货币为“虚拟”。
- 镜头间的数字必须一致。“虚拟百万富翁”之后展示一块写着 9,100 美元的板子,破坏了英雄台词。
- 英雄镜头静止了 1.4 秒。在每个停顿中保持运动(硬币落下、灯光闪烁、台词结束时第二次爆发),并从第一帧开始就采用宽景别。
- 超过 1 秒的语音间隙,如果只有微弱的背景音乐,会显得像死寂。缩短它,或者加入一个搞笑元素和音效。
- 带有清晰边缘的平面形状即使添加了颗粒感也看起来像矢量图。略微不稳定的切割线和边缘处更亮的纸芯(故事书
paper.js中的piece())可以解决这个问题。标牌应使用切割字母(cutSign),而非印刷字体。 - 任何漂浮物体都需要可见的支撑物(杆、弹簧、标签)。光束必须使用不透明纸张。
- 关键动作在手机上显得太小:硬币抛掷、王冠换面、按钮按压。放大动作并推进摄像机拍摄。
- 弹出式元素相互穿越,也穿过翻页中的书页。正确的折叠几何结构使得面对读者的折页在书页开始合拢时立即躺下。保持这些折页直立,让所有弹出式元素在书页接近全开之前保持低位(
book.js中的rise),并隐藏平放在闭合书内的部分。 - 页面不能在句子结束前开始翻动:镜头的
lead不能长于其前的gap。 - 重复画面已传达的笑点的字幕会破坏效果。某句台词的
cc可只保留开头几个字;台词讲完后字幕随之消失。 - 以第一帧结束:书合上后展示封面,地址显示在书带上。同时能干净地循环播放。
用户在观看该电影后要求修改的内容(v4 剪辑):
- 拿其他角色开玩笑的台词(“Sam 恨 Kim”,乌云)显得刻薄。用户要求将笑点对准主角:Sam 落泪,然后幻想自己成为第一(“梦想吧,Sam,梦想吧”)。笑点应针对主角。
- 从产品复制来的标语(“月收入最高者胜”)让用户质疑胜者得到什么;实际上什么也没有。录制前检查剧本中每一句陈述是否与产品实际功能一致。
- 思想气泡高度超出画框:摄像机随之抬高,保持气泡对应物在画面内(梦想板下方的真实板子),并在页面翻动前几帧爆破气泡,避免高耸物体随书页移动。
任务拆分:
- 先在一个会话中构建视觉效果和引擎(两到三个用户认可的帧),并将镜头合约和每个镜头的简报写入文件(
SHOTS.md、BRIEFS.md)。然后将镜头分配给新代理,每个代理负责一两个镜头,使用model: "opus"和这些文件作为简报。不要使用分叉(fork)来实现这一点:分叉总是使用会话自身的模型和努力值,无法分配更便宜的模型(在风格电影中,分叉消耗了 55% 的使用量)。每个代理只拥有自己的镜头文件;先编写共享角色;逐个加载镜头模块,这样某个文件在编辑中损坏时只会影响它自己的镜头。使用同样的方式将评审修改分配给新代理(提供镜头文件和修改列表),而不是恢复构建代理;引擎文件保留在主会话中。 - 每轮评审分配给一个新代理,并告知第二个代理不要阅读第一个代理的笔记。
流程:
pkill -f <模式>会匹配运行它的 shell。将模式写成[p]attern以避免误杀。- 页面错误会导致工具包等待。它会在 45 秒后超时并打印页面错误;调试时不要将其通过
tail管道传输,否则错误信息只在最后才出现。
...
[为翻译而截断]