# DramaClaw

> Self-hosted production line that takes a script through storyboards to a finished film

- Category: Multimodal Generation / Video Generation
- Language: Python
- Licence: Elastic License 2.0
- Repository: https://github.com/dramaclaw/dramaclaw
- Website: https://dramaclaw.ai
- Canonical page: https://ai-tldr.dev/tools/dramaclaw/

## In short

DramaClaw is a source-available production line for AI drama and, increasingly, for any visual story told with generative models. It has two faces sharing one asset library and one agent. It sits in the Video Generation category of the Multimodal Generation tools and is open-source, written in Python and licensed Elastic License 2.0.

## Overview

DramaClaw is a source-available production line for AI drama and, increasingly, for any visual story told with generative models. It has two faces sharing one asset library and one agent. XiaHua is an infinite node canvas — 18 node types covering upload, image generation and editing, storyboard generation, script, beat context, video, video compose, audio, style, skill, group, 360° panorama, 3D world and export — where each node keeps its own generation history and anything you like can be promoted back into a series. Series (XiaJi) is the structured pipeline: ingest, plan, produce, deliver, each step with its own interface, skippable and resumable from a checkpoint.

The pipeline is built around what a drama actually needs. Structured ingest builds episodes, characters and scenes straight from a manuscript or screenplay (Fountain supported) with no knowledge graph or embeddings required. The XiaTang asset library keeps characters, scenes, props and voices organised with stable identities across episodes and per-episode variants. Then come beat-driven storyboards and first frames with grid splitting and image-pool selection, emotion-aware voice-over, episode assembly, and video-plus-subtitle export with a full asset pack. A Task Center shows status, progress and logs with cancel, retry and resume-from-checkpoint for long runs. Director World turns an image into a 3D Gaussian Splat set and 360° panoramas so a location — and the camera placement in it — stays consistent across shots.

Nothing runs models locally: all text, image, video and audio inference goes through an OpenAI-compatible gateway, either the official RelayClaw service or the bundled `dramaclaw-gateway` pointed at providers you configure, which keeps the local footprint at roughly 2 vCPU and 4 GB. There is no Postgres, Redis, Celery or Ray — tasks run in-process and state lives on the filesystem as SQLite plus files. Xia Director, the built-in agent, checks project progress, advances script and shot tasks and audits deliverable completeness, and exposes DramaClaw to Claude Code, Codex or any MCP client over a loopback-only MCP server. The licence is Elastic License 2.0: run it, modify it and sell what you build, with a "Powered by DramaClaw" credit requested and hosted SaaS resale excluded.

## What it does

- XiaHua infinite canvas with 18 node types, per-node generation history, canvas tabs, minimap, outline and revision history
- Image tooling — generate, edit, redraw, outpaint, relight, upscale, multi-view, reverse-prompt — plus a style wall of 45 short-drama looks
- Video tooling — text/image/keyframe to video, omni-reference generation from files, web links and canvas nodes, edit, erase, upscale, audio separation, camera templates
- Series pipeline: structured ingest from manuscript or Fountain screenplay, asset library with stable character identities, beat planning, multi-episode arcs and script generation
- Storyboards and first frames, emotion-aware speech, episode assembly and video + subtitle export with the full asset pack
- Director World — image to 3D Gaussian Splat sets and 360° panoramas so location, blocking and camera stay consistent across shots
- Xia Director agent that audits progress and deliverables, plus a loopback-only MCP server for Claude Code, Codex and other MCP clients
- Model-neutral by design: every model reached through an OpenAI-compatible gateway, official or self-hosted, with no local datastores to run

## Getting started

Docker is the recommended path. DramaClaw needs about 2 vCPU and 4 GB of RAM because inference happens on the gateway, not locally; only the optional world extra (voxel and panorama-to-3D) needs a GPU. Ports 8080 (web UI), 8780 (REST API) and 3000 (bundled gateway admin, host-only by default) are used.

1. Clone and build with Docker

   The default compose file builds all three services from two sibling checkouts — DramaClaw and the bundled gateway.

```bash
git clone https://github.com/dramaclaw/dramaclaw.git
git clone https://github.com/dramaclaw/dramaclaw-gateway.git
cd dramaclaw

cp .env.example .env
# Edit .env — set PROMPT_EXPORT_PASSWORD to a non-default value.

docker compose up -d --build
```

2. Or pull published images

   Every GitHub release publishes multi-arch (amd64/arm64) images, so no gateway clone is needed.

```bash
docker compose -f docker-compose.release.yml up -d
```

3. Point it at models

   Open http://localhost:8080 and go to Settings → Model Config. Official mode takes a DC key from relayclaw.cdnfg.com and needs no model mapping. Custom mode initialises the bundled newapi gateway in one click so you can add your own upstream channels. Hybrid mode uses the official models for the main pipeline and the bundled gateway for extras such as a local ComfyUI video workflow.

4. Run from source instead

   Local development needs Python 3.11–3.12, uv and ffmpeg. The frontend runs separately with `cd frontend && pnpm install && pnpm dev`.

```bash
git clone https://github.com/dramaclaw/dramaclaw.git
cd dramaclaw

uv sync
cp .env.example .env && $EDITOR .env

uv run novelvideo api --port 8780
```

5. Run the gateway for custom mode

   Custom and hybrid modes expect a gateway on 127.0.0.1:3000 whose SQLite file is ./state/newapi/one-api.db — which is what "Initialize" in Settings writes to.

```bash
mkdir -p state/newapi
docker run -d --name dramaclaw-gateway -p 127.0.0.1:3000:3000 \
  -v "$PWD/state/newapi:/data" \
  claymorelab/dramaclaw-gateway:v1.0.0-rc.24-dramaclaw.1
```

## When to use it

- Reach for it to take a novel or screenplay through episodes, characters, storyboards and shots to an exported cut in one system
- Reach for it when character and location identity must stay consistent across many shots and episodes
- Reach for it when you want a free node canvas for generative media that still understands beats, episodes and shots
- Reach for it to keep a video pipeline self-hosted and model-neutral, swapping providers behind an OpenAI-compatible gateway