内容
align="center">
<img src=".github/assets/spoooler-hero.png" alt="Spoooler — AI 驱动的视频剪辑" width="720" />
<p><strong>本地优先的 Instagram 短视频制作，完全通过 MCP 驱动。</strong></p>
<p>
<a href="https://instagram-reel-tool.vercel官网</a> ·
<a href="https.com/4nw3rprod/spoooler/releases">下载</a> ·
<a href="https://github.com/4nw3rprod/ReelRecon">ReelRecon（配套工具）</a>
</p>
<p>
<img alt="许可证" src="https://img.shields.io/badge/license-MIT-a78bfa?style=flat-square">
<img alt="Node" src="https://img.shields.io/badge/node-20%20%7C%2022-a78bfa?style=flat-square">
<img alt="MCP" src="https://img.shields.io/badge/interface-MCP--only-a78bfa?style=flat-square">
<img alt="平台" src="https://img.shields.io/badge/platform-macOS-a78bfa?style=flat-square">
</p>
</div>
---
> **MCP 是唯一的入口点。** 所有调用都通过 MCP 服务器
> (`node mcp/server.mjs` 或 `node mcp/client.mjs <tool> '<json>'` 从
> shell）。没有 Web UI 或 HTTP API — `instagram-reel-generator.mjs`
> 引擎除非 MCP 服务器启动它（`REEL_MCP`）。
> 从 [VIDEO-DIRECTOR-SKILL.md](VIDEO-DIRECTOR-SKILL.md)（如何指导
> 短视频）和 [FOOTAGE-MCP-SKILL.md](FOOTAGE-MCP-SKILL.md) / [mcp/README.md](mcp/README.md)
> （工具目录）开始。
Spoooler 将原始素材、Instagram URL 或一行主题转换为成品、发布就绪的 1080×1920 短视频 — 通过 MCP 驱动的工具逐一编排。
它可以：
- 通过 MCP 公开工作流，以便 Codex 和其他 MCP 主机可以逐一驱动工具
- 抓取真实的产品媒体
- 收集库存背景
- 使用 Kokoro 或您自己的克隆 `pocket-tts`/TADA 语音生成语音
- 使用 `whisper.cpp` 对齐字幕
- 使用 Remotion 渲染最终的 MP4
## 开箱即用 vs. 自带
| 功能 | 要求 |
|---|---|
| 主题/转录 → 脚本化短视频，库存媒体，字幕，渲染 | 仅 密钥（见下文） |
| Instagram URL / 上传视频 → 转录 | 您自己的 MCP 兼容转录器（`IG_TRANSCRIBER_ROOT`）— **不包含** |
| 克隆语音旁白（Pocket-TTS / TADA） | 您自己的语音嵌入 — **不包含** |
/品牌媒体raplingwright 本地这些都不需要在不尝试工具的情况下 — `--skip-transcribe --transcript "..."` 让您在没有外部转录器或语音设置的情况下完成渲染。
## 系统要求
- Node.js 20 或 22
- npm 10+
- Python 3.11+
- `ffmpeg` 和 `ffprobe`
- Git
可选，仅当您使用这些功能时：
- Scrapling 能力的 Python venv（产品/品牌媒体抓取）
- `pocket-tts` 在 `PATH` 上（克隆语音旁白）
- Apple Silicon 上的 MLX-TADA 设置（替代语音引擎）
-兼容的转录Instagram URL / 视频上传
您还需要使用一 API 密钥：Google Gemini、NVIDIA NIM、Groq、Pexels、Unsplash、logo.dev。
快速开始
```git clone <此仓库cd instagram-reel-tool
npm install
cp .env.example .env
```
env` 中填写的密钥（参见环境变量” — 大多数是可选的，如果没有它们，工具也会正常运行验证主要包是否已
```bash
e "require.resolve('@protocol/sdk')"
node -e "require.resolve('')"
node -e.resolve('@remotion/install')"
node -require.resolve('zod')"
```
运行离线烟雾测试（无 Instagram 下载，无 LLM 调用，无 TTS）：
```bash
node instagram-reel-generator.mjs \
--skip-transcribe \
--skip-tts \
--offline \
--transcript "停止自动化随机任务。最佳 AI 系统首先找到工作流瓶颈。然后他们删除一个交接并衡量结果。" \
--topic "AI 工作流自动化适用于创始人"
```
这会在 `runs/<slug>/` 下写入运行工件。
## 环境变量
复制 `.env.example` 到 `.env`。关键变量- `GOOGLE`, `GEMINI_MODEL本生成（- `NVIDIA_API `NVIDIA_MODEL`本生成（尝试 Gemini- `G_API_KEY`, `GROQ_MODEL` — 脚本生成（最终备用）
- `KOKORO_API_URL`, `KOKORO_API_KEY`, `KOKORO_MODEL`, `KOKORO_VOICE`, `KOKORO_SPEED` — Kokoro TTS
- `PEXELS`, `UNS_ACCESS_KEY` —媒体
- `_PUBLIC_KEY`, `` — 标获取
- `IG_TRANSCRIBER_ROOT可选**， MCP 兼容转绝对路径（参见）
- `SCRAP` — 具有pling 的 Python 路径
- `PEG_PATH`, `PER_MODEL` —/字幕
-OCKET_TTS_V`, `POCKET_TTS_TONE`, `_TTS_QUALITY 克隆语音旁白
- `TADA_*` — 替代克隆参见下文）
仅安装和运行线烟雾测试。
## 可选 URL / 视频转录Recon 配套 Instagram 短视频上传的视频文件 MCP ，此仓库它。必须公开_mcp_server.sh本和一个 `_input` 工具（输入网址/路径 →文本）。
**elRecon](https/4nw3rprod/ReelRecon)** — 配套工具，同样由该作者开发 — 是一个直接适配的工具：它使用 转录 Instagram、直接视频网址的音频/视频附自己的 `run_mcp_server.sh` + `transcribe_input` MCP 工具，接口完全相同。典型配对：
```bash
git clone https://github.com/4nw3/ReelRecon.git
```
```dotenv
IG_TRANSCRIBER_ROOT=/绝对路径/到/ReelRecon
```
将原始 Instagram 短视频送入 ReelRecon 以获取干净的转录，然后将该转录交给 Spoooler（通过 `transcribe_source` / `--`）以编剧、配音、字幕派生短视频两个专注的工具试图同时完成这两个工具。
如果没有 ReelRecon，Spoooler可以通过 `--transcript `--topic`正常工作 — 您过“给我一个步骤脚本输入。
## 可选：克隆语音旁白
该工具支持两种克隆语音后端。两者都不附带任何语音数据 — 自带。
### Pocket-TTS（Kyutai）
1. 安装 `pocket-tts` CLI 并验证 `pocket-tts --help` 工作2. 使用 Kyut兼容嵌入的嵌入（`.ensors`）。
3其放在 `audio-tts/voices（此仓库的 `../audio/p/voices/`附上 `voices 索引：json
[
{"id": "my-name": " "embeddingFilemy-voice.s"}
]
```
4. 在 `.env` 中POCKET_TTSICE=audio/ptts/voices/my.safetensors`每次运行传递 `--`。
如果 `` 丢失或，MCP `list_voices` 工具将简单地返回没有克隆语音 — Kokoro 预设仍然有效。
### Tume MLX，Apple Silicon）
可选语音克隆引擎参考音频剪辑录中克隆训练的嵌入。
python3 -venv-tsource .venv-t/activate
python pip install --upgradetools wheel
pip install mlx-tada
dotenv
TADA绝对路径/到-tada/bin/pythonADA_MODEL=HumeAI/mlx-tada-1b
TADA=/绝对路径/到/您的/reference.wav_TEXT=
_REFERENCE_CACHE=/绝对路径/到/instagram-reel-tool/.cache/tada/defaultpz
```
注意：
- 仅限；遵循 Hume 的/` 实现。
- 依赖于 Hugging Face控的 Meta Llama 3.2模型用于分词- 需要 `T_AUDIO`（您的辑）；`T_TEXT` 是可选的。
- 使用 `TADA_MODEL=HumeAI/mlx-tada-1b`（英文）或 `HumeAI/mlx-tada-3b`（多语言）。
- 设置 `TADA_WEIGHTS`/`TADA_TOKENIZER` 以强制使用本地分词器而不是 Hub 下载。
- 通过 MCP `synthesize_voice` 工具中的 `voiceEngine=tada` 或 CLI 中的 `--voice-engine tada` 触发。
- 包装脚本：[scripts/tada-tts.py](scripts/tada-tts.py)。
## 可选：产品/品牌媒体抓取rapling）抓取管道使用 [Scrahttps://github.comVinci/Sc)。
```bash
python3 -m venv .venv-scrapling
source .venv-scrapling/bin/activate
python -m pip install --upgrade pip wheel
pip installrapling>=0,<0.5 -m playwright install
```
```dotenv
SCRAPLING_PYTHON=/绝对路径/到/instagram-reel-tool/.venv-scrapling/bin/python3
```
验证：
```bash
source .venv-scrapling/bin/activate
python - <<'PY'
from scrapling.fetchers import Fet DynamicFetcher, StealthyFetcher
printrapling fetchersPY
```
如果pling 未设置，取将降仅限库存媒体运行失败。
##
此仓库在 [mcp/server.mmcp/server.m 包含一个 MCP 服务器。
### 本地烟雾测试
```bash
node mcp/test-client.mjs
node mcp.mjs
```
这些确认服务器工具注册，策略在没有 LLM 脚步骤的情况下工作 MCP 主机配置 MCP 主机使用mcpServers`，对于通用主机：
```json "mcp {
"instagram-tool": {
"command": "node "args": [路径/到/instagram-tool/mcp/server.mjs"]
}
}
}
```
### Code
添加到 `~/.codex/config.toml
```tomlcp.instagram-reel = "node"
args = ["/绝对路径/到/instagram-re/mcp/server.mjs"]
```
参见 [/README.md](mcp/README.md) 以获取完整的工具目录和更多。
## 完整渲染检查
一旦配置了密钥和（可选）语音：
```bash
node instagram-reel-generator.mjs \
--skip-transcribe \
--transcript "这是一个关于 AI 工作流自动化的短测试短 --topic "AI 工作流自动化" \
--render
```
注意：
- 第一次 `whisper.cpp` 对齐运行可能需要一段时间，因为模型安装到 `.cache/whisper-align`
- 第一次克隆语音运行可能需要更长时间，而 `pocket-tts` 加载
- 如果未配置媒体 API，则渲染完成但媒体层为空或降级
## 故障排除
###_voices` 返回没有克隆语音
检查audio/pocket-tts/voices/voices.json` 和引用的 `.safetensors` 文件### 抓取
检查 `LING_PYTHON` 可用的 venv，pling 导入Playwright 的浏览器，并且您有网络访问权限。
### 视频上传无法转录
检查 `IG_TRANSCRIBER_ROOT` 指向一个可用的转录器，公开 `run_mcp_server.sh` + `transcribe_input`，`ffmpeg` 可用，并且上传的文件小于 200 MB。
### 克隆语音生成失败
检查 `pocket-tts` 是否在 `PATH` 上，选定的 `.safetensors` 文件是否存在，并且 `voices.json` 引用正确的嵌入文件名。
### 字幕未对齐
检查 `ffmpeg` 是否已安装，`npm install` 成功完成，`@remotion/install-whisper-cpp` 已解析，并且第一个 whisper 模型安装允许完成。
### 渲染成功但视觉效果为空
检查 `PEXELS_API_KEY`/`UNSPLASH_ACCESS_KEY` 是否已设置，并且库存/抓取的媒体实际下载到运行文件夹中。
## 值得阅读的文件
- [README-instagram-reel-generator.md](README-instagram-reel-generator.md)
- [mcp/READMEmcp/README.md [SKILLSKILL.md)
instagram-reeljs](instagram-re.mjs)
##
- **[Recon](https://github.com/4nw3rprod/ReelRecon)** — 通过 MCP 或 Web UI 进行 Instagram/视频转录。参见上面的 [可选：Instagram URL / 视频转录](#optional-instagram-url--video-transcription--pairs-with-reelrecon)，了解两者如何配合。
## 路线图：一个闭环、自主的内容管道
Spoooler 和 [Recon](https://github.com/4nw3rprod/Re) 已经涵盖转录 → 脚 制作* 端到端，完全通过 MCP。在此基础上将完成从原始发布帖子的，无需手动交接：
| 工具 | 角色 |
|---|---|---|
发现/转录 [Reelhttps://github.com3relRecon) |转录源内容（Instagram、视频、音频） |
| **路由 LLM 调用** | [OmniRoute](https://github.com/diegosouzapw/OmniRoute) | 跨提供商的单一网关 — 智能备用和成本感知路由，用于管道中的每个脚本/视觉调用 |
| **脚本、制作、渲染** | **Spoooler（此仓库）** | 钩子、场景、语音、字幕、品牌媒体、最终 MP4 — 完全通过 MCP 驱动 |
| **发布** | [Postiz](https://github.com/gitroomhq/postiz-app)多个平台上发布成品短视频工具调用 CLI 进行代理驱动 |
目标：只需将管道指向一个源，然后让它从头运行 — 从发现到发布 — 作为一个单一的 MCP 协调工作流。无需手动导出/上传步骤，无需处理单独的调度工具，无需手动重新规划内容一次，然后停止发布*，转而思考 *值得制作什么*。
这是计划中的，但尚未连接 — 在代码可用之前，这里公开集成的大致形状。
## 构建工具
Spoool薄的编，基于几个进行实际工作： 项目 | 角色 |
|---|---|
| [Remotion](https.remotion.dev React 的视频 MP4 | [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) | 工具完全通过的 MCP 服务器/客户端 |
| [whisper.cpp](https://github.com/ggml-org/whisper.cpp)（通过 `@remotion/install-whisper-cpp`） | 单词级字幕对齐 |
| [Scrapling](https://github.com/D4Vinci/Scrapling) + [Playwright](https://playwright | 产品/发现和抓取 |
| [Kokoro://github.com/hexgrad/kokoro) | 默认文本转 |
| [Kyutai 的 Pocket-https://github.com/kyutai-l | 可选的自带克隆语音 |
| [Hume 的 TADA）](https://github.com/Hume 可选的替代克隆语音引擎 |
| [Next.js](https://nextjs.org/) | landing 页面/营销曲面 |
| [Zod](https://zod.dev/) | MCP 工具输入模式验证 |
[package.json](package.json) 中有完整的依赖项列表。
## 许可证
MIT — LICENSE](LICENSE align="center">
<sub>在本地构建，使用 Remotion 渲染。</sub>
</div>
