自动叙事动画师 是做什么的?
给它一个语音文件和一个剧本。它就能完成整部影片:时间线、布局、渲染、剪辑、字幕、音效、混音和质检。无需手动分镜、无需场景代码、无需编辑时间线。
python scripts/run.py --project my-film --voice voice.mp3 --script script.md
这一条命令运行完整流水线,并在 my-film/out/ 目录下生成 FILM.mp4、FILM.srt(以及 captioned.mp4)、credits.md、beats.json、plan.json、beats.md、out/qa/ 中的审查截图,以及所有中间产物。
开始前——自动前置检查
每次运行都从 check_requirements.py 开始,先于其他任何操作。如果所有可用工具已安装,则立即继续生产——无需设置。如果缺少某些工具,则会自动下载/安装,然后继续生产。
依次检查:
- Python 3.8+
- Python 包 —— numpy、skia-python、Pillow、faster-whisper —— 如果缺失则通过 pip 自动安装
- ffmpeg + ffprobe 在 PATH 中 —— 如果缺失,则通过
winget(Windows)、brew(macOS) 或apt-get(Linux) 自动安装 - 与此技能位于同一目录下的 cinematic-film(或设置
CINEMATIC_SCRIPTS=<指向其脚本目录的路径>)
如果一切就绪:显示一行 requirements: ok 并开始构建。如果 Python 包无法安装,脚本会打印出修复该问题的精确命令并退出,而不是启动一个注定失败的构建。如果找不到 cinematic-film,同样处理——你会确切知道缺少什么以及需要设置什么。
输出效果(视觉风格)
两种视觉语言每 3-10 秒硬切换一次,由导演按块决定:
- 白板(Board) - 一张满版蓝图稿纸。文字以手绘粉笔字体形式出现在深蓝色网格上,带有草图矩形标注框、抖动线条、涂鸦代码窗口、勾选标记、分隔线和霓虹图标(两层发光 + 炽热核心),均由代码绘制。
- 照片(Photo) - 来自 cinematic-film 的夜间证据墙:真实的 Wikimedia Commons 授权照片,带有投影和别针、排版纸质文件、抖动高光规则、发光的霓虹图标,所有内容均在
credits.md中注明出处。
字幕位于底部居中,并紧贴底部边缘(720p 时为 6 像素,随分辨率缩放),大写,使用九种糖果色墨水之一(带种子随机性),缓入效果(上升/弹出/滑动/倾斜/淡入/交错/滚动)和缓出效果(淡出/下落/上升消失/收缩),三层泛光光晕,口语单词上带有彩虹渐变扫光(霓虹管白色描边)。字幕行后方的渐变背景确保其在任何背景下都清晰可读。文字内容与语音完全一致。
从零开始 vs. 恢复运行
- 新项目:提供语音和剧本;技能构建一切。
python scripts/run.py --project my-film --voice voice.mp3 --script script.md - 恢复运行:在已有
out/FILM.mp4(以及计划/照片)的项目上重新运行,仅通过 QA 重新验证——不会重新下载或重新渲染任何内容。添加--force以从头重建。
输入
--voice:任何 ffmpeg 能读取的音频文件(mp3/wav/m4a...)。使用干净的单次录制旁白效果最佳。文件会被直接使用,仅转换为 48 kHz 立体声 AAC。--script:.md/.txt/.srt/.json文件。Markdown 标题会变为屏幕上的章节提示字幕;空行和段落被分割成句子,然后拆分为字幕块(<= 9 个单词 / <= 64 个字符)。屏幕上的文字与文件中的文字逐字一致。当存在script.json且格式为{"title": ..., "takes": [...]}时,会优先使用。
选项
| 标志 | 效果 |
|---|---|
--size 1920x1080 | 渲染尺寸(默认 1920x1080) |
--crf 16 | 质量(数值越低质量越好;16 为影片质量,26 为预览质量) |
--photos auto|existing|none | 按块获取照片(Wikimedia Commons,仅限免费许可)/ 复用 photos.json / 无照片 |
--music auto|none|file | 随附的 Kevin MacLeod "Crypto"(CC BY 4.0)循环至影片长度 / 静音 / 使用你的文件 |
--model tiny.en | 用于对齐的 faster-whisper 模型尺寸(base.en/small.en 更准确) |
--preview | 仅以 640x360 渲染 0-1 块,用于快速预览 |
--skip-render | 仅重新规划(不渲染) |
--workers WORKERS | 渲染 + 字幕工作线程数(0 = 所有核心减一) |
--force | 即使已存在完成的 out/FILM.mp4,也强制重建 |
性能与安全性
- 生产缓存位于
E:\Storyteller catche files(可通过STORYTELLER_CACHE覆盖)。每项重量级产物都根据内容哈希进行缓存,因此重新运行或调整后续阶段时,只会重新执行已更改的部分:
| 文件夹 | 缓存内容 | 键值 |
|---|---|---|
whisper/ | faster-whisper 单词时间戳 | 语音文件 + 模型 + 设备 |
commons_search/ | Commons 搜索结果集 | 查询词 + 限制数 |
commons_files/ | 下载的 Commons 原始文件及信用侧车文件 | Commons 标题 |
blocks/ | 已渲染的样式块 | 场景 + 节拍 + 块几何 + 尺寸 + CRF |
silent/ | 拼接后的无声影片 | 块文件 + CRF + fps |
captioned/ | 带字幕的影片 + SRT | 视频 + 时间线 + 字幕代码 + CRF |
sfx/ | 合成的音效总线 | 提示表 + build_sfx.py |
music/ | 循环的背景配乐 | 配乐文件 + 影片长度 |
mix/ | 完成的音频混音 | 语音 + 提示 + 音乐 + 音量 + LUFS |
文件命名为 <label>-<hash12>.<ext> 并按类型排序(sort 列表可自然阅读),在根目录下有一个仅追加的 index.jsonl 清单和 README.txt 文件。缓存未命中会自动重新构建;删除缓存始终安全。完全重新运行未改变的阶段只需几秒钟(whisper/块/拼接/字幕/音效/混音全部命中缓存)。
- 每个块单独渲染,然后使用帧精确的
concat滤镜拼接块。编辑剧本后重新运行时,仅重新渲染计划发生变化的块(render_blocks.py会复用最新的块文件,并以生产缓存作为第二层保障)。 - 12 核 / 大量内存:使用
--workers 6。一部 3 分钟的 1080p 影片大约需要 15-30 分钟。 - 切勿在用户未要求的情况下渲染最终影片:先使用
--preview或较小的--size,展示结果,然后才以全尺寸生成FILM.mp4。 - Whisper tiny.en 在 CPU 上约为实时速度的 1 倍;如果长行的时间戳漂移,请使用
--model base.en。
导演的工作内容
每行字幕变成一个节拍(beat)。一个节拍会从其文字中精确选择一个布局:
| 布局 | 触发词 | 绘制内容 |
|---|---|---|
title / end | 前 2 行 / 后 2 行 | 霓虹图标 + 大粉笔标题(标题 = 该行内容词的首字母大写) |
chain | first/second/then/process/pipeline | 3 个带箭头的草图框 |
split | before/after/versus/compared/instead | 两个带标签的框架分别位于撕裂分隔线两侧 |
window | code/script/terminal/agent/model/server | 手绘终端窗口,带有涂鸦行 + 高亮行 |
check | protect/patch/secure/prevent/never | 列表中粉笔勾选标记 |
stat | 任何数字 | 巨大的发光数字 |
quote | 所有其他 / 疑问句 | 粉笔引用块 |
| 照片变体 | 每隔一个块 | station(照片 + 卡片)、doc(纸质文档 + 印章)、stat |
连续的行(1-4 行,最长约 9 秒,在句子结尾处切断)组成块(block);块在整部影片中交替使用白板/照片风格。第一个和最后一个块始终是白板。
生成的文件
audio/narration.m4a 标准化的语音
audio/timing.json 每行开始/结束时间(引擎架构)
script.json 按说话顺序排列的片段,保留 id 顺序
beats.json 每行:开始/结束/布局/提示字幕/标题/要点/数字/图标/墨水颜色/照片/X 坐标
plan.json 块(样式、帧范围、世界 X 坐标)、fps、时长
beats.md 整个计划的人类可读表格
sfx_cues.json 为 build_sfx.py 合成的效果
photos.json Commons 选取的照片,包含许可证/出处/来源
out/blocks/bNNN.mp4 每个样式块对应的一个剪辑
out/silent.mp4 拼接后的无声画面
out/captioned.mp4 + 烧录的霓虹字幕(+ .srt)
out/FILM.mp4 最终成品,包含混音后的音频
out/qa/*.png 审查截图
credits.md 图片+音乐出处
QA 门控(scripts/qa.py,由 run.py 自动运行)
在以下情况构建失败:帧数计数与 timing.total_duration * fps 不匹配、缺少/无音频流、响度超出 -15 +/- 1.5 LUFS、真实峰值高于 -0.8 dBTP、某个字幕块不可见、或字幕基线距离底部边缘超过帧高度的 8.5%。
配套技能(制作的完整流程)
该技能是教育/解说类视频工作流(“像 AI 漏洞利用智能体影片那样的视频”)的专用编排器。它驱动两个配套技能来完成制作,就像之前制作影片一样——你永远不需要直接调用它们;run.py 和 qa.py 会处理。规则是绝对的:永远不要编辑配套技能——或其他任何项目(例如 C:\remotion-build\dark-reality-explainer)——来使此技能工作;按它们发布时的原样驱动。所有编排逻辑、缓存、QA 和样式决策都在此技能中。
1. cinematic-film——世界、照片、声音(必需,硬依赖)
位于此技能旁边(可通过 CINEMATIC_SCRIPTS=<指向其脚本目录的路径> 覆盖)。由以下脚本调用:
| 脚本 | 用于 | 为本影片执行的操作 |
|---|---|---|
prep_assets.py | prep 阶段 | 将 Commons 照片分级为黑白外观(`--grade bw |
fetch_commons.py | fetch_photos.py | 下载授权的原始照片(get),填写文件/信用/许可证,并写入 credits.md(credits) |
render.py | render_blocks.py | 使用 --t0/--t1 渲染每个样式块;逐帧绘制白板/照片世界、相机和每个项目 |
engine.py | storyboard.py,每个渲染 | 世界模型:Film、摄像机关键帧、Board、PaperDoc、StylePanel、样条摄像机 |
captions.py | captions_burn.py | 用于给热词计时的字时钟(words_with_times) |
build_sfx.py | audio_finish.py | 从 sfx_cues.json 合成音效总线(无需采样库许可) |
mix_soundtrack.py | audio_finish.py | 语音 + 音效 + 配乐:音效 -19 dB、音乐 -18 dB、4:1 闪避、-15 LUFS / -1.5 dBTP 母带 |
参与规则:不要为此技能编辑它的脚本——行为更改应放在 storyboard.py / render_blocks.py / 本技能中。它的 CLI 契约(--t0/--t1、fetch_commons get|credits、mix_soundtrack --lufs)是生产缓存的哈希依据;如果 cinematic-film 更改了某项,请更新此处的阶段并删除 E:\Storyteller catche files,以便没有过时的缓存命中。
2. remotion-studio——浏览器预览/操控(可选,仅用于审查)
npx remotion studio(打开打印的 URL;或使用 --no-open 并自行打开 URL)。
坦诚的说明,以免浪费时间:Studio 仅预览 Remotion 合成——在 Remotion 项目中注册的 React 组件。它无法播放此技能的完成版母带(out/FILM.mp4 是 skia/ffmpeg 渲染,不是 Remotion 项目;AI 攻击影片也不是)。当交付物也以 Remotion 项目形式存在,并且你希望获得所见即所得的编辑体验(或操控基于 Remotion 的变体)时,请使用它。要审查此技能自身的输出,请使用 out/FILM.mp4 / out/preview_captioned.mp4 以及 out/qa/ 截图——Studio 没有可附加的内容。
制作配方(如同上次一样,三个技能如何完成一部影片)
- 语音 + 剧本 ->
run.py --preview(2 个块,640x360,约 2 分钟)。检查视觉效果、白板/照片节奏、字幕大小和底部对齐,以及qa.py是否报告 PASS。 - 完整计划——导入(whisper 对齐)-> 导演(节拍、布局、样式交替)-> Commons 照片(免费许可证,信用记录在
credits.md)-> 准备(黑白分级)-> 场景 -> 提示。 - 渲染——在 1080p 下单独渲染每个块;通过
E:\Storyteller catche files上的生产缓存复用。 - 完成——拼接(concat 滤镜)-> 底部对齐的霓虹字幕 -> 音效
-19 dB/ 配乐-18 dB,闪避处理,-15 LUFS母带。 - 审查——播放
out/FILM.mp4;out/qa/存放截图。如果需要 Remotion 打包/审查步骤,则用remotion studio打开该 Remotion 项目,并验证其能正常加载。 - 交付——
FILM.mp4+FILM.srt+credits.md。上传/导出在此技能之外完成。
SRT / 分发的副产品
在 qa PASS 之后:out/captioned.srt 位于 out/captioned.mp4 旁(完成步骤可以将其复制到 FILM.mp4 旁边)。对于社交媒体变体(9:16 重新剪辑、平台导出、缩略图制作),请使用分发技能而不是在此技能中重新渲染——此技能仅生成 16:9 母带。
要求
请参阅上面的开始前——自动前置检查:Python 3.8+、numpy、skia-python、Pillow、faster-whisper、ffmpeg/ffprobe 在 PATH 中,以及与该技能位于同一目录下的 cinematic-film 技能(可通过 CINEMATIC_SCRIPTS 覆盖)。该检查在每次运行开始时自动执行。
已知限制
- 默认情况下,对齐使用 whisper tiny.en;含糊的录音可能导致行内漂移。检查
audio/timing.json(会打印弱行警告)或传递--model base.en。 - Commons 搜索匹配文件名/描述;非常具体的查询可能无法命中。不匹配的照片块会回退到卡片,绝不会使用虚构的照片。
- 音乐是循环的,而非重新创作的。如需不同氛围,将任意 mp3 放入项目并传递
--music path.mp3。 - 无口型同步角色、无讲话大头像、无真人实拍:这是一个剧本驱动的动画短片。
参见
references/pipeline.md- 逐阶段内部原理及每个文件的架构references/sound.md- 提示种类、电平、音乐许可references/layout-catalogue.md- 每个布局绘制的内容以及何时强制使用