Book Video Generator

三分钟精读一本书 视频生成器

概述

将任意书籍自动生成一个 3 分钟解说视频：从书评文案撰写、分镜生成、AI 插图、TTS 配音到字幕合成，全流程自动化。

源于扣子工作流 "Pipadushuvideo1"，本 Skill 遵循 Agent Skills 开放标准，跨平台兼容 WorkBuddy、OpenClaw、Codex CLI、TRAE Work。

使用本地开源工具替代扣子插件：剪映小助手 → ffmpeg，扣子图像生成 → 多模型图像生成（默认 ImageGen + 备选火山即梦/Gemini/Agnes），扣子 TTS → 火山引擎 TTS（默认，1.2x 语速）/ edge-tts（备选）。v2.8.0 新增火山即梦/Gemini/Agnes 三种图像生成备选方案，用户可通过环境变量 IMAGE_API 切换。v2.7.0 新增背景音乐、转场音效、字幕入场/出场动画，移除画面缩放。

平台工具映射

本 Skill 的工作流涉及 3 个平台相关工具，各平台替代方案如下。执行时根据当前运行平台选择对应工具。

联网搜索（阶段 1 用于搜索书籍信息）

| 平台 | 工具 | 说明 | |------|------|------| | WorkBuddy | WebSearch | 内置工具，直接调用 | | OpenClaw | 内置 web search | 自动可用 | | Codex CLI | shell: curl 或 MCP 搜索插件 | 通过 shell 命令或安装搜索 MCP | | TRAE Work | 内置联网搜索 | 自动可用 |

图像生成（阶段 4a 用于生成分镜插图）

提供了 1 个默认 + 3 个备选 图像生成方案，用户可通过环境变量 IMAGE_API 切换：

| 方案 | 工具 | 模型 | 环境变量 | 说明 | |------|------|------|----------|------| | 🏠 默认 | ImageGen | 腾讯混元（WorkBuddy 内置） | 无需配置 | 在 WorkBuddy 中直接调用 DeferExecuteTool | | 🏔️ 备选 | volcengine | 火山引擎即梦 Seedream 5.0 lite（字节跳动） | ARK_API_KEY（推荐）或 VOLCENGINE_AK + VOLCENGINE_SK | 原扣子工作流用的字节生图，中文扁平风最优，支持去水印。使用前需在火山方舟控制台开通模型。已开通: 5.0 Pro / 5.0 lite / 4.5 / 4.0，默认 5.0 lite（doubao-seedream-5-0-260128） | | 🤖 备选 | gemini | Google Gemini 3 Pro Image | GEMINI_API_KEY | 细节丰富，语义理解强 | | ✨ 备选 | agnes | Agnes AI（完全免费） | AGNES_API_KEY | 免费注册获取，OpenAI 兼容接口 |

切换方式：

• WorkBuddy：默认使用 ImageGen。如需切换，设置 IMAGE_API=volcengine|gemini|agnes 后，脚本自动调用 scripts/generate_image.py 而非 ImageGen
• CLI 平台（Codex CLI / OpenClaw）：直接运行 scripts/generate_image.py --api

```bash # 单张生成 python3 scripts/generateimage.py --prompt "" --output "scene000.png" --api volcengine

# 批量生成（从 storyboard.json） python3 scripts/generate_image.py --batch storyboard.json --output-dir images/ --api gemini ```

> 无论使用哪个平台，图像生成的 prompt 统一使用分镜中的 desc_promopt 字段。

LLM 调用（阶段 1-3 用于生成文案和分镜）

所有平台均内置 LLM 对话能力，直接将 references/prompts.md 中的 System Prompt 发送给当前平台的 LLM 即可。

输入

| 参数 | 说明 | 必填 | |------|------|------| | book_name | 书籍名称 | 是 | | author_name | 作者名称 | 是 | | ip_name | 账号名称（用于封面图底部水印） | 否，默认不显示 |

环境准备

执行前确保以下 Python 依赖已安装：

pip install edge-tts imageio-ffmpeg pillow

> 脚本会在首次运行时自动安装缺失的依赖，但建议预先安装以避免中断。

