🎬 UU889-Drama - AI Short Drama Studio

A full-stack TypeScript platform that automates AI short-drama production

English | 简体中文 | 日本語 | 한국어

Features • Quick Start • aiask.me • Local image generation • Local ComfyUI video • Deployment

Text · image · video (Grok) with a single key — paste it into "Settings → aiask.me Quick Config" to write three recommended configs at once

UU889-Drama is a fork of chatfire-AI/huobao-drama (Huobao Drama) under the same CC BY-NC-SA 4.0 license. On top of a rebrand it adds aiask.me text / image / video providers, aiask.me Grok video and local ComfyUI video generation.

---

📖 Overview

UU889-Drama turns a novel into a finished short drama: script rewriting → character / scene / prop extraction → image generation → storyboard breakdown → video generation → FFmpeg export. It runs as an Electron desktop app (macOS / Windows), on a server, or in Docker.

frontend/   — Nuxt 3 + Vue 3 + TypeScript (plain CSS, no UI framework)
backend/    — Hono + Drizzle ORM + Mastra AI Agents + better-sqlite3
backend/workspace/skills/ — Agent skills (SKILL.md, editable in the UI)
desktop/    — Electron shell (main process + esbuild bundle + electron-builder dmg/exe)
data/       — Generated media and the SQLite database

---

✨ Features

• 🎭 Characters / scenes / props: AI extraction and de-duplication, batch reference-image generation
• 🎬 Storyboards: script → shot list with generated video prompts (@name maps to reference images)
• 🎥 Video: batch generation per shot with one-click retry of failures; FFmpeg episode export
• 🤖 4 Mastra agents: script_rewriter / extractor / storyboard_breaker / prompt_generator, with prompts and skills editable in Settings
• 🌐 Languages: UI and generated content in Chinese / English / Japanese / Korean / Vietnamese / German / French / Spanish / Portuguese (prompts and skills without a dedicated translation fall back to English)

🔌 Providers

Type	Providers
Text	aiask.me, OpenAI (compatible), Gemini, Volcengine, DeepSeek, Qwen, Claude, Grok (xAI)
Image	aiask.me (gpt-image / grok-imagine-image / gemini-image), Grok image (xAI), OpenAI, Gemini, Volcengine, local ComfyUI / Stable Diffusion WebUI / Fooocus
Video	aiask.me Grok video (grok-imagine-video-1.5), Grok video (xAI native), Google Veo, Runway, local ComfyUI, Volcengine Seedance 2.0, MiniMax H3, Alibaba Cloud Wan 3.0

---

🚀 Quick Start

Requirements: Node.js 20+ and npm 9+. SQLite and FFmpeg are bundled — nothing else to install.

git clone https://github.com/uu889/uu889-drama.git
cd uu889-drama

cd backend && npm install && npm run dev      # terminal 1: API at http://localhost:5679/api/v1
cd frontend && npm install && npm run dev     # terminal 2: UI at http://localhost:3013

Single-service mode:

cd frontend && npm run generate && cp -r .output/public dist   # the backend serves frontend/dist
cd ../backend && npm start                                      # open http://localhost:5679

⚙️ Environment variables

Variable	Default	Description
SQLITE_PATH	<repo>/data/uu889.sqlite3	SQLite database file
PORT	5679	Backend port
STORAGE_PATH	<repo>/data/static	Generated media directory
UU889_DATA_DIR	—	Data root injected by the desktop app
WORKSPACE_PATH	backend/workspace	Agent skills / prompts directory
FRONTEND_DIST	frontend/dist	Frontend build directory
FFMPEG_BIN / FFPROBE_BIN	bundled binaries	Custom ffmpeg / ffprobe paths
PUBLIC_BASE_URL	—	Public URL needed when Seedance references local video/audio
MODEL_INSTALLER_LOCAL	1	0 disables "this computer" mode of the one-click model download on server deployments (remote SSH mode stays available)
SUBTITLE_FONT	auto	Font file for burned-in subtitles; by default a system CJK font is found automatically (Microsoft YaHei on Windows, PingFang / Heiti on macOS, Noto CJK / WenQuanYi on Linux)
MODEL_INSTALLER_DETACHED	1	0 makes this-computer model downloads run inside the app instead of a detached background process (by default downloads keep going after UU889-Drama exits)
UU889_UPDATE_FEED	GitHub Releases latest.json	Custom update feed

