Remotion Claude Agent

基于 Remotion 和 Claude Agent SDK 的视频创作系统。通过 AI 编排实现从自然语言需求到产品演示视频的自动化生产。

项目概述

本项目是一个 AI 驱动的视频生产平台，支持将产品教程、Demo 演示、SaaS 介绍等需求转化为高质量的视频内容。

核心能力

• perceiver - 浏览器感知/录屏，获取内容理解
• creator - 生成脚本、分镜、风格配置
• crafter - 协调素材下载、语音合成、视频渲染
• composer-agent - Remotion 视频编排与渲染

工作流程

用户需求
    ↓
1. Perceiver → 浏览器感知/录屏，获取内容理解
    ↓
2. Creator → 生成脚本、分镜、风格配置
    ↓
   [用户确认方案]
    ↓
3. Crafter → 协调素材下载、语音合成、视频渲染
    ↓
4. 运行预览 → 执行 remotion 预览操作
    ↓
5. 最终输出 → 渲染成 mp4 格式的视频

项目结构

remotion-claude-agent/
├── apps/                    # Web 应用
│   └── web/                # Next.js 前端 (Next.js 16 + React 19)
├── bin/                    # CLI 入口
│   └── remotion-agent.js   # npm 全局命令
├── templates/              # 初始化模板
│   └── .claude/            # Claude Agent 配置模板
│       ├── agents/         # 子代理定义
│       └── skills/         # 技能库
├── workspace/              # 工作区 (运行时创建)
│   ├── .claude/            # Claude Agent 配置
│   │   ├── agents/         # 子代理（perceiver, creator, crafter, composer-agent）
│   │   └── skills/         # 技能库（语音合成、字幕处理、BGM 等）
│   └── projects/           # 项目产出目录
└── openspec/               # 规格说明书
    ├── AGENTS.md           # OpenSpec 使用指南
    ├── project.md          # 项目约定
    └── changes/            # 变更提案
        └── archive/        # 已归档变更

技术栈

• 前端: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS v4
• 状态管理: Jotai
• Markdown 渲染: Streamdown (自定义渲染器)
• 视频引擎: Remotion (React-based video framework)
• AI 编排: Claude Agent SDK
• 语音合成: 阿里云 DashScope (cosyvoice-v3-flash)
• 视频生成: Seedance (AI 视频生成)
• 协议: A2A (Agent-to-Agent) Protocol

开发指南

环境配置

# 安装依赖
npm install

# 配置环境变量 (在 apps/web/.env)
cp apps/web/env.example apps/web/.env

启动开发服务器

# 启动 Web 应用 (开发模式)
npm run dev

# 或使用 CLI
remotion-agent web start --port 3000

CLI 使用（npm 分发）

# 全局安装
npm install -g remotion-claude-agent-demo

# 设置默认 workspace（持久化）
remotion-agent config set workspace /path/to/workspace

# 设置环境变量（持久化）
remotion-agent env set ANTHROPIC_AUTH_TOKEN your_token
remotion-agent env set ANTHROPIC_API_KEY your_key
remotion-agent env set DASHSCOPE_API_KEY your_dashscope_key

# 交互式初始化（写入配置）
remotion-agent init

# 启动 Web UI（前台）
remotion-agent web start --port 3000

配置文件路径：

• macOS/Linux：~/.remotion-claude-agent/config.json
• Windows：%USERPROFILE%\\.remotion-claude-agent\\config.json

说明：

• 未配置 workspace 时，默认使用启动命令时的 pwd
• 首次启动会自动初始化 workspace 下的 .claude 配置目录
• Web 运行时依赖缓存至 ~/.remotion-claude-agent/web/

OpenSpec 使用

# 查看活动提案
openspec list

# 查看规格列表
openspec list --specs

# 验证变更
openspec validate [change-id] --strict

# 归档已完成的变更
openspec archive [change-id] --yes

技能库 (Skills)

| 技能 | 描述 | |------|------| | voice-synthesizer | 阿里云 cosyvoice-v3-flash 语音合成，支持多音色、SSML | | subtitle-processor | 从 VTT 文件生成 Remotion 字幕数据 | | subtitle-composer | 字幕合成与样式编排 | | timeline-generator | 从 VTT 自动计算场景时长和帧数 | | bgm-manager | 背景音乐管理与音量控制 | | asset-validator | 素材验证，确保渲染前完整性 | | audio-video-sync | 音视频同步，确保画面与语音完美同步 | | video-preflight-check | 视频渲染前预检 | | render-config | 渲染配置管理 | | remotion-best-practices | Remotion 开发最佳实践指南 | | remotion-components | Remotion 组件库 | | script-writer | 脚本创作辅助 | | style-director | 风格导演，统一视觉风格 | | image-generator | AI 图片生成 | | seedance-video-generator | Seedance AI 视频生成 | | agent-browser | 浏览器自动化代理 | | algorithmic-art | 算法艺术创作 | | youtube-downloader | YouTube 视频下载 | | web-design-guidelines | Web 设计规范指南 |

后台任务

支持独立运行的后台任务，通过 SSE 活动流实时通知前端：

• 并发控制：多个任务可并行执行
• 进度追踪：通过 TaskCreate/TodoWrite 输出任务进度
• 自动投递：结果自动写回主会话

A2A 协议

遵循 Agent-to-Agent Protocol，支持：

• /messages/stream - 流式消息处理
• /background-tasks - 后台任务管理
• /events/stream - 活动事件流（支持断线重连）

约定

文档语言

• 项目内的需求/设计/任务/规格等文档默认使用中文
• 保留 OpenSpec 固定格式关键字（如 ## ADDED Requirements）

SDK 优先

• 优先使用 Claude Agent SDK 原生能力
• 仅在原生能力无法满足时，才引入自定义实现

视频生产约定

• 默认必须配音 + VTT 字幕：除非用户明确表示不要
• 默认必须 BGM：除非用户明确表示不要背景音乐
• 字幕禁止实时跟读：仅使用静态样式，不做逐字高亮
• 时间线必须由字幕生成：timeline-config.ts 由 VTT 自动生成
• 音画字幕必须对齐：渲染前必须通过同步检查

许可证

商业使用需授权

Copyright (c) 2025 Remotion Claude Agent

本项目采用商业授权模式：

• 个人学习/研究用途：免费使用
• 商业用途：需获得书面授权许可

如需商业授权，请联系项目维护者获取授权协议。未经授权的商业使用将被视为侵权行为。

详细许可条款请参见 LICENSE 文件。