ffmpeg 由 imageio-ffmpeg 包自动提供二进制，无需单独安装系统级 ffmpeg。

TTS 引擎配置（可选）

| 引擎 | 凭证 | 时间戳 | 说明 | |------|------|--------|------| | 火山引擎 TTS（默认） | VOLC_TTS_API_KEY | 基于音频时长估算 | 豆包语音合成 2.0，中文自然度最高，1.2x 语速（匹配扣子工作流），可商用，需在火山引擎控制台获取 API Key | | edge-tts（备选） | 无需配置 | WordBoundary 原生精确 | 微软免费 TTS，pip 安装即用，无凭证时自动回退 |

设置火山引擎凭证：

export VOLC_TTS_API_KEY="your-api-key"

> 未设置火山引擎凭证时，脚本自动使用 edge-tts，功能完整不受影响。 > 火山引擎 TTS 2.0 不原生支持词级时间戳，脚本基于返回的音频时长按字符均匀估算时间戳（标点符号占比较短时间），字幕同步精度略低于 edge-tts 但完全可用。

完整工作流（5 个阶段）

阶段 1：生成书评文案

目标：根据书名+作者，用 LLM 生成约 1000 字的 3 分钟视频文案。

操作：

1. 用当前平台的联网搜索工具搜索书籍真实信息（简介、解读、出版年份）
2. 使用 system prompt（见 references/prompts.md 第 1 节），要求 LLM 输出 JSON：

{
  "book_name": "...",
  "author_name": "...",
  "year": "yyyy-MM",
  "content": "1000+字书评文案（含开篇引言+核心内容+观点提炼）",
  "category": "图书分类"
}

要点：

• 文案需满足约 3 分钟口播时长（约 700-1000 字）
• 开篇引言必须极具吸引力
• 信息来源需通过搜索获取，确保内容准确

阶段 2：生成分镜脚本

目标：将书评文案拆分为 8-50 个分镜，每个分镜包含字幕文案、画面描述、AI 图像提示词。

操作： 使用 system prompt（见 references/prompts.md 第 2 节），输入阶段 1 的 content，输出：

{
  "list": [
    {
      "story_name": "分镜名称",
      "desc": "画面描述",
      "cap": "字幕文案（一句话）",
      "desc_promopt": "图像生成提示词"
    }
  ],
  "keywords": ["重点词1", "重点词2"]
}

然后在 list 开头插入引言分镜（模仿原工作流 node 150774 的逻辑）：

list.insert(0, {
    "story_name": "引言",
    "desc": "每日精读一本书",
    "cap": f"3分钟精读一本书，今天我们读《{book_name}》",
    "desc_promopt": "每日精读一本书"
})

风格约束：扁平插画风，人物卡通风简洁线条，背景扁平化符号，柔和明亮低饱和度色调。

阶段 3：生成标题进度条

目标：根据文案内容划分为 4 个板块，每板块 6 字以内标题，用于视频顶部进度条显示。

操作： 使用 system prompt（见 references/prompts.md 第 3 节），输出 4 个标题（title1-title4）。

使用方式：4 个标题通过 segments.json 的 chapter_titles 字段传入 compose_video.py，在视频顶部渲染为进度条（当前板块橙色高亮 + 底部进度线）。同时需要 segment_chapters 字段指定每个分镜所属的板块索引（0-3），未指定时自动均匀分配。

阶段 4：生成素材（并行）

本阶段生成视频所需的全部素材：

4a. AI 插图生成

对每个分镜的 desc_promopt，调用图像生成工具生成插图。默认使用 WorkBuddy 内置的 ImageGen（腾讯混元模型），可通过环境变量 IMAGE_API 切换到备选方案。

统一风格参数（原工作流图像生成节点配置）：

• 尺寸：1024x768
• 风格：扁平风（flat illustration）
• 主角上衣 #FF7F72，裤子 #243139
• 30% 透明玻璃效果背景
• 负向提示词：无

方案选择与调用方式：

