OpenClaw Video - 自动化视频生成流水线

基于 OpenClaw + Remotion + OpenAI 的完全自动化视频生成系统。只需提供文本脚本，即可生成配音、时间戳、场景编排并最终渲染视频。

✨ 特性

• 🎤 TTS 语音生成 - OpenAI TTS API，支持多种声音和语速
• ⏱️ 时间戳提取 - OpenAI Whisper API，精确分段识别
• 🎬 场景编排 - 智能检测场景类型，自动生成 Remotion 数据
• 🎨 赛博风格 - 线框动画、故障效果、霓虹色彩
• 🖼️ 背景视频 - 支持自定义背景视频，可调透明度和遮罩
• 📸 海报生成 - HTML/CSS + Chrome Headless，一键生成项目海报
• 🤖 完全自动化 - 一行命令完成从文本到视频的全流程

🔒 安全和隐私

本地处理:

• ✅ 视频渲染（Remotion）
• ✅ 场景检测和编排
• ✅ 文件管理

云端处理（数据发送到外部 API）:

• ⚠️ 文本转语音（TTS）- 文本脚本发送到 OpenAI/Azure/阿里云/腾讯云
• ⚠️ 语音识别（Whisper）- 音频文件发送到云端
• ⚠️ 数据受提供商隐私政策约束（如 OpenAI 隐私政策）

API 密钥安全:

• ✅ 使用 .env 文件或环境变量存储密钥
• ⚠️ 避免通过命令行传递密钥（在进程列表中可见）
• ✅ 本工具不收集任何数据，无追踪或分析

🚀 快速开始

前置要求

• Node.js >= 18
• pnpm (或 npm/yarn)
• OpenAI API Key
• ffmpeg (视频处理)
• Python 3 (TTS/ASR 脚本)

安装方式选择

项目支持两种安装方式，根据你的使用场景选择：

| 特性 | npm 全局安装 | Git Clone 本地安装 | |------|------------|-------------------| | 安装难度 | ⭐ 简单（一条命令） | ⭐⭐ 需要克隆 + npm install | | 更新方式 | npm update -g | git pull && npm install | | 适用场景 | 普通用户、快速使用 | 开发者、需要修改代码 | | 环境变量 | 系统级配置或命令行传递 | 项目内 .env 文件（推荐） | | 磁盘占用 | 较小（单份全局） | 每个项目独立一份 | | 推荐给 | 终端用户、AI Agent | 开发者、团队协作 |

方式 1: npm 全局安装（快速使用）

适合普通用户和快速开始：

# 安装
npm install -g openclaw-video-generator

# 配置 API Key（两种方式任选一种）
# 方式 A: 环境变量（✅ 推荐 - 最安全）
export OPENAI_API_KEY="sk-..."
# macOS 用户添加到 ~/.zshrc，Linux 用户添加到 ~/.bashrc

# 方式 B: 命令行传递（⚠️  不推荐 - 在进程列表中可见）
# openclaw-video-generator generate "你的文本" --api-key "sk-..."
# 警告：命令行传递的 API 密钥在 'ps aux' 中对其他用户可见

# 验证安装
openclaw-video-generator --version

优点:

• ✅ 安装简单，一条命令搞定
• ✅ 全局可用，任何目录都能调用
• ✅ 自动更新方便

注意事项:

• ⚠️ macOS 用户如遇权限问题，见下方"macOS 特别说明"
• ⚠️ 环境变量需要在系统级配置

方式 2: Git Clone 本地安装（开发推荐）

适合开发者和需要自定义的用户：

安装

通过 ClawHub（推荐 AI Agent 使用）:

# 1. 安装 skill
clawhub install video-generator

# 2. 克隆项目
git clone https://github.com/ZhenRobotics/openclaw-video-generator.git ~/openclaw-video-generator
cd ~/openclaw-video-generator

# 3. 安装依赖
npm install

# 4. 配置 .env 文件（项目内管理密钥）
cp .env.example .env
nano .env  # 填入你的 API Key

# 5. 验证安装
./agents/video-cli.sh help

ClawHub Skill 链接: https://clawhub.ai/ZhenStaff/video-generator

直接从 GitHub:

# 1. 克隆项目
git clone https://github.com/ZhenRobotics/openclaw-video-generator.git
cd openclaw-video-generator

# 2. 安装依赖
npm install

# 3. 配置 .env 文件
cp .env.example .env
nano .env  # 填入你的 API Key

