Communitygithub.com

documentary-video

制作YouTube历史纪录片,风格为手工刺绣中世纪挂毯(Bayeux风格)。支持短篇(~2分钟)或长片(分2分钟片段在多天内制作,保存进度)。使用脚本、ElevenLabs旁白、Google Flow免费图片及少量Flow图转视频片段,通过ffmpeg组装并无缝拼接。

documentary-video 是什么?

该技能用于制作YouTube历史纪录片,视觉风格为手工刺绣中世纪挂毯(Bayeux风格)。短片约2分钟,长片按2分钟片段分多天构建,支持保存进度并后续继续。工作流程包括:编写脚本、用ElevenLabs生成旁白、通过Google Flow(免费)生成图片,并为特定场景(每片段中的场景1、2、3、5、8)使用Flow图片转视频生成动画片段,其余场景使用带细微慢速缩放效果的静态图片。所有素材通过ffmpeg组装成1080p视频,长片各片段之间通过静音尾部和画面溶解实现无缝拼接。该技能已在实际项目(如“793:维京时代的开始”纪录片)中验证。支持Claude Code等AI代理平台,需要ElevenLabs MCP和Google Flow访问权限,并依赖`project.py`、`assemble.py`、`timing.py`等脚本管理项目状态和素材生成。

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

在你喜欢的 AI 中提问

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

文档

纪录片视频技能(挂毯风格)

已在"793:维京时代的开始"(doc-test/lindisfarne_793_documentary.mp4)上验证。 每个片段:1920x1080,约2:00,英国旁白,15个场景。场景1、2、3、5和8为真实动态Flow片段;其余场景为带有极慢缩放效果的静态图片。

首先查看参考资料:

  • references/style/:用户的目标外观。哑光米色、石板蓝、苔藓绿、赭色和铁锈色缝线,旋转缝制的云朵和波浪。
  • references/approved-examples/:用户已接受的生成静帧。它们为全帧画面,无边框,无白色边距。
  • references/avoid/:用户拒绝的内容:
    1. 画面四周的布边或白色边距。
    2. 底部装饰性动物饰带边框。

用户规则(重要)

  • 如果一条消息同时包含提问和任务,先回答问题并等待,然后再花费任何额度。
  • 只有用户自己的话才算指令。请节约额度,不做任何未请求的额外工作,并简要报告。
  • 动画模式: 对每个片段的场景1、2、3,然后5,然后8使用真实的Flow图片转视频动画。即5个片段,每个片段约120额度。其余每个场景使用带有极小慢速缩放(约3%,交替放大和缩小)的图片。assemble.py会自动处理。
    • 切勿将缩放的图片呈现为“视频”。真实片段必须来自Flow。
    • 在提交前告知成本(每个片段24额度)。如果用户选择不同的场景集,使用project.py decide记录。
  • 每个视频一个Flow项目。 创建一次并始终传递其id。切勿每次调用都使用--project-name,因为这会每次都创建一个新项目。
  • 用户经常中断。中断后,先检查哪些任务仍在运行或已计费,然后再做其他事情。

长片:按2分钟片段构建,跨多天完成

一个8分钟视频分为约2分钟的4个片段,一次制作一个片段。每个片段经历两次审核:

  1. 免费草稿审核。
  2. 花费额度后的最终审核。

所有状态保存在项目文件夹中,因此新会话可以随时继续。

在现有视频上开始会话:

  1. 读取 <project>/PROGRESS.md。
  2. 运行 python3 scripts/project.py status <project>。它会打印决策、每个片段的状态和NEXT(下一步操作)。
  3. 从NEXT继续。切勿重做已完成片段,也切勿在未经用户同意的情况下更改决策(语音、风格、Flow项目、模式)。

项目布局(使用 project.py new doc-test/videos --title "..." --minutes 8 创建):

doc-test/videos/<slug>/
  project.json      决策(voice_id, style, flow_project_id, animation_pattern, zoom...)+ 每个片段的状态/额度
  PROGRESS.md       每个步骤和决策的带日期日志 - 通过project.py追加,切勿重写
  outline.md        整个视频大纲 + 每个片段:封面 / 开场白 / 结尾过渡语
  parts/partNN/     scenes.json, voiceover.mp3, timing.json, images/, clips/, draft.mp4, partNN.mp4
  final/<slug>_full.mp4

片段状态流转: planned → script_review → draft_review → final_review → final。使用 project.py set <project> <n> <status> --note "..." [--credits N] 设置每个状态。