| 方案 | IMAGE_API 值 | 调用方式 | 需要配置 | |------|----------------|----------|---------| | 🏠 腾讯混元（默认） | 不设置或 imagegen | WorkBuddy 内置 ImageGen 工具 | 无 | | 🏔️ 火山即梦 | volcengine | python3 scripts/generate_image.py --api volcengine | ARK_API_KEY（推荐）或 VOLCENGINE_AK + VOLCENGINE_SK。默认用 Seedream 5.0 lite（doubao-seedream-5-0-260128），可通过 VOLCENGINE_MODEL 切换。5.0 lite 最小 2K 分辨率，代码自动升级 | | 🤖 Google Gemini | gemini | python3 scripts/generate_image.py --api gemini | GEMINI_API_KEY | | ✨ Agnes AI | agnes | python3 scripts/generate_image.py --api agnes | AGNES_API_KEY |

执行逻辑：

1. 如果运行在 WorkBuddy 且未设置 IMAGE_API：直接调用 ImageGen 工具（DeferExecuteTool），参数 prompt = desc_promopt，size = "1024x768"
2. 如果设置了 IMAGE_API=volcengine|gemini|agnes：调用 scripts/generate_image.py 脚本，自动安装依赖并通过 API 生成
3. 如果运行在 CLI 平台（Codex CLI 等）：默认调用 scripts/generate_image.py --api gemini

> 生成的图片统一命名为 scene_000.png ~ scene_NNN.png，存放到 output/{book_name}/images/ 目录。

4b. TTS 语音合成

对每个分镜的 cap（字幕文案），使用 TTS 引擎生成 MP3 音频，同时生成词级时间戳（保存为同名 .words.json 文件，用于阶段 5 的逐句字幕精确同步）。

双引擎架构：

• 火山引擎 TTS（默认）：V1 API + X-Api-Key 认证，豆包语音合成 2.0 音色，中文自然度最高，可商用，需设置环境变量 VOLC_TTS_API_KEY
• edge-tts（备选）：免费无需配置，原生 WordBoundary 词级时间戳，未设置火山引擎凭证时自动回退

默认音色：

• 火山引擎：zh_female_zhixingnv_uranus_bigtts（知性女声 2.0，适合读书解说）
• edge-tts：zh-CN-XiaoxiaoNeural（晓晓，女声）

查看所有可用音色：python3 scripts/generate_audio.py --list-voices

运行（所有平台通用，自动选择引擎）：

python3 scripts/generate_audio.py --text "" --output "audio_001.mp3"

指定引擎或音色：

# 强制使用火山引擎
python3 scripts/generate_audio.py --text "" --output "audio_001.mp3" --engine volcano --voice zh_female_zhixingnv_uranus_bigtts

# 强制使用 edge-tts
python3 scripts/generate_audio.py --text "" --output "audio_001.mp3" --engine edge --voice zh-CN-XiaoxiaoNeural

批量模式：

python3 scripts/generate_audio.py --batch captions.json --output-dir audio/ --voice "zh_female_zhixingnv_uranus_bigtts"

4c. 开场封面图

为视频第一帧生成专属封面图（1920x1080），包含书名、作者、品牌文字。

操作：运行 python3 scripts/generate_cover.py

# 用第一张分镜图做模糊背景（推荐，与视频风格一致）
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png \
  --bg output/原子习惯/images/scene_000.png

# 无背景图，使用深蓝渐变
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png

封面布局：

• 顶部：「3 分钟精读一本书」品牌文字 + 橙色分隔线（#FF7F72，与分镜主角上衣同色）
• 中部：书名大字（自动换行居中，80pt）
• 中下：作者名（42pt）
• 底部：账号名称水印（可选，通过 --ip-name 指定，不传则不显示）

字体：自动检测系统中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK），无需手动修改。