优点:

• ✅ 可以修改源码和配置
• ✅ 环境变量在项目内（.env 文件），更安全
• ✅ 适合开发和调试
• ✅ 多个项目可以有不同配置
• ✅ 团队协作时配置统一

macOS 用户特别说明

无论选择哪种安装方式，macOS 用户请注意：

1. 安装依赖工具:

# 使用 Homebrew 安装
brew install node ffmpeg python3

# 检查版本
node --version  # 应该 >= 18
ffmpeg -version
python3 --version

2. npm 全局安装权限问题（如选择方式 1）:

如果遇到权限错误，选择以下方案之一：

# 方案 A: 使用 sudo（简单但需要密码）
sudo npm install -g openclaw-video-generator

# 方案 B: 配置 npm 到用户目录（推荐，一劳永逸）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw-video-generator

3. 环境变量配置:

macOS Catalina+ 默认使用 zsh，配置文件是 ~/.zshrc（不是 ~/.bashrc）：

# 添加 API Key 到 zsh 配置
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

# 验证
echo $OPENAI_API_KEY

4. 推荐方式:

对于 macOS 用户，我们推荐使用 Git Clone 方式（方式 2），因为：

• ✅ 路径更清晰，不需要处理全局安装权限
• ✅ .env 文件管理更方便
• ✅ 更容易调试和排查问题
• ✅ 避免 zsh/bash 环境变量混淆

生成第一个视频

方式 1: 使用 Agent (推荐) 🤖

# 直接用自然语言生成视频
./agents/video-cli.sh generate "三家巨头同一天说了一件事。微软说Copilot已经能写掉90%的代码。"

# 或者使用完整 Agent
node -r ts-node/register agents/video-agent.ts "帮我生成一个关于 AI 工具的视频"

方式 2: 使用脚本

# 使用示例脚本生成视频
./scripts/script-to-video.sh scripts/example-script.txt

# 查看结果
mpv out/example-script.mp4

就这么简单！ 🎉

📖 完整流程

1. 准备文本脚本

创建一个文本文件，每句话自然分段：

cat > scripts/my-video.txt <<'EOF'
三家巨头同一天说了一件事。
微软说Copilot已经能写掉百分之九十的代码。
OpenAI说GPT5能替代大部分程序员。
Google说Gemini2.0改变游戏规则。
但真相是什么？
AI不会取代开发者，而是让优秀开发者效率提升十倍。
关注我学习AI工具。
EOF

2. 运行生成流水线

./scripts/script-to-video.sh scripts/my-video.txt \
  --voice nova \            # 选择声音 (alloy/echo/nova/shimmer等)
  --speed 1.15 \            # 语速 (0.25-4.0)
  --bg-video bg.mp4 \       # 背景视频 (可选)
  --bg-opacity 0.4          # 背景透明度 (可选, 0-1)

3. 输出文件

audio/my-video.mp3                  # TTS 生成的语音
audio/my-video-timestamps.json      # Whisper 提取的时间戳
src/scenes-data.ts                  # Remotion 场景数据
out/my-video.mp4                    # 最终视频 ✨

🎯 流水线架构

文本脚本 (txt)
    ↓
TTS 语音生成 (OpenAI TTS)
    ↓
时间戳提取 (OpenAI Whisper)
    ↓
场景数据转换 (智能检测)
    ↓
视频渲染 (Remotion)
    ↓
成品视频 (MP4, 1080x1920)

🎨 场景类型

流水线自动检测并生成以下 6 种场景类型：

| 类型 | 效果 | 触发条件 | |------|------|----------| | title | 故障效果 + 弹簧缩放 | 第一个片段 | | emphasis | 放大弹出 | 包含百分比 (90%, 10倍) | | pain | 震动 + 红色警告 | 包含"说"、"问题" | | content | 平滑淡入 | 包含"真相"、"但" | | circle | 旋转圆环高亮 | 手动标记 | | end | 上滑淡出 | 最后一个片段 |

🛠️ 可用脚本

Agent 工具 (推荐)

| 脚本 | 功能 | 用法 | |------|------|------| | video-cli.sh | Agent CLI 工具 | ./agents/video-cli.sh generate <脚本> | | video-agent.ts | 智能 Agent | node -r ts-node/register agents/video-agent.ts <请求> | | tools.ts | 工具函数库 | node -r ts-node/register agents/tools.ts test |

核心脚本