API keys, base URLs and models are configured in Settings and stored in the database.

🔑 First run

1. Open Settings
2. Paste an aiask.me API key into aiask.me Quick Config (get one at aiask.me) to write text, image and video configs at once
3. Or add providers one by one with Manual templates (including local ComfyUI) and test connectivity

---

🔑 aiask.me Integration

aiask.me is an OpenAI-compatible AI API gateway. Use https://aiask.me as the base URL (https://aiask.me/v1 also works; /v1 is never doubled).

Type	Endpoint	Default models
Text	POST /v1/chat/completions	gpt-6-astra, gpt-5.5, deepseek-v4-pro
Image	POST /v1/images/generations (/v1/images/edits with references)	gpt-image-2, grok-imagine-image, gemini-3-pro-image
Video	POST /v1/videos → GET /v1/videos/{id} → GET /v1/videos/{id}/content	grok-imagine-video-1.5

Text requests only carry parameters each model family accepts: OpenAI reasoning models (o* / gpt-5* / gpt-6* / codex*) get no temperature and use max_completion_tokens; DeepSeek / GLM etc. get thinking disabled. Configure Gemini with the native Gemini provider.

Grok video (video task API)

• Create POST /v1/videos with model, prompt, mode, duration_seconds (1–15), ratio (1:1 16:9 9:16 4:3 3:4 3:2 2:3; other ratios snap to the closest) and video_resolution (480p / 720p / 1080p)
• Mode is chosen automatically:
  • no images → text_to_video (JSON)
  • first frame → image_to_video (multipart image)
  • first + last frame → first_last_frames (first_frame / last_frame)
  • shot reference images (characters / scenes / props) → multimodal_reference (repeated image[] files, up to 7); *-lite models fall back to image_to_video with the first image
  • 1080p is only used for text/image-to-video; other modes are capped at 720p
• Poll GET /v1/videos/{id}: in_progress (with queue.position while queued) → completed / failed / cancelled
• Download content_url (/v1/videos/{id}/content) with the same API key; the MP4 is saved under data/static/videos/

Grok video (xAI native API)

Settings → Video → Add and pick the Grok 视频（xAI 原生） template: use https://api.x.ai with an xAI API key, or https://aiask.me with an aiask.me key from a Grok group.

