cinematic-film

电影感影片

以这种方式制作的影片，就是在一个世界里完成的一次镜头移动。每张照片、卡片、剪报、地图和数字都摆在同一块大看板上；随着故事推进，镜头沿着绳线、路线和箭头在它们之间移动。每个视觉画面都与旁白说出的词精准同步。这一切都是代码（Python 中的 Skia），因此每次渲染结果都相同，适用于任何主题；换一段新配音，整部影片就会自动重新计时。

本项目最初基于一部关于 Al Capone 的 5:22 纪录片制作，之后扩展为适用于任何主题。以下规则总结自制作过程中遇到的问题。

工具

文件	功能
scripts/check_setup.py	检查 Python、skia-python、ffmpeg、字体和内存；并指出需要安装的内容
scripts/get_fonts.py	为这台机器上缺少的任意文本用途下载采用开放许可的字体（Bebas Neue、Homemade Apple）
scripts/new_project.py	从 assets/template/（可运行的解说影片模板）创建项目，或使用 --example 创建纪录片示例
scripts/make_beats.py	编写 beats.md，即供你审核的表格；检查时间顺序、行长和口播文本中的数字
scripts/tts_say.py	使用免费的临时配音（macOS say、espeak-ng 或任何 TTS 命令），在最终配音前为影片计时
scripts/split_takes.py	将整段录音切分为每行一个片段，并标记可疑的切点
scripts/build_narration.py	将各行合并为 audio/narration.m4a 和 audio/timing.json，影片将基于这两者制作
scripts/fetch_commons.py	搜索 Wikimedia Commons，下载并附上许可和署名信息；拒绝非免费文件，并写入 credits.md
scripts/make_map.py	为地图投影公有领域的边界数据（适用于任何国家或地区）
scripts/prep_assets.py	将每张图片调色为统一风格（黑白、棕褐色或自然色）；并生成看板纹理
scripts/engine.py	影片引擎：镜头、聚光灯、元素、地图、风格和影片质感
scripts/render.py	渲染静帧、联系表、提示列表和并行 MP4
scripts/build_sfx.py	根据提示列表合成所有音效（不使用采样，无需处理许可）
scripts/mix_soundtrack.py	混合人声、音效和可选音乐，并进行自动压低和响度标准化
scripts/burn_captions.py	将四种字幕样式之一烧录到成片中，并生成 SRT

需要 Python 3.9+、pip install skia-python numpy pillow（scipy 可选）和 ffmpeg。请先运行 scripts/check_setup.py；在 Linux 或 Windows 上，还请为每个项目运行 scripts/get_fonts.py。所有命令都接受 --project <folder>。

选择影片类型

类型	风格	图片	常见元素
历史、真实犯罪、调查	wall、slate	档案照片和文件，调色为 bw	照片、撕裂剪报、印章、红线、地图路线
产品发布、品牌或创始人故事	studio、charcoal	产品照片和团队照片，调色为 natural	卡片、大号数字、计数器、箭头
科学、工程、工作原理	blueprint、paper	示意图、档案图片或 AI 静帧	卡片、计数器、笔迹、地图
科技、太空、预告片	night	截图、渲染图、AI 静帧	大号文字、计数器、路线、卡片

可以自由混搭：风格决定看板和成片效果，每种元素都适用于任何风格。references/story.md 为每种类型提供了故事结构。

规则

1. 每行只聚焦一个主体。 每行旁白中，镜头只对准一个对象。聚光灯会让其他所有内容变暗。
2. 效果要与说出的词同步。 印章要在说到“charged”时砸下，而不是在整行开头。使用 doc.W(line, "word") 为所有内容计时。
3. 一个短语只用一种方式呈现。 要么将它打在屏幕上，要么将它展示在真实文档上，不能两者兼用。文档上的正文用灰色行呈现，不能用填充词。
4. 开场后，时间只能向前推进。 冷开场可以跳到未来。在一行过渡语（“四年前……”）之后，故事时间只能向前推进。
5. 手机上能在一秒内读完的文字。 使用大号、窄体大写字母。屏幕上的文字标签应占画面高度的约 3% 或更多。
6. 少即是多。 字符串在对应节拍后淡出，旧项目变暗。最后的拉远镜头应构图得当，而不是杂乱无章。
7. 不得杜撰看起来像真实内容的东西。 真实照片和文档都要标注来源。用代码绘制的文档要标注为复原件，且只引用实际写过的文字。AI 图像可以用于插图，但绝不能作为真实事件或真人的证据。

