# Reels Studio

Make a vertical 3D reel from a short script. An AI assistant can direct the editor over MCP (Model Context Protocol), or you can edit the example scene as JSON and render it from the terminal. Blender draws the frames and FFmpeg writes the MP4 on your computer.

## Render your first reel

You'll need Node.js 20 or newer, Blender **5.2.x**, and FFmpeg with H.264 encoding on macOS or Linux. Install Blender in the usual macOS Applications folder or put the blender executable on your PATH. If it lives elsewhere, set `REELS_BLENDER` to its full path.

Clone the repository and render the example

```sh
git clone https://github.com/Endroe/reels-studio.git
cd reels-studio
npm ci
npm run demo
```

The demo renders a silent, two-shot reel called **What if gravity took a coffee break?** The last line gives the MP4 path. [Watch the sample export](examples/gravity-break.mp4).

Open [the scene file](examples/gravity-break.json). Change the second shot's title or the ball's final position, save, and run the demo again. Each run creates a separate draft under `.workspace/demo/`. The demo uses built-in shapes and requires no accounts or API keys.

## Make your own

Use the [creator workflow](docs/creator-workflow.md) for the brief, script review, shot plan, narration timing, and final viewing pass. It includes prompts you can paste into your assistant.

To let an MCP-capable assistant operate the editor, create an import folder with `mkdir -p imports`. Add the entry below to your client's stdio MCP configuration. Replace every `/absolute/path/to/reels-studio` with the location of this checkout. Launch Node directly. If the client cannot find Node, use the full path printed by `which node`.

```json
{
  "mcpServers": {
    "reels": {
      "command": "node",
      "args": ["/absolute/path/to/reels-studio/server.mjs"],
      "env": {
        "REELS_DATA_DIR": "/absolute/path/to/reels-studio/.workspace/studio",
        "REELS_IMPORT_ROOT": "/absolute/path/to/reels-studio/imports",
        "REELS_FONT": "/absolute/path/to/reels-studio/assets/Montserrat-Black.ttf"
      }
    }
  }
}
```

Reconnect the client and try this prompt

> Use the reels tools. Create a demo project, show me the opening frame with safe-zone guides, then change the hero's shirt to orange and show me the same frame. Wait for my feedback before rendering the full reel.

Each editor process needs its own data directory. The editor stores scenes, imported assets, and exports there. Your latest successful export is at `exports/<project-id>/video.mp4` inside that directory. Copy a version you want to keep before rendering another revision. Publishing is a separate creator step.

## Development

`npm test` runs the core suite, including a real stdio client handshake. Tests require Python 3. For render integration tests, install the optional Chromium backend and run

```sh
npm run browser:install
REELS_BLENDER_TEST=1 REELS_RENDER_TEST=1 npm test
```

Blender is the default. The optional Three.js backend can be selected for MCP with `REELS_RENDERER=three`.

## Included notices

Reels Studio code and the original example are licensed under [GPL-3.0-or-later](LICENSE). Copyright 2026 Endroe. The [Blender worker notice](LICENSE.blender-worker) is retained. The bundled Montserrat font is distributed under its [SIL Open Font License](assets/Montserrat-OFL.txt). Dependencies retain their respective licenses.