> 封面图在阶段 5 合成时，通过 segments.json 中的 cover 字段指定，会在第一分镜前 cover_duration 秒（默认5秒）显示封面图，之后切换回原始分镜图（旁白全程不中断）。 > > ``json > { > "output": "output/书名_三分钟精读书.mp4", > "cover": "output/书名/images/cover.png", > "chapter_titles": ["开篇引言", "核心方法", "实践技巧", "总结"], > "segment_chapters": [0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3], > "keywords": ["原子习惯", "微小改变", "复利效应"], > "bgm": "assets/bgm_reading.mp3", > "bgm_volume": 0.15, > "transition_sound": "assets/transition_page_flip.mp3", > "transition_interval": 3, > "transition_volume": 0.3, > "segments": [ > {"image": "images/scene_000.png", "audio": "audio/audio_000.mp3", "caption": "字幕文本"}, > ... > ] > } > ` > - cover：可选，封面图路径，在第一分镜前 coverduration 秒显示，之后切回原始分镜图 > - coverduration：可选，封面显示时长（秒），默认 5.0，仅作用于第一分镜前半段 > - chaptertitles：可选，板块标题列表，用于顶部进度条显示 > - segmentchapters：可选，每个分镜所属板块索引（0-based），未提供时自动均匀分配 > - keywords：可选，关键词列表，字幕中匹配到的关键词显示为橙色高亮 > - bgm：可选，背景音乐路径，未提供时自动查找 assets/bgmreading.mp3，传空字符串禁用 > - bgmvolume：可选，BGM 音量 (0.0-1.0)，默认 0.15 > - transitionsound：可选，转场音效路径，未提供时自动查找 assets/transitionpageflip.mp3，传空字符串禁用 > - transitioninterval：可选，每 N 个分镜添加一次转场音效，默认 3 > - transition_volume`：可选，转场音效音量 (0.0-1.0)，默认 0.3

阶段 5：视频合成

目标：将所有素材合成为最终 MP4 视频。

操作：运行 python3 scripts/compose_video.py，该脚本执行：

1. 计算每个分镜时长（基于 TTS 音频时长 + gap 间隔）
2. 图片缩放/裁剪为 1920x1080（16:9）
3. 为每个分镜添加 0.3s 淡入淡出转场（dip-to-black）
4. 使用 ffmpeg 将图片+音频合成为视频片段
5. 进度条 overlay：顶部显示板块标题（当前板块橙色高亮+实心圆点，其余灰色+空心圆点），底部进度线显示总体播放进度
6. 生成逐句单行 ASS 字幕（基于 TTS 词级时间戳精确同步语音，按标点+字数拆分为单行短句，白色加粗文字+黑色描边，关键词橙色高亮，入场淡入+上滑/出场淡出动画）
7. 拼接所有片段为完整视频
8. 混音：将背景音乐（BGM）以低音量全程混合 + 每 3 个分镜在边界处叠加转场翻页音效

字幕参数（对应原工作流 addcaptions1 节点）：