工作流

在四个关卡（标有 Gate）处暂停，等待用户批准。

1. 故事。 先研究，再编写 script.json：将行分成若干段（sections），每行包含 text、spoken（将数字写成单词）、hero 和 typed。同时记录事实说明。60 到 90 秒约为 150 到 230 个词。详情见 references/story.md。
2. 节拍表。 运行 scripts/make_beats.py，并修复所有 lint 警告。关卡： 用户批准 beats.md，包括其中的事实。
3. 图片。 在 photos.json 中列出每张图片：其 id、类型和来源。
   • 档案图片：使用 fetch_commons.py search、category 和 get。
   • 用户自己的文件：放入 <project>/assets/photos/。
   • AI 静帧：统一采用一种风格生成（motion-assets 技能会规划并估算价格）。
   • 其他档案来源和版权规则见 references/archive.md。
4. 临时配音。 运行 tts_say.py，然后运行 split_takes.py，再运行 build_narration.py。听完 split_takes.py 标记的每一行。现在，时间信息就准确了。
5. 素材。 如果故事涉及地点变化，运行 make_map.py，然后运行 prep_assets.py。
6. 场景。 编写 scene.py：按段落将画板布局为多个集群，使用 doc.L/doc.W 时间点添加项目，然后设置摄像机和聚光灯关键帧（film.shot）。阅读 references/film.md。两个随项目提供的示例都展示了这些模式：assets/template/scene.py（解释类，演播室风格）和 assets/wright-flyer/scene.py（纪录片风格，涵盖所有项目类型）。
7. 视觉测试。 在 1280x720 分辨率下，对每行的一个静帧运行 render.py --probe，并逐一查看；对每个大型镜头移动运行 --strip。关卡： 向用户展示开场和整体风格的静帧。
8. 初稿。 使用临时配音，以 1280x720 分辨率渲染前 30 秒。关卡： 用户观看初稿。
9. 最终配音。 使用任意 TTS 或真人录制（见 references/voice.md）。再次运行 split、build 和 probes；场景中不得有任何改动。
10. 声音。 运行 render.py --cues，然后运行 build_sfx.py，再运行 mix_soundtrack.py，也可以按需添加配乐。阅读 references/sound.md。
11. 完成。 完整渲染，然后运行 burn_captions.py 并生成 SRT。以 1440p 或 4K 分辨率渲染前，阅读 references/performance.md。将 credits.md 与影片一并交付。

每次都要自我检查

在声称效果正常前，先查看静帧。以下是在真实渲染中出现的所有错误：

• 深色墨水印在深色底板上：看不见。深色画面请使用浅色字体，或者使用 bar_h=0.92，在深色字体后方添加完整的标签块。
• 镜头已经移动，但聚光灯还留在原地，导致画面一片黑。除非需要让它们分开，否则请使用 film.shot()。
• 地图比例太小：整段海岸线还没有一张照片大。选择合适的 K，让每个放置照片的地点都有自己的空间（references/film.md）。
• 地图标签重叠。将标签放在远离相邻标签的一侧。
• 簇群跨出地图边缘。让簇群要么位于地图上，要么明确地位于地图外。
• 高亮与对应文字相差几个像素。使用 PaperDoc.phrase_spans，并使用 doc.on(print, fx, fy)，其中分数应从图像网格叠加层上读取。

已交付项目

• assets/template/：“从樱桃到咖啡杯”，一部采用工作室风格、时长 25 秒的解说短片，由卡片、箭头和计数器组成，不含图像。new_project.py my-film 会复制此模板。添加临时配音后即可渲染。
• assets/wright-flyer/：“十二秒”，一部时长 90 秒的纪录片，讲述首次飞行以及那位坠机两次的 50,000 美元竞争者。它使用了七张公有领域照片、美国地图、两份排版文档以及每种项目类型。

python3 scripts/new_project.py wright --example
python3 scripts/fetch_commons.py get --project wright
python3 scripts/make_map.py --project wright && python3 scripts/prep_assets.py --project wright
python3 scripts/tts_say.py --project wright && python3 scripts/split_takes.py --project wright && python3 scripts/build_narration.py --project wright
python3 scripts/render.py --project wright --size 1280x720 --out out/draft.mp4 --audio audio/narration.m4a

相关技能

来自 Open 3D Skills：motion-assets 会在影片需要插图时规划并估算 AI 静帧的成本；frame-capture 则会记录网页，而不是用代码绘制影片。