内容
# Frameloop
MCP 服务器，闭环 Claude 与 [Remotion](https://remotion.dev) 之间的反馈。Claude 可以查看参考视频，编写 Remotion 代码，渲染预览帧，并自我纠正 — 所有操作无需离开对话。
还包括用于独立视频帧提取的 CLI 和 Web UI。
## 问题
Claude 可以生成 Remotion 代码，但无法看到自己的输出。它在编写动画时是盲目的。当某些内容不正确时，您必须手动截图，粘贴，描述问题，然后迭代。
## 解决方案
Frameloop 让 Claude 有了眼睛。完整的工作流程：
1. **Claude 查看参考视频** — 使用场景检测提取关键帧
2. **Claude 编写 Remotion 代码** — 基于它所看到的内容
3. **Claude 渲染自己的帧** — 使用 `render_still` / `render_preview`
4. **Claude 查看结果** — 读取渲染的图像
5. **Claude 自我纠正** — 如果输出不匹配，则调整代码
6. **重复** 直到看起来正确
## 杀手级功能：复制任何视频
Frameloop 的旗舰工作流程：**指向 Claude 任意视频，获取可工作的 Remotion 重现。**
```
参考视频（文件或 YouTube URL）
│
▼
┌─────────────────────┐
│ Frameloop 提取 │ 场景检测 + 间隔采样。
│ 密集帧批次 │ 每批次 180 帧，3x3 网格。
└─────────┬───────────┘
▼
┌─────────────────────┐
│ Claude 分析每个 │ 描述元素、颜色、时间、
│ 批次帧逐帧 │ 缓动曲线、过渡效果。
└─────────┬───────────┘
▼
┌─────────────────────┐
│ Claude 编写 │ 使用 Frameloop 的配方库、
│ Remotion 代码 │ 运动预设和 IR 代码生成。
└─────────┬───────────┘
▼
┌─────────────────────┐
│ render_preview │ 生成自己的输出的联系表。
│ 与参考对比 │ 使用 compare_frames 比较。
└─────────┬───────────┘
▼
┌─────────────────────┐
│ 自我纠正循环 │ 调整时间、缓动、布局直到
│ 直到匹配 │ 实现视觉匹配。
└─────────────────────┘
```
**两种输入模式：**
- **本地文件** — 将任意 `MP4 / MOV / WebM / AVI` 文件拖入 Studio Extract 面板
- **YouTube URL** — 粘贴 `youtube.com`、`youtu.be` 或 `youtube.com/shorts` 链接。Frameloop 直接通过 `yt-dlp` 流式传输视频（无需完整下载），提取帧并将其提供给 Claude。适用于常规视频、短视频和动态图形。
**两种提取策略：**
| 模式 | 输出 | 用例 |
|------|--------|----------|
| **提取帧** | 15-60 个关键帧（场景检测 + 间隔） | 视觉检查、单次分析、询问 Claude 关于内容 |
| **复制运动** | 密集批次，每批次 180 帧，3x3 网格 @ 6fps | 重现动画 — Claude 读取逐帧时间 |
复制模式使 Frameloop 独一无二。标准帧提取工具提供 10-20 帧；Frameloop 为 Claude 提供足够的密度来重建运动曲线。
**复制后向 Claude 发送示例提示：**
> "以下是 Stripe 广告的批次。构建一个 Remotion 组合，重新创建标题显示和仪表板滑动。使用 @recipe:fade-up-word-by-word 作为标题，并为所有过渡应用 @preset:ease-out-expo。完成后渲染预览，以便我可以比较。"
Claude 将：
1. 使用 `analyze_video` （已经完成 — 聊天中的帧）
2. 使用配方 + 预设生成 Remotion 代码
3. 调用 `render_preview` 查看其自己的输出
4. 使用 `compare_frames` 将原始与渲染的并排比较
5. 迭代直到匹配
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `render_still` | 从 Remotion 组合中渲染单个帧 |
| `render_frames` | 渲染多个特定帧以检查动画进度 |
| `render_preview` | 生成整个组合的联系表网格 |
| `get_compositions` | 列出 Remotion 项目中的所有组合 |
| `analyze_video` | 从参考视频中提取关键帧（场景检测、间隔或组合） |
| `extract_frames_at_timestamps` | 在视频中的特定时间戳处提取帧 |
## 要求
- Python 3.10+
- [FFmpeg](https://ffmpeg.org/download.html) 在您的 PATH 中
- [Node.js](https://nodejs.org/) 18+（用于 Remotion 渲染工具）
## 安装
```bash
pip install frameloop
```
或从源代码：
```bash
git clone https://github.com/Alan-Lucena/frameloop.git
cd frameloop
pip install -e ".[web,dev]"
```
## 使用 Claude 代码设置
在 Claude Code 设置中添加 Frameloop 作为 MCP 服务器（`~/.claude/settings.json`）：
```json
{
"mcpServers": {
"frameloop": {
"command": "frameloop",
"args": ["mcp"]
}
}
}
```
或在项目级 `.claude/settings.json` 中：
```json
{
"mcpServers": {
"frameloop": {
"command": "frameloop",
"args": ["mcp"],
"env": {
"FRAMELOOP_OUTPUT_DIR": "./frameloop_output"
}
}
}
}
```
配置后，重启 Claude Code。工具将自动可用。
## 示例工作流程
```
您：这里有一个参考视频，位于 ./reference.mp4。分析它并在 Remotion 中重新创建。
Claude：[使用 analyze_video 从 reference.mp4 中提取关键帧]
[查看提取的帧以了解设计]
[为组合编写 Remotion 代码]
[使用 render_preview 查看其代码生成的内容]
[查看联系表并与参考进行比较]
[调整时间、颜色和布局]
[使用 render_frames 检查特定动画时刻]
[进行最终调整]
完成！组合与参考相符。
```
## CLI 使用
CLI 保留所有原始帧提取功能：
### 提取关键帧
```bash
# 默认：组合方法，15 帧，保存为 JPEG
frameloop extract video.mp4
# 仅场景检测
frameloop extract video.mp4 --method scene --max-frames 8
# 生成网格图像
frameloop extract video.mp4 --format grid
# 具有丰富元数据的详细网格
frameloop extract video.mp4 --format grid --detailed --max-frames 40
# 来自 YouTube
frameloop extract "https://www.youtube.com/watch?v=..." --format grid
```
### 向 Claude 询问视频
```bash
export ANTHROPIC_API_KEY=sk-ant-...
frameloop ask video.mp4 "逐步描述视频中发生的内容"
frameloop ask "https://youtu.be/..." "总结这个视频"
```
### 复制模式（用于 Remotion 的高密度提取）
```bash
frameloop replicate video.mp4
frameloop replicate "https://youtu.be/..." --fps 5 --output-dir ./my_output
```
### Web UI
```bash
# 终端 1：API 服务器
frameloop serve
# 终端 2：前端
cd web && npm install && npm run dev
```
打开 [http://localhost:3000](http://localhost:3000) — 拖放视频，调整提取设置，预览帧。
### 手动启动 MCP 服务器
```bash
frameloop mcp
```
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `FRAMELOOP_OUTPUT_DIR` | `./frameloop_output` | 保存渲染的帧和网格的位置 |
| `ANTHROPIC_API_KEY` | — | `ask` CLI 命令所需 |
## 作为库使用
```python
from frameloop.extractor import extract_frames, ExtractionMethod, compose_grids
# 提取帧
result = extract_frames("video.mp4", method=ExtractionMethod.COMBINED, max_frames=10)
for frame in result.frames:
print(f"帧 {frame.index}：{frame.timestamp:.1f}s — {frame.reason}")
# 生成网格
grids = compose_grids(result, grid_layout="full", detailed=True)
grids[0].save("grid.jpg", "JPEG", quality=92)
```
## 项目结构
```
frameloop/
├── frameloop/
│ ├── __init__.py # 包版本
│ ├── mcp_server.py # 具有 6 种工具的 MCP 服务器
│ ├── extractor.py # 核心帧提取引擎
│ ├── downloader.py # YouTube 流分辨率（yt-dlp）
│ ├── claude_client.py # Anthropic API 集成
│ ├── cli.py # CLI（extract, ask, replicate, serve, mcp）
│ └── server.py # Web UI 的 FastAPI 后端
├── web/ # Next.js 前端
├── pyproject.toml
├── LICENSE
└── README.md
```
## 开发
```bash
git clone https://github.com/Alan-Lucena/frameloop.git
cd frameloop
python -m venv .venv && source .venv/bin/activate
pip install -e ".[web,dev]"
ruff check frameloop/
pytest
```
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
