Reelwright 是做什么的?
Reelwright 只需一段意图描述,即可输出完整的1080p、H.264/AAC 视频:包含书面场景计划、每场景插图、旁白语音、烧录字幕、交叉淡入淡出、慢速 Ken Burns 镜头移动,以及一份确保文件可播放的验证报告。
所有创意内容均来自 Pollinations。唯一本地依赖是 ffmpeg/ffprobe。
适用场景
- “帮我制作一个关于 X 的 60 秒视频。”
- “把这篇文章转化成一个带旁白的幻灯片。”
- “我需要一个配有旁白和字幕的社交媒体短视频。”
- “用五个场景解释 X。”
不适用于:长片编辑、人物访谈、你已有的素材,或任何需要真实摄像机的场景。Reelwright 是一个图解讲解工具,而非视频编辑器。
设置
npx @pollinations/cli auth login # 一次性 Pollinations 登录
npm install # 拉取 ffmpeg-static + ffprobe-static
Reelwright 依次从 --api-key、POLLINATIONS_API_KEY 环境变量,以及 polli auth login 存储在 ~/.pollinations/credentials.json 的登录信息中获取密钥。推荐使用登录方式:用户在浏览器中确认设备代码,密钥不会出现在对话中。在 CI 环境下运行时,可通过环境变量覆盖。
如果 ffmpeg 已在 PATH 中,Reelwright 会直接使用。否则回退到 node_modules 中的静态版本,再之后尝试 $FFMPEG / $FFPROBE 环境变量指定路径。
运行
一条命令,从概要到成品:
python3 skills/reelwright/scripts/reelwright.py make \
--brief examples/salt-road/brief.txt \
--out examples/salt-road \
--scenes 5 \
--transcribe
或者分步执行,当文案质量很重要时,这是更好的方式:
# 1. 规划:文本模型写入标题、副标题、风格和 N 个场景
python3 skills/reelwright/scripts/reelwright.py plan --brief brief.txt --out myreel --scenes 5
# 2. 手动编辑 myreel/project.json(如果某句文案不够好)—— 这是最便宜的修改时机
# 3. 渲染:图片、语音、剪辑、封装
python3 skills/reelwright/scripts/reelwright.py render --project myreel
# 4. 检查:用 ffprobe 验证结果,可选转录音频并与脚本对比
python3 skills/reelwright/scripts/reelwright.py check --project myreel --transcribe
输出文件位于项目目录:
| 文件 | 说明 |
|---|---|
project.json | 规划结果:标题、风格、场景、模型选择。可编辑。 |
images/scNN.jpg | 每场景一张插图,附带 scNN.prompt.txt 包含精确提示词。 |
audio/scNN.mp3 | 每场景旁白。 |
clips/scNN.mp4 | 每场景的静音 Ken Burns 镜头片段。 |
timings.json | 场景开始/结束时间、旁白长度、推导出的场景时长。 |
captions.ass | 标题、副标题、每场景字幕、致谢行。 |
reel.mp4 | 最终交付视频。 |
poster.jpg | 1.2 秒处的帧,用于缩略图。 |
render.json、check.json | 机器可读的渲染和验证报告。 |
时间线工作原理
场景时长不是猜测的:Reelwright 使用 ffprobe 测量每个旁白 MP3 的长度,添加固定的尾部填充时间,然后基于这些数字构建时间线。字幕被写入相同的时间线,因此字幕不会偏离对应的语音。交叉淡入淡出以固定量重叠剪辑,xfade 偏移量根据相同的时长计算。
这是大多数幻灯片生成器出错的地方。如果你更改了 PAD、FADE 或 MIN_SCENE,下游的所有内容都会自动调整。
验证
check 不是主观感受检查。它读取完成的文件,并在以下情况时大声报错:
- 没有视频或音频流;
- 编解码器不是 H.264 / AAC;
- 分辨率不是 1920×1080 或帧率不是 30;
- 实际时长与规划时间线偏差超过 0.8 秒;
- 时间线引用的图像或音频文件缺失;
captions.ass中的对话行数少于场景数;- 使用
--transcribe时:最终音频的语音转文字覆盖率低于脚本词汇量的 80%,这能捕获静音、截断或错误语言的音轨。
最后一项检查最有意思。它是一个廉价的端到端验证,证明 MP4 中的音频确实是你要求的旁白,而不是一个返回 200 OK 但主体为空的内容。
成本与模型
默认设置,所有参数均可通过标志替换:
- 文本:
openai/gpt-5.4-nano— 一次规划调用,如果验证失败则另加一次修复调用 - 图片:
tongyi-mai/z-image-turbo— 每场景一次调用 - 语音:
openai/tts-1,语音onyx— 每场景一次调用
所有默认模型均为免费层级(paid_only: false),包括 --transcribe 背后使用的 openai/whisper-large-v3 转写服务,因此免费账户可以完整运行整个流程。
一个五场景的视频需要五张图片和五段简短视频语音。重新运行 render 会复用磁盘上已有的内容;--force 强制重新生成。--seed 使图片生成可重现。
提示词撰写
提示词是脚本的北极星,需要提供节奏点而不是形容词:
标题:盐之路。
一段 50 秒的微型纪录片,解释为什么海水是咸的。跟随一滴雨水从花岗岩山脉到海洋的旅程。五个节奏点,按顺序:
1. 雨水落在花岗岩山脉上,开始流向山下。
2. 山间溪流切割岩石,携带溶解的矿物质。
3. 河流变宽,携带矿物负荷向大海前进。
4. 太阳加热海水;水蒸气上升,盐分留下。
5. 黄昏时分的盐晶体。
视觉风格:编辑风格的广告水彩插画,柔和的青色与琥珀色色调,纹理冷压纸张,柔和颗粒,电影级宽屏 16:9 构图。
提示词中的风格行比后面的任何提示工程都更有价值:它会逐字带入每个图像提示,这是让五个独立的生成看起来像同一部电影的关键。
值得了解的失败模式
- 来自 Pollinations 的 402 错误 — 密钥关联的账户花粉(pollens)用尽。脚本会直接说明问题,而不是转储 JSON 数据。
image_prompt包含文字 — 模型喜欢写“一张标记有‘蒸发’的地图”。系统提示禁止文字,每个图像提示末尾都添加了“无文字、无字母、无标志”的约束,但修复有缺陷的规划在project.json中比重新渲染更便宜。- 旁白时长超出预期 — 场景会拉伸以配合语音。不会有内容被截断,视频会变长。如果需要严格时长,请减少每场景的字数。
- 没有 ffmpeg — 在仓库中运行
npm install是预期的修复方式。错误消息会同时指明软件包和环境变量。 - 字幕涉及非拉丁文字 — ASS 格式支持 UTF-8,DejaVu Sans 覆盖拉丁、西里尔和希腊字母。对于中日韩或阿拉伯文字,请更改
captions.ass中的字体,并确保它在渲染机器上已安装。