| 脚本 | 功能 | 用法 | |------|------|------| | script-to-video.sh | 完整流水线 | ./scripts/script-to-video.sh <script.txt> | | tts-generate.sh | TTS 语音生成 | ./scripts/tts-generate.sh <文本> | | whisper-timestamps.sh | 时间戳提取 | ./scripts/whisper-timestamps.sh <audio.mp3> | | timestamps-to-scenes.js | 场景转换 | node scripts/timestamps-to-scenes.js <timestamps.json> | | generate-poster.js | 海报生成器 | npm run poster [template] [output-name] |

测试脚本

| 脚本 | 功能 | |------|------| | test-agent.sh | 测试 Agent 功能 | | test-tts.sh | 测试 TTS 生成 | | test-whisper.sh | 测试 Whisper 提取 |

📚 文档

快速开始

• QUICKSTART.md - 5 分钟快速开始 ⚡
• DELIVERY.md - 项目交付文档 📦
• PROJECT_SUMMARY.md - 项目总结 📊

使用指南

• AGENT.md - 智能 Agent 使用指南 ⭐
• FAQ.md - 常见问题解答 🔧
• PIPELINE.md - 完整流水线架构和使用指南

技术文档

• TTS.md - TTS 语音生成详解
• WHISPER.md - Whisper 时间戳提取详解
• TESTING.md - 测试指南

集成和扩展

• openclaw-integration.md - OpenClaw 集成指南

🤖 Agent 使用

智能视频生成

Agent 可以理解自然语言并自动生成视频：

# 示例 1: 直接生成
./agents/video-cli.sh generate "AI 改变世界"

# 示例 2: 带配置
./agents/video-cli.sh generate "三个AI工具提升效率" --voice nova --speed 1.2

# 示例 3: 使用自然语言
node -r ts-node/register agents/video-agent.ts "帮我生成一个关于 GPT 的视频"

# 示例 4: 脚本优化
./agents/video-cli.sh optimize "这是我的脚本内容"

# 示例 5: 获取帮助
./agents/video-cli.sh help

Agent 特性

• 🧠 自然语言理解 - 理解多种表达方式
• 📊 脚本分析 - 自动分析长度、风格、关键词
• 💡 智能建议 - 提供优化建议
• 🎬 一键生成 - 完整流水线自动化
• 🔧 灵活配置 - 支持自定义声音、语速等

详见 Agent 文档。

💡 使用示例

示例 1: 技术教程视频

cat > scripts/tech-tutorial.txt <<'EOF'
今天教大家如何使用AI工具。
第一步，安装必要的软件。
第二步，配置API密钥。
第三步，开始使用。
是不是很简单？
关注我学习更多技巧。
EOF

./scripts/script-to-video.sh scripts/tech-tutorial.txt \
  --voice alloy \
  --speed 1.0

示例 2: 快节奏短视频

cat > scripts/quick-tips.txt <<'EOF'
三个AI工具改变你的工作效率。
第一个，GPT帮你写代码。
第二个，Whisper帮你转写音频。
第三个，Remotion帮你生成视频。
试试看，效率提升十倍！
EOF

./scripts/script-to-video.sh scripts/quick-tips.txt \
  --voice nova \
  --speed 1.3

示例 3: 生成项目海报

# 使用默认模板生成海报
npm run poster

# 生成研究分析师海报
npm run poster:research

# 使用自定义模板和输出名称
npm run poster default my-custom-poster

# 批量生成所有模板
npm run poster default poster && npm run poster research-analyst research-poster

海报生成特性：

• 📐 标准尺寸 - 1200x1600 像素（3:4 比例）
• 🎨 赛博风格 - 霓虹色彩、网格背景、光效动画
• 📸 Chrome 渲染 - 高质量 HTML/CSS 转图片
• 🖼️ 双格式输出 - PNG（高清）+ JPG（压缩）
• 🔧 可自定义 - 支持创建自定义 HTML 模板

依赖要求：

• Chrome/Chromium（必需）
• FFmpeg（可选，用于 JPG 转换）

可用模板：

• default - OpenClaw Video Generator 标准海报
• research-analyst - Research Analyst 项目海报

详细文档：scripts/poster-templates/README.md

⚙️ 高级配置

自定义视频参数

编辑 src/scenes-data.ts:

export const videoConfig = {
  fps: 30,              // 帧率
  width: 1080,          // 宽度
  height: 1920,         // 高度 (竖屏)
};

添加背景视频

方式 1：通过命令行参数（推荐）