• Create POST /v1/videos/generations with model, prompt, duration (1–15 s), aspect_ratio (1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9 5:2) and resolution (480p / 720p / 1080p)
• Images: a first frame becomes image: {url} (xAI has no last-frame field; a lone last frame is used as the image); shot reference images become reference_images: [{url}] (up to 14 on grok-imagine-video-1.5, 7 otherwise; max 720p; non-1.5 models max 10 s), and @图片1name in the prompt is rewritten to xAI's <IMAGE_0>name
• Poll GET /v1/videos/{request_id}: pending → done / failed / expired
• Download video.url (xAI's temporary URL is fetched without the key; a gateway-rewritten /v1/videos/{id}/content gets the key)

---

🧩 More Official Providers

Pick the template under Settings → Text / Image / Video → Add, paste the provider's own API key and use Test to check it.

Provider	Template base URL	Notes
DeepSeek (text)	https://api.deepseek.com	deepseek-v4-pro / deepseek-v4-flash; thinking mode is switched off (thinking: {type: "disabled"}) so agent tool calls work
Qwen (text)	https://dashscope.aliyuncs.com/compatible-mode/v1	Alibaba Cloud Model Studio OpenAI-compatible mode; enable_thinking: false
Claude (text)	https://api.anthropic.com	Native Messages API (x-api-key); temperature / top_p are dropped for models that reject them (Opus 5.5, Sonnet 5.5, …)
Grok (text)	https://api.x.ai	grok-4.7 / grok-4.6 / grok-4.5
Grok image	https://api.x.ai	grok-imagine-image-2.0; /v1/images/generations with aspect_ratio, /v1/images/edits when the shot has a reference image
Google Veo (video)	https://generativelanguage.googleapis.com	Gemini API key; :predictLongRunning → operation polling → download with the key. 4 / 6 / 8 s, 16:9 or 9:16, 720p / 1080p; 1080p or reference images (up to 3; Lite models take the first one as the start frame) force 8 s
Runway (video)	https://api.dev.runwayml.com	X-Runway-Version: 2024-11-06; gen4.5 (2–10 s, text or image), gen4_turbo (image only, 5 / 10 s), veo3.1 / veo3.1_fast (4 / 6 / 8 s, first + last frame). The aspect ratio snaps to the closest supported pixel ratio; images over 5 MB are recompressed

---

🎨 Local Image Generation (ComfyUI / Stable Diffusion WebUI / Fooocus)

Settings → Image → Add and pick the template; the API key is usually empty. Test lists the models the service has — put those names in the model list.

Service	Default URL	API	Model name	Reference images
ComfyUI	http://127.0.0.1:8188	/prompt → /history/{id} → /view (same queue / cancel / lost-task handling as video)	checkpoint file name (the built-in template's ckpt_name is {{model}})	uploaded when a custom workflow references {{image}} / {{reference_image_N}}
Stable Diffusion WebUI (A1111 / Forge …)	http://127.0.0.1:7860	POST /sdapi/v1/txt2img (start with --api)	checkpoint name; default keeps the loaded model	not used
Fooocus (Fooocus-API)	http://127.0.0.1:8888	/v1/generation/text-to-image, or /v2/generation/text-to-image-with-ip with references → query-job polling	checkpoint file name; default keeps the default	sent as Image Prompts (IP-Adapter, up to 4)

• Size: the project size keeps its aspect ratio at about base-size² pixels, aligned to 64 (base 1024 for SDXL: 1920×1080 → 1344×768; 512 for SD1.5); Fooocus snaps to its closest built-in SDXL ratio
• Parameters: negative prompt (generic default), steps (25), CFG (7), SD WebUI sampler, Fooocus performance (Speed / Quality / Extreme Speed / Lightning / Hyper-SD) and styles
• ComfyUI image placeholders: {{prompt}} {{negative_prompt}} {{seed}} {{width}} {{height}} {{steps}} {{cfg}} {{model}} {{aspect_ratio}} {{image}} {{reference_image_1..6}}; the built-in template is Checkpoint + KSampler + SaveImage (SDXL / SD1.5)
• Auth: SD WebUI with --api-auth → API key user:password; Fooocus-API with --apikey → the same key
• Built-in ComfyUI templates: SDXL (default), SD 1.5, FLUX.1 dev fp8, FLUX.1 schnell fp8 — the settings page lists the model files, folders and download links, and can copy a template into the editor
• Auto-bind (ComfyUI): a workflow straight from Export (API) needs no placeholders; prompt / negative prompt, LoadImage references, seed, size and checkpoint are wired by node structure. Check workflow shows every binding and missing model files
• Prompt template: e.g. masterpiece, best quality, {{prompt}} for all three services, plus SD WebUI / Fooocus parameter and style presets
• Prompt translation: SD / SDXL / FLUX only understand English, so local image prompts in Chinese / Japanese / Korean are translated with the active text model first (can be turned off; falls back to the original)
• Read local models: list ComfyUI checkpoints / diffusion models / LoRAs, SD WebUI models and samplers, Fooocus models and styles, and click to fill
• Live progress: queue position, sampling step, ETA and download progress in the Tasks drawer and asset cards

---

🖥️ Local ComfyUI Video

UU889-Drama talks to ComfyUI's native HTTP API:

1. Start ComfyUI (default http://127.0.0.1:8188; from Docker use http://host.docker.internal:8188 and run ComfyUI with --listen 0.0.0.0)
2. Settings → Video → Add and pick the 本地 ComfyUI (local ComfyUI) template; the API key is optional (only for authenticating reverse proxies)
3. Workflow source:
   • Built-in template: Wan 2.2 TI2V 5B (text + image, default), Wan 2.2 I2V 14B (two-stage high / low noise), Wan 2.2 first-last frame 14B, Wan 2.2 T2V 14B, MiniMax H3 with native audio (20 steps / Turbo 8-step / Turbo 4-step 768p; fixed 24 fps, 17k+5 frames, 768 short edge; ComfyUI 0.30.0+); by VRAM: nine Wan 2.2 image-to-video 14B tiers — 12G / 16G (GGUF + 4-step LoRA, needs ComfyUI-GGUF, capped at 480p / 640p), 24G (fp8 + 4-step), 32G (fp8, 20 steps), 48G (fp16, 20 steps), 96G (fp16, 30 steps, up to 1080p), 141G / 192G / 288G (fp16, 40 steps, 1080p, longer shots as VRAM grows), IDs wan2.2-i2v-14b-<vram>g; and the same nine tiers for MiniMax H3 with audio, minimax-h3-<vram>g, on the reference-to-video (Ref2VA) model so the shot's scene / character / prop images are <Picture N> references and characters match your assets (first / last frames anchored with guide nodes; plus an untiered minimax-h3-r2v) — 12G / 16G / 24G pruned GGUF Q3 / Q4 / Q5 + 4-step Turbo (ComfyUI-GGUF; 12G capped at 480p), 32G official pruned int8 + 4-step (same as ComfyUI's template), 48G full int8 20 steps, 96G full int8 + int8 text encoder 25 steps, 141G / 192G / 288G full bf16 at 30 / 40 / 50 steps — with model files, folders and download links; a template ID in Models (e.g. wan2.2-i2v-14b) selects it
   • Custom workflow: paste the JSON from ComfyUI Export (API). No placeholders needed — with Auto-bind on (default) the prompt / negative prompt, first / last frame / references (LoadImage), seed, width / height, frames, FPS and diffusion model are wired automatically; hand-written placeholders win for their category
4. Models: a template ID, or model file names that replace the UNETLoader / CheckpointLoaderSimple values (high-noise-file|low-noise-file for the 14B pair)
5. Optional: FPS (empty = template / workflow value), steps / CFG (empty = keep the workflow; set = override every sampler, two-stage split rescaled), negative prompt, prompt template
6. Check workflow lists every node field → parameter binding and missing model files

Live progress: the backend subscribes to ComfyUI's WebSocket (/ws?clientId=, the same client_id is sent with /prompt); the video panel, shot list and Tasks drawer show reference upload → queue position → current node → sampler stage and step → ETA → decode / encode → download bytes, with an activity log. Without WebSocket it falls back to queue position and elapsed time.

Flow: POST /upload/image (reference images used by the workflow) → POST /prompt → poll GET /history/{prompt_id} → download via GET /view?filename=….

Placeholders replaced before submitting (a field that is exactly one placeholder gets a typed value, e.g. "{{seed}}" becomes a number):

Placeholder	Meaning
{{prompt}} / {{negative_prompt}}	Shot video prompt / negative prompt
{{seed}}	Random seed (different every run)
{{width}} / {{height}}	From aspect ratio and resolution tier, aligned to 32 (720p 16:9 = 1248×704)
{{duration}} / {{fps}} / {{frames}}	Seconds / frame rate / frame count aligned to 4n+1 (5 s at 24 fps = 121)
{{aspect_ratio}} / {{resolution}} / {{model}}	Aspect ratio / resolution tier / selected model name
{{image}}	First frame, or the first reference image when there is none
{{first_frame}} / {{last_frame}}	Explicit first / last frame
{{reference_image_1}} … {{reference_image_9}}	Shot reference images

When an image placeholder has no media, the node using it (e.g. LoadImage), any node that only depends on it, and links pointing at them are removed — so a workflow with an optional start_image (like Wan 2.2 TI2V) handles both text-to-video and image-to-video. The workflow must save a video (SaveVideo, VHS_VideoCombine, …).

---

🎬 Dialogue, Consistency and Continuity

Fixes for the three most common AI-video problems:

• Improvised speech / gibberish (5 s of lines in a 10 s shot, the model makes up the rest): shot duration is derived from the lines and auto-corrected during breakdown; the workbench shows "lines X s / shot Y s" with a one-click fix; generation adds a dialogue-control block — only these lines, word for word, silence the rest of the time
• Faces, sets and style drifting: generation adds character locks (reference + look / outfit text), scene and style consistency
• Shots that don't cut together (blocking errors, broken conversation rhythm): storyboards now carry blocking (opening positions + end state) and conversations follow shot / reverse shot and the 180-degree rule; the next shot in the same scene opens from the previous shot's last frame (first frame for ComfyUI / MiniMax / Runway, reference 1 elsewhere), and batch generation runs same-scene shots in order

Each can be toggled in the video panel.

---

🖌️ Visual Style → Local Models

The project's visual style (3D, anime cel, Ghibli, watercolor, American comic, guofeng 2.5D, webtoon, black-and-white manga) can drive model selection for local services. In a ComfyUI / SD WebUI / Fooocus config, turn on Visual style → models; generation then switches to the style's checkpoint, style LoRA, trigger words and recommended params:

• SD WebUI (models from Civitai): override_settings.sd_model_checkpoint + <lora:name:weight> in the prompt
• ComfyUI image / Fooocus (models from Hugging Face): checkpoint written into CheckpointLoaderSimple + an injected LoraLoader; Fooocus gets base_model_name + loras + matching Fooocus styles
• ComfyUI video: Wan 2.2 I2V 14B from the styled first frame, with a Wan 14B style LoRA on the low-noise model (skipped on TI2V 5B / MiniMax H3)

Per-style overrides, an installed-file check and copy-ready download commands (bash / PowerShell, Civitai token, hf-mirror) are on the settings page. Every model carries a license level — ✅ commercial OK, ⚠️ conditions (e.g. no paid generation service, credit required, re-upload of unclear origin), ⛔ non-commercial / author permission needed. Defaults never use ⛔ models; GuoFeng4, Juggernaut and similar are listed only as flagged alternatives. Full mapping tables, license notes, API examples and download scripts: docs/style-models.md.

One-click / automatic model download: the "One-click model download" section in the same dialog checks which files each style needs and downloads the missing ones into the program's model folders —

• this computer (Windows / macOS / Linux) or remote over SSH (Windows / macOS / Linux; password or key/certificate login on macOS and Linux — OpenSSH, PEM, PKCS#8 and PuTTY .ppk keys); detects SD WebUI / ComfyUI / Fooocus install folders or lets you pick one
• sources in order: Hugging Face → hf-mirror.com → Civitai → Civitai mirror (CivArchive); Civitai models with an identical (same SHA256) copy on Hugging Face come from HF without a Civitai key
• progress bars (overall + per file speed / ETA / source), resume, SHA256 verification, pause / resume / cancel
• background ("offline") downloads: local downloads continue with the page closed and resume after restart; remote downloads run on the remote machine and finish even if UU889-Drama is closed
• optional "download missing models when generating": generation waits for the missing files, then starts

---

📦 Deployment

🖥️ Desktop app

Download: GitHub Releases (Windows .exe, macOS Apple Silicon / Intel .dmg)

Publishing a release: bump version in desktop/package.json and backend/package.json, commit, then push an annotated tag — GitHub Actions builds Windows + both macOS architectures and uploads the installers and the latest.json update feed:

git tag -a v1.0.1 -m "Release notes"
git push origin v1.0.1

Build locally:

npm run build:frontend   # repo root
cd desktop && npm install
npm run dist        # macOS dmg (arm64 + Intel) + updater zip
npm run dist:win    # Windows NSIS installer (win-x64)

• User data: macOS ~/Library/Application Support/UU889Drama/, Windows %APPDATA%\UU889Drama\
• Unsigned macOS builds reported as "damaged": run the bundled 如提示已损坏请双击我.command or sudo xattr -cr /Applications/UU889Drama.app
• In-app updates: installed apps read latest.json from the latest GitHub Release and offer the upgrade
• After changing the logo, run node desktop/scripts/make-brand-icons.mjs to regenerate every icon from docs/images/logo.svg

🏭 Server

cd frontend && npm run generate && cp -r .output/public dist && cd ..
cd backend && npm start

Put Nginx in front and serve /static/ straight from data/static/ for best performance.

🐳 Docker

cp .env.example .env                              # set WATCHTOWER_TOKEN
UU889_VERSION=1.0.0 docker compose up -d --build  # open http://localhost:5679

• Data lives in the uu889-data volume mounted at /app/data
• Updating a source build: git pull && UU889_VERSION=<new version> docker compose up -d --build
• One-click updates (optional): the bundled Watchtower sidecar can only pull an image that exists in a registry. Publish the image (command below) and point image in docker-compose.yml at it to make "Settings → About → Update now" work; remove the app's UU889_WATCHTOWER_* variables to keep only the new-version notice
• Multi-arch image: docker buildx build --platform linux/amd64,linux/arm64 --build-arg UU889_VERSION=x.y.z -t <your-registry>/uu889-drama:x.y.z --push .

---

📝 FAQ

aiask.me video stays "generating"? Grok video is an asynchronous job; the backend polls every 10 seconds. failed / cancelled results show the upstream error immediately.

ComfyUI says the workflow is in UI format? You pasted a regular save (with nodes / links). Use Export (API) instead.

ComfyUI reports UNETLoader … not found? Download the models used by the built-in template or paste your own workflow.

ComfyUI fails with CLIPLoader … incomplete metadata, file not fully covered? The model file is truncated or corrupt, usually from an interrupted download; the error names the file and its folder. For the built-in template it is the text encoder: delete ComfyUI/models/text_encoders/umt5_xxl_fp8_e4m3fn_scaled.safetensors, download it again from Hugging Face Comfy-Org/Wan_2.2_ComfyUI_Repackaged (split_files/text_encoders, 6,735,906,897 bytes) and restart ComfyUI.

---

🎨 Tech Stack

• Backend: Node.js 20+, Hono, Drizzle ORM + better-sqlite3 (WAL), Mastra + AI SDK, FFmpeg, Sharp
• Frontend: Nuxt 3 (SPA), Vue 3 + TypeScript, plain CSS, Lucide, vue-i18n
• Desktop: Electron (backend in a utilityProcess), esbuild, electron-builder

cd backend && npm run typecheck && node --import tsx --test "tests/*.test.ts"
cd ../frontend && npm run generate

---

📄 License & Credits

UU889-Drama is derived from chatfire-AI/huobao-drama (Huobao Drama); the original authors retain copyright in their work and the full upstream commit history is preserved in this repository.

As required by the upstream license, this project is also released under CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike 4.0 International):

• ✅ Free for personal, research and non-commercial use
• ✅ Modification and redistribution allowed with attribution under the same license
• ❌ No commercial use without written permission from the original authors