每个片段:

  1. 脚本(片段1还需先填写整个视频的outline.md)。
    • 使用 templates/scenes.example.json 作为模板,编写 parts/partNN/scenes.json。保持 style 字符串来自 project.json。
    • 第一个场景必须承接上一片段的结尾语。最后一行过渡到下一个片段。
    • 视觉上,片段N的最后一个场景和片段N+1的第一个场景应共享场景设置和色调,使它们之间的溶解过渡显得自然。
    • 将脚本发送给用户,然后运行 set ... script_review。
  2. 用户批准脚本后,一口气完成整个片段:
    • 生成旁白(步骤A)和时间信息(步骤D),然后生成图片(步骤B;通常用户从 image_prompts.txt 生成)。
    • 在Flow中为模式场景1、2、3、5和8制作动画(步骤C)。用户期望在他们审核的第一个版本中看到真实片段。
    • 运行 assemble.py parts/partNN 生成1080p的 partNN.mp4。
    • 将完整路径发送给用户,并用 xdg-open 打开。
    • 然后运行 set ... final_review --credits <spent>。
    • 切勿发送仅由缩放图片组成的草稿作为“视频”。--draft 仅用于快速私下检查。
  3. (draft_review 状态是可选的。除非用户要求先看廉价预览,否则跳过。)
  4. 用户批准最终渲染后: 运行 set ... final。
  5. 所有片段均为最终状态后: 运行 python3 scripts/join_parts.py <project>,它会写入 final/<slug>_full.mp4。然后抽查每个拼接点(音频和画面)。

为什么拼接平滑(不要破坏这一点):

  • assemble.py 渲染每个片段时使用相同的格式:1920x1080,30 fps,yuv420p,AAC 48 kHz立体声,旁白响度归一化至-16 LUFS。
  • 每个片段还有相同的边缘:第一个词前0.4秒画面,最后一个词后1.2秒静默画面。
  • join_parts.py 在静默尾部的1秒内溶解画面,并在静默中剪切音频,因此没有词语重叠,音量水平不会跳跃。
  • 已验证:拼接间隙为0.84秒,与正常段落停顿相同,两侧响度分别为-16.4和-16.5 LUFS。
  • 始终为每个片段使用相同的 voice_id 和 tts_model,如 project.json 中所记录。

制作步骤(在每个片段内部使用)

A. 旁白(ElevenLabs MCP)

  1. 调用 creative_generate_speech,参数如下:
    • model_id:项目的 tts_model,如 eleven_v4
    • voice_id:项目的 voice_id,如 QngvLQR8bsLR5bzoa6Vv(“Michael Dan – 英国纪录片旁白”)
    • prompt:该片段的旁白文本,用空行分隔
  2. 轮询 creative_get_flow_run_status 直至完成。它会返回2个录音版本,每个约1650 ElevenLabs额度(≈$0.30)。
  3. 使用 curl 从 content_url 下载版本1到 parts/partNN/voiceover.mp3。

将年份写为单词,例如“seven ninety-three”,以便旁白正确朗读。

B. 图片(免费) - 用户通常用自己的浏览器扩展生成

图片仅通过文本提示(风格字符串 + 场景)生成。不传递参考图片:gflow 在此账号上拒绝参考图片,参考文件夹仅用于目视检查结果。

首选(用户的扩展): 先做旁白和 timing.py,这样就知道场景时间,然后写入 parts/partNN/image_prompts.txt 并将该路径交给用户。格式为每个场景一个提示,然后一个空行:

[0.00-0.06] <style>. Scene: <image>. IMPORTANT: do not write the time, any numbers, any label or any text anywhere in the image.

[0.06-0.14] ...
  • 时间来自 timing.json 的 m.ss 格式。
  • 用户将文件传递给扩展,并返回一个文件夹,例如 ~/Downloads/zapi-img-doc/。其中包含名为 NN_[mss-mss]_....webp 的文件,有时会有 _1/_2 版本。
  • 在带标签的接触片上检查每张图片。查找布边或条纹、边距、边框、多余文字、错误主题或风格不匹配。选择最佳版本并转换为 parts/partNN/images/sceneNN.jpg。
  • 仅使用 gflow(免费)重新生成有问题的图片,并告知用户哪些图片以及原因。

备用方案(gflow MCP):

  1. 运行 gflow_generate_image,参数为 prompt "<style>. Scene: <image>.",aspect "16:9",model nano2 和 project <flow_project_id>。
  2. 对于新视频的第一张图片,省略 project 并传递 project_name。然后运行 project.py decide <p> flow_project_id <id>。
  3. 将文件从 ~/Downloads/gflow-cli/images/<date>/<media>_1.jpg 复制到 parts/partNN/images/sceneNN.jpg。

