Communitygithub.com

纪录片视频技能

将任何话题转化为一部完整的短纪录片——包括调研、事实核查过的旁白脚本、配音、带来源的档案图片、字幕、致谢、背景音乐以及由FFmpeg渲染的MP4影片。每当有人要求制作纪录片、微型纪录片、视频论文、历史或科学短片、档案风格影片、带解说的讲解片,或者说“制作一个关于……的视频”并希望使用真实素材而非幻灯片时,均可使用。

纪录片视频技能 是什么?

该技能旨在将用户提供的任何主题自动转化为一部完整的短纪录片,输出为1920x1080、H.264/AAC编码的MP4文件,同时生成SRT字幕文件、CREDITS.md致谢文件以及完整的脚本和来源记录。它集成了调研、脚本撰写、档案图片采集、语音合成、视频渲染等全流程,用户无需自行安装、研究、写作或渲染任何内容,只需要在必要时做出关键决策(如是否使用付费生成或下载需权限的资源)。该技能支持多种平台(如macOS、Linux、Termux),依赖python3和ffmpeg,并提供“doctor”命令进行环境检查。其核心工作流程包括:先通过至多两个问题确定影片长度和论点角度,然后进行在线调研并保存到research.md,接着按照严格的字数限制和叙事结构撰写脚本,再基于脚本生成逐镜头的shots.json文件,并优先从维基共享等开放档案中下载真实影像素材(如不足可生成AI图像但必须明确标注),最后使用TTS生成旁白并组装成片。整个过程强调事实准确性和伦理规范,禁止编造数据、日期或引语,AI生成图像不得冒充档案照片,且影片本身必须是带有论点的叙述而非事实罗列。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

纪录片视频

用户提供一个主题。你交付一部完整的影片: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 则查看所有内容(然后自行检查每张的许可证)。

如果档案中没有找到,按以下优先级:

  1. 其他开放馆藏 —— 美国国会图书馆、史密森尼开放获取、NASA、互联网档案、Europeana。在从新网站下载前先询问用户,并在 CREDITS.md 中记录许可证和URL。
  2. 使用任何可用的图片工具生成图像,参考 references/image-prompts.md。在 CREDITS.md 中将生成的帧标记为 AI生成的重建,并在字幕中说明,避免观众误认为是照片。
  3. 字体和物体镜头 —— 一份文件、一张地图、一本日志的某一页、一块抽象图板。诚实且低成本。

永远不要将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镜头示例(脚本+镜头列表)。

相关技能