• 字体颜色：白色 (#FFFFFF)
• 关键词高亮：橙色 (#FF7F72)，通过 ASS 内联颜色标签 {\c&H727FFF&} 实现
• 边框颜色：黑色 (#000000)
• 字号：64pt（加粗）
• 位置：底部居中（MarginV=30）
• 字体：自动检测系统可用中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK SC），无需手动修改
• 字幕格式：ASS（Advanced SubStation Alpha），支持行内颜色标签+动画标签
• 逐句单行显示：利用 TTS 词级时间戳（火山引擎基于音频时长估算 / edge-tts WordBoundary 原生精确），将长字幕按标点拆分为单行短句，每句时间与语音同步
• 入场动画：淡入 200ms + 从下方 20px 上滑（ASS \fad + \move 标签）
• 出场动画：淡出 150ms（ASS \fad 标签）

进度条参数：

• 位置：画面顶部（80px 高度）
• 背景：半透明深色（alpha=130）
• 当前板块：橙色 (#FF7F72) 文字 + 实心圆点
• 非当前板块：灰色 (#AAAAAA) 文字 + 空心圆点
• 底部进度线：橙色填充 + 深灰底色，显示总体播放进度
• 字体：自动检测系统中文字体，44pt

动态效果参数：

• 转场淡入淡出时长：0.3s（短于 0.6s 的分镜自动减半）

音频混音参数：

• 背景音乐：assets/bgm_reading.mp3（3分56秒读书背景音乐，自动循环），音量 0.15
• 转场音效：assets/transition_page_flip.mp3（0.71s 翻页声效），每 3 个分镜在结尾前 0.5s 触发，音量 0.3
• 混音方式：ffmpeg amix 滤镜，BGM 循环播放 + 转场音效按时间点 adelay 叠加

> 📌 音频素材为可选：由于 SkillHub 不支持上传 .mp3 文件，音频素材未随技能打包。如果 assets/ 目录下没有这些文件，视频仍可正常生成（仅不含 BGM 和转场音效）。如需添加，请参考 assets/README.md 中的获取方式。

输出

最终输出：output/{book_name}_三分钟精读书.mp4

跨平台安装

WorkBuddy

技能已安装在 ~/.workbuddy/skills/book-video-generator/，直接使用。

OpenClaw

# 复制到 OpenClaw 技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.openclaw/skills/

# 或通过 ClawHub 安装（如果已发布）
openclaw skills install book-video-generator

如需在 frontmatter 中声明图像生成 tool，参考 OpenClaw 文档的 tools 字段定义。

Codex CLI

# 1. 开启 Skills 功能（如未开启）
echo '[features]\nsskills = true' >> ~/.codex/config.toml

# 2. 复制技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.codex/skills/

# 3. 重启 Codex CLI
# 4. 输入 /skills 确认技能已加载

Codex CLI 无内置图像生成，需在 scripts/ 目录中添加 generate_image.py 脚本，调用外部 API（如 OpenAI DALL-E、Stability AI）。脚本需接受 --prompt 和 --output 参数。

TRAE Work

1. 打开 TRAE Work → 规则和技能 → 技能 → 创建 → 导入文件
2. 上传 SKILL.md 文件
3. 确保 scripts/ 和 references/ 目录也复制到技能目录

TRAE Work 通过 MCP 接入图像生成服务。在 TRAE 的 MCP 配置中添加火山引擎或通义万相的图像生成 MCP，然后在执行阶段 4a 时通过 MCP 调用。

原工作流参考

原始扣子工作流文件位于 references/workflow-original.yaml，包含 30+ 节点的完整链路：

开始 → LLM(DeepSeek V3.2)生成书评 → 上标题总结 → 分镜画面描述
→ 代码拼接引言 → 批量图像生成+抠图 → TTS语音合成
→ 创建剪映草稿 → 批量添加图片/字幕/音频 → 保存草稿 → 结束

原始流程依赖剪映小助手插件（视频合成核心）、扣子内置图像生成+抠图和TTS插件。 本 Skill 使用 ffmpeg、edge-tts、平台图像生成工具替代。

快速使用示例

用户说："帮我生成《原子习惯》James Clear 的 3 分钟精读视频"

执行流程：

1. 搜索"原子习惯 James Clear 简介 书评"
2. 用阶段 1 prompt 生成书评文案
3. 用阶段 2 prompt 生成分镜脚本
4. 用阶段 3 prompt 生成标题进度条
5. 对每个分镜：图像生成工具生成插图 + TTS 生成配音（火山引擎默认 / edge-tts 备选）
6. compose_video.py 合成最终视频
7. 输出 output/原子习惯_三分钟精读书.mp4

资源文件

• references/prompts.md — 所有 LLM 提示词原文（平台无关，可直接复用）
• references/workflow-original.yaml — 原始扣子工作流（完整 YAML 备份）
• scripts/compose_video.py — 视频合成脚本（纯 Python + ffmpeg，跨平台，含淡入淡出转场 + 字体自动检测 + 封面图支持 + 逐句单行 ASS 字幕精确语音同步 + 关键词高亮 + 入场/出场动画 + 顶部进度条 + BGM 背景音乐混音 + 转场音效）
• scripts/generate_audio.py — TTS 语音生成脚本（纯 Python，双引擎：火山引擎 TTS V1 API + X-Api-Key 默认 1.2x 语速 / edge-tts 备选 +20% 语速，含词级时间戳输出，自动检测凭证切换引擎）
• scripts/generate_cover.py — 封面图生成脚本（纯 Python + Pillow，自动换行 + 模糊背景 + 字体自动检测）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chenjun198711
• Source: chenjun198711/book-video-generator
• License: MIT

Install and usage instructions live in the source repository linked above.