# YoutuberBox

Faceless YouTube video automation **MCP server** — shorts (9:16) and long-form (16:9).

The connected LLM does the *creative* work (script, scene beats, image prompts); YoutuberBox does the *execution*: TTS narration via [voicebox](https://github.com/jamiepine/voicebox), AI images via [CodexImage](https://github.com/saroby/CodexImage), whisper-timed burned-in captions, and ffmpeg assembly with Ken Burns motion. Built-in quality guardrails push output away from AI slop.

## Pipeline

```
create_project → set_script → generate_narration ┐
                              generate_images    ├→ generate_captions → assemble_video
                                                 ┘
```

| Tool | What it does |
|---|---|
| `create_project` | New project (shorts 1080×1920 / long 1920×1080), returns the quality guide |
| `set_script` | LLM-authored scenes (narration + 1–3 image prompts each), returns pacing/quality lint warnings |
| `generate_narration` | Per-scene TTS via voicebox (`/generate/stream`); reports durations; per-scene regeneration via `sceneIds` |
| `generate_images` | Per-scene images via CodexImage; 2–3 prompts per scene = intra-scene cuts; consistent style anchor |
| `generate_captions` | Word timestamps via `mlx_whisper`/`whisper` (proportional fallback) → karaoke word-highlight ASS; `position`/`highlightColor` knobs |
| `assemble_video` | Ken Burns per still (alternating direction), cuts every few seconds, caption burn-in, looped/ducked BGM, −14 LUFS loudnorm |
| `list_voices` | Voicebox voice profiles so the LLM picks a fitting narrator |
| `generate_thumbnail` | Text-free thumbnail via CodexImage (add typography yourself — AI text is a slop tell) |
| `project_status` | Pipeline state per scene |

Resource: `guide://quality` — the anti-slop guide (hooks, pacing targets, image prompt rules, mix levels).

## Requirements

- Node.js 20+
- `ffmpeg` / `ffprobe` on PATH
- [voicebox](https://github.com/jamiepine/voicebox) for TTS
- [CodexImage](https://github.com/saroby/CodexImage) for image generation
- Optional: `mlx_whisper` or `whisper` CLI for word-accurate caption timing

## Install

```bash
npm install
npm run build
```

Register with your MCP client (e.g. Claude Code):

```json
{
  "mcpServers": {
    "youtuberbox": {
      "command": "node",
      "args": ["/path/to/YoutuberBox/dist/index.js"]
    }
  }
}
```

Projects land in `~/YoutuberBox/projects/<id>/` (override with `YOUTUBERBOX_HOME`).

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `VOICEBOX_URL` | `http://127.0.0.1:17493` | Voicebox REST API (run the Voicebox app) |
| `CODEXIMAGE_URL` | — (required) | CodexImage server base URL |
| `CODEXIMAGE_API_KEY` | — (required) | CodexImage API token (Bearer) |
| `CODEXIMAGE_QUALITY` | `medium` | `low` \| `medium` \| `high` |
| `YOUTUBERBOX_HOME` | `~/YoutuberBox` | Where projects and renders are stored |

Voice selection: pass `voice` to `create_project`/`generate_narration` as a Voicebox profile name or id; defaults to your first profile.

Captions: if your ffmpeg has libass, captions are burned in (styled, word-group pop for shorts). Otherwise they're muxed as a soft `mov_text` track and the tool tells you how to upgrade.

## Design notes

Ideas borrowed from the best of the ecosystem: granular execution tools the LLM orchestrates (stephengpope/remotion-media-mcp) instead of a single god-tool (gyoridavid/short-video-maker's `create-short-video`); scene = {narration, visual spec} as the exchange format and dual-aspect maturity (MoneyPrinterTurbo); LLM-authored structure over hidden config (ShortGPT's edit-markup thesis); karaoke captions and voice discovery endpoints (short-video-maker); motion-on-stills + a cut every few seconds — the #1 documented "AI slop" complaint is static visuals.

The deliberate difference: **no built-in script generation** — the LLM you connect writes the script with full context of your channel and audience, and the server lints it against pacing/quality rules (hook length, words/sec, cliché openers, text-in-image prompts, static-scene warnings) instead of generating generic content itself.

## License

MIT