接触片: ffmpeg -pattern_type glob -i 'images/scene*.jpg' -vf "scale=344:192,tile=5x3" -frames:v 1 contact.jpg

C. 为模式场景制作动画(Flow网站,消耗额度)

在此账号上,gflow 的 i2v 被拒绝:Flow向其提供“仅代理作曲家”(gflow issue #799)。拒绝不产生费用。请改用网站。Flow 布局在2026年11月已更改:不再有代理聊天或审批步骤。

如果用户也想自己制作片段,请以相同的 [m.ss-m.ss] prompt 格式写入 parts/partNN/video_prompts.txt。使用“精确动画化此图像...”文本加上场景的 motion,每个动画场景一条,并列出每个场景对应的 sceneNN.jpg。

  1. 使用 gflow_get_credits 检查额度。不产生费用。
  2. 运行 scripts/launch_flow_chrome.sh "https://flow.google.com/project/<id>"。
  3. 运行 ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_animate.py --project <id> --part parts/partNN --upload --prefix <short>_pN_ 1 2 3 5 8。
    • --upload 将场景图片上传到Flow项目。当用户的扩展生成图片时需要。
    • 它将作曲家切换到 视频 → 帧 → x1,因此片段从精确图像开始。这是 Omni 1.2 Flash,720p,8秒,每个片段24额度。
    • 它选择每个起始帧,输入运动提示,提交并等待。
    • 切勿在作曲家处于图像/Nano Banana模式时提交。 那会生成2张图片,而不是视频。它们是免费的,但不会有动画。
  4. 运行 ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_download.py --project <id> --part parts/partNN 1 2 3 5 8。
    • 它下载最新的视频(原始大小)并根据其第一帧与场景图像的匹配情况,将每个文件命名为 clips/sceneNN.mp4。
    • 正确场景的匹配距离应约为4,其他场景大于30。
  5. 检查每个片段的帧:相同的挂毯外观,无文字。
  6. 使用 CDP Browser.close 关闭 CDP Chrome 窗口。gflow MCP 调用在它持有配置文件时失败。
  7. 再次检查额度。减少量应恰好为 24 × 片段数量。

D. 时间信息和组装

  1. python3 scripts/timing.py parts/partNN:将场景边界对齐到旁白中的段落停顿。检查打印的持续时间。任何低于5秒或超过11秒的都是错误对齐,需手动在 timing.json 中修复。
  2. python3 scripts/assemble.py parts/partNN --draft 制作审核副本。不带 --draft 则制作最终渲染版。
  3. 发送前抽查帧。

E. YouTube标题

保持在60个字符以内,将亮点放在前面,并包含年份。例如:“The Day the Viking Age Began (793 AD)”。提供3-5个选项以及一个包含2-3个单词文字的缩略图想法。

环境注意事项/陷阱

  • gflow MCP: 通过 ~/.local/bin/gflow-clean 注册(scripts/gflow-clean 中的副本)。该包装器会剥离VS Code快照GTK/GIO环境变量。没有它,Chrome启动时崩溃,gflow 会误报为“配置文件已锁定”。
  • 账户: gflow 配置文件是 sajeel135。图片生成免费;视频消耗额度。
  • Chrome 必须使用 --password-store=basic: 在 gflow 配置文件上打开的任何 Chrome 都需要 --password-store=basic,launch_flow_chrome.sh 现在已设置。没有它,Chrome 会使用系统密钥环重新加密cookie。gflow 无法读取它们,并会跳转到 flow.google.com/about(退出代码31),用户必须重新登录。
    • 当Flow显示 /about 但Google已登录时,打开CDP窗口,点击“Create with Google Flow”,让用户完成任何登录,然后使用 CDP Browser.close 干净地关闭。
  • 陈旧锁定: 删除 ~/.local/share/gflow-cli/profile_sajeel135/ 中的陈旧 Singleton* 锁定文件,但仅当没有Chrome正在使用该配置文件时(launch_flow_chrome.sh 会执行此操作)。
  • 停止进程: 不要从命令本身也包含该名称的shell中运行 pkill -f <name>,因为它会杀死自己。改用PID杀死。
  • 长时间渲染: 最终片段渲染需要几分钟。如果工具调用可能超时,则在后台运行长时间渲染。

相关技能