纪录片视频
用户提供一个主题。你交付一部完整的影片:out/<slug>.mp4(1920×1080,H.264/AAC),附带 .srt、CREDITS.md、脚本和来源。用户无需自行安装、研究、写作或渲染任何内容。仅在以下情况下才停下来等待用户决策:需要付费生成、需要权限才能下载的内容,或无法核实的事实主张。
SKILL_DIR 是该文件夹。DOC 指代 python3 "$SKILL_DIR/scripts/doc.py"。
1. 下笔前先定框架
最多问两个问题,并且仅在它们会影响影片时才问:时长(默认为3分钟)和论点(影片要论证什么,而不仅仅是主题)。其他一切由你决定。
纪录片是用画面论证观点的叙述,而非摘要。选择一个观众看完后能复述的主张——例如“守灯塔的人不是输给了科技,而是输给了一张电子表格”——并删掉所有不服务于该主张的内容。
永远不要罗列事实。要拍摄一种变化:曾经是那样,然后不再如此,以及为此付出的代价。
2. 环境搭建(仅首次运行)
DOC doctor
需要 python3 和带有 libx264 的 ffmpeg。Termux 用户:pkg install ffmpeg。macOS 用户:brew install ffmpeg。如果仅仅缺少 ffmpeg,请安装它并重新运行。在 doctor 输出“Ready”之前,不要写其他任何内容。
DOC new <project> --title "最后的守灯人" --subtitle "1985 – 1997"
这将创建 project.json、shots.json、research.md、script.md,以及 work/img、work/audio、out 目录。
3. 调研
使用网络搜索。目标是四到六个可靠来源:原始文献、档案馆、大学或机构页面、有信誉的新闻报道、一本书。要读透,能解释机制,而不仅仅是结果。
保存到 research.md:
# 调研
## 论点
影片所论证的一句话。
## 事实(每个事实附带来源)
- 1841年:<事实> – <来源URL>
- <年份>:<事实> – <来源URL>
## 有争议 / 未知
- <各来源存在分歧的内容以及影片将如何表述>
## 视觉素材
- <档案、馆藏、可能为公有领域的图片搜索>
旁白中的每一句话都必须能对应到这里的某一行。如果两个来源相互矛盾,要么在画面上说明,要么放弃该事实。禁止编造任何数字、日期、引语或轶事。 缺少事实是情节问题;编造事实是欺诈。
4. 撰写脚本
动笔前请先阅读 references/script-craft.md。摘要如下:
- 每分钟155词。 3分钟约460词。按幕分配预算,而非凭感觉。
- 四个段落: 之前的世界(钩子)、机制(变化是如何发生的)、代价(对人们造成了什么影响)、回响(回到钩子,但已改变)。
- 每句一个想法。 每行一口气。句子不超过22词。
- 具体胜过抽象。 “他每晚两次爬117级台阶”比“这份工作很辛苦”更好。
- 故事用现在时,结论用过去时。
- 旁白承载论证;字幕承载证据(姓名、日期、地点)。绝不在声音轨道上说出字幕已经证明的内容。
将脚本按幕写入 script.md,每句一行,因为 shots.json 中的行必须逐字匹配:
## 第一幕 – 之前的世界
两百年来,必须有人保持清醒,船只才能找到海岸。
...
然后在一则消息中向用户展示整个脚本——大约30行——并继续。除非用户要求审阅,否则无需等待批准。
5. 分镜头列表
阅读 references/shot-list.md 了解每个字段及完整示例,然后编写 shots.json:
{"shots": [
{"id": "s01", "kind": "card", "text": "最后的守灯人",
"sub": "一份在十二年内消失的工作", "hold": 4.0},
{"id": "s02", "line": "两百年来,必须有人保持清醒。",
"img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
"caption": "拜伦角灯塔,1891年"}
]}
重要规则:
line为旁白,必须按顺序逐字来自脚本。 时长由音频决定,因此改动的行会影响剪辑。- 每个镜头3.5 – 6秒。 静态图片需要比你想象的更长时长。除非有意的闪切,否则不得少于2.5秒。
- 一个画面一个想法。 如果一个镜头需要两张图片,那就拆成两个镜头。
- 移动镜头,而非移动世界。
zoom-in用于营造亲密感,zoom-out用于展示后果,pan-*用于风景和文档,static用于面孔和文字。 - 卡片代表章节切换。 在3分钟影片中使用2-4张卡片:标题卡、日期/数字卡、以及最后的落点卡。卡片没有旁白。
caption是画面上的小字证据行:地点、年份、来源。保持在6词以内。
6. 静态图片
优先使用真实的档案素材。这是纪录片与幻灯片之间的区别。
DOC archive <project> --query "拜伦角灯塔 1900年" --n 3
该命令搜索维基共享资源,将可用图片下载到 work/img/,并写入 sources.json 和 CREDITS.md(包含作者和许可证信息)。默认情况下仅保留公有领域、CC0 和 CC BY / BY-SA 图片,因为发布的影片通常需要商业使用权。添加 --license pd 以严格限制公有领域,--license any 则查看所有内容(然后自行检查每张的许可证)。
如果档案中没有找到,按以下优先级:
- 其他开放馆藏 —— 美国国会图书馆、史密森尼开放获取、NASA、互联网档案、Europeana。在从新网站下载前先询问用户,并在
CREDITS.md中记录许可证和URL。 - 使用任何可用的图片工具生成图像,参考
references/image-prompts.md。在CREDITS.md中将生成的帧标记为 AI生成的重建,并在字幕中说明,避免观众误认为是照片。 - 字体和物体镜头 —— 一份文件、一张地图、一本日志的某一页、一块抽象图板。诚实且低成本。
永远不要将AI生成的图像当作档案照片。这一句话便是整个格式的伦理底线。
7. 配音
DOC tts <project>
当设置了 ELEVENLABS_API_KEY 时使用 ElevenLabs(效果最佳),否则使用离线语音(espeak-ng、Android 的 termux-tts-speak、macOS 的 say)。一次录制完成。为听觉而写:短句、避免绕口令、按实际发音拼写数字。
如果根本没有语音,影片仍会使用估算时间渲染——请告知用户,并交付 .srt 文件,以便用户之后自行录制旁白。保持 line 不变,以便重新录制时可直接替换。
录音质量优于模型质量:在安静房间用手机录音,对大多数纪录片而言也比合成声音更好。请主动提供该选项。
8. 构建并观看
DOC build <project> --draft # 迭代时的快速预览
DOC build <project> --subs # 最终版,字幕嵌入
DOC sheet <project> # 12帧联系表
每次都要查看 out/contact.jpg。 检查:
- 任何重要部分没有被字幕遮挡,且字幕没有跑出画面;
- 剪辑点落在句子结尾处,且没有任何镜头停留在图片的空白或无关部分;
- 调色一致,人脸没有过度压缩,文字图片可读;
- 最后一张卡片在旁白结束后出现,而非叠加在上面。
通过编辑 shots.json(图像、运动、字幕、顺序)并重新构建来修正。内部片段按镜头ID缓存,因此只有更改的镜头会重新渲染。
速度。 渲染为CPU密集型。在笔记本上,1080p的三分钟影片大约需要一分钟,在手机上则需10-20分钟。始终先使用 --draft(半分辨率、快速预设)进行迭代,最后再做一次完整渲染。build 会逐个打印镜头,因此你可以停止明显有问题的渲染。
9. 音乐
在添加音乐前先询问用户。建议一个来源,检查许可证,将文件放到 public/music/bed.mp3,然后:
DOC build <project> --music public/music/bed.mp3
音乐循环播放,音量约为14%,并在语音下方自动降低音量。沉默也是一种合理的选择,对于严肃题材的影片通常更好。
10. 交付
向用户提供:
- MP4文件;
.srt文件(在YouTube上也有用);CREDITS.md—— 每张图片、作者、许可证、链接;- 脚本、关于论点的段落,以及3-5个来源链接;
- 一份直接说明:哪些是档案素材、哪些是生成的、哪些因缺乏证据而被剪掉。
然后提供一个下一步:制作更长的版本、不同的开场、第二幕,或者将同一部影片剪成60秒的竖版。
良好的判断力
- 影片是论证,而非镜头。 如果画面很漂亮但论点模糊,就重写。
- 删掉第三个例子。 两个例子证明一个模式;三个例子就是列表。
- 在画面上标注来源,而不仅仅在描述中。 带有年份和地点的字幕能让观众信任其余部分。
- 承认你不知道的内容。 “没有人同意具体数字”比一个自信但错误的数字更有力。
- 尊重逝者。 真实人物、真实事件:禁止虚构对话、禁止将重演当作记录呈现、禁止为具名人物生成人脸。
- 时长是一种承诺。 如果素材只能支撑90秒,那就交付90秒。
文件
scripts/doc.py—— 整个流水线(DOC -h查看所有参数)。references/script-craft.md—— 如何写出像电影一样的旁白。references/shot-list.md—— 完整的shots.json模式及示例。references/sourcing.md—— 档案、许可证规则、署名格式。references/image-prompts.md—— 用于生成能与档案素材匹配的静态图片的提示词。examples/last-lightkeeper/—— 一个完整的3镜头示例(脚本+镜头列表)。