./scripts/script-to-video.sh scripts/my-script.txt \
  --bg-video /path/to/background.mp4 \   # 背景视频路径
  --bg-opacity 0.4 \                     # 透明度 (0-1, 默认 0.3)
  --bg-overlay "rgba(10, 10, 15, 0.6)"   # 遮罩颜色 (可选)

方式 2：手动编辑配置文件

编辑 src/scenes-data.ts:

export const videoConfig = {
  fps: 30,
  width: 1080,
  height: 1920,
  durationInFrames: 450,
  audioPath: 'audio.mp3',
  bgVideo: 'background.mp4',              // 背景视频 (放在 public/)
  bgOpacity: 0.4,                         // 透明度
  bgOverlayColor: 'rgba(10, 10, 15, 0.6)', // 遮罩颜色
};

透明度建议：

• 0.2-0.3 - 背景若隐若现，文字非常清晰（推荐用于文字密集内容）
• 0.4-0.5 - 背景较明显，文字仍然清晰（推荐用于平衡效果）
• 0.6-0.8 - 背景很明显，需要更深的遮罩层（推荐用于视觉效果优先）

自定义场景检测规则

编辑 scripts/timestamps-to-scenes.js:

function determineSceneType(index, total, text) {
  // 添加你的自定义规则
  if (text.includes('重要')) return 'emphasis';
  if (text.includes('注意')) return 'pain';

  // 保留默认规则
  if (index === 0) return 'title';
  if (index === total - 1) return 'end';
  return 'content';
}

自定义视觉风格

编辑 src/SceneRenderer.tsx:

// 修改颜色
const primaryColor = '#00F5FF';  // 青色霓虹
const bgColor = '#0A0A0F';       // 深色背景

// 修改动画
spring({
  frame,
  fps,
  config: { damping: 10, stiffness: 100 }
})

💰 成本估算

| 组件 | 定价 | 15秒视频成本 | |------|------|--------------| | OpenAI TTS | $0.015/1K字符 | ~$0.001 | | OpenAI Whisper | $0.006/分钟 | ~$0.0015 | | Remotion 渲染 | 本地免费 | $0 | | 总计 | | ~$0.003 |

每个视频成本不到 1 美分！ 💰

🎬 视频规格

• 分辨率: 1080 x 1920 (竖屏，适合抖音/视频号)
• 帧率: 30 fps
• 格式: MP4 (H.264 + AAC)
• 时长: 根据脚本自动计算

🐛 故障排查

TTS 问题

# 测试 TTS
./scripts/test-tts.sh

# 常见问题
export OPENAI_API_KEY="sk-..."  # 设置 API Key

Whisper 问题

# 使用示例数据测试
node scripts/timestamps-to-scenes.js audio/example-timestamps.json

# 如果 API 超时，可以手动编辑时间戳文件

Remotion 问题

# 开发模式预览
pnpm dev

# 打开浏览器访问 http://localhost:3000

📦 项目结构

openclaw-video-generator/
├── audio/                      # 音频文件
│   ├── example-timestamps.json # 示例时间戳
│   └── *.mp3                   # 生成的音频
├── src/
│   ├── types.ts                # TypeScript 类型定义
│   ├── scenes-data.ts          # 场景数据 (自动生成)
│   ├── Root.tsx                # Remotion 根组件
│   ├── CyberWireframe.tsx      # 主视频组件
│   └── SceneRenderer.tsx       # 场景渲染器
├── scripts/
│   ├── script-to-video.sh      # 🎯 完整流水线
│   ├── tts-generate.sh         # TTS 生成
│   ├── whisper-timestamps.sh   # Whisper 提取
│   ├── timestamps-to-scenes.js # 场景转换
│   ├── test-tts.sh             # TTS 测试
│   ├── test-whisper.sh         # Whisper 测试
│   └── example-script.txt      # 示例脚本
├── docs/
│   ├── PIPELINE.md             # 流水线文档
│   ├── TTS.md                  # TTS 文档
│   └── WHISPER.md              # Whisper 文档
├── out/                        # 渲染输出
│   └── *.mp4                   # 生成的视频
└── package.json

🔮 未来计划

• [ ] Agent 自动化选题和脚本生成
• [ ] 支持更多视觉风格模板
• [ ] 集成背景音乐
• [ ] 自动字幕生成
• [ ] 多语言支持

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT

用 AI 生成视频，从未如此简单！ ✨🎬🚀