Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+data/bgm/calm.mp3 filter=lfs diff=lfs merge=lfs -text
+data/bgm/epic.mp3 filter=lfs diff=lfs merge=lfs -text
+data/bgm/sad.mp3 filter=lfs diff=lfs merge=lfs -text
+data/bgm/tense.mp3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+venv/
+
+# Environment
+.env
+
+# Workdir (runtime output)
+workdir/
+
+# Test outputs (generated images, videos, audio — large binary files)
+test_*_output/
+test_tts_calibration/
+test_*.png
+
+# IDE / Claude
+.vscode/
+.idea/
+.claude/
+
+# Node
+node_modules/
+.next/
+
+# OS
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,51 @@
+FROM python:3.12-slim
+
+# Install FFmpeg + git
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ffmpeg git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+WORKDIR /app
+
+# Install Python dependencies (cache layer)
+RUN pip install --no-cache-dir \
+    "fastapi[standard]>=0.115.0" \
+    "uvicorn[standard]>=0.32.0" \
+    "sqlalchemy[asyncio]>=2.0.0" \
+    "aiosqlite>=0.20.0" \
+    "pydantic>=2.0.0" \
+    "pydantic-settings>=2.0.0" \
+    "python-jose[cryptography]>=3.3.0" \
+    "passlib[bcrypt]>=1.7.4" \
+    "python-multipart>=0.0.9" \
+    "httpx>=0.27.0" \
+    "edge-tts>=6.1.0" \
+    "Pillow>=10.0.0" \
+    "pymupdf>=1.24.0" \
+    "opencv-python-headless>=4.9.0" \
+    "numpy>=1.26.0" \
+    "pocket-tts>=0.1.0" \
+    "huggingface-hub>=0.20.0" \
+    "scipy>=1.12.0" \
+    "safetensors>=0.4.0" \
+    "pyarrow>=15.0.0" \
+    "soundfile>=0.12.0"
+
+# Copy application code
+COPY app/ app/
+COPY data/*.json data/
+COPY scripts/ scripts/
+COPY deploy/start.sh .
+RUN chmod +x start.sh
+
+# Create directories with correct permissions
+RUN mkdir -p /data/workdir/projects /data/genshin_voices /data/animevox_voices && \
+    chown -R user:user /app /data
+
+USER user
+
+EXPOSE 7860
+
+CMD ["./start.sh"]

RESEARCH.md

@@ -0,0 +1,953 @@
+# Web Novel to Anime -- Complete Research Report
+
+> Generated: 2026-02-27 | Status: Comprehensive research across 5 domains
+
+---
+
+## TABLE OF CONTENTS
+
+1. [Executive Summary & Verdict](#1-executive-summary--verdict)
+2. [PLAN A: Free Video Generation APIs](#2-plan-a-free-video-generation-apis)
+3. [PLAN B: The Hybrid Pipeline](#3-plan-b-the-hybrid-pipeline)
+   - 3.1 [Image Generation (Free APIs)](#31-image-generation-free-apis)
+   - 3.2 [Character Consistency Solutions](#32-character-consistency-solutions)
+   - 3.3 [TTS / Voice Acting](#33-tts--voice-acting)
+   - 3.4 [Interpolation & Animation](#34-interpolation--animation)
+   - 3.5 [Video Assembly](#35-video-assembly)
+4. [NLP & Intelligence Layer](#4-nlp--intelligence-layer)
+5. [System Architecture](#5-system-architecture)
+6. [Your Hardware Advantage: Intel Arc + OpenVINO](#6-your-hardware-advantage)
+7. [Implementation Roadmap](#7-implementation-roadmap)
+8. [Monetization Strategy](#8-monetization-strategy)
+9. [Final Recommendation](#9-final-recommendation)
+
+---
+
+## 1. EXECUTIVE SUMMARY & VERDICT
+
+### The Honest Truth About Plan A (Pure Video Generation)
+
+**Plan A is NOT viable today for free, automated, anime-quality video generation.** Here's why:
+
+| Service | Free API? | Anime Quality? | Programmatic? | Verdict |
+|---------|-----------|----------------|---------------|---------|
+| Wan 2.1 (Alibaba) | HuggingFace free inference (slow, queued) | Good anime style | Yes via HF API | **Best free option but too slow/unreliable for production** |
+| CogVideoX (Tsinghua) | HuggingFace free inference | Decent | Yes via HF API | Queue times make it impractical |
+| Kling AI | Free web tier, NO free API | Good | No API on free tier | Unusable for automation |
+| Runway Gen-3 | No free API | Good | Paid API only | Too expensive |
+| Pika Labs | No free API | Decent | No API access | Unusable |
+| Minimax (Hailuo) | Limited free API credits | Good | Yes | Credits run out fast |
+| Luma Dream Machine | No free API | Decent | Paid only | Unusable |
+| Stable Video Diffusion | Open source | Basic (image-to-4sec) | Yes locally | Too short, needs GPU |
+| AnimateDiff | Open source | Good anime | Yes locally | **Needs 8GB+ VRAM** |
+| Google Veo | No public API | Unknown | No | Not available |
+
+**The core problem**: Video generation models need massive GPU power (12-24GB VRAM minimum). Free API tiers either:
+- Don't exist (Runway, Pika, Luma)
+- Have no programmatic access (Kling free tier)
+- Are too slow/queued on HuggingFace (Wan, CogVideoX -- minutes of queue time per 4-second clip)
+- Produce only 3-6 second clips (not episodes)
+
+**However**, there ARE some usable free options for short video clips via HuggingFace that could supplement Plan B (see section 2 below).
+
+### Why Plan B Is Actually BETTER
+
+Plan B (Image + TTS + Interpolation) is not just a fallback -- it's the **superior approach** because:
+
+1. **Character consistency** -- Image gen with IP-Adapter keeps characters looking the same. Video gen cannot do this yet.
+2. **Controllability** -- You control every frame, every camera angle, every expression. Video gen is a black box.
+3. **This IS how anime works** -- Real anime uses 8-12 unique drawings per second with camera movements. That's literally Plan B.
+4. **Free and unlimited** -- Multiple free image gen APIs exist with generous limits.
+5. **Your Intel Arc GPU helps** -- OpenVINO acceleration makes interpolation and animation feasible on your hardware.
+
+---
+
+## 2. PLAN A: FREE VIDEO GENERATION APIs
+
+Despite video gen not being viable as the primary approach, here's every free option found:
+
+### 2.1 Wan 2.1 (Best Free Video Gen Available)
+
+- **Source**: Alibaba's open-source video generation model
+- **Access**: HuggingFace Inference API (free, queued) + HuggingFace Spaces
+- **Quality**: Excellent anime-style output, one of the best for anime
+- **Clip Length**: 4-8 seconds
+- **Resolution**: Up to 720p
+- **Limitations**: Queue wait times of 2-15 minutes per clip. Rate limited. Not reliable for batch processing.
+- **Programmatic access**:
+```python
+from huggingface_hub import InferenceClient
+client = InferenceClient(token="YOUR_HF_TOKEN")
+
+# Text-to-video
+video = client.text_to_video(
+    "anime girl with silver hair walking through a fantasy forest, detailed anime style",
+    model="Wan-AI/Wan2.1-T2V-14B"
+)
+with open("output.mp4", "wb") as f:
+    f.write(video)
+```
+- **Or via Gradio Spaces**:
+```python
+from gradio_client import Client
+client = Client("Wan-AI/Wan2.1-T2V-14B")
+result = client.predict(prompt="...", api_name="/generate")
+```
+- **Verdict**: Usable for generating occasional hero clips (opening shots, climactic moments). NOT for generating full episodes.
+
+### 2.2 CogVideoX (Tsinghua)
+
+- **Access**: HuggingFace Inference API + Spaces
+- **Quality**: Good, less anime-specific than Wan
+- **Clip Length**: 6 seconds
+- **Programmatic access**: Same pattern as Wan via HF
+- **Verdict**: Backup to Wan 2.1
+
+### 2.3 Stable Video Diffusion (Stability AI)
+
+- **Access**: Open source, can run locally
+- **What it does**: Image-to-video (takes a still image, adds subtle motion)
+- **Clip Length**: 3-4 seconds
+- **Hardware**: Needs ~6GB VRAM minimum. **Might work on Intel Arc via OpenVINO** (untested but theoretically possible)
+- **Verdict**: Could complement Plan B by adding subtle motion to generated keyframes. Worth testing on Intel Arc.
+
+### 2.4 Free Cloud GPU Options for Running Video Models
+
+| Platform | Free GPU | GPU Type | Time Limit | Video Gen Feasible? |
+|----------|----------|----------|------------|-------------------|
+| Google Colab | Yes | T4 (15GB VRAM) | ~4hrs/day | **Yes** -- can run AnimateDiff, Wan 2.1 small |
+| Kaggle | Yes | T4x2 or P100 | 30hrs/week | **Yes** -- best free option |
+| Lightning.ai | Yes | T4 | 22hrs/month | Marginal |
+| Paperspace | Free tier | M4000 (8GB) | Limited | Tight but possible |
+
+**Google Colab + Kaggle Strategy**: Use Kaggle's 30 hours/week to batch-generate video clips. AnimateDiff on a T4 can produce ~4 seconds of anime video per 30-60 seconds of compute. That's about 120-240 4-second clips per week = ~8-16 minutes of video content.
+
+### 2.5 Recommended Use of Video Gen (Hybrid with Plan B)
+
+```
+Plan B generates 95% of the episode (images + camera + TTS + interpolation)
+    |
+    v
+For KEY MOMENTS (5% of episode):
+    - Opening/ending sequence → Wan 2.1 via HuggingFace
+    - Dramatic reveals → AnimateDiff via Kaggle/Colab
+    - Action climaxes → CogVideoX via HuggingFace
+    |
+    v
+These premium clips are spliced into the Plan B video
+```
+
+---
+
+## 3. PLAN B: THE HYBRID PIPELINE
+
+### 3.1 Image Generation (Free APIs)
+
+#### TOP TIER: Truly Free with Good Anime Quality
+
+**1. Together AI -- FLUX.1 (Best Overall)**
+- **Free**: $5 credits on signup (~500 images). Periodically refreshed for active users.
+- **Quality**: FLUX produces excellent anime art with strong prompt adherence
+- **API**:
+```python
+from together import Together
+client = Together(api_key="YOUR_KEY")
+
+response = client.images.generate(
+    model="black-forest-labs/FLUX.1-schnell-Free",  # Free model
+    prompt="anime girl, silver hair, blue eyes, holding a sword, fantasy forest background, detailed anime illustration",
+    width=1024, height=768, n=1
+)
+image_url = response.data[0].url
+```
+- **Anime-specific**: FLUX.1-schnell is fast and free. Excellent prompt following.
+
+**2. HuggingFace Inference API -- Stable Diffusion XL / FLUX**
+- **Free**: Rate-limited (rough estimate: 100-1000 requests/day depending on model load)
+- **Models available**: SDXL, FLUX, SD 1.5 anime finetunes
+- **API**:
+```python
+from huggingface_hub import InferenceClient
+client = InferenceClient(token="YOUR_HF_TOKEN")
+
+image = client.text_to_image(
+    "1girl, silver hair, blue eyes, anime style, masterpiece, best quality",
+    model="stabilityai/stable-diffusion-xl-base-1.0"
+)
+image.save("output.png")
+
+# Anime-specific model:
+image = client.text_to_image(
+    "1girl, silver hair, detailed anime illustration",
+    model="cagliostrolab/animagine-xl-3.1"  # Top anime SDXL model
+)
+```
+- **Key anime models on HF**: `animagine-xl-3.1`, `CounterfeitXL`, `BluePencilXL`
+
+**3. Stability AI Free Tier**
+- **Free**: Limited free credits on signup
+- **Models**: SDXL, SD3, Stable Image Core
+- **API**:
+```python
+import requests
+
+response = requests.post(
+    "https://api.stability.ai/v2beta/stable-image/generate/sd3",
+    headers={"Authorization": f"Bearer {api_key}"},
+    files={"none": ""},
+    data={
+        "prompt": "anime style illustration, young warrior...",
+        "output_format": "png",
+        "model": "sd3.5-large",
+    }
+)
+```
+
+**4. Pollinations.ai (Completely Free, No API Key)**
+- **Free**: 100% free, no signup, no API key needed
+- **Quality**: Uses FLUX under the hood
+- **API**:
+```python
+import requests
+import urllib.parse
+
+prompt = urllib.parse.quote("anime girl, silver hair, fantasy setting, detailed illustration")
+url = f"https://image.pollinations.ai/prompt/{prompt}?width=1024&height=768&model=flux"
+response = requests.get(url)
+with open("output.png", "wb") as f:
+    f.write(response.content)
+```
+- **Limits**: No hard limits documented, but be respectful with rate
+- **Verdict**: **Best for prototyping and early development. Zero friction.**
+
+**5. Google Colab / Kaggle -- Run Your Own**
+- Run SDXL, FLUX, or anime-specialized models on free T4 GPUs
+- Full control over model selection, LoRA, IP-Adapter, ControlNet
+- 30 hrs/week on Kaggle = ~3,000-5,000 images per week
+- This is the **production-grade free option**
+
+#### Anime-Specialized Models (All Free/Open Source)
+
+| Model | Base | Anime Quality | Best For |
+|-------|------|---------------|----------|
+| Animagine XL 3.1 | SDXL | Excellent | General anime |
+| CounterfeitXL | SDXL | Excellent | Detailed anime |
+| BluePencilXL | SDXL | Very Good | Soft anime style |
+| Anything V5 | SD 1.5 | Good | Classic anime |
+| NovelAI anime model | SD 1.5 | Excellent | Light novel style |
+| Pony Diffusion XL | SDXL | Good | Stylized anime |
+
+### 3.2 Character Consistency Solutions
+
+This is **THE hardest problem** in the entire pipeline. Every image gen call produces a different-looking character.
+
+#### Solution 1: IP-Adapter (Recommended Primary)
+
+IP-Adapter takes a reference image and forces new generations to match the character's appearance.
+
+- **How**: Generate one "canonical" image of each character, then use it as reference for ALL subsequent images
+- **Where to run**: Kaggle/Colab with ComfyUI, or via API services that support it
+- **Quality**: ~70-85% consistency (face may drift slightly)
+- **ComfyUI workflow on Kaggle**:
+```python
+# In a Kaggle notebook:
+# 1. Install ComfyUI
+# 2. Load SDXL + IP-Adapter
+# 3. Provide reference image + new pose/scene prompt
+# 4. Get consistent character in new situation
+```
+
+#### Solution 2: PuLID / InstantID (Best for Face Consistency)
+
+- Specifically designed to maintain facial identity across images
+- Takes a single face reference and locks facial features
+- Available as ComfyUI nodes
+- Run on Kaggle/Colab
+
+#### Solution 3: Character Sheet + Reference Technique
+
+1. First, generate a character reference sheet (front/side/3-quarter views)
+2. Use this sheet as IP-Adapter reference for all subsequent generations
+3. This is how professional anime production works
+
+```python
+CHARACTER_SHEET_PROMPT = """
+character reference sheet, multiple views, front view, side view,
+three-quarter view, same character, {character_description},
+anime style, white background, character turnaround,
+masterpiece, best quality
+"""
+```
+
+#### Solution 4: LoRA Training (Most Consistent, More Work)
+
+- Train a small LoRA model on 10-20 images of a specific character design
+- Then use this LoRA every time you generate that character
+- Can be done for free on Kaggle (LoRA training takes ~20-30 minutes on T4)
+- Most consistent results but requires upfront work per character
+
+#### Solution 5: StoryDiffusion (Emerging Research)
+
+- Research project specifically designed for consistent characters across comic/manga panels
+- Maintains character identity without LoRA training
+- Still experimental but very promising for this exact use case
+
+#### Recommended Strategy:
+
+```
+1. Generate character reference sheet (one-time per character)
+2. Use IP-Adapter + PuLID for all subsequent images
+3. For protagonist/main characters: train a quick LoRA on Kaggle
+4. Store all reference images in character database
+5. Include character visual description in EVERY prompt
+```
+
+### 3.3 TTS / Voice Acting
+
+#### PRIMARY: Edge TTS (Unlimited, Free, Great Quality)
+
+```python
+pip install edge-tts
+```
+
+- **Cost**: Completely free, no API key, no account
+- **Limits**: Effectively unlimited
+- **Emotion support**: SSML with styles: `cheerful`, `sad`, `angry`, `excited`, `terrified`, `whispering`, `shouting`, and more
+- **Voices**: 300+ voices, including Japanese voices for anime feel
+- **Code**:
+```python
+import edge_tts
+import asyncio
+
+async def speak(text, voice="en-US-AriaNeural", style="cheerful", output="out.mp3"):
+    if style:
+        ssml = f"""
+        <speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis'
+          xmlns:mstts='https://www.w3.org/2001/mstts' xml:lang='en-US'>
+          <voice name='{voice}'>
+            <mstts:express-as style='{style}' styledegree='1.5'>
+              {text}
+            </mstts:express-as>
+          </voice>
+        </speak>"""
+        communicate = edge_tts.Communicate(ssml)
+    else:
+        communicate = edge_tts.Communicate(text, voice)
+    await communicate.save(output)
+
+asyncio.run(speak("I won't let you down!", style="excited"))
+```
+
+- **Recommended voice assignments**:
+```python
+CHARACTER_VOICES = {
+    "narrator":      {"voice": "en-US-AriaNeural",  "style": "narration-professional"},
+    "male_hero":     {"voice": "en-US-GuyNeural",   "style": "chat"},
+    "female_lead":   {"voice": "en-US-JennyNeural", "style": "cheerful"},
+    "villain":       {"voice": "en-US-DavisNeural", "style": "angry"},
+    "old_mentor":    {"voice": "en-US-TonyNeural",  "style": "calm"},
+    "child":         {"voice": "en-US-SaraNeural",  "style": "friendly"},
+    # Japanese voices for anime feel:
+    "jp_female":     {"voice": "ja-JP-NanamiNeural", "style": None},
+    "jp_male":       {"voice": "ja-JP-KeitaNeural",  "style": None},
+}
+
+EMOTION_TO_STYLE = {
+    "happy": "cheerful",    "sad": "sad",         "angry": "angry",
+    "scared": "terrified",  "excited": "excited",  "calm": "calm",
+    "whisper": "whispering", "shout": "shouting",  "love": "affectionate",
+    "nervous": "embarrassed",
+}
+```
+
+#### SECONDARY: Azure TTS (500K chars/month free, BEST emotion system)
+
+- Same voices as Edge TTS but with full API control
+- `styledegree` (0.01 to 2.0) for emotion intensity
+- Role tags: `Girl`, `Boy`, `YoungAdultFemale`, `OlderAdultMale`, `SeniorFemale`
+- Requires Azure account (free tier, credit card on file but charges nothing)
+
+#### SPECIAL: Bark by Suno (Local, CPU, Sound Effects)
+
+- Open source, runs on CPU (slow: ~30-90s per 10s of audio)
+- **Unique feature**: Inline sound effect tags:
+  - `[laughs]`, `[sighs]`, `[gasps]`, `[clears throat]`
+  - Great for moments Edge TTS can't handle
+- Use for 5-10% of lines that need sound effects
+- Batch process overnight
+
+```python
+os.environ["SUNO_USE_SMALL_MODELS"] = "True"
+os.environ["SUNO_OFFLOAD_CPU"] = "True"
+
+from bark import generate_audio, SAMPLE_RATE
+audio = generate_audio("[sighs] I thought we were friends... [laughs nervously]",
+                       history_prompt="v2/en_speaker_6")
+```
+
+#### BACKUP: Piper TTS (Local, CPU, Real-Time)
+
+- Designed specifically for CPU -- runs in real-time on your hardware
+- No emotion control but perfect for bulk narration
+- Use as offline fallback when internet is unavailable
+
+#### Total Free Monthly Capacity:
+
+| Service | Free Chars/Month | Emotion | Speed |
+|---------|-----------------|---------|-------|
+| Edge TTS | **Unlimited** | Good SSML | Fast |
+| Azure TTS | **500,000** | **Best** | Fast |
+| Bark (local) | **Unlimited** | **Excellent** ([laughs] etc.) | Slow |
+| Piper (local) | **Unlimited** | None | Real-time |
+
+### 3.4 Interpolation & Animation
+
+#### Frame Interpolation: RIFE (Primary Tool)
+
+Takes 2 keyframe images and generates smooth intermediate frames.
+
+```
+Frame A → [RIFE generates 7 in-between frames] → Frame B
+Result: 9 frames of smooth animation from just 2 images
+```
+
+- **Best option for your hardware**: `rife-ncnn-vulkan-python`
+  - Uses Vulkan backend -- **works natively on Intel Arc**
+  - No OpenVINO conversion needed
+  - Fast: near real-time at 512x512
+
+```bash
+pip install rife-ncnn-vulkan-python
+```
+```python
+from rife_ncnn_vulkan_python import Rife
+rife = Rife(gpuid=0)  # Uses Vulkan on Intel Arc
+mid_frame = rife.process(img0, img1)  # Returns interpolated frame
+```
+
+- **Alternative**: RIFE via OpenVINO (potentially faster but requires model conversion)
+- **Fallback**: FILM by Google (better for large motion gaps, runs on CPU via TensorFlow)
+
+#### Image Animation: SadTalker (For Talking Faces)
+
+Takes character image + TTS audio → outputs video of character talking with lip sync.
+
+- **CPU mode**: `--cpu` flag, ~30-60s for 10s video at 256x256
+- **Free on HuggingFace Spaces**: Can call remotely via `gradio_client`
+
+```python
+from gradio_client import Client
+client = Client("vinthony/SadTalker")
+result = client.predict("character.png", "speech.wav", "crop", True, True)
+```
+
+#### Image Animation: LivePortrait (For Character Motion)
+
+Animates portrait with expressions and head movements.
+
+- Has OpenVINO support -- can use Intel Arc GPU
+- ~15-30 FPS with OpenVINO on Intel Arc
+
+#### Lip Sync: Rhubarb Lip Sync (CPU, Real-Time)
+
+Analyzes audio and outputs timed mouth shape data. Anime only uses ~5-7 mouth shapes.
+
+```python
+# Rhubarb outputs: {"mouthCues": [{"start": 0.00, "end": 0.05, "value": "A"}, ...]}
+# Map to anime mouth shapes: Closed, Small, Medium, Open, Wide
+```
+
+#### Ken Burns Effects: FFmpeg (ZERO AI, Instant)
+
+This should be **70-80% of your animation**. Real anime uses this constantly.
+
+```python
+# Slow zoom into image
+ffmpeg -loop 1 -i image.png -vf "zoompan=z='min(zoom+0.001,1.3)':s=1920x1080:fps=24:d=120" \
+  -t 5 -c:v libx264 output.mp4
+
+# Pan left to right
+ffmpeg -loop 1 -i image.png -vf "zoompan=z=1.2:x='iw/2-(iw/zoom/2)+(-0.3+on/120*0.6)*iw/zoom':..." \
+  -t 5 output.mp4
+```
+
+- **Performance**: Instant. FFmpeg is heavily optimized.
+- **Intel QSV**: Use `h264_qsv` encoder for 3-5x faster encoding on Intel Arc
+
+#### Anime-Specific Effects (CPU, OpenCV)
+
+All of these are trivial on CPU:
+
+| Effect | Implementation | Use Case |
+|--------|---------------|----------|
+| Speed lines | OpenCV line drawing overlay | Action scenes |
+| Camera shake | Random frame offset | Impact moments |
+| White flash | Alpha blend with white | Explosions, reveals |
+| Dramatic zoom lines | Radial lines from center | Power-up moments |
+| Vignette | Radial gradient overlay | Moody scenes |
+| Screen shake | Sine wave displacement | Earthquakes, impacts |
+
+#### Parallax / 2.5D Effect
+
+Use MiDaS depth estimation (has OpenVINO support!) to create depth maps, then move foreground/background at different speeds.
+
+```python
+from openvino.runtime import Core
+core = Core()
+model = core.compile_model("midas_v21_small.xml", "GPU")  # Intel Arc
+depth_map = model([image])[0]
+# Separate into layers based on depth → animate at different speeds
+```
+
+### 3.5 Video Assembly
+
+#### FFmpeg Pipeline (Core)
+
+```python
+class AnimeVideoAssembler:
+    def images_to_video(self, images, fps=24):
+        """Number images → video"""
+
+    def add_audio(self, video, tts_audio):
+        """Combine video + TTS"""
+
+    def mix_audio(self, tts, bg_music, music_vol=0.15):
+        """Mix narration + background music"""
+
+    def add_subtitles(self, video, srt_file):
+        """Burn anime-style subtitles"""
+
+    def crossfade(self, clip1, clip2, duration=0.5):
+        """Scene transitions"""
+
+    def concat(self, clips):
+        """Join all scenes into episode"""
+
+    def encode_qsv(self, input, output):
+        """Intel Arc hardware-accelerated encoding"""
+        # ffmpeg -i input -c:v h264_qsv -global_quality 23 output.mp4
+```
+
+#### MoviePy (Python-Friendly Alternative)
+
+```python
+from moviepy.editor import *
+
+# Per scene: image + Ken Burns + audio + subtitle
+clip = ImageClip("scene.png", duration=5)
+clip = clip.resize(lambda t: 1 + 0.04*t)  # Zoom effect
+clip = clip.set_audio(AudioFileClip("tts.mp3"))
+txt = TextClip("Dialogue here", fontsize=36, color='white', stroke_color='black')
+clip = CompositeVideoClip([clip, txt.set_position(('center','bottom'))])
+```
+
+---
+
+## 4. NLP & INTELLIGENCE LAYER
+
+### 4.1 Free LLM APIs (for Scene Parsing, Prompt Generation)
+
+| Provider | Free Limits | Best Model | Context | Best For |
+|----------|------------|------------|---------|----------|
+| **Google Gemini** | 1500 req/day, 1M TPM | Gemini 2.0 Flash | **1M tokens** | Scene parsing (fit whole chapter in one call) |
+| **Groq** | 14,400 req/day | Llama 3.3 70B | 128K | Batch emotion analysis (fastest) |
+| **Together AI** | $5 free credits | Llama 3.3 70B | 128K | Backup + image gen (FLUX) |
+| **OpenRouter** | 200 req/day | Various free models | Varies | Unified fallback |
+| **HuggingFace** | ~100 req/hour | Specialized NLP models | Varies | Emotion classification |
+| **Cohere** | 1000 calls/month | Command-R | 128K | Structured extraction backup |
+| **SambaNova** | Free during beta | Llama 3.1 405B | 128K | Strongest reasoning |
+
+**Strategy**: Gemini as primary (1M context = entire chapter in one call), Groq as fast secondary, others as fallbacks.
+
+### 4.2 Text → Scene Pipeline
+
+```
+Raw Chapter Text
+    ↓
+[spaCy + NLTK] -- Fast local NLP (FREE)
+    - Sentence tokenization
+    - Dialogue extraction (regex)
+    - Named Entity Recognition
+    - Scene break detection (--- markers, time skips)
+    ↓
+[Gemini API] -- Semantic understanding (FREE)
+    - Scene segmentation
+    - Emotion per line
+    - Action extraction
+    - Setting descriptions
+    ↓
+[Prompt Generator] -- Convert to image prompts
+    - Character visual descriptions (from database)
+    - Camera angle selection
+    - Art style tags
+    ↓
+Structured Scene JSON
+```
+
+### 4.3 Key Libraries
+
+```bash
+pip install spacy nltk google-generativeai groq huggingface-hub
+python -m spacy download en_core_web_lg
+```
+
+### 4.4 Character Management
+
+```python
+# Each character gets:
+# - Canonical name + aliases
+# - Visual description (50 words, prompt-ready, NO name)
+# - Reference image paths (for IP-Adapter)
+# - Voice assignment (Edge TTS voice + default emotion)
+# - Outfit tracking per chapter
+
+# Example:
+{
+    "name": "Sarah",
+    "aliases": ["the silver-haired girl", "the mage"],
+    "visual_prompt": "young woman, long silver hair, blue eyes, slender build, wearing blue mage robes with gold trim, carrying wooden staff",
+    "reference_images": ["characters/sarah_ref1.png", "characters/sarah_ref2.png"],
+    "voice": {"engine": "edge-tts", "voice": "en-US-JennyNeural", "default_style": "cheerful"},
+}
+```
+
+### 4.5 Web Novel Scraping
+
+- **Primary target**: Royal Road (easy, clean HTML, minimal anti-scraping)
+- **Best existing library**: `lightnovel-crawler` (supports 100+ sites)
+- **Custom scraper**: BeautifulSoup + requests with 2s delay between pages
+- **Legal**: Author opt-in system for commercial use. Public domain novels for demos.
+
+---
+
+## 5. SYSTEM ARCHITECTURE
+
+### 5.1 Full Pipeline Overview
+
+```
+USER INPUT (URL or pasted text)
+    │
+    ▼
+┌─────────────────────┐
+│  1. TEXT INGESTION   │  Scraper or paste → raw chapter text
+│     (2 seconds)      │  lightnovel-crawler / BeautifulSoup
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  2. NLP ANALYSIS     │  spaCy + NLTK → entities, dialogue, breaks
+│     (5 seconds)      │  Gemini API → scenes, emotions, actions
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  3. VISUAL SCRIPT    │  Scene → shots → image prompts
+│     (10 seconds)     │  Character DB → consistent descriptions
+│                      │  Camera angle selection
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  4. ASSET GENERATION (parallel)         │
+│                                          │
+│  ┌──────────────┐  ┌──────────────────┐ │
+│  │ Image Gen    │  │ TTS Generation   │ │
+│  │ 15-30 images │  │ All dialogue +   │ │
+│  │ via FLUX/SDXL│  │ narration via    │ │
+│  │ + IP-Adapter │  │ Edge TTS         │ │
+│  │ (2-5 min)    │  │ (1-2 min)        │ │
+│  └──────┬───────┘  └──────┬───────────┘ │
+└─────────┼─────────────────┼─────────────┘
+          │                 │
+          ▼                 ▼
+┌─────────────────────────────────────────┐
+│  5. ANIMATION LAYER                      │
+│                                          │
+│  • Ken Burns on all scenes (instant)     │
+│  • RIFE interpolation between keyframes  │
+│  • SadTalker for key dialogue faces      │
+│  • Lip sync via Rhubarb                  │
+│  • Camera shake / effects for action     │
+│  • Depth parallax for atmosphere         │
+│  (1-3 min)                               │
+└────────┬────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  6. VIDEO ASSEMBLY   │  FFmpeg: concat scenes + add subtitles
+│     (30 seconds)     │  Mix TTS + background music
+│                      │  Encode with Intel QSV
+└────────┬────────────┘
+         │
+         ▼
+    FINAL MP4 EPISODE
+    (3-10 minutes per chapter)
+```
+
+### 5.2 Tech Stack
+
+```
+Backend:     Python 3.11+, FastAPI, Celery + Redis (task queue)
+NLP:         spaCy (en_core_web_lg) + NLTK + Gemini API
+Image Gen:   FLUX/SDXL via Together AI, HuggingFace, Pollinations, or Kaggle
+Animation:   RIFE (rife-ncnn-vulkan), SadTalker, FFmpeg, OpenCV
+TTS:         Edge TTS (primary), Bark (effects), Piper (offline fallback)
+Video:       FFmpeg + MoviePy, Intel QSV encoding
+Frontend:    Next.js + Tailwind CSS + Video.js player
+Storage:     Local filesystem → Cloudflare R2 (production)
+Database:    SQLite (start) → PostgreSQL (scale)
+```
+
+### 5.3 Performance Estimates (Your Hardware)
+
+| Task | Time | Tool |
+|------|------|------|
+| Scrape 1 chapter | 3s | requests/beautifulsoup |
+| NLP analysis | 5s | spaCy local |
+| LLM scene parsing | 10s | Gemini API |
+| Generate 1 image (API) | 5-15s | FLUX via Together/HF/Pollinations |
+| Generate 1 image (Kaggle) | 10-30s | SDXL + IP-Adapter |
+| RIFE interpolation (1 pair) | 0.5-2s | ncnn-vulkan on Intel Arc |
+| Ken Burns 5s clip | <1s | FFmpeg |
+| TTS for 1 line | 1-3s | Edge TTS |
+| SadTalker 10s video | 30-60s | CPU mode |
+| Depth map | 1-3s | MiDaS + OpenVINO on Intel Arc |
+| Final encoding | 5-10s/min | FFmpeg + QSV |
+| **FULL CHAPTER** | **~5-15 minutes** | **Complete pipeline** |
+
+---
+
+## 6. YOUR HARDWARE ADVANTAGE
+
+### Intel Core Ultra 5 + Intel Arc Graphics
+
+Your hardware is actually better than you think for AI:
+
+1. **Intel Arc GPU supports**:
+   - OpenVINO (Intel's AI inference toolkit)
+   - Vulkan (for ncnn-based models like RIFE)
+   - Intel QSV (hardware video encoding -- 3-5x faster)
+   - DirectML (Windows AI acceleration)
+
+2. **NPU (Neural Processing Unit)** in Core Ultra:
+   - Can run lightweight models (face detection, classification)
+   - Accessible via OpenVINO
+
+3. **What this means for your pipeline**:
+
+| Task | Without Intel Arc | With Intel Arc (OpenVINO/Vulkan) |
+|------|-------------------|----------------------------------|
+| RIFE interpolation | 2-5s/frame on CPU | **0.1-0.5s/frame** |
+| MiDaS depth | 5-10s on CPU | **1-3s** |
+| First Order Motion | Not practical on CPU | **5-15 FPS** |
+| Video encoding | Software libx264 | **h264_qsv (3-5x faster)** |
+
+### Setup Commands
+
+```bash
+# Install OpenVINO
+pip install openvino openvino-dev
+
+# Install Intel PyTorch Extension
+pip install intel-extension-for-pytorch
+
+# RIFE with Vulkan (works on Intel Arc)
+pip install rife-ncnn-vulkan-python
+
+# Verify Intel Arc is detected
+python -c "from openvino.runtime import Core; print(Core().available_devices)"
+# Expected: ['CPU', 'GPU', 'NPU']
+```
+
+---
+
+## 7. IMPLEMENTATION ROADMAP
+
+### Phase 1: Proof of Concept (Week 1-2)
+**Goal**: URL → scene JSON → static image set + narration audio
+
+- Set up project structure
+- Build Royal Road scraper
+- Implement NLP pipeline (spaCy + Gemini)
+- Build basic prompt generator
+- Generate images via Pollinations.ai (zero friction, no API key)
+- Generate TTS via Edge TTS
+- **Deliverable**: A folder of images + audio files for one chapter
+
+### Phase 2: First Video (Week 3-4)
+**Goal**: Images + audio → watchable motion comic episode
+
+- Implement FFmpeg Ken Burns pipeline
+- Build scene assembler (concat, transitions, subtitles)
+- Add background music mixing
+- Generate SRT subtitles from TTS timestamps
+- **Deliverable**: First complete video episode from a web novel chapter
+
+### Phase 3: Character Consistency (Week 5-6)
+**Goal**: Characters look the same across all scenes
+
+- Set up ComfyUI on Kaggle notebook
+- Implement IP-Adapter / PuLID workflow
+- Build character management system
+- Generate character reference sheets
+- Switch from Pollinations to Kaggle/Together for image gen
+- **Deliverable**: Episode with consistent characters
+
+### Phase 4: Animation Enhancement (Week 7-8)
+**Goal**: Add motion beyond Ken Burns
+
+- Integrate RIFE interpolation (ncnn-vulkan on Intel Arc)
+- Add SadTalker for talking face close-ups
+- Implement Rhubarb lip sync
+- Add anime effects (speed lines, camera shake, flash)
+- Implement depth-based parallax via MiDaS
+- **Deliverable**: Significantly more animated episodes
+
+### Phase 5: Web Application (Week 9-10)
+**Goal**: Users can access the tool via browser
+
+- Build FastAPI backend with task queue (Celery)
+- Build Next.js frontend (paste URL → get video)
+- Add progress tracking
+- Add art style selection
+- Add video player
+- **Deliverable**: Working web app
+
+### Phase 6: Launch & Monetize (Week 11+)
+**Goal**: Get users and start earning
+
+- Deploy to cloud (Vercel frontend, Railway backend)
+- Implement user accounts
+- Add Stripe payments (freemium model)
+- Create demo episodes for marketing (TikTok, YouTube Shorts)
+- Submit to ProductHunt, HackerNews, Reddit
+- Author partnership program
+
+---
+
+## 8. MONETIZATION STRATEGY
+
+### Pricing Model (Freemium SaaS)
+
+```
+FREE TIER:
+  - 1 chapter/day
+  - 720p resolution
+  - Watermarked
+  - Basic art style
+  - 30-second preview
+
+PREMIUM ($9.99/month):
+  - 10 chapters/day
+  - 1080p resolution
+  - No watermark
+  - Multiple art styles
+  - Full episodes
+  - Download as MP4
+
+PRO ($29.99/month):
+  - Unlimited chapters
+  - 4K resolution
+  - API access
+  - Custom character LoRA training
+  - Batch processing
+  - Commercial usage rights
+```
+
+### Revenue Projections (Conservative)
+
+```
+Month 6:    10K users,   500 paid  →  ~$5,000/mo
+Month 12:   50K users,  2,500 paid →  ~$25,000/mo
+Month 24:  200K users, 10,000 paid →  ~$100,000/mo
+```
+
+### Market Opportunity
+
+- 200M+ monthly web novel readers globally
+- Zero competitors doing exactly this (novel text → anime video)
+- Growing AI video generation market ($500M+ in 2024)
+- Strong social media virality potential (anime clips from popular novels)
+
+---
+
+## 9. FINAL RECOMMENDATION
+
+### The Strategy
+
+**Plan A (pure video gen) is not viable for free** -- but it's useful for ~5% of content (hero moments via HuggingFace).
+
+**Plan B IS the plan.** And it's not a compromise. Here's why:
+
+The "motion comic" style (images + Ken Burns + TTS + effects + interpolation) is:
+1. Literally how real anime handles dialogue and atmospheric scenes
+2. Fully achievable on your hardware at $0 cost
+3. Character-consistent (via IP-Adapter)
+4. Infinitely controllable (every frame, every angle, every expression)
+5. Scalable to production quality
+
+### Your Secret Weapons
+
+1. **Edge TTS** -- Unlimited free voice acting with emotion control
+2. **Pollinations.ai / Together AI / HuggingFace** -- Free anime image generation
+3. **Intel Arc + OpenVINO** -- Accelerated AI inference most people don't have
+4. **RIFE + ncnn-vulkan** -- Smooth frame interpolation on Intel Arc
+5. **Gemini API** -- 1500 free scene parsing calls/day (100+ chapters/day)
+6. **Kaggle free GPUs** -- 30 hrs/week for heavy image gen with IP-Adapter
+
+### What to Build First
+
+```
+THIS WEEKEND:
+  1. pip install edge-tts spacy google-generativeai requests beautifulsoup4
+  2. Scrape a Royal Road chapter
+  3. Parse it with spaCy + Gemini into scenes
+  4. Generate images via Pollinations.ai
+  5. Generate TTS via Edge TTS
+  6. FFmpeg: images + audio → your first anime episode
+
+COST: $0 | TIME: 1 weekend | RESULT: Proof of concept video
+```
+
+### Key Dependencies to Install
+
+```bash
+# Core
+pip install edge-tts spacy nltk google-generativeai groq
+pip install requests beautifulsoup4 Pillow opencv-python
+pip install moviepy numpy librosa
+
+# Intel Arc acceleration
+pip install openvino rife-ncnn-vulkan-python
+
+# NLP models
+python -m spacy download en_core_web_lg
+python -m nltk.downloader vader_lexicon punkt
+
+# For HuggingFace model access
+pip install huggingface-hub gradio-client
+
+# For web novel scraping
+pip install lightnovel-crawler
+```
+
+---
+
+## APPENDIX: Quick Reference of All Free APIs
+
+| Service | What | Free Limit | API Key? | URL |
+|---------|------|-----------|----------|-----|
+| Edge TTS | Voice synthesis | Unlimited | No | `pip install edge-tts` |
+| Pollinations.ai | Image generation (FLUX) | Unlimited | No | image.pollinations.ai |
+| Google Gemini | LLM (scene parsing) | 1500 req/day | Yes (free) | aistudio.google.com |
+| Groq | LLM (fast inference) | 14,400 req/day | Yes (free) | console.groq.com |
+| HuggingFace | Images, video, TTS, LLMs | Rate-limited | Yes (free) | huggingface.co |
+| Together AI | Images (FLUX) + LLMs | $5 free credits | Yes (free) | api.together.xyz |
+| Azure TTS | Voice synthesis + emotion | 500K chars/mo | Yes (free) | azure.microsoft.com |
+| Kaggle | Free T4 GPUs | 30 hrs/week | Account | kaggle.com |
+| Google Colab | Free T4 GPUs | ~4 hrs/day | Account | colab.research.google.com |
+| OpenRouter | Various free LLMs | 200 req/day | Yes (free) | openrouter.ai |
+
+---
+
+*This research was conducted across web searches, model documentation, API documentation, and community reports as of February 2026. Verify current free tier limits before relying on them in production.*

TESTED_APIS.md

@@ -0,0 +1,128 @@
+# Image Generation APIs -- TESTED RESULTS (2026-02-27)
+
+## CONFIRMED WORKING (with your actual API keys)
+
+### 1. NVIDIA NIM -- FLUX.1-dev (BEST QUALITY)
+- **Status**: WORKING
+- **Speed**: 4.8 seconds per image
+- **Resolution**: 1024x768
+- **Anime Quality**: EXCELLENT (professional anime key visual level)
+- **Free Credits**: 1,000 on signup (up to 5,000 with business email + 90-day enterprise license)
+- **API**:
+```python
+import requests, base64
+
+r = requests.post(
+    "https://ai.api.nvidia.com/v1/genai/black-forest-labs/flux.1-dev",
+    headers={"Authorization": "Bearer YOUR_NVIDIA_KEY", "Accept": "application/json"},
+    json={
+        "prompt": "anime style, young warrior girl, silver hair, blue eyes, glowing sword, fantasy forest, masterpiece",
+        "mode": "base",
+        "cfg_scale": 3.5,
+        "width": 1024,
+        "height": 768,
+        "seed": -1,
+        "steps": 30
+    }
+)
+img_bytes = base64.b64decode(r.json()["artifacts"][0]["base64"])
+with open("output.png", "wb") as f:
+    f.write(img_bytes)
+```
+
+### 2. NVIDIA NIM -- FLUX.1-schnell (FASTEST)
+- **Status**: WORKING
+- **Speed**: 3.4 seconds per image
+- **Resolution**: 1024x1024
+- **Anime Quality**: EXCELLENT
+- **API**: Same as above, endpoint: `black-forest-labs/flux.1-schnell`, steps=4
+
+### 3. HuggingFace -- FLUX.1-schnell (MOST GENEROUS FREE)
+- **Status**: WORKING
+- **Speed**: 1.4-3.8 seconds per image
+- **Resolution**: up to 1024x768
+- **Anime Quality**: EXCELLENT
+- **Free Tier**: Rate-limited but generous (3 rapid requests all succeeded)
+- **API**:
+```python
+import requests
+
+r = requests.post(
+    "https://router.huggingface.co/hf-inference/models/black-forest-labs/FLUX.1-schnell",
+    headers={"Authorization": "Bearer YOUR_HF_TOKEN", "Content-Type": "application/json"},
+    json={
+        "inputs": "1girl, silver hair, blue eyes, holding sword, anime style, masterpiece",
+        "parameters": {"negative_prompt": "low quality, blurry", "width": 1024, "height": 768}
+    }
+)
+with open("output.png", "wb") as f:
+    f.write(r.content)  # Returns raw image bytes
+```
+
+### 4. HuggingFace -- SDXL Base (GOOD PAINTERLY STYLE)
+- **Status**: WORKING
+- **Speed**: 9.8 seconds per image
+- **Resolution**: up to 1024x768
+- **Anime Quality**: EXCELLENT (more painterly/artistic style)
+- **API**: Same as above, model: `stabilityai/stable-diffusion-xl-base-1.0`
+
+---
+
+## NOT WORKING / NOT FREE
+
+| Service | Status | Reason |
+|---------|--------|--------|
+| OpenRouter | NO free image models | All 29 free models are text-only |
+| Prodia | Needs paid upgrade | Free accounts can't create API tokens |
+| Google Gemini | Quota = 0 on free tier | Image gen removed from free tier entirely |
+| Google Imagen | Paid only | "Imagen 3 is only available on paid plans" |
+| Pollinations | HTTP 530 | Cloudflare blocking (may work from other networks) |
+| Together AI | No free tier (2026) | User confirmed free tier discontinued |
+| DeepInfra | Needs auth/credits | 403 without authentication |
+| fal.ai | Needs auth/credits | 401 without authentication |
+| HF FLUX.1-dev | DEPRECATED | "No longer supported by provider hf-inference" |
+| HF Animagine XL | 404 | Not available on inference API |
+| Stability AI | Needs API key | 401 without key |
+
+---
+
+## RECOMMENDED STRATEGY
+
+### Primary: HuggingFace FLUX.1-schnell
+- Fastest (1.4-3.8s)
+- No visible hard limit yet
+- Excellent anime quality
+- Use for bulk image generation
+
+### Secondary: NVIDIA NIM FLUX.1-dev
+- Best quality (30-step generation)
+- 1,000-5,000 free credits
+- Use for hero/key moment images
+- Save credits for important scenes
+
+### Fallback: HuggingFace SDXL
+- Different artistic style
+- Good for variety
+- 9.8s per image (slower)
+
+### Combined Monthly Estimate
+- HuggingFace: Unknown hard limit, but generous for free tier
+- NVIDIA: 1,000+ credits (unknown images-per-credit ratio)
+- Pollinations: ~1,000 images (if accessible from your network)
+- **Total: Likely 1,000-5,000+ images/month for $0**
+
+### Images Per Chapter
+- A 3-5 minute episode needs ~20-30 keyframe images
+- At 2,000 images/month = ~66-100 chapters/month
+- More than enough for production
+
+---
+
+## QUALITY RANKING (for anime)
+
+1. NVIDIA FLUX.1-dev (30 steps) -- Most detailed, best composition
+2. NVIDIA FLUX.1-schnell -- Great quality, fastest NVIDIA
+3. HuggingFace FLUX.1-schnell -- Slightly different style, very fast
+4. HuggingFace SDXL -- More painterly, artistic feel
+
+All four produce professional-grade anime art suitable for our project.

app/api/auth.py

@@ -0,0 +1,104 @@
+from fastapi import APIRouter, Depends, HTTPException, Response, Cookie, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.schemas.auth import UserCreate, UserLogin, UserResponse, TokenResponse
+from app.services.auth import (
+    hash_password, verify_password,
+    create_access_token, create_refresh_token, decode_token,
+    get_current_user,
+)
+from app.config import get_settings
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+settings = get_settings()
+
+
+@router.post("/register", response_model=UserResponse, status_code=201)
+async def register(data: UserCreate, db: AsyncSession = Depends(get_db)):
+    # Check existing
+    existing = await db.execute(
+        select(User).where((User.email == data.email) | (User.username == data.username))
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail="Email or username already registered")
+
+    user = User(
+        email=data.email,
+        username=data.username,
+        password_hash=hash_password(data.password),
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(data: UserLogin, response: Response, db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(User).where(User.email == data.email))
+    user = result.scalar_one_or_none()
+    if not user or not verify_password(data.password, user.password_hash):
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+
+    access_token = create_access_token(user.id)
+    refresh_token = create_refresh_token(user.id)
+
+    response.set_cookie(
+        key="refresh_token",
+        value=refresh_token,
+        httponly=True,
+        secure=False,  # Set True in production with HTTPS
+        samesite="lax",
+        max_age=settings.refresh_token_expire_days * 86400,
+        path="/api/auth",
+    )
+
+    return TokenResponse(access_token=access_token)
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(
+    response: Response,
+    refresh_token: str | None = Cookie(default=None),
+    db: AsyncSession = Depends(get_db),
+):
+    if not refresh_token:
+        raise HTTPException(status_code=401, detail="No refresh token")
+
+    payload = decode_token(refresh_token)
+    if payload.get("type") != "refresh":
+        raise HTTPException(status_code=401, detail="Invalid token type")
+
+    user_id = int(payload["sub"])
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+
+    new_access = create_access_token(user.id)
+    new_refresh = create_refresh_token(user.id)
+
+    response.set_cookie(
+        key="refresh_token",
+        value=new_refresh,
+        httponly=True,
+        secure=False,
+        samesite="lax",
+        max_age=settings.refresh_token_expire_days * 86400,
+        path="/api/auth",
+    )
+
+    return TokenResponse(access_token=new_access)
+
+
+@router.post("/logout")
+async def logout(response: Response):
+    response.delete_cookie("refresh_token", path="/api/auth")
+    return {"message": "Logged out"}
+
+
+@router.get("/me", response_model=UserResponse)
+async def me(user: User = Depends(get_current_user)):
+    return user

app/api/chapters.py

@@ -0,0 +1,82 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.models.project import Project
+from app.models.chapter import Chapter
+from app.schemas.chapter import ChapterCreate, ChapterResponse
+from app.services.auth import get_current_user
+
+router = APIRouter(prefix="/api/projects/{project_id}/chapters", tags=["chapters"])
+
+
+async def _get_user_project(project_id: int, user: User, db: AsyncSession) -> Project:
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+@router.get("", response_model=list[ChapterResponse])
+async def list_chapters(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    result = await db.execute(
+        select(Chapter)
+        .where(Chapter.project_id == project_id)
+        .order_by(Chapter.chapter_number)
+    )
+    return list(result.scalars().all())
+
+
+@router.post("", response_model=ChapterResponse, status_code=201)
+async def create_chapter(
+    project_id: int,
+    data: ChapterCreate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    chapter = Chapter(
+        project_id=project_id,
+        chapter_number=data.chapter_number,
+        title=data.title,
+        source_text=data.source_text,
+        word_count=len(data.source_text.split()),
+    )
+    db.add(chapter)
+    await db.commit()
+    await db.refresh(chapter)
+    return chapter
+
+
+@router.post("/bulk", response_model=list[ChapterResponse], status_code=201)
+async def create_chapters_bulk(
+    project_id: int,
+    chapters: list[ChapterCreate],
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    db_chapters = []
+    for data in chapters:
+        chapter = Chapter(
+            project_id=project_id,
+            chapter_number=data.chapter_number,
+            title=data.title,
+            source_text=data.source_text,
+            word_count=len(data.source_text.split()),
+        )
+        db.add(chapter)
+        db_chapters.append(chapter)
+    await db.commit()
+    for ch in db_chapters:
+        await db.refresh(ch)
+    return db_chapters

app/api/characters.py

@@ -0,0 +1,74 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.models.project import Project
+from app.models.character import Character
+from app.schemas.character import CharacterCreate, CharacterUpdate, CharacterResponse
+from app.services.auth import get_current_user
+
+router = APIRouter(prefix="/api/projects/{project_id}/characters", tags=["characters"])
+
+
+async def _get_user_project(project_id: int, user: User, db: AsyncSession) -> Project:
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+@router.get("", response_model=list[CharacterResponse])
+async def list_characters(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    result = await db.execute(
+        select(Character)
+        .where(Character.project_id == project_id)
+        .order_by(Character.name)
+    )
+    return list(result.scalars().all())
+
+
+@router.post("", response_model=CharacterResponse, status_code=201)
+async def create_character(
+    project_id: int,
+    data: CharacterCreate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    character = Character(project_id=project_id, **data.model_dump(exclude_none=True))
+    db.add(character)
+    await db.commit()
+    await db.refresh(character)
+    return character
+
+
+@router.patch("/{character_id}", response_model=CharacterResponse)
+async def update_character(
+    project_id: int,
+    character_id: int,
+    data: CharacterUpdate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    result = await db.execute(
+        select(Character).where(Character.id == character_id, Character.project_id == project_id)
+    )
+    character = result.scalar_one_or_none()
+    if not character:
+        raise HTTPException(status_code=404, detail="Character not found")
+
+    for key, value in data.model_dump(exclude_none=True).items():
+        setattr(character, key, value)
+    await db.commit()
+    await db.refresh(character)
+    return character

app/api/episodes.py

@@ -0,0 +1,68 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.models.project import Project
+from app.models.episode import Episode
+from app.schemas.episode import EpisodeCreate, EpisodeResponse
+from app.services.auth import get_current_user
+
+router = APIRouter(prefix="/api/projects/{project_id}/episodes", tags=["episodes"])
+
+
+async def _get_user_project(project_id: int, user: User, db: AsyncSession) -> Project:
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+@router.get("", response_model=list[EpisodeResponse])
+async def list_episodes(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    result = await db.execute(
+        select(Episode)
+        .where(Episode.project_id == project_id)
+        .order_by(Episode.episode_number)
+    )
+    return list(result.scalars().all())
+
+
+@router.post("", response_model=EpisodeResponse, status_code=201)
+async def create_episode(
+    project_id: int,
+    data: EpisodeCreate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    episode = Episode(project_id=project_id, **data.model_dump(exclude_none=True))
+    db.add(episode)
+    await db.commit()
+    await db.refresh(episode)
+    return episode
+
+
+@router.get("/{episode_id}", response_model=EpisodeResponse)
+async def get_episode(
+    project_id: int,
+    episode_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    await _get_user_project(project_id, user, db)
+    result = await db.execute(
+        select(Episode).where(Episode.id == episode_id, Episode.project_id == project_id)
+    )
+    episode = result.scalar_one_or_none()
+    if not episode:
+        raise HTTPException(status_code=404, detail="Episode not found")
+    return episode

app/api/generation.py

@@ -0,0 +1,241 @@
+import asyncio
+import json
+import logging
+from pathlib import Path
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.models.project import Project
+from app.models.generation_job import GenerationJob
+from app.schemas.generation import GenerationStart, GenerationJobResponse
+from app.services.auth import get_current_user
+from app.pipeline.orchestrator import run_pipeline
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/projects/{project_id}", tags=["generation"])
+
+# Keep references to running pipeline tasks so they don't get garbage-collected
+_running_tasks: set[asyncio.Task] = set()
+
+
+def _launch_pipeline(job_id: int, resume: bool = False, chapter_ids: list[int] | None = None):
+    """Launch pipeline as background task with error logging."""
+    async def _wrapper():
+        try:
+            await run_pipeline(job_id, resume=resume, chapter_ids=chapter_ids)
+        except Exception:
+            logger.exception("Pipeline failed for job %s", job_id)
+
+    task = asyncio.create_task(_wrapper())
+    _running_tasks.add(task)
+    task.add_done_callback(_running_tasks.discard)
+
+
+# ── Asset endpoints ──────────────────────────────────────────────────
+
+@router.get("/assets/images")
+async def list_images(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """List generated images for a project."""
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    if not result.scalar_one_or_none():
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    img_dir = Path("workdir/projects") / str(project_id) / "images"
+    if not img_dir.exists():
+        return []
+
+    files = sorted(f.name for f in img_dir.iterdir() if f.suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"))
+    return files
+
+
+# ── Generation endpoints ─────────────────────────────────────────────
+
+@router.post("/generate", response_model=GenerationJobResponse, status_code=201)
+async def start_generation(
+    project_id: int,
+    data: GenerationStart,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    job = GenerationJob(
+        project_id=project_id,
+        user_id=user.id,
+        episode_id=data.episode_id,
+        chapter_ids_json=data.chapter_ids,
+        status="queued",
+        current_stage="ingest",
+        progress_pct=0.0,
+    )
+    db.add(job)
+    await db.commit()
+    await db.refresh(job)
+
+    # Launch pipeline in background with error handling
+    _launch_pipeline(job.id, chapter_ids=data.chapter_ids)
+
+    return job
+
+
+@router.get("/generate/jobs", response_model=list[GenerationJobResponse])
+async def list_jobs(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(GenerationJob)
+        .where(GenerationJob.project_id == project_id, GenerationJob.user_id == user.id)
+        .order_by(GenerationJob.created_at.desc())
+    )
+    return list(result.scalars().all())
+
+
+@router.get("/generate/jobs/{job_id}", response_model=GenerationJobResponse)
+async def get_job(
+    project_id: int,
+    job_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(GenerationJob).where(
+            GenerationJob.id == job_id,
+            GenerationJob.project_id == project_id,
+            GenerationJob.user_id == user.id,
+        )
+    )
+    job = result.scalar_one_or_none()
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return job
+
+
+@router.get("/generate/jobs/{job_id}/stream")
+async def stream_progress(
+    project_id: int,
+    job_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """SSE endpoint for real-time generation progress."""
+    result = await db.execute(
+        select(GenerationJob).where(
+            GenerationJob.id == job_id,
+            GenerationJob.project_id == project_id,
+            GenerationJob.user_id == user.id,
+        )
+    )
+    job = result.scalar_one_or_none()
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    from app.database import async_session as session_factory
+
+    async def event_stream():
+        last_data = None
+        while True:
+            try:
+                async with session_factory() as session:
+                    result = await session.execute(
+                        select(GenerationJob).where(GenerationJob.id == job_id)
+                    )
+                    current_job = result.scalar_one_or_none()
+                    if not current_job:
+                        yield f"data: {json.dumps({'status': 'not_found'})}\n\n"
+                        break
+
+                    data = {
+                        "status": current_job.status or "queued",
+                        "stage": current_job.current_stage or "ingest",
+                        "progress": current_job.progress_pct or 0,
+                        "detail": (current_job.progress_detail or "")[:200],
+                        "error": (current_job.error_message or "")[:500] if current_job.status == "failed" else None,
+                    }
+
+                    # Always send (even if same) so frontend knows connection is alive
+                    yield f"data: {json.dumps(data)}\n\n"
+                    last_data = data
+
+                    if current_job.status in ("completed", "failed", "cancelled"):
+                        break
+            except Exception:
+                logger.exception("SSE stream error for job %s", job_id)
+                yield f"data: {json.dumps({'status': 'error', 'detail': 'Server error'})}\n\n"
+                break
+
+            await asyncio.sleep(1)
+
+    return StreamingResponse(
+        event_stream(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/generate/retry", response_model=GenerationJobResponse, status_code=201)
+async def retry_generation(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Retry the last failed job for a project, resuming from where it left off."""
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    # Find the last failed job
+    result = await db.execute(
+        select(GenerationJob)
+        .where(
+            GenerationJob.project_id == project_id,
+            GenerationJob.user_id == user.id,
+            GenerationJob.status == "failed",
+        )
+        .order_by(GenerationJob.created_at.desc())
+        .limit(1)
+    )
+    failed_job = result.scalar_one_or_none()
+    if not failed_job:
+        raise HTTPException(status_code=404, detail="No failed job to retry")
+
+    # Create new job, carrying over chapter_ids from failed job
+    job = GenerationJob(
+        project_id=project_id,
+        user_id=user.id,
+        episode_id=failed_job.episode_id,
+        chapter_ids_json=failed_job.chapter_ids_json,
+        status="queued",
+        current_stage="ingest",
+        progress_pct=0.0,
+    )
+    db.add(job)
+    await db.commit()
+    await db.refresh(job)
+
+    _launch_pipeline(job.id, resume=True, chapter_ids=failed_job.chapter_ids_json)
+
+    return job

app/api/novels.py

@@ -0,0 +1,80 @@
+"""Novel search, URL resolution, and PDF upload endpoints."""
+import os
+import tempfile
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
+from pydantic import BaseModel
+from app.services.auth import get_current_user
+from app.models.user import User
+from app.services.scraper import search_novels, resolve_novel_url, extract_text_from_pdf
+
+router = APIRouter(prefix="/api/novels", tags=["novels"])
+
+
+class SearchResult(BaseModel):
+    title: str
+    url: str
+    source: str
+
+
+class NovelInfo(BaseModel):
+    title: str
+    author: str | None = None
+    cover_url: str | None = None
+    synopsis: str | None = None
+    chapters: list[dict] = []
+    source: str = ""
+
+
+@router.get("/search", response_model=list[SearchResult])
+async def search(
+    q: str = Query(..., min_length=2),
+    user: User = Depends(get_current_user),
+):
+    results = await search_novels(q)
+    return [SearchResult(title=r.title, url=r.url, source=r.source) for r in results]
+
+
+@router.post("/resolve-url", response_model=NovelInfo)
+async def resolve_url(
+    data: dict,
+    user: User = Depends(get_current_user),
+):
+    url = data.get("url", "").strip()
+    if not url:
+        raise HTTPException(status_code=400, detail="URL is required")
+
+    result = await resolve_novel_url(url)
+    if not result:
+        raise HTTPException(status_code=404, detail="Could not resolve novel from URL")
+
+    return NovelInfo(
+        title=result.title,
+        author=result.author,
+        cover_url=result.cover_url,
+        synopsis=result.synopsis,
+        chapters=result.chapters,
+        source=result.source,
+    )
+
+
+@router.post("/upload-pdf", response_model=list[dict])
+async def upload_pdf(
+    file: UploadFile = File(...),
+    user: User = Depends(get_current_user),
+):
+    if not file.filename or not file.filename.lower().endswith(".pdf"):
+        raise HTTPException(status_code=400, detail="Only PDF files are supported")
+
+    # Save to temp file
+    with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+        content = await file.read()
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        chapters = await extract_text_from_pdf(tmp_path)
+        if not chapters:
+            raise HTTPException(status_code=422, detail="Could not extract text from PDF")
+        return chapters
+    finally:
+        os.unlink(tmp_path)

app/api/projects.py

@@ -0,0 +1,96 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.models.project import Project
+from app.schemas.project import ProjectCreate, ProjectUpdate, ProjectResponse, ProjectListResponse
+from app.services.auth import get_current_user
+
+router = APIRouter(prefix="/api/projects", tags=["projects"])
+
+
+@router.get("", response_model=ProjectListResponse)
+async def list_projects(
+    skip: int = 0,
+    limit: int = 20,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Project)
+        .where(Project.user_id == user.id)
+        .order_by(Project.updated_at.desc())
+        .offset(skip).limit(limit)
+    )
+    projects = list(result.scalars().all())
+    count_result = await db.execute(
+        select(func.count()).select_from(Project).where(Project.user_id == user.id)
+    )
+    total = count_result.scalar() or 0
+    return ProjectListResponse(projects=projects, total=total)
+
+
+@router.post("", response_model=ProjectResponse, status_code=201)
+async def create_project(
+    data: ProjectCreate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    project = Project(user_id=user.id, **data.model_dump(exclude_none=True))
+    db.add(project)
+    await db.commit()
+    await db.refresh(project)
+    return project
+
+
+@router.get("/{project_id}", response_model=ProjectResponse)
+async def get_project(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+@router.patch("/{project_id}", response_model=ProjectResponse)
+async def update_project(
+    project_id: int,
+    data: ProjectUpdate,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    for key, value in data.model_dump(exclude_none=True).items():
+        setattr(project, key, value)
+    await db.commit()
+    await db.refresh(project)
+    return project
+
+
+@router.delete("/{project_id}", status_code=204)
+async def delete_project(
+    project_id: int,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Project).where(Project.id == project_id, Project.user_id == user.id)
+    )
+    project = result.scalar_one_or_none()
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    await db.delete(project)
+    await db.commit()

app/config.py

@@ -0,0 +1,38 @@
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+import json
+
+
+class Settings(BaseSettings):
+    # Auth
+    jwt_secret_key: str = "change-this-to-a-random-secret-key-in-production"
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+    refresh_token_expire_days: int = 7
+
+    # Database
+    database_url: str = "sqlite+aiosqlite:///./workdir/anime.db"
+
+    # API Keys
+    hf_api_token: str = ""
+    nvidia_api_key: str = ""
+    gemini_api_key: str = ""
+    openrouter_api_key: str = ""
+    pollinations_api_key: str = ""
+
+    # Server
+    port: int = 8000
+
+    # CORS
+    cors_origins: str = '["http://localhost:3000"]'
+
+    @property
+    def cors_origin_list(self) -> list[str]:
+        return json.loads(self.cors_origins)
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/database.py

@@ -0,0 +1,51 @@
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from app.config import get_settings
+
+settings = get_settings()
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    connect_args={"timeout": 30},
+)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db():
+    async with async_session() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+
+async def init_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    # Migrate existing DBs: add chapter_ids_json to generation_jobs
+    async with engine.begin() as conn:
+        try:
+            await conn.execute(
+                __import__("sqlalchemy").text(
+                    "ALTER TABLE generation_jobs ADD COLUMN chapter_ids_json TEXT"
+                )
+            )
+        except Exception:
+            pass  # Column already exists
+
+    # Migrate existing DBs: add recap_summary to episodes
+    async with engine.begin() as conn:
+        try:
+            await conn.execute(
+                __import__("sqlalchemy").text(
+                    "ALTER TABLE episodes ADD COLUMN recap_summary TEXT"
+                )
+            )
+        except Exception:
+            pass  # Column already exists

app/main.py

@@ -0,0 +1,54 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from app.config import get_settings
+from app.database import init_db
+from app.api import auth, projects, chapters, characters, episodes, generation, novels
+import os
+
+settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: create tables
+    os.makedirs("workdir", exist_ok=True)
+    await init_db()
+    yield
+    # Shutdown
+
+
+app = FastAPI(
+    title="Anime Generator API",
+    version="0.1.0",
+    description="Web novel to anime video converter",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origin_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Serve generated media files
+os.makedirs("workdir", exist_ok=True)
+app.mount("/media", StaticFiles(directory="workdir"), name="media")
+
+# Routes
+app.include_router(auth.router)
+app.include_router(projects.router)
+app.include_router(chapters.router)
+app.include_router(characters.router)
+app.include_router(episodes.router)
+app.include_router(generation.router)
+app.include_router(novels.router)
+
+
+@app.get("/api/health")
+async def health():
+    return {"status": "ok", "version": "0.1.0"}

app/models/__init__.py

@@ -0,0 +1,13 @@
+from app.models.user import User
+from app.models.project import Project
+from app.models.chapter import Chapter
+from app.models.character import Character
+from app.models.episode import Episode
+from app.models.generation_job import GenerationJob
+from app.models.critic_result import CriticResult
+from app.models.api_usage import ApiUsage
+
+__all__ = [
+    "User", "Project", "Chapter", "Character",
+    "Episode", "GenerationJob", "CriticResult", "ApiUsage",
+]

app/models/api_usage.py

@@ -0,0 +1,13 @@
+from sqlalchemy import Column, Integer, String, Date, DateTime, func
+from app.database import Base
+
+
+class ApiUsage(Base):
+    __tablename__ = "api_usage"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    service = Column(String(100), nullable=False)  # huggingface, nvidia, gemini, edge_tts
+    endpoint = Column(String(500), nullable=True)
+    request_count = Column(Integer, default=1)
+    date = Column(Date, nullable=False)
+    created_at = Column(DateTime, server_default=func.now())

app/models/chapter.py

@@ -0,0 +1,19 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, JSON, func
+from app.database import Base
+from sqlalchemy.orm import relationship
+
+
+class Chapter(Base):
+    __tablename__ = "chapters"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False)
+    chapter_number = Column(Integer, nullable=False)
+    title = Column(String(500), nullable=True)
+    source_text = Column(Text, nullable=False)
+    word_count = Column(Integer, default=0)
+    status = Column(String(50), default="raw")  # raw, parsed, processed
+    parsed_json = Column(JSON, nullable=True)  # storyboard output
+    created_at = Column(DateTime, server_default=func.now())
+
+    project = relationship("Project", back_populates="chapters")

app/models/character.py

@@ -0,0 +1,27 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, JSON, func
+from app.database import Base
+from sqlalchemy.orm import relationship
+
+
+class Character(Base):
+    __tablename__ = "characters"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False)
+    name = Column(String(200), nullable=False)
+    aliases_json = Column(JSON, default=list)  # ["Su Ling'er", "Ling'er"]
+    role = Column(String(50), default="supporting")  # protagonist, antagonist, supporting, minor
+    gender = Column(String(20), nullable=True)
+    age_category = Column(String(20), nullable=True)  # child, teen, young_adult, adult, elder
+    visual_prompt = Column(Text, nullable=True)  # 50-80 word prompt-ready description
+    reference_image_path = Column(String(500), nullable=True)
+    portrait_url = Column(String(500), nullable=True)  # Pollinations media URL for portrait reference
+    reference_seed = Column(Integer, nullable=True)  # seed pinning for consistency
+    voice_config_json = Column(JSON, nullable=True)  # {voice_name, rate, pitch, style}
+    voice_reference_path = Column(String(500), nullable=True)  # path to .safetensors voice state (Pocket TTS)
+    voice_source_json = Column(JSON, nullable=True)  # {"source": "animevox", "character": "...", "anime": "..."}
+    wiki_data_json = Column(JSON, nullable=True)  # cached fandom wiki data
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
+
+    project = relationship("Project", back_populates="characters")

app/models/critic_result.py

@@ -0,0 +1,18 @@
+from sqlalchemy import Column, Integer, Float, DateTime, ForeignKey, JSON, func
+from app.database import Base
+from sqlalchemy.orm import relationship
+
+
+class CriticResult(Base):
+    __tablename__ = "critic_results"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    episode_id = Column(Integer, ForeignKey("episodes.id"), nullable=False)
+    visual_consistency_score = Column(Float, nullable=True)
+    pacing_score = Column(Float, nullable=True)
+    audio_sync_score = Column(Float, nullable=True)
+    overall_score = Column(Float, nullable=True)
+    feedback_json = Column(JSON, nullable=True)
+    created_at = Column(DateTime, server_default=func.now())
+
+    episode = relationship("Episode", back_populates="critic_results")

app/models/episode.py

@@ -0,0 +1,25 @@
+from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey, JSON, Text, func
+from app.database import Base
+from sqlalchemy.orm import relationship
+
+
+class Episode(Base):
+    __tablename__ = "episodes"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False)
+    episode_number = Column(Integer, nullable=False)
+    title = Column(String(500), nullable=True)
+    chapter_ids_json = Column(JSON, default=list)
+    storyboard_json = Column(JSON, nullable=True)  # full storyboard data
+    duration_seconds = Column(Float, nullable=True)
+    video_path = Column(String(500), nullable=True)
+    thumbnail_path = Column(String(500), nullable=True)
+    recap_summary = Column(Text, nullable=True)  # narrative recap for continuity
+    status = Column(String(50), default="pending")  # pending, generating, completed, error
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
+
+    project = relationship("Project", back_populates="episodes")
+    generation_jobs = relationship("GenerationJob", back_populates="episode", cascade="all, delete-orphan")
+    critic_results = relationship("CriticResult", back_populates="episode", cascade="all, delete-orphan")

app/models/generation_job.py

@@ -0,0 +1,25 @@
+from sqlalchemy import Column, Integer, String, Float, Text, DateTime, ForeignKey, JSON, func
+from app.database import Base
+from sqlalchemy.orm import relationship
+
+
+class GenerationJob(Base):
+    __tablename__ = "generation_jobs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    episode_id = Column(Integer, ForeignKey("episodes.id"), nullable=True)
+    chapter_ids_json = Column(JSON, nullable=True)
+    status = Column(String(50), default="queued")  # queued, running, completed, failed, cancelled
+    current_stage = Column(String(50), nullable=True)  # ingest, characters, scene_parse, image_gen, tts, animation, assembly, critic
+    progress_pct = Column(Float, default=0.0)
+    progress_detail = Column(Text, nullable=True)
+    error_message = Column(Text, nullable=True)
+    started_at = Column(DateTime, nullable=True)
+    completed_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, server_default=func.now())
+
+    project = relationship("Project", back_populates="generation_jobs")
+    user = relationship("User", back_populates="generation_jobs")
+    episode = relationship("Episode", back_populates="generation_jobs")

app/models/project.py

@@ -0,0 +1,24 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, JSON, func
+from sqlalchemy.orm import relationship
+from app.database import Base
+
+
+class Project(Base):
+    __tablename__ = "projects"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    title = Column(String(500), nullable=False)
+    novel_url = Column(String(2000), nullable=True)
+    cover_image_url = Column(String(2000), nullable=True)
+    synopsis = Column(Text, nullable=True)
+    settings_json = Column(JSON, default=dict)  # art style, episode length, etc.
+    status = Column(String(50), default="created")  # created, processing, completed, error
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
+
+    user = relationship("User", back_populates="projects")
+    chapters = relationship("Chapter", back_populates="project", cascade="all, delete-orphan")
+    characters = relationship("Character", back_populates="project", cascade="all, delete-orphan")
+    episodes = relationship("Episode", back_populates="project", cascade="all, delete-orphan")
+    generation_jobs = relationship("GenerationJob", back_populates="project", cascade="all, delete-orphan")

app/models/user.py

@@ -0,0 +1,18 @@
+from sqlalchemy import Column, Integer, String, DateTime, func
+from sqlalchemy.orm import relationship
+from app.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    username = Column(String(100), unique=True, nullable=False, index=True)
+    password_hash = Column(String(255), nullable=False)
+    role = Column(String(20), default="user")  # user, admin
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
+
+    projects = relationship("Project", back_populates="user", cascade="all, delete-orphan")
+    generation_jobs = relationship("GenerationJob", back_populates="user", cascade="all, delete-orphan")

app/pipeline/orchestrator.py

@@ -0,0 +1,435 @@
+"""Pipeline Orchestrator — runs all stages in sequence.
+
+Stages:
+1. Ingest — load chapters from DB
+2. Characters — extract + enrich characters
+2b. Portraits — generate reference portraits (Pollinations)
+2c. Voice Enroll — match characters to AnimeVox voices (Pocket TTS)
+3. Scene Parse — Gemini → e-konte storyboard JSON
+4. Image Gen — generate images for all cuts (Pollinations + fallback)
+5. TTS — generate voice clips (Pocket TTS for main chars, Edge TTS for narration/minor)
+6. Video Gen — AI video clips (Pollinations grok-video) with Ken Burns fallback
+7. Assembly — concat clips, scene transitions, subtitles, BGM
+8. Critic — QA review
+"""
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import async_session
+from app.models.project import Project
+from app.models.character import Character
+from app.models.episode import Episode
+from app.models.generation_job import GenerationJob
+from app.models.critic_result import CriticResult
+from app.pipeline.stage_1_ingest import run_ingest
+from app.pipeline.stage_2_characters import run_character_extraction
+from app.pipeline.stage_2b_portraits import run_portrait_generation
+from app.pipeline.stage_2c_voice_enroll import run_voice_enrollment
+from app.pipeline.stage_3_scene_parse import run_scene_parse
+from app.pipeline.stage_4_image_gen import run_image_generation
+from app.pipeline.stage_5_tts import run_tts_generation
+from app.pipeline.stage_6_video_gen import run_video_generation
+from app.pipeline.stage_6_animation import run_animation as run_ken_burns
+from app.pipeline.stage_7_assembly import run_assembly
+from app.pipeline.stage_8_critic import run_critic
+from app.pipeline.recap_generator import generate_episode_recap, build_continuity_context
+
+logger = logging.getLogger(__name__)
+
+STAGES = [
+    ("ingest", 3),
+    ("characters", 7),
+    ("portraits", 8),
+    ("voice_enroll", 4),
+    ("scene_parse", 8),
+    ("image_gen", 28),
+    ("tts", 12),
+    ("video_gen", 23),
+    ("assembly", 12),
+    ("critic", 5),
+]
+
+
+async def _update_job(job_id: int, **kwargs):
+    """Update a generation job in the database with SQLite retry on lock."""
+    for attempt in range(3):
+        try:
+            async with async_session() as db:
+                result = await db.execute(
+                    select(GenerationJob).where(GenerationJob.id == job_id)
+                )
+                job = result.scalar_one_or_none()
+                if job:
+                    for k, v in kwargs.items():
+                        setattr(job, k, v)
+                    await db.commit()
+            return
+        except Exception as e:
+            if "database is locked" in str(e) and attempt < 2:
+                await asyncio.sleep(0.5 * (attempt + 1))
+                continue
+            if attempt == 2:
+                logger.warning("_update_job failed after retries: %s", e)
+            else:
+                raise
+
+
+def _make_progress_callback(job_id: int, stage_name: str, stage_base_pct: float, stage_weight: float):
+    """Create a progress callback for a specific stage."""
+    async def callback(detail: str, stage_pct: float):
+        overall_pct = stage_base_pct + (stage_pct / 100.0) * stage_weight
+        await _update_job(
+            job_id,
+            current_stage=stage_name,
+            progress_pct=min(overall_pct, 99.0),
+            progress_detail=detail,
+        )
+    return callback
+
+
+def _check_pollinations_available() -> bool:
+    """Check if Pollinations API key is configured."""
+    from app.config import get_settings
+    settings = get_settings()
+    return bool(settings.pollinations_api_key)
+
+
+async def run_pipeline(job_id: int, resume: bool = False, chapter_ids: list[int] | None = None):
+    """Run the complete generation pipeline for a job.
+
+    If resume=True, skip stages whose outputs already exist on disk/DB.
+    If chapter_ids is provided, only ingest those specific chapters.
+    """
+    async with async_session() as db:
+        result = await db.execute(
+            select(GenerationJob).where(GenerationJob.id == job_id)
+        )
+        job = result.scalar_one_or_none()
+        if not job:
+            return
+
+        project_id = job.project_id
+        # Use chapter_ids from param, falling back to what's stored on the job
+        if chapter_ids is None:
+            chapter_ids = job.chapter_ids_json
+
+        # Get project
+        proj_result = await db.execute(
+            select(Project).where(Project.id == project_id)
+        )
+        project = proj_result.scalar_one_or_none()
+        if not project:
+            await _update_job(job_id, status="failed", error_message="Project not found")
+            return
+
+        # Compute episode number early (before any stage runs)
+        from sqlalchemy import func as sa_func
+        count_result = await db.execute(
+            select(sa_func.count()).select_from(Episode).where(Episode.project_id == project_id)
+        )
+        ep_number = (count_result.scalar() or 0) + 1
+
+        project_dir = str(Path("workdir/projects") / str(project_id))
+        Path(project_dir).mkdir(parents=True, exist_ok=True)
+
+        # Per-episode directory for episode-specific assets (storyboard, images, audio, clips)
+        episode_dir = str(Path(project_dir) / f"ep_{ep_number}")
+        Path(episode_dir).mkdir(parents=True, exist_ok=True)
+
+    use_pollinations = _check_pollinations_available()
+
+    try:
+        logger.info("Pipeline starting for job %s, project %s (resume=%s, pollinations=%s)",
+                     job_id, project_id, resume, use_pollinations)
+        await _update_job(
+            job_id,
+            status="running",
+            started_at=datetime.now(timezone.utc),
+            progress_detail="Starting pipeline..." if not resume else "Resuming pipeline...",
+        )
+
+        # Calculate stage base percentages
+        total_weight = sum(w for _, w in STAGES)
+        cumulative = 0.0
+
+        # ─── Stage 1: Ingest ───
+        logger.info("[Job %s] Stage 1: Ingest (chapter_ids=%s)", job_id, chapter_ids)
+        stage_weight = (STAGES[0][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "ingest", cumulative, stage_weight)
+        async with async_session() as db:
+            chapters = await run_ingest(project_id, db, on_progress, chapter_ids=chapter_ids)
+        cumulative += stage_weight
+        logger.info("[Job %s] Stage 1 complete: %d chapters", job_id, len(chapters))
+
+        # ─── Stage 2: Characters ───
+        logger.info("[Job %s] Stage 2: Characters", job_id)
+        stage_weight = (STAGES[1][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "characters", cumulative, stage_weight)
+
+        if resume and not chapter_ids:
+            async with async_session() as db:
+                char_result = await db.execute(
+                    select(Character).where(Character.project_id == project_id)
+                )
+                existing_chars = list(char_result.scalars().all())
+
+            if existing_chars:
+                characters = existing_chars
+                logger.info("[Job %s] Stage 2 skipped (resume): %d characters exist", job_id, len(characters))
+                await on_progress(f"Reusing {len(characters)} existing characters", 100)
+            else:
+                async with async_session() as db:
+                    characters = await run_character_extraction(
+                        project_id, project.title, chapters, db, on_progress
+                    )
+        else:
+            async with async_session() as db:
+                characters = await run_character_extraction(
+                    project_id, project.title, chapters, db, on_progress
+                )
+        cumulative += stage_weight
+        logger.info("[Job %s] Stage 2 complete: %d characters", job_id, len(characters))
+
+        # ─── Stage 2b: Portraits (Pollinations only) ───
+        if use_pollinations:
+            logger.info("[Job %s] Stage 2b: Portraits", job_id)
+            stage_weight = (STAGES[2][1] / total_weight) * 100
+            on_progress = _make_progress_callback(job_id, "portraits", cumulative, stage_weight)
+
+            # Skip if all prominent characters already have portraits
+            needs_portraits = any(
+                c.role in ("protagonist", "antagonist", "supporting") and not c.portrait_url
+                for c in characters
+            )
+
+            if needs_portraits or not resume:
+                async with async_session() as db:
+                    # Re-attach characters to this session
+                    char_result = await db.execute(
+                        select(Character).where(Character.project_id == project_id)
+                    )
+                    characters = list(char_result.scalars().all())
+                    characters = await run_portrait_generation(
+                        project_id, characters, project_dir, db, on_progress
+                    )
+            else:
+                await on_progress("All portraits exist", 100)
+
+            cumulative += stage_weight
+            portrait_count = sum(1 for c in characters if c.portrait_url)
+            logger.info("[Job %s] Stage 2b complete: %d portraits", job_id, portrait_count)
+        else:
+            cumulative += (STAGES[2][1] / total_weight) * 100
+            logger.info("[Job %s] Stage 2b skipped (no Pollinations API key)", job_id)
+
+        # ─── Stage 2c: Voice Enrollment ───
+        logger.info("[Job %s] Stage 2c: Voice Enrollment", job_id)
+        stage_weight = (STAGES[3][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "voice_enroll", cumulative, stage_weight)
+
+        # Skip if all prominent characters already have voice references
+        needs_enrollment = any(
+            c.role in ("protagonist", "antagonist", "supporting") and not c.voice_reference_path
+            for c in characters
+        )
+
+        if needs_enrollment or not resume:
+            async with async_session() as db:
+                char_result = await db.execute(
+                    select(Character).where(Character.project_id == project_id)
+                )
+                characters = list(char_result.scalars().all())
+                characters = await run_voice_enrollment(
+                    project_id, characters, project_dir, db, on_progress
+                )
+        else:
+            await on_progress("All voices already enrolled", 100)
+
+        cumulative += stage_weight
+        voice_count = sum(1 for c in characters if c.voice_reference_path)
+        logger.info("[Job %s] Stage 2c complete: %d voice enrollments", job_id, voice_count)
+
+        # ─── Narrative Continuity (pre-Stage 3) ───
+        continuity_context = None
+        if ep_number > 1:
+            logger.info("[Job %s] Building narrative continuity for Episode %d", job_id, ep_number)
+            try:
+                continuity_context = await build_continuity_context(project_id, ep_number)
+                if continuity_context:
+                    logger.info("[Job %s] Continuity context built (%d chars)", job_id, len(continuity_context))
+                else:
+                    logger.info("[Job %s] No prior episodes with recaps found", job_id)
+            except Exception as e:
+                logger.warning("[Job %s] Failed to build continuity context: %s", job_id, e)
+
+        # ─── Stage 3: Scene Parse ───
+        logger.info("[Job %s] Stage 3: Scene Parse", job_id)
+        stage_weight = (STAGES[4][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "scene_parse", cumulative, stage_weight)
+
+        storyboard_path = Path(episode_dir) / "storyboard.json"
+
+        if resume and storyboard_path.exists():
+            with open(storyboard_path, "r") as f:
+                storyboard = json.load(f)
+            logger.info("[Job %s] Stage 3 skipped (resume): loaded storyboard from disk", job_id)
+            await on_progress("Loaded existing storyboard", 100)
+        else:
+            storyboard = await run_scene_parse(chapters, characters, on_progress, continuity_context=continuity_context)
+            with open(storyboard_path, "w") as f:
+                json.dump(storyboard, f)
+            logger.info("[Job %s] Stage 3: storyboard saved to disk", job_id)
+
+        cumulative += stage_weight
+        scene_count = len(storyboard.get("scenes", []))
+        cut_count = sum(
+            len(s.get("cuts", s.get("shots", [])))
+            for s in storyboard.get("scenes", [])
+        )
+        logger.info("[Job %s] Stage 3 complete: %d scenes, %d cuts", job_id, scene_count, cut_count)
+
+        # ─── Stage 4 + 5: Image Gen + TTS (parallel) ───
+        logger.info("[Job %s] Stage 4+5: Image Gen + TTS (parallel)", job_id)
+        img_weight = (STAGES[5][1] / total_weight) * 100
+        tts_weight = (STAGES[6][1] / total_weight) * 100
+        img_progress = _make_progress_callback(job_id, "image_gen", cumulative, img_weight)
+        tts_progress = _make_progress_callback(job_id, "tts", cumulative + img_weight, tts_weight)
+
+        storyboard_img, storyboard_tts = await asyncio.gather(
+            run_image_generation(storyboard, characters, episode_dir, img_progress, resume=resume),
+            run_tts_generation(storyboard, characters, episode_dir, tts_progress, resume=resume),
+        )
+
+        # Merge TTS data into storyboard (image gen already updated in-place)
+        for scene in storyboard.get("scenes", []):
+            for cut in scene.get("cuts", scene.get("shots", [])):
+                cut_id = cut.get("cut_id") or cut.get("shot_id")
+                for tts_scene in storyboard_tts.get("scenes", []):
+                    for tts_cut in tts_scene.get("cuts", tts_scene.get("shots", [])):
+                        tts_cut_id = tts_cut.get("cut_id") or tts_cut.get("shot_id")
+                        if tts_cut_id == cut_id:
+                            cut["tts_path"] = tts_cut.get("tts_path")
+                            cut["word_timestamps"] = tts_cut.get("word_timestamps")
+                            if tts_cut.get("actual_duration_sec"):
+                                cut["actual_duration_sec"] = tts_cut["actual_duration_sec"]
+                                cut["duration_sec"] = max(
+                                    tts_cut["actual_duration_sec"] + 0.3,
+                                    cut.get("duration_sec", 2.0)
+                                )
+
+        cumulative += img_weight + tts_weight
+        logger.info("[Job %s] Stage 4+5 complete", job_id)
+
+        # Persist updated storyboard (now includes image_path, tts_path)
+        with open(Path(episode_dir) / "storyboard.json", "w") as f:
+            json.dump(storyboard, f)
+
+        # ─── Stage 6: Video Generation (or Ken Burns fallback) ───
+        logger.info("[Job %s] Stage 6: Video Generation", job_id)
+        img_count = sum(
+            1 for sc in storyboard.get("scenes", [])
+            for cut in sc.get("cuts", sc.get("shots", []))
+            if cut.get("image_path")
+        )
+        logger.info("[Job %s] Pre-video: %d cuts have image_path", job_id, img_count)
+        stage_weight = (STAGES[7][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "video_gen", cumulative, stage_weight)
+
+        if use_pollinations:
+            # Try AI video generation with Ken Burns fallback built-in
+            storyboard = await run_video_generation(storyboard, episode_dir, on_progress)
+        else:
+            # Pure Ken Burns animation (legacy path)
+            storyboard = await run_ken_burns(storyboard, episode_dir, on_progress)
+
+        cumulative += stage_weight
+
+        # Persist storyboard after video gen (includes clip_path + _video_error for debugging)
+        with open(Path(episode_dir) / "storyboard.json", "w") as f:
+            json.dump(storyboard, f)
+
+        clip_count = sum(
+            1 for sc in storyboard.get("scenes", [])
+            for cut in sc.get("cuts", sc.get("shots", []))
+            if cut.get("clip_path") and Path(cut["clip_path"]).exists()
+        )
+        logger.info("[Job %s] Stage 6 complete: %d/%d clips produced", job_id, clip_count, cut_count)
+
+        # ─── Stage 7: Assembly ───
+        logger.info("[Job %s] Stage 7: Assembly", job_id)
+        stage_weight = (STAGES[8][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "assembly", cumulative, stage_weight)
+
+        assembly_result = await run_assembly(storyboard, episode_dir, ep_number, on_progress, output_dir=project_dir)
+        cumulative += stage_weight
+        logger.info("[Job %s] Stage 7 complete: %s", job_id, assembly_result.get("video_path", "?"))
+
+        # ─── Stage 8: Critic ───
+        logger.info("[Job %s] Stage 8: Critic", job_id)
+        stage_weight = (STAGES[9][1] / total_weight) * 100
+        on_progress = _make_progress_callback(job_id, "critic", cumulative, stage_weight)
+        critic_result = await run_critic(storyboard, episode_dir, on_progress)
+
+        # Save episode and critic result to DB
+        async with async_session() as db:
+            episode = Episode(
+                project_id=project_id,
+                episode_number=ep_number,
+                title=storyboard.get("episode_title", f"Episode {ep_number}"),
+                chapter_ids_json=[ch.id for ch in chapters],
+                storyboard_json=storyboard,
+                duration_seconds=assembly_result["duration_seconds"],
+                video_path=assembly_result["video_path"],
+                status="completed",
+            )
+            db.add(episode)
+            await db.commit()
+            await db.refresh(episode)
+
+            critic = CriticResult(
+                episode_id=episode.id,
+                visual_consistency_score=critic_result.get("visual_consistency_score"),
+                pacing_score=critic_result.get("pacing_score"),
+                audio_sync_score=critic_result.get("audio_sync_score"),
+                overall_score=critic_result.get("overall_score"),
+                feedback_json=critic_result.get("feedback"),
+            )
+            db.add(critic)
+            await db.commit()
+
+            # Generate and save episode recap for future continuity
+            try:
+                recap = await generate_episode_recap(
+                    storyboard,
+                    storyboard.get("episode_title", f"Episode {ep_number}"),
+                )
+                if recap:
+                    episode.recap_summary = recap
+                    await db.commit()
+                    logger.info("[Job %s] Episode recap saved (%d chars)", job_id, len(recap))
+            except Exception as e:
+                logger.warning("[Job %s] Failed to generate episode recap: %s (non-fatal)", job_id, e)
+
+        # Mark job complete
+        await _update_job(
+            job_id,
+            status="completed",
+            progress_pct=100.0,
+            progress_detail=f"Episode {ep_number} generated successfully",
+            current_stage="completed",
+            episode_id=episode.id,
+            completed_at=datetime.now(timezone.utc),
+        )
+
+    except Exception as e:
+        logger.exception("[Job %s] Pipeline failed at stage", job_id)
+        await _update_job(
+            job_id,
+            status="failed",
+            error_message=str(e)[:2000],
+            progress_detail=f"Failed: {str(e)[:200]}",
+        )

app/pipeline/recap_generator.py

@@ -0,0 +1,191 @@
+"""Recap generator — episode narrative continuity for multi-episode series.
+
+After each episode, generates a 3-5 sentence narrative recap from the storyboard.
+Before generating a new episode, builds a continuity context block from prior recaps.
+"""
+import logging
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import async_session
+from app.models.episode import Episode
+from app.services.llm import call_gemini
+
+logger = logging.getLogger(__name__)
+
+RECAP_PROMPT = """You are summarizing an anime episode for production continuity.
+
+Given the storyboard below (dialogue, narration, and scene descriptions), write a 3-5 sentence narrative recap (~150 words).
+
+Focus on:
+- Key plot events that happened
+- Important character actions and decisions
+- Relationship changes or reveals
+- How the episode ended (cliffhanger, resolution, etc.)
+
+Write in past tense, third person. Be specific about WHAT happened, not vague.
+
+EPISODE TITLE: {episode_title}
+
+STORYBOARD:
+{storyboard_text}
+
+Write ONLY the recap, no headers or labels."""
+
+COMPRESS_PROMPT = """Compress these episode recaps into a single "story so far" summary (~200 words).
+Preserve the most important plot points, character arcs, and world-building. Drop minor details.
+Write in past tense, third person.
+
+{recaps_text}
+
+Write ONLY the compressed summary, no headers or labels."""
+
+
+def _extract_storyboard_text(storyboard: dict) -> str:
+    """Extract readable dialogue/narration from storyboard JSON."""
+    lines = []
+    for scene in storyboard.get("scenes", []):
+        setting = scene.get("setting", "")
+        mood = scene.get("mood", "")
+        if setting:
+            lines.append(f"[Scene: {setting} | Mood: {mood}]")
+
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            dialogue = cut.get("dialogue")
+            if not dialogue or not dialogue.get("text"):
+                continue
+
+            speaker = dialogue.get("speaker", "Narrator")
+            text = dialogue["text"]
+            is_narration = dialogue.get("is_narration", False)
+            is_thought = dialogue.get("is_inner_thought", False)
+
+            if is_narration:
+                lines.append(f"  (Narration) {text}")
+            elif is_thought:
+                lines.append(f"  ({speaker} thinks) {text}")
+            else:
+                lines.append(f"  {speaker}: \"{text}\"")
+
+    return "\n".join(lines)
+
+
+async def generate_episode_recap(storyboard: dict, episode_title: str) -> str:
+    """Generate a 3-5 sentence narrative recap from a completed episode's storyboard."""
+    storyboard_text = _extract_storyboard_text(storyboard)
+    if not storyboard_text.strip():
+        return ""
+
+    prompt = RECAP_PROMPT.format(
+        episode_title=episode_title,
+        storyboard_text=storyboard_text,
+    )
+
+    recap = await call_gemini(prompt, max_tokens=512, temperature=0.3)
+    return recap.strip()
+
+
+async def build_continuity_context(project_id: int, current_ep_number: int) -> str | None:
+    """Build narrative continuity context from prior episodes' recaps.
+
+    Returns a formatted continuity block string, or None if this is the first episode.
+    """
+    async with async_session() as db:
+        result = await db.execute(
+            select(Episode)
+            .where(
+                Episode.project_id == project_id,
+                Episode.episode_number < current_ep_number,
+                Episode.status == "completed",
+            )
+            .order_by(Episode.episode_number)
+        )
+        prior_episodes = list(result.scalars().all())
+
+    if not prior_episodes:
+        return None
+
+    # Lazy-generate missing recaps
+    for ep in prior_episodes:
+        if not ep.recap_summary:
+            if ep.storyboard_json:
+                logger.info("Lazy-generating recap for Episode %d", ep.episode_number)
+                try:
+                    recap = await generate_episode_recap(
+                        ep.storyboard_json,
+                        ep.title or f"Episode {ep.episode_number}",
+                    )
+                    if recap:
+                        async with async_session() as db:
+                            result = await db.execute(
+                                select(Episode).where(Episode.id == ep.id)
+                            )
+                            db_ep = result.scalar_one()
+                            db_ep.recap_summary = recap
+                            await db.commit()
+                        ep.recap_summary = recap
+                except Exception as e:
+                    logger.warning("Failed to lazy-generate recap for Episode %d: %s",
+                                   ep.episode_number, e)
+            else:
+                logger.warning("Episode %d has no storyboard_json, skipping recap",
+                               ep.episode_number)
+
+    # Collect available recaps
+    episodes_with_recaps = [(ep.episode_number, ep.title, ep.recap_summary)
+                            for ep in prior_episodes if ep.recap_summary]
+
+    if not episodes_with_recaps:
+        return None
+
+    # Build the continuity block
+    if len(episodes_with_recaps) <= 3:
+        # Few episodes — include all recaps directly
+        recap_lines = []
+        for ep_num, title, recap in episodes_with_recaps:
+            label = title or f"Episode {ep_num}"
+            recap_lines.append(f'EPISODE {ep_num} ("{label}"):\n{recap}')
+        all_recaps = "\n\n".join(recap_lines)
+
+        # Last episode gets special "PREVIOUS EPISODE" treatment
+        last_ep_num, last_title, last_recap = episodes_with_recaps[-1]
+        if len(episodes_with_recaps) == 1:
+            story_so_far = ""
+            previous_block = f'PREVIOUS EPISODE ("{last_title or f"Episode {last_ep_num}"}"):\n{last_recap}'
+        else:
+            earlier = "\n\n".join(
+                f'Episode {n} ("{t or f"Episode {n}"}"): {r}'
+                for n, t, r in episodes_with_recaps[:-1]
+            )
+            story_so_far = f"STORY SO FAR:\n{earlier}\n\n"
+            previous_block = f'PREVIOUS EPISODE ("{last_title or f"Episode {last_ep_num}"}"):\n{last_recap}'
+    else:
+        # 4+ episodes — compress older ones, keep latest full
+        older_recaps = "\n\n".join(
+            f'Episode {n} ("{t or f"Episode {n}"}"): {r}'
+            for n, t, r in episodes_with_recaps[:-1]
+        )
+        try:
+            compressed = await call_gemini(
+                COMPRESS_PROMPT.format(recaps_text=older_recaps),
+                max_tokens=512,
+                temperature=0.3,
+            )
+            story_so_far = f"STORY SO FAR:\n{compressed.strip()}\n\n"
+        except Exception as e:
+            logger.warning("Failed to compress recaps: %s — using last recap only", e)
+            story_so_far = f"STORY SO FAR:\n{older_recaps}\n\n"
+
+        last_ep_num, last_title, last_recap = episodes_with_recaps[-1]
+        previous_block = f'PREVIOUS EPISODE ("{last_title or f"Episode {last_ep_num}"}"):\n{last_recap}'
+
+    return f"""═══ NARRATIVE CONTINUITY ═══
+This is NOT the first episode. The audience has already watched the previous episode(s).
+
+{story_so_far}{previous_block}
+
+CONTINUITY RULES:
+- Do NOT re-introduce characters the audience already knows. They can appear immediately.
+- Do NOT repeat exposition from prior episodes.
+- You MAY open with a brief 1-2 cut "recall" moment echoing the previous ending (optional).
+- Reference prior events naturally through dialogue or narration when relevant.
+- Character relationships carry forward — show evolution, not reset."""

app/pipeline/stage_1_ingest.py

@@ -0,0 +1,39 @@
+"""Stage 1: Text Ingestion — get chapter text into the database."""
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.chapter import Chapter
+from app.models.project import Project
+
+
+async def run_ingest(
+    project_id: int,
+    db: AsyncSession,
+    on_progress: callable = None,
+    chapter_ids: list[int] | None = None,
+) -> list[Chapter]:
+    """Ensure chapters are loaded for the project. Returns chapter list.
+
+    If chapter_ids is provided, only load those specific chapters.
+    """
+    if on_progress:
+        await on_progress("Loading chapters...", 0)
+
+    query = select(Chapter).where(Chapter.project_id == project_id)
+    if chapter_ids:
+        query = query.where(Chapter.id.in_(chapter_ids))
+    query = query.order_by(Chapter.chapter_number)
+
+    result = await db.execute(query)
+    chapters = list(result.scalars().all())
+
+    if not chapters:
+        raise ValueError("No chapters found for this project. Add chapters first.")
+
+    total_words = sum(len(ch.source_text.split()) for ch in chapters)
+    if on_progress:
+        await on_progress(
+            f"Loaded {len(chapters)} chapter{'s' if len(chapters) != 1 else ''} ({total_words:,} words)",
+            100,
+        )
+
+    return chapters

app/pipeline/stage_2_characters.py

@@ -0,0 +1,172 @@
+"""Stage 2: Character Extraction & Enrichment."""
+import json
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.character import Character
+from app.models.chapter import Chapter
+from app.services.llm import call_gemini_json
+from app.services.fandom import search_fandom_wiki
+from app.utils.voice_mapper import assign_voice
+from app.utils.prompt_builder import build_character_visual_prompt
+
+CHARACTER_EXTRACTION_PROMPT = """You are an expert manhwa/webtoon character designer. Analyze the following novel chapter text and extract ALL named characters with COMPLETE visual designs.
+
+CRITICAL RULES:
+1. NEVER output "unknown" for ANY visual field. If the text doesn't describe a trait, INVENT a distinctive, fitting appearance based on the character's role, personality, and name origin.
+2. Every character must be VISUALLY DISTINCT from all others — no two characters should share the same hair color + style combination.
+3. Use SPECIFIC colors, not vague ones: "platinum silver" not "light", "deep crimson" not "red", "midnight blue" not "dark blue".
+4. Clothing should be detailed: "black high-collar military coat with silver trim and crimson epaulettes" not "dark clothes".
+
+For each character, provide:
+- name: The character's primary name
+- aliases: Other names/titles they go by (list)
+- role: protagonist, antagonist, supporting, or minor
+- gender: male, female, or unknown (guess from name/context if possible)
+- age_category: child, teen, young_adult, adult, or elder
+- hair_color: specific color (e.g. "jet black", "platinum silver", "deep crimson", "ash blonde")
+- hair_style: specific style (e.g. "long flowing with side-swept bangs", "short spiky undercut", "waist-length straight with center part")
+- eye_color: specific color (e.g. "golden amber", "deep violet", "ice blue", "emerald green")
+- skin_tone: specific tone (e.g. "fair porcelain", "warm olive", "deep bronze", "pale ivory")
+- height: tall, average, or short
+- build: muscular, athletic, slim, average, or heavyset
+- clothing: detailed outfit description with colors and accessories
+- distinctive_features: scars, tattoos, accessories, jewelry, etc. (invent something unique if none mentioned)
+- color_palette: 3 main colors associated with this character (e.g. ["black", "crimson", "silver"])
+- personality_notes: brief personality traits relevant to voice acting
+
+Return a JSON array of character objects. Include EVERY named character that appears, even briefly.
+
+Chapter text:
+{chapter_text}"""
+
+
+CHARACTER_DEDUP_PROMPT = """Review these character visual designs and fix any that look too similar. Two characters should NEVER share the same hair color + style combination.
+
+Current characters:
+{characters_json}
+
+Rules:
+1. If two characters have similar hair (same color family AND similar style), change ONE of them to be distinct.
+2. Ensure color_palette entries don't overlap too much between characters.
+3. Keep changes minimal — only modify what's needed for visual distinction.
+4. Return the FULL array with corrections applied.
+
+Return a JSON array of all characters (modified where needed)."""
+
+
+async def run_character_extraction(
+    project_id: int,
+    project_title: str,
+    chapters: list[Chapter],
+    db: AsyncSession,
+    on_progress: callable = None,
+) -> list[Character]:
+    """Extract characters from chapters, enrich with wiki data, assign voices."""
+
+    if on_progress:
+        await on_progress("Analyzing chapter text for characters...", 0)
+
+    # Check for existing characters
+    existing = await db.execute(
+        select(Character).where(Character.project_id == project_id)
+    )
+    existing_list = existing.scalars().all()
+    existing_chars = {c.name.lower(): c for c in existing_list}
+    # Also index by aliases for dedup
+    for c in list(existing_chars.values()):
+        for alias in (c.aliases_json or []):
+            existing_chars.setdefault(alias.lower(), c)
+
+    # Combine chapter texts for extraction (first 3 chapters for efficiency)
+    combined_text = "\n\n---\n\n".join(
+        ch.source_text[:5000] for ch in chapters[:3]
+    )
+
+    # Call Gemini for character extraction
+    prompt = CHARACTER_EXTRACTION_PROMPT.format(chapter_text=combined_text[:15000])
+    extracted = await call_gemini_json(prompt)
+
+    # Gemini may return {"characters": [...]} instead of [...]
+    if isinstance(extracted, dict):
+        extracted = extracted.get("characters", [extracted])
+    if not isinstance(extracted, list):
+        extracted = [extracted]
+
+    # Visual deduplication pass — ensure all characters look distinct
+    if len(extracted) > 1:
+        if on_progress:
+            await on_progress("Ensuring visual distinctness...", 12)
+        import json as _json
+        dedup_prompt = CHARACTER_DEDUP_PROMPT.format(
+            characters_json=_json.dumps(extracted, indent=2)
+        )
+        try:
+            deduped = await call_gemini_json(dedup_prompt)
+            if isinstance(deduped, dict):
+                deduped = deduped.get("characters", [deduped])
+            if isinstance(deduped, list) and len(deduped) == len(extracted):
+                extracted = deduped
+        except Exception:
+            pass  # dedup is nice-to-have, not critical
+
+    total = len(extracted)
+    characters = []
+
+    if on_progress and total:
+        await on_progress(f"Discovered {total} characters", 15)
+
+    for i, char_data in enumerate(extracted):
+        name = char_data.get("name", "").strip()
+        if not name or name.lower() in existing_chars:
+            if name.lower() in existing_chars:
+                characters.append(existing_chars[name.lower()])
+            continue
+
+        if on_progress:
+            pct = int(20 + (i / max(total, 1)) * 60)
+            await on_progress(f"Enriching {name} ({i+1}/{total})", pct)
+
+        # Try fandom wiki enrichment
+        wiki_data = await search_fandom_wiki(project_title, name)
+        if wiki_data and wiki_data.get("description"):
+            # Merge wiki appearance data (prefer wiki, more detailed)
+            char_data["wiki_appearance"] = wiki_data["description"]
+
+        # Build visual prompt
+        visual_prompt = build_character_visual_prompt(char_data)
+
+        # Assign voice
+        voice_config = assign_voice(
+            project_id,
+            char_data.get("gender"),
+            char_data.get("age_category"),
+        )
+
+        # Normalize aliases (Gemini may return a comma-separated string)
+        aliases = char_data.get("aliases", [])
+        if isinstance(aliases, str):
+            aliases = [a.strip() for a in aliases.split(",") if a.strip()]
+
+        # Create character record
+        character = Character(
+            project_id=project_id,
+            name=name,
+            aliases_json=aliases,
+            role=char_data.get("role", "supporting"),
+            gender=char_data.get("gender"),
+            age_category=char_data.get("age_category"),
+            visual_prompt=visual_prompt,
+            voice_config_json=voice_config,
+            wiki_data_json=wiki_data,
+        )
+        db.add(character)
+        characters.append(character)
+
+    await db.commit()
+    for ch in characters:
+        await db.refresh(ch)
+
+    if on_progress:
+        await on_progress(f"{len(characters)} characters ready", 100)
+
+    return characters

app/pipeline/stage_2b_portraits.py

@@ -0,0 +1,118 @@
+"""Stage 2b: Character Portrait Generation.
+
+Generates a high-quality reference portrait for each prominent character,
+uploads to media.pollinations.ai, and stores the URL in the Character model.
+These portraits are used as visual references during scene image generation
+with vision-capable models (klein, gptimage) for character consistency.
+"""
+import asyncio
+import logging
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.character import Character
+from app.services.pollinations import generate_image, upload_media, VISION_MODELS
+from app.utils.prompt_builder import MANHWA_STYLE_PREFIX
+
+logger = logging.getLogger(__name__)
+
+PORTRAIT_PROMPT_TEMPLATE = (
+    "{style_prefix}, character portrait sheet, front-facing bust shot, "
+    "{visual_prompt}, clean white background, reference sheet style, "
+    "sharp details, no background elements, studio lighting, "
+    "high detail face and eyes, character design reference"
+)
+
+# Only generate portraits for prominent roles
+PROMINENT_ROLES = {"protagonist", "antagonist", "supporting"}
+
+# Use klein-large for portraits — scene images also use klein-large with this
+# portrait as reference. Same model = same style space = consistent characters.
+PORTRAIT_MODEL = "klein-large"
+PORTRAIT_SEED = 42
+
+
+async def run_portrait_generation(
+    project_id: int,
+    characters: list[Character],
+    project_dir: str,
+    db: AsyncSession,
+    on_progress: callable = None,
+) -> list[Character]:
+    """Generate reference portraits for prominent characters.
+
+    Skips characters that already have a portrait_url.
+    Returns the updated character list.
+    """
+    # Filter to prominent characters without portraits
+    targets = [
+        c for c in characters
+        if c.role in PROMINENT_ROLES
+        and c.visual_prompt
+        and not c.portrait_url
+    ]
+
+    if not targets:
+        if on_progress:
+            await on_progress("All characters already have portraits", 100)
+        return characters
+
+    total = len(targets)
+    if on_progress:
+        await on_progress(f"Generating {total} character portraits...", 0)
+
+    portrait_dir = Path(project_dir) / "portraits"
+    portrait_dir.mkdir(parents=True, exist_ok=True)
+
+    completed = 0
+
+    for char in targets:
+        if on_progress:
+            pct = int((completed / max(total, 1)) * 90)
+            await on_progress(f"[{completed + 1}/{total}] Painting {char.name}...", pct)
+
+        portrait_path = str(portrait_dir / f"{char.name.replace(' ', '_')}_portrait.png")
+
+        try:
+            # Generate portrait image
+            prompt = PORTRAIT_PROMPT_TEMPLATE.format(
+                style_prefix=MANHWA_STYLE_PREFIX,
+                visual_prompt=char.visual_prompt,
+            )
+
+            await generate_image(
+                prompt=prompt,
+                output_path=portrait_path,
+                model=PORTRAIT_MODEL,
+                width=768,
+                height=1024,  # Portrait orientation
+                seed=PORTRAIT_SEED,
+            )
+
+            # Upload to media.pollinations.ai for permanent URL
+            portrait_url = await upload_media(portrait_path)
+            char.portrait_url = portrait_url
+            char.reference_image_path = portrait_path
+
+            logger.info("Portrait generated for %s: %s", char.name, portrait_url)
+
+        except Exception as e:
+            logger.warning("Portrait generation failed for %s: %s", char.name, e)
+            # Non-fatal — character just won't have a portrait reference
+
+        completed += 1
+
+    # Persist portrait URLs to database
+    try:
+        await db.commit()
+        for char in characters:
+            await db.refresh(char)
+    except Exception as e:
+        logger.warning("Failed to persist portrait URLs: %s", e)
+
+    if on_progress:
+        success_count = sum(1 for c in targets if c.portrait_url)
+        await on_progress(f"{success_count}/{total} portraits generated", 100)
+
+    return characters

app/pipeline/stage_2c_voice_enroll.py

@@ -0,0 +1,177 @@
+"""Stage 2c: Voice Enrollment — assign AnimeVox voices to prominent characters.
+
+Runs after Stage 2b (portraits), before Stage 3 (scene parse).
+Matches each protagonist/antagonist/supporting character to an AnimeVox voice
+based on gender, age, and personality traits, then stores the voice state path
+for Pocket TTS to use during TTS generation.
+
+Gracefully degrades: if AnimeVox is not set up, all characters fall back to Edge TTS.
+"""
+import logging
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.character import Character
+from app.utils.voice_catalog import match_voice, is_available
+
+logger = logging.getLogger(__name__)
+
+PROMINENT_ROLES = {"protagonist", "antagonist", "supporting"}
+
+# Manual voice overrides: character name (case-insensitive) → catalog voice ID
+# Use this to force a specific voice when auto-matching picks a bad fit.
+VOICE_OVERRIDES: dict[str, str] = {
+    "ye chen": "genshin_diluc",
+}
+
+
+async def run_voice_enrollment(
+    project_id: int,
+    characters: list[Character],
+    project_dir: str,
+    db: AsyncSession,
+    on_progress: callable = None,
+) -> list[Character]:
+    """Enroll voices for prominent characters using AnimeVox catalog.
+
+    For each protagonist/antagonist/supporting without a voice_reference_path:
+    1. Load voice catalog
+    2. Match character to best AnimeVox voice (gender + age + traits)
+    3. Store voice state path in character model
+    4. Persist to DB
+
+    Returns the updated character list.
+    """
+    if not is_available():
+        if on_progress:
+            await on_progress("AnimeVox not set up — using Edge TTS for all characters", 100)
+        logger.info("Voice enrollment skipped: AnimeVox catalog not found")
+        return characters
+
+    # Filter to prominent characters that need voice enrollment
+    targets = [
+        c for c in characters
+        if c.role in PROMINENT_ROLES
+        and not c.voice_reference_path  # don't re-enroll
+    ]
+
+    if not targets:
+        if on_progress:
+            await on_progress("All characters already have voices assigned", 100)
+        return characters
+
+    total = len(targets)
+    if on_progress:
+        await on_progress(f"Matching voices for {total} characters...", 0)
+
+    enrolled = 0
+    for i, char in enumerate(targets):
+        if on_progress:
+            pct = int((i / max(total, 1)) * 90)
+            await on_progress(f"[{i+1}/{total}] Matching voice for {char.name}...", pct)
+
+        # Check manual overrides first
+        override_id = VOICE_OVERRIDES.get(char.name.lower())
+        if override_id:
+            match = _get_override_voice(override_id)
+            if match:
+                logger.info("Voice override: %s → %s", char.name, match["display_name"])
+        else:
+            match = None
+
+        if not match:
+            # Extract personality hints from visual_prompt or wiki data
+            personality_hints = _extract_personality_hints(char)
+
+            match = match_voice(
+                project_id=project_id,
+                gender=char.gender or "male",
+                age_category=char.age_category or "young_adult",
+                role=char.role,
+                personality_hints=personality_hints,
+            )
+
+        # Determine voice reference: .safetensors path or preset name
+        voice_ref = None
+        if match:
+            if match.get("voice_state_path") and Path(match["voice_state_path"]).exists():
+                voice_ref = match["voice_state_path"]
+            elif match.get("preset_voice"):
+                voice_ref = match["preset_voice"]
+
+        if match and voice_ref:
+            char.voice_reference_path = voice_ref
+            char.voice_source_json = {
+                "source": "animevox",
+                "character": match["display_name"],
+                "anime": match["source_anime"],
+                "voice_id": match["id"],
+                "type": "cloned" if voice_ref.endswith(".safetensors") else "preset",
+            }
+            enrolled += 1
+            logger.info(
+                "Voice enrolled: %s → %s (%s)",
+                char.name, match["display_name"], match["source_anime"],
+            )
+        else:
+            logger.info(
+                "No voice match for %s (%s/%s) — will use Edge TTS",
+                char.name, char.gender, char.age_category,
+            )
+
+    # Persist to database
+    if enrolled > 0:
+        try:
+            await db.commit()
+            for char in characters:
+                await db.refresh(char)
+        except Exception as e:
+            logger.warning("Failed to persist voice enrollment: %s", e)
+
+    if on_progress:
+        await on_progress(
+            f"{enrolled}/{total} characters matched to anime voices", 100
+        )
+
+    logger.info(
+        "Voice enrollment complete: %d/%d characters enrolled", enrolled, total
+    )
+    return characters
+
+
+def _get_override_voice(voice_id: str) -> dict | None:
+    """Look up a specific voice by ID from the catalog."""
+    from app.utils.voice_catalog import get_catalog
+
+    for entry in get_catalog():
+        if entry.get("id") == voice_id:
+            return entry
+    logger.warning("Voice override ID '%s' not found in catalog", voice_id)
+    return None
+
+
+def _extract_personality_hints(char: Character) -> list[str]:
+    """Extract personality keywords from character data for voice matching."""
+    hints = []
+
+    # From wiki data
+    wiki = char.wiki_data_json or {}
+    if isinstance(wiki, dict):
+        personality = wiki.get("personality", "")
+        if personality:
+            # Extract adjectives from personality description
+            for word in personality.lower().split():
+                word = word.strip(".,;:!?()[]")
+                if len(word) > 3:  # skip short words
+                    hints.append(word)
+
+    # From role — add implied traits
+    role_hints = {
+        "protagonist": ["determined", "heroic"],
+        "antagonist": ["cold", "menacing", "calculating"],
+        "supporting": ["warm", "loyal"],
+    }
+    hints.extend(role_hints.get(char.role, []))
+
+    return hints[:10]  # cap to avoid noise

app/pipeline/stage_3_scene_parse.py

@@ -0,0 +1,346 @@
+"""Stage 3: Scene Parsing — convert chapter text to e-konte storyboard JSON."""
+import re
+from app.models.chapter import Chapter
+from app.models.character import Character
+from app.services.llm import call_gemini_json
+from app.templates.storyboard_prompt import (
+    STORYBOARD_SYSTEM,
+    STORYBOARD_PROMPT,
+    format_characters_block,
+)
+
+
+def _estimate_duration(dialogue: dict | None, action: str | None) -> float:
+    """Estimate cut duration based on content."""
+    if dialogue:
+        text = dialogue.get("text") or ""
+        if not text:
+            return 2.0
+        if dialogue.get("is_narration") or dialogue.get("is_inner_thought"):
+            dur = len(text) / 12 + 0.5
+        else:
+            dur = len(text) / 15 + 0.5
+        return max(0.5, min(dur, 12.0))
+    if action:
+        return max(2.0, min(len(action) / 20, 5.0))
+    return 2.0
+
+
+def _normalize_cuts(storyboard: dict) -> dict:
+    """Normalize storyboard to use 'cuts' consistently.
+
+    The new e-konte format uses 'cuts', but the old format used 'shots'.
+    This function ensures we always have a 'cuts' key on each scene,
+    while keeping 'shots' as an alias for backward compatibility.
+    """
+    for scene in storyboard.get("scenes", []):
+        # If scene has 'shots' but not 'cuts', rename
+        if "shots" in scene and "cuts" not in scene:
+            scene["cuts"] = scene.pop("shots")
+        # If scene has 'cuts', also set 'shots' alias for backward compat
+        if "cuts" in scene:
+            scene["shots"] = scene["cuts"]
+        # Handle cut_id vs shot_id
+        for cut in scene.get("cuts", []):
+            if "shot_id" in cut and "cut_id" not in cut:
+                cut["cut_id"] = cut["shot_id"]
+            elif "cut_id" in cut and "shot_id" not in cut:
+                cut["shot_id"] = cut["cut_id"]
+    return storyboard
+
+
+def _build_alias_map(characters: list[Character]) -> dict[str, str]:
+    """Build a lowercase alias → canonical name map from characters."""
+    alias_map = {}
+    for c in characters:
+        for alias in (c.aliases_json or []):
+            alias_map[alias.lower()] = c.name
+    return alias_map
+
+
+def _resolve_name(name: str, character_names: set[str], alias_map: dict[str, str]) -> str | None:
+    """Resolve a name to its canonical form via direct match or alias lookup."""
+    if name in character_names:
+        return name
+    canonical = alias_map.get(name.lower())
+    if canonical and canonical in character_names:
+        return canonical
+    return None
+
+
+def _validate_storyboard(storyboard: dict, characters: list[Character]) -> dict:
+    """Post-process storyboard: fix IDs, validate characters, recalc durations."""
+    character_names = {c.name for c in characters}
+    alias_map = _build_alias_map(characters)
+    cut_counter = 0
+
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            cut_counter += 1
+            cut_id = f"C{cut_counter:02d}"
+            cut["cut_id"] = cut_id
+            cut["shot_id"] = cut_id  # Backward compat alias
+
+            # Coerce characters_present to list and resolve aliases
+            chars_present = cut.get("characters_present", [])
+            if isinstance(chars_present, str):
+                chars_present = [chars_present]
+            valid_chars = []
+            for c in chars_present:
+                resolved = _resolve_name(c, character_names, alias_map)
+                if resolved and resolved not in valid_chars:
+                    valid_chars.append(resolved)
+            cut["characters_present"] = valid_chars
+
+            # Resolve focal_character via alias
+            focal = cut.get("focal_character")
+            if focal:
+                resolved_focal = _resolve_name(focal, character_names, alias_map)
+                cut["focal_character"] = resolved_focal if resolved_focal else (valid_chars[0] if valid_chars else None)
+            elif focal is not None and not focal:
+                cut["focal_character"] = None
+
+            # Enforce: on-screen speaker should be focal_character
+            dialogue = cut.get("dialogue")
+            if dialogue and dialogue.get("text"):
+                speaker = dialogue.get("speaker", "")
+                resolved_speaker = _resolve_name(speaker, character_names, alias_map)
+                # Replace alias in dialogue.speaker with canonical name
+                if resolved_speaker and resolved_speaker != speaker:
+                    dialogue["speaker"] = resolved_speaker
+                    speaker = resolved_speaker
+                is_offscreen = dialogue.get("is_offscreen", False)
+                is_narration = dialogue.get("is_narration", False)
+                is_thought = dialogue.get("is_inner_thought", False)
+
+                if (speaker != "Narrator"
+                    and speaker in character_names
+                    and not is_offscreen
+                    and not is_narration
+                    and not is_thought):
+                    # Speaker is on-screen → must be in characters_present and focal
+                    if speaker not in valid_chars:
+                        valid_chars.append(speaker)
+                        cut["characters_present"] = valid_chars
+                    if not cut.get("focal_character") or cut["focal_character"] != speaker:
+                        cut["focal_character"] = speaker
+
+            # Coerce dialogue: if string, wrap as narration
+            dialogue = cut.get("dialogue")
+            if isinstance(dialogue, str):
+                cut["dialogue"] = {
+                    "text": dialogue,
+                    "speaker": "Narrator",
+                    "is_narration": True,
+                }
+
+            # Coerce duration_sec to float
+            try:
+                cut["duration_sec"] = float(cut.get("duration_sec", 0))
+            except (TypeError, ValueError):
+                cut["duration_sec"] = 0
+
+            # Recalculate duration
+            cut["duration_sec"] = _estimate_duration(
+                cut.get("dialogue"), cut.get("action_description")
+            )
+
+            # Ensure effects is a list
+            if not isinstance(cut.get("effects"), list):
+                cut["effects"] = []
+
+            # Default camera movement
+            if not cut.get("camera_movement"):
+                cut["camera_movement"] = "FIX"
+
+            # Ensure video_prompt exists (backfill from action + camera if missing)
+            if not cut.get("video_prompt"):
+                parts = []
+                if cut.get("action_description"):
+                    parts.append(cut["action_description"])
+                camera = cut.get("camera_movement", "FIX")
+                if camera != "FIX":
+                    parts.append(f"camera: {camera}")
+                cut["video_prompt"] = ", ".join(parts) if parts else "subtle idle animation, atmospheric motion"
+
+            # Ensure transition_out exists
+            if not cut.get("transition_out"):
+                cut["transition_out"] = "cut"
+
+            # Ensure emotional_beat exists
+            if not cut.get("emotional_beat"):
+                cut["emotional_beat"] = "setup"
+
+    # Narration backfill: ensure every cut has dialogue
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            dialogue = cut.get("dialogue")
+            has_text = dialogue and dialogue.get("text")
+            if not has_text:
+                action = cut.get("action_description", "")
+                if action:
+                    cut["dialogue"] = {
+                        "speaker": "Narrator",
+                        "text": action,
+                        "is_narration": True,
+                        "emotion": "neutral",
+                        "delivery": "normal",
+                    }
+
+    return storyboard
+
+
+def _enforce_cut_limit(storyboard: dict, max_cuts: int = 12) -> dict:
+    """If total cut count exceeds max_cuts, keep the highest-scoring cuts."""
+    all_cuts = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            # Score: dialogue=3, establishing=2, narration=1, reaction/empty=0
+            # Bonus for climax/tension_peak emotional beats
+            score = 0
+            dialogue = cut.get("dialogue")
+            if dialogue and dialogue.get("text"):
+                if dialogue.get("is_narration"):
+                    score = 1
+                else:
+                    score = 3
+            if cut.get("shot_type") == "establishing":
+                score = max(score, 2)
+            # Emotional beat bonus
+            beat = cut.get("emotional_beat", "")
+            if beat in ("climax", "tension_peak"):
+                score += 2
+            elif beat in ("rising_tension", "resolution"):
+                score += 1
+            all_cuts.append((scene["scene_id"], cut, score))
+
+    total = len(all_cuts)
+    if total <= max_cuts:
+        return storyboard
+
+    # Sort by score descending, keep top max_cuts, then restore original order
+    indexed = [(i, sid, cut, score) for i, (sid, cut, score) in enumerate(all_cuts)]
+    indexed.sort(key=lambda x: x[3], reverse=True)
+    kept = sorted(indexed[:max_cuts], key=lambda x: x[0])  # restore order
+
+    # Rebuild scenes with only kept cuts
+    kept_by_scene: dict[str, list] = {}
+    for _, sid, cut, _ in kept:
+        kept_by_scene.setdefault(sid, []).append(cut)
+
+    new_scenes = []
+    for scene in storyboard.get("scenes", []):
+        sid = scene["scene_id"]
+        if sid in kept_by_scene:
+            scene["cuts"] = kept_by_scene[sid]
+            scene["shots"] = scene["cuts"]  # Backward compat
+            new_scenes.append(scene)
+
+    storyboard["scenes"] = new_scenes
+
+    # Re-number cut IDs
+    counter = 0
+    for scene in storyboard["scenes"]:
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            counter += 1
+            cut["cut_id"] = f"C{counter:02d}"
+            cut["shot_id"] = f"C{counter:02d}"
+
+    return storyboard
+
+
+async def run_scene_parse(
+    chapters: list[Chapter],
+    characters: list[Character],
+    on_progress: callable = None,
+    continuity_context: str | None = None,
+) -> dict:
+    """Parse chapter text into an e-konte storyboard JSON using Gemini."""
+    if on_progress:
+        await on_progress("AI Director is composing the e-konte...", 0)
+
+    # Prepare character data
+    char_data = [
+        {"name": c.name, "role": c.role, "visual_prompt": c.visual_prompt}
+        for c in characters
+    ]
+    char_names = {c.name for c in characters}
+    characters_block = format_characters_block(char_data)
+
+    # Combine chapter text (limit to ~15k chars for Gemini)
+    combined_text = "\n\n".join(ch.source_text for ch in chapters)
+    if len(combined_text) > 15000:
+        combined_text = combined_text[:15000] + "\n\n[Text truncated for processing]"
+
+    continuity_block = continuity_context or ""
+
+    # Count paragraphs so the LLM knows how much content to cover
+    paragraphs = [p.strip() for p in combined_text.split("\n") if p.strip()]
+    para_hint = f"\n\n[This chapter has {len(paragraphs)} paragraphs. You need at least {max(25, len(paragraphs))} cuts to cover it all.]\n"
+
+    prompt = STORYBOARD_PROMPT.format(
+        characters_block=characters_block,
+        continuity_block=continuity_block,
+        chapter_text=combined_text + para_hint,
+    )
+
+    if on_progress:
+        await on_progress("Composing storyboard...", 20)
+
+    # Use the stronger model for storyboard — flash-lite truncates large JSON
+    storyboard = await call_gemini_json(
+        prompt,
+        system_instruction=STORYBOARD_SYSTEM,
+        max_tokens=65536,
+        model="gemini-2.5-flash",
+    )
+
+    # Gemini may return the scenes array directly instead of {"scenes": [...]}
+    if not isinstance(storyboard, dict) or "scenes" not in storyboard:
+        if isinstance(storyboard, list):
+            storyboard = {"scenes": storyboard}
+        else:
+            raise ValueError("Storyboard must be a dict with 'scenes' key")
+
+    scene_count = len(storyboard.get("scenes", []))
+    raw_cuts = sum(
+        len(s.get("cuts", s.get("shots", [])))
+        for s in storyboard.get("scenes", [])
+    )
+
+    if on_progress:
+        await on_progress(f"Validating {scene_count} scenes, {raw_cuts} cuts...", 80)
+
+    # Normalize cuts/shots naming
+    storyboard = _normalize_cuts(storyboard)
+
+    # Post-process
+    storyboard = _validate_storyboard(storyboard, characters)
+    storyboard = _enforce_cut_limit(storyboard, max_cuts=50)
+
+    total_cuts = sum(
+        len(scene.get("cuts", scene.get("shots", [])))
+        for scene in storyboard.get("scenes", [])
+    )
+    total_duration = sum(
+        cut.get("duration_sec", 2)
+        for scene in storyboard.get("scenes", [])
+        for cut in scene.get("cuts", scene.get("shots", []))
+    )
+
+    storyboard["metadata"] = {
+        "total_shots": total_cuts,
+        "total_cuts": total_cuts,
+        "total_duration_estimate": round(total_duration, 1),
+        "scene_count": len(storyboard.get("scenes", [])),
+    }
+
+    if on_progress:
+        mins = int(total_duration // 60)
+        secs = int(total_duration % 60)
+        await on_progress(
+            f"E-konte ready — {total_cuts} cuts, ~{mins}:{secs:02d}",
+            100,
+        )
+
+    return storyboard

app/pipeline/stage_4_image_gen.py

@@ -0,0 +1,137 @@
+"""Stage 4: Image Generation — bulk generate images for all storyboard cuts."""
+import asyncio
+from pathlib import Path
+from app.models.character import Character
+from app.services.image_gen import generate_image
+from app.utils.prompt_builder import build_image_prompt
+
+
+async def run_image_generation(
+    storyboard: dict,
+    characters: list[Character],
+    project_dir: str,
+    on_progress: callable = None,
+    resume: bool = False,
+) -> dict:
+    """Generate images for all cuts in the storyboard.
+
+    Returns updated storyboard with image_path set on each cut.
+    If resume=True, skip cuts whose image files already exist on disk.
+
+    Uses Pollinations as primary provider with vision-capable models
+    for characters that have portrait references (for consistency).
+    """
+    # Support both new "cuts" and legacy "shots" format
+    all_cuts = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            all_cuts.append(cut)
+
+    total = len(all_cuts)
+    if on_progress:
+        await on_progress(f"Preparing {total} images...", 0)
+
+    # Build character prompt map and portrait URL map (with alias support)
+    char_prompts = {c.name: c.visual_prompt for c in characters if c.visual_prompt}
+    char_portraits = {c.name: c.portrait_url for c in characters if c.portrait_url}
+    # Alias map: alias → canonical name
+    alias_map: dict[str, str] = {}
+    for c in characters:
+        for alias in (c.aliases_json or []):
+            alias_map[alias.lower()] = c.name
+
+    completed = 0
+    skipped = 0
+    errors = []
+
+    img_dir = Path(project_dir) / "images"
+    img_dir.mkdir(parents=True, exist_ok=True)
+
+    async def generate_one(cut: dict) -> None:
+        nonlocal completed, skipped
+        cut_id = cut.get("cut_id") or cut.get("shot_id", "S00")
+        output_path = str(img_dir / f"{cut_id}.png")
+
+        # Resume: skip if file already exists on disk
+        if resume and Path(output_path).exists():
+            cut["image_path"] = output_path
+            skipped += 1
+            completed += 1
+            if on_progress:
+                pct = int((completed / max(total, 1)) * 100)
+                await on_progress(f"[{completed}/{total}] {cut_id} (cached)", pct)
+            return
+
+        # Build prompt
+        prompt = build_image_prompt(cut, char_prompts)
+
+        # Use klein-large for ALL shots to maintain consistent aesthetics.
+        # Same model + same seed = uniform art style across entire episode.
+        # grok-imagine only used as fallback if klein-large fails.
+        provider = "pollinations"
+        pollinations_model = "klein-large"
+        reference_url = None
+        seed = 42  # Locked seed for style consistency
+
+        # Pass portrait reference for character shots (with alias fallback)
+        focal = cut.get("focal_character")
+        resolved_focal = focal
+        if focal and focal not in char_portraits:
+            resolved_focal = alias_map.get(focal.lower(), focal)
+        if resolved_focal and resolved_focal in char_portraits:
+            reference_url = char_portraits[resolved_focal]
+        else:
+            # Wide/establishing: use any present character's portrait as ref
+            for c in cut.get("characters_present", []):
+                resolved_c = c if c in char_portraits else alias_map.get(c.lower(), c)
+                if resolved_c in char_portraits:
+                    reference_url = char_portraits[resolved_c]
+                    break
+
+        try:
+            await generate_image(
+                prompt=prompt,
+                output_path=output_path,
+                provider=provider,
+                seed=seed,
+                pollinations_model=pollinations_model,
+                reference_image_url=reference_url,
+            )
+            cut["image_path"] = output_path
+        except Exception as e:
+            # Fallback: retry with grok-imagine (no reference) if klein-large failed
+            if pollinations_model == "klein-large":
+                try:
+                    await generate_image(
+                        prompt=prompt,
+                        output_path=output_path,
+                        provider=provider,
+                        seed=seed,
+                        pollinations_model="grok-imagine",
+                        reference_image_url=None,
+                    )
+                    cut["image_path"] = output_path
+                    errors.append(f"{cut_id}: klein-large failed, used grok-imagine fallback")
+                except Exception as e2:
+                    errors.append(f"{cut_id}: {e} | fallback also failed: {e2}")
+                    cut["image_path"] = None
+            else:
+                errors.append(f"{cut_id}: {e}")
+                cut["image_path"] = None
+
+        completed += 1
+        if on_progress:
+            pct = int((completed / max(total, 1)) * 100)
+            prompt_preview = prompt[:40].rstrip() + "..." if len(prompt) > 40 else prompt
+            await on_progress(f"[{completed}/{total}] {prompt_preview}", pct)
+
+    # Run with concurrency limit (semaphores are in the image_gen service)
+    await asyncio.gather(*[generate_one(cut) for cut in all_cuts])
+
+    if on_progress:
+        err_suffix = f" ({len(errors)} errors)" if errors else ""
+        skip_suffix = f" ({skipped} cached)" if skipped else ""
+        await on_progress(f"{total} images generated{skip_suffix}{err_suffix}", 100)
+
+    storyboard["_image_errors"] = errors
+    return storyboard

app/pipeline/stage_5_tts.py

@@ -0,0 +1,242 @@
+"""Stage 5: TTS Generation — generate voice clips for all dialogue/narration.
+
+Dual-engine dispatch:
+- Characters with voice_reference_path → Pocket TTS (anime voice cloning)
+- Narration + characters without voice_reference_path → Edge TTS (fast, free)
+"""
+import asyncio
+import logging
+from pathlib import Path
+from app.models.character import Character
+from app.services.tts import generate_tts_batch
+
+logger = logging.getLogger(__name__)
+
+# Narrator voice: Zhongli via Pocket TTS (deep, wise, authoritative)
+NARRATOR_VOICE_REF = "data/genshin_voices/zhongli/voice_state.safetensors"
+
+# Edge TTS fallback for narrator (if Pocket TTS fails)
+NARRATOR_VOICE = {
+    "voice_name": "en-US-ChristopherNeural",
+    "rate": "-5%",
+    "pitch": "-5Hz",
+}
+
+
+async def _generate_pocket_tts_items(items: list[dict]) -> list[dict]:
+    """Generate TTS clips using Pocket TTS (sequential, CPU-bound).
+
+    Pocket TTS is single-threaded internally so we process one at a time
+    via asyncio.to_thread() to avoid blocking the event loop.
+    """
+    from app.services.pocket_tts_service import PocketTTSService
+
+    results = []
+    for item in items:
+        try:
+            result = await PocketTTSService.generate(
+                text=item["text"],
+                voice_ref=item["voice_ref"],
+                output_path=item["output_path"],
+            )
+            result["shot_id"] = item.get("shot_id")
+            result["word_timestamps"] = []  # Pocket TTS doesn't provide word timing
+            results.append(result)
+        except Exception as e:
+            logger.warning(
+                "Pocket TTS failed for %s: %s — falling back to Edge TTS",
+                item.get("shot_id"), e,
+            )
+            # Fallback: use Edge TTS for this item
+            fallback_result = await _edge_tts_fallback(item)
+            results.append(fallback_result)
+
+    return results
+
+
+async def _edge_tts_fallback(item: dict) -> dict:
+    """Generate a single clip via Edge TTS as fallback."""
+    from app.services.tts import generate_tts
+
+    # Change extension to .mp3 for Edge TTS
+    output_path = item["output_path"]
+    if output_path.endswith(".wav"):
+        output_path = output_path[:-4] + ".mp3"
+
+    vc = item.get("voice_config") or NARRATOR_VOICE
+    result = await generate_tts(
+        text=item["text"],
+        output_path=output_path,
+        voice_name=vc.get("voice_name", "en-US-ChristopherNeural"),
+        rate=vc.get("rate", "+0%"),
+        pitch=vc.get("pitch", "+0Hz"),
+        emotion=item.get("emotion", "neutral"),
+    )
+    result["shot_id"] = item.get("shot_id")
+    return result
+
+
+async def run_tts_generation(
+    storyboard: dict,
+    characters: list[Character],
+    project_dir: str,
+    on_progress: callable = None,
+    resume: bool = False,
+) -> dict:
+    """Generate TTS for all cuts with dialogue/narration.
+
+    Dispatches to Pocket TTS (cloned anime voices) or Edge TTS based on
+    whether the character has a voice_reference_path set.
+
+    Returns updated storyboard with tts_path and actual_duration_sec set.
+    If resume=True, skip cuts whose audio files already exist on disk.
+    """
+    if on_progress:
+        await on_progress("Preparing voice clips...", 0)
+
+    # Build character maps
+    char_voices = {}  # name -> Edge TTS voice config
+    char_voice_refs = {}  # name -> Pocket TTS voice ref (safetensors path or preset name)
+    for c in characters:
+        if c.voice_reference_path:
+            ref = c.voice_reference_path
+            # Accept both file paths (if they exist) and preset names
+            if Path(ref).exists() or not ref.endswith((".safetensors", ".wav")):
+                char_voice_refs[c.name] = ref
+        if c.voice_config_json:
+            char_voices[c.name] = c.voice_config_json
+
+    audio_dir = Path(project_dir) / "audio"
+    audio_dir.mkdir(parents=True, exist_ok=True)
+
+    # Collect TTS tasks, split by engine
+    edge_items = []
+    pocket_items = []
+    skipped = 0
+
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            dialogue = cut.get("dialogue")
+            if not dialogue or not dialogue.get("text"):
+                # Belt-and-suspenders: create narration from action_description
+                action = cut.get("action_description", "")
+                if not action:
+                    continue  # truly empty — skip
+                dialogue = {
+                    "speaker": "Narrator",
+                    "text": action,
+                    "is_narration": True,
+                    "emotion": "neutral",
+                    "delivery": "normal",
+                }
+                cut["dialogue"] = dialogue
+
+            speaker = dialogue.get("speaker", "Narrator")
+            is_narration = dialogue.get("is_narration", False)
+
+            # Determine engine:
+            # - Narrator → Pocket TTS with Zhongli (fallback to Edge TTS)
+            # - Characters with voice refs → Pocket TTS
+            # - Others → Edge TTS
+            is_narrator_line = is_narration or speaker == "Narrator"
+            narrator_ref_exists = Path(NARRATOR_VOICE_REF).exists()
+            use_pocket = (
+                (is_narrator_line and narrator_ref_exists)
+                or (not is_narrator_line and speaker in char_voice_refs)
+            )
+
+            # File extension: .wav for Pocket TTS, .mp3 for Edge TTS
+            ext = ".wav" if use_pocket else ".mp3"
+            output_path = str(audio_dir / f"{cut_id}{ext}")
+
+            # Resume: skip if audio file already exists (check both extensions)
+            if resume:
+                wav_path = str(audio_dir / f"{cut_id}.wav")
+                mp3_path = str(audio_dir / f"{cut_id}.mp3")
+                if Path(wav_path).exists() or Path(mp3_path).exists():
+                    cut["tts_path"] = wav_path if Path(wav_path).exists() else mp3_path
+                    skipped += 1
+                    continue
+
+            if use_pocket:
+                voice_ref = NARRATOR_VOICE_REF if is_narrator_line else char_voice_refs[speaker]
+                pocket_items.append({
+                    "shot_id": cut_id,
+                    "text": dialogue["text"],
+                    "output_path": output_path,
+                    "voice_ref": voice_ref,
+                    "voice_config": char_voices.get(speaker, NARRATOR_VOICE),
+                    "emotion": dialogue.get("emotion", "neutral"),
+                })
+            else:
+                voice_config = NARRATOR_VOICE if is_narrator_line else char_voices.get(speaker, NARRATOR_VOICE)
+                edge_items.append({
+                    "shot_id": cut_id,
+                    "text": dialogue["text"],
+                    "output_path": output_path,
+                    "voice_config": voice_config,
+                    "emotion": dialogue.get("emotion", "neutral"),
+                })
+
+    total_items = len(edge_items) + len(pocket_items)
+    if total_items == 0:
+        if on_progress:
+            msg = "No dialogue found" if skipped == 0 else f"All {skipped} voice clips cached"
+            await on_progress(msg, 100)
+        return storyboard
+
+    if on_progress:
+        skip_msg = f" ({skipped} cached)" if skipped else ""
+        engine_msg = ""
+        if pocket_items and edge_items:
+            engine_msg = f" [{len(pocket_items)} anime + {len(edge_items)} standard]"
+        elif pocket_items:
+            engine_msg = f" [{len(pocket_items)} anime voices]"
+        await on_progress(f"Recording {total_items} voice clips{engine_msg}{skip_msg}...", 10)
+
+    # Generate clips — Pocket TTS (sequential) and Edge TTS (concurrent) in parallel
+    pocket_results = []
+    edge_results = []
+
+    if pocket_items and edge_items:
+        # Run both engines in parallel
+        pocket_results, edge_results = await asyncio.gather(
+            _generate_pocket_tts_items(pocket_items),
+            generate_tts_batch(edge_items),
+        )
+    elif pocket_items:
+        pocket_results = await _generate_pocket_tts_items(pocket_items)
+    else:
+        edge_results = await generate_tts_batch(edge_items)
+
+    all_results = pocket_results + edge_results
+
+    # Map results back to cuts
+    result_map = {r["shot_id"]: r for r in all_results if r.get("shot_id")}
+
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            if cut_id in result_map:
+                r = result_map[cut_id]
+                cut["tts_path"] = r["path"]
+                cut["word_timestamps"] = r.get("word_timestamps", [])
+                # Audio-first: actual TTS duration overrides estimate
+                if r.get("duration_sec"):
+                    cut["actual_duration_sec"] = r["duration_sec"]
+                    cut["duration_sec"] = max(r["duration_sec"] + 0.3, cut.get("duration_sec", 2.0))
+
+    if on_progress:
+        pocket_count = len(pocket_results)
+        edge_count = len(edge_results)
+        detail = f"{len(all_results)} voice clips recorded"
+        if pocket_count > 0:
+            detail += f" ({pocket_count} anime, {edge_count} standard)"
+        await on_progress(detail, 100)
+
+    logger.info(
+        "TTS complete: %d pocket + %d edge = %d total (%d cached)",
+        len(pocket_results), len(edge_results), len(all_results), skipped,
+    )
+    return storyboard

app/pipeline/stage_6_animation.py

@@ -0,0 +1,121 @@
+"""Stage 6 (Fallback): Ken Burns Animation on each cut image.
+
+This is the fallback animation method when Pollinations video generation
+is unavailable or fails. Applies Ken Burns zoom/pan effects to static images.
+"""
+import asyncio
+import logging
+from pathlib import Path
+from app.services.ffmpeg import animate_shot
+
+logger = logging.getLogger(__name__)
+
+# Map professional camera notation to Ken Burns presets
+CAMERA_TO_KEN_BURNS = {
+    "FIX": "static",
+    "PAN_LEFT": "pan_left",
+    "PAN_RIGHT": "pan_right",
+    "TILT_UP": "pan_up",
+    "TILT_DOWN": "pan_down",
+    "T.U.": "zoom_in_slow",
+    "T.B.": "zoom_out",
+    "DOLLY_LEFT": "pan_left",
+    "DOLLY_RIGHT": "pan_right",
+    "FOLLOW": "pan_right",
+    "CRANE_UP": "pan_up",
+    "CRANE_DOWN": "pan_down",
+    "SHAKE": "shake",
+}
+
+
+async def run_animation(
+    storyboard: dict,
+    project_dir: str,
+    on_progress: callable = None,
+) -> dict:
+    """Apply Ken Burns animation to all cut images.
+
+    Returns updated storyboard with clip_path set on each cut.
+    Supports both new 'cuts' and legacy 'shots' format.
+    """
+    total_cuts = sum(
+        len(s.get("cuts", s.get("shots", [])))
+        for s in storyboard.get("scenes", [])
+    )
+    if on_progress:
+        await on_progress(f"Animating {total_cuts} cuts (Ken Burns)...", 0)
+
+    clips_dir = Path(project_dir) / "clips"
+    clips_dir.mkdir(parents=True, exist_ok=True)
+
+    # Collect cuts with images, annotating scene position for fades
+    cuts = []
+    for scene in storyboard.get("scenes", []):
+        scene_cuts = [
+            c for c in scene.get("cuts", scene.get("shots", []))
+            if c.get("image_path")
+        ]
+        for idx, cut in enumerate(scene_cuts):
+            is_first = idx == 0
+            is_last = idx == len(scene_cuts) - 1
+            if is_first and is_last:
+                cut["_fade_in"] = 0.4
+                cut["_fade_out"] = 0.4
+            elif is_first:
+                cut["_fade_in"] = 0.4
+                cut["_fade_out"] = 0.15
+            elif is_last:
+                cut["_fade_in"] = 0.15
+                cut["_fade_out"] = 0.4
+            else:
+                cut["_fade_in"] = 0.15
+                cut["_fade_out"] = 0.15
+            cuts.append(cut)
+
+    total = len(cuts)
+    logger.info("Animation: %d/%d cuts have image_path", total, total_cuts)
+    completed = 0
+    semaphore = asyncio.Semaphore(2)  # Limit concurrent FFmpeg processes
+
+    async def animate_one(cut: dict) -> None:
+        nonlocal completed
+        async with semaphore:
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            output = str(clips_dir / f"{cut_id}.mp4")
+
+            # Use actual TTS duration if available (audio-first)
+            duration = cut.get("actual_duration_sec", cut.get("duration_sec", 3.0))
+            duration = max(duration, 0.5)
+
+            # Map professional camera notation to Ken Burns presets
+            camera = cut.get("camera_movement", "static")
+            kb_camera = CAMERA_TO_KEN_BURNS.get(camera, camera)
+
+            try:
+                await animate_shot(
+                    image_path=cut["image_path"],
+                    output_path=output,
+                    duration_sec=duration,
+                    camera_movement=kb_camera,
+                    audio_path=cut.get("tts_path"),
+                    fade_in=cut.get("_fade_in", 0.0),
+                    fade_out=cut.get("_fade_out", 0.0),
+                )
+                cut["clip_path"] = output
+            except Exception as e:
+                cut["clip_path"] = None
+                cut["_animation_error"] = str(e)
+                logger.error("Animation failed for %s: %s", cut_id, e)
+
+            completed += 1
+            if on_progress:
+                pct = int((completed / max(total, 1)) * 100)
+                dur = cut.get("duration_sec", 0)
+                await on_progress(f"[{completed}/{total}] {kb_camera} ({dur:.1f}s)", pct)
+
+    await asyncio.gather(*[animate_one(c) for c in cuts])
+
+    if on_progress:
+        await on_progress(f"{total} cuts animated", 100)
+
+    return storyboard

app/pipeline/stage_6_video_gen.py

@@ -0,0 +1,304 @@
+"""Stage 6 (Video): AI Video Generation via Pollinations grok-video.
+
+Replaces Ken Burns animation with actual AI-generated video clips.
+Each keyframe image is uploaded and used as img2vid reference.
+
+Falls back to Ken Burns (stage_6_animation.py) on failure.
+"""
+import asyncio
+import logging
+import math
+import os
+from pathlib import Path
+
+from app.services.pollinations import generate_video, upload_media
+from app.pipeline.stage_6_animation import run_animation as run_ken_burns_fallback
+from app.services.ffmpeg import get_duration, mux_audio, rescale_to_landscape
+
+logger = logging.getLogger(__name__)
+
+# Sequential video gen — Pollinations throttles concurrent pk_* key requests
+_video_semaphore = asyncio.Semaphore(1)
+
+# Delay between video gen requests to avoid throttling
+_VIDEO_DELAY_SEC = 6.0
+
+# Camera movement → video prompt mapping for enhanced motion descriptions
+CAMERA_MOTION_MAP = {
+    "FIX": "static camera, subtle atmospheric motion",
+    "PAN_LEFT": "camera pans smoothly to the left",
+    "PAN_RIGHT": "camera pans smoothly to the right",
+    "TILT_UP": "camera tilts upward slowly",
+    "TILT_DOWN": "camera tilts downward slowly",
+    "T.U.": "camera slowly zooms in, tracking toward subject",
+    "T.B.": "camera slowly pulls back, revealing more of the scene",
+    "DOLLY_LEFT": "camera moves laterally to the left",
+    "DOLLY_RIGHT": "camera moves laterally to the right",
+    "FOLLOW": "camera follows the character's movement",
+    "CRANE_UP": "camera rises upward, bird's eye perspective",
+    "CRANE_DOWN": "camera descends from above",
+    "SHAKE": "handheld camera shake, intense impact feel",
+    # Legacy camera movements (from old storyboard format)
+    "static": "subtle idle motion, breathing animation",
+    "zoom_in_slow": "camera slowly zooms in",
+    "zoom_in_fast": "camera quickly zooms in with urgency",
+    "zoom_out": "camera zooms out, revealing the scene",
+    "pan_left": "camera pans smoothly to the left",
+    "pan_right": "camera pans smoothly to the right",
+    "pan_up": "camera tilts upward",
+    "pan_down": "camera tilts downward",
+    "tilt": "camera tilts with slight rotation",
+    "shake": "handheld camera shake, impact",
+    "dolly_in": "camera tracks toward subject",
+}
+
+
+ANIME_VIDEO_PREFIX = "anime cel-shading style, 2D manhwa animation, "
+
+
+def _build_video_prompt(cut: dict) -> str:
+    """Build a video generation prompt from cut data.
+
+    Combines the explicit video_prompt (from e-konte storyboard) with
+    camera movement description and action description.
+    Prepends anime style cue to keep grok-video from going realistic.
+    """
+    parts = []
+
+    # Use explicit video_prompt if available (new e-konte format)
+    video_prompt = cut.get("video_prompt", "")
+    if video_prompt:
+        parts.append(video_prompt)
+
+    # Add camera movement context
+    camera = cut.get("camera_movement", "static")
+    camera_desc = CAMERA_MOTION_MAP.get(camera, "subtle camera motion")
+    if camera_desc not in (video_prompt or ""):
+        parts.append(camera_desc)
+
+    # Add action description for additional motion context
+    action = cut.get("action_description", "")
+    if action and action not in (video_prompt or ""):
+        parts.append(action)
+
+    # If still empty, create a basic motion prompt
+    if not parts:
+        parts.append("subtle idle animation, slight breathing motion, atmospheric particles floating")
+
+    return ANIME_VIDEO_PREFIX + ", ".join(parts)
+
+
+async def _generate_video_clip(
+    cut: dict,
+    clips_dir: Path,
+    image_upload_cache: dict,
+) -> bool:
+    """Generate a video clip for a single cut. Returns True on success."""
+    cut_id = cut.get("cut_id") or cut.get("shot_id")
+    image_path = cut.get("image_path")
+    output_path = str(clips_dir / f"{cut_id}.mp4")
+
+    if not image_path or not Path(image_path).exists():
+        logger.warning("No image for %s, skipping video gen", cut_id)
+        return False
+
+    # Duration: round UP so video is always >= audio length.
+    # grok-video accepts integer seconds 1-10. Rounding up ensures
+    # -shortest in mux_audio trims to the exact audio duration.
+    tts_duration = cut.get("actual_duration_sec")
+    storyboard_duration = cut.get("duration_sec", 3.0)
+    target_duration = tts_duration or storyboard_duration
+    video_duration = max(1, min(math.ceil(target_duration), 10))
+
+    async with _video_semaphore:
+        # Rate-limit delay for pk_* keys
+        await asyncio.sleep(_VIDEO_DELAY_SEC)
+
+        try:
+            # Upload image (with caching to avoid re-uploading)
+            if image_path not in image_upload_cache:
+                image_url = await upload_media(image_path)
+                image_upload_cache[image_path] = image_url
+            else:
+                image_url = image_upload_cache[image_path]
+
+            # Build video prompt
+            video_prompt = _build_video_prompt(cut)
+
+            # Step 1: Generate silent video from grok-video
+            silent_path = str(clips_dir / f"{cut_id}_silent.mp4")
+            await generate_video(
+                prompt=video_prompt,
+                output_path=silent_path,
+                model="grok-video",
+                duration=video_duration,
+                image_url=image_url,
+            )
+
+            # Step 2: Rescale to landscape (grok-video outputs portrait)
+            scaled_path = str(clips_dir / f"{cut_id}_scaled.mp4")
+            await rescale_to_landscape(silent_path, scaled_path, 1024, 768)
+
+            # Step 3: Mux TTS audio into the video (or add silent track)
+            tts_path = cut.get("tts_path")
+            await mux_audio(
+                video_path=scaled_path,
+                audio_path=tts_path,
+                output_path=output_path,
+                duration_sec=target_duration,
+            )
+
+            # Clean up temp files
+            for tmp in [silent_path, scaled_path]:
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+
+            cut["clip_path"] = output_path
+            logger.info(
+                "Video generated for %s: %s (video=%ds, audio=%.1fs)",
+                cut_id, output_path, video_duration,
+                tts_duration or 0,
+            )
+            return True
+
+        except Exception as e:
+            logger.error("Video generation failed for %s: %r", cut_id, e, exc_info=True)
+            cut["_video_error"] = repr(e)
+            # Clean up partial files
+            for p in [str(clips_dir / f"{cut_id}_silent.mp4"),
+                       str(clips_dir / f"{cut_id}_scaled.mp4"),
+                       output_path]:
+                try:
+                    os.unlink(p)
+                except OSError:
+                    pass
+            return False
+
+
+async def run_video_generation(
+    storyboard: dict,
+    project_dir: str,
+    on_progress: callable = None,
+) -> dict:
+    """Generate AI video clips for all cuts in the storyboard.
+
+    Falls back to Ken Burns animation for any cuts where video generation fails.
+    Returns updated storyboard with clip_path set on each cut.
+    """
+    clips_dir = Path(project_dir) / "clips"
+    clips_dir.mkdir(parents=True, exist_ok=True)
+
+    # Collect all cuts that have images
+    all_cuts = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            if cut.get("image_path"):
+                all_cuts.append(cut)
+
+    total = len(all_cuts)
+    if on_progress:
+        await on_progress(f"Generating {total} video clips...", 0)
+
+    if total == 0:
+        if on_progress:
+            await on_progress("No images available for video generation", 100)
+        return storyboard
+
+    # Shared upload cache to avoid re-uploading the same image
+    image_upload_cache = {}
+    completed = 0
+    succeeded = 0
+    failed_cuts = []
+
+    async def gen_one(cut: dict):
+        nonlocal completed, succeeded
+        try:
+            success = await _generate_video_clip(cut, clips_dir, image_upload_cache)
+        except Exception as e:
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            logger.error("Unexpected error in video gen for %s: %s", cut_id, e)
+            success = False
+        if success:
+            succeeded += 1
+        else:
+            failed_cuts.append(cut)
+        completed += 1
+        if on_progress:
+            pct = int((completed / max(total, 1)) * 80)
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            status = "OK" if success else "FALLBACK"
+            await on_progress(f"[{completed}/{total}] {cut_id} ({status})", pct)
+
+    # Generate videos (limited by semaphore)
+    await asyncio.gather(*[gen_one(cut) for cut in all_cuts])
+
+    # Fallback: Ken Burns for failed cuts
+    if failed_cuts:
+        if on_progress:
+            await on_progress(f"Ken Burns fallback for {len(failed_cuts)} clips...", 85)
+        logger.info("Falling back to Ken Burns for %d cuts", len(failed_cuts))
+
+        # Create a mini-storyboard with just the failed cuts for Ken Burns
+        # We need to set up the fade values and pass to the existing Ken Burns code
+        from app.services.ffmpeg import animate_shot
+        kb_completed = 0
+
+        for cut in failed_cuts:
+            cut_id = cut.get("cut_id") or cut.get("shot_id")
+            output = str(clips_dir / f"{cut_id}.mp4")
+            duration = cut.get("actual_duration_sec", cut.get("duration_sec", 3.0))
+            duration = max(duration, 0.5)
+
+            # Map new camera notation back to Ken Burns presets
+            camera = cut.get("camera_movement", "static")
+            kb_camera = _map_camera_to_ken_burns(camera)
+
+            try:
+                await animate_shot(
+                    image_path=cut["image_path"],
+                    output_path=output,
+                    duration_sec=duration,
+                    camera_movement=kb_camera,
+                    audio_path=cut.get("tts_path"),
+                    fade_in=0.15,
+                    fade_out=0.15,
+                )
+                cut["clip_path"] = output
+                cut["_used_fallback"] = True
+            except Exception as e:
+                logger.error("Ken Burns fallback also failed for %s: %r", cut_id, e, exc_info=True)
+                cut["clip_path"] = None
+
+            kb_completed += 1
+
+    if on_progress:
+        fallback_count = sum(1 for c in failed_cuts if c.get("clip_path"))
+        total_success = succeeded + fallback_count
+        await on_progress(
+            f"{total_success}/{total} clips ready ({succeeded} video, {fallback_count} Ken Burns)",
+            100,
+        )
+
+    return storyboard
+
+
+def _map_camera_to_ken_burns(camera: str) -> str:
+    """Map professional camera notation to Ken Burns preset names."""
+    mapping = {
+        "FIX": "static",
+        "PAN_LEFT": "pan_left",
+        "PAN_RIGHT": "pan_right",
+        "TILT_UP": "pan_up",
+        "TILT_DOWN": "pan_down",
+        "T.U.": "zoom_in_slow",
+        "T.B.": "zoom_out",
+        "DOLLY_LEFT": "pan_left",
+        "DOLLY_RIGHT": "pan_right",
+        "FOLLOW": "pan_right",
+        "CRANE_UP": "pan_up",
+        "CRANE_DOWN": "pan_down",
+        "SHAKE": "shake",
+    }
+    return mapping.get(camera, camera)  # Pass through if already a Ken Burns name

app/pipeline/stage_7_assembly.py

@@ -0,0 +1,278 @@
+"""Stage 7: Video Assembly — concat clips, scene-aware transitions, subtitles, BGM."""
+import logging
+import os
+from pathlib import Path
+from app.services.ffmpeg import concat_clips, add_subtitles, mix_background_music, get_duration
+
+logger = logging.getLogger(__name__)
+
+# Map storyboard mood keywords to BGM filenames
+BGM_MOOD_MAP = {
+    "tense": "tense",
+    "mysterious": "tense",
+    "action": "epic",
+    "dramatic": "epic",
+    "epic": "epic",
+    "calm": "calm",
+    "romantic": "calm",
+    "comedic": "calm",
+    "melancholic": "sad",
+    "sad": "sad",
+}
+BGM_DIR = Path("data/bgm")
+
+
+# Overlap durations for xfade transitions (seconds eaten from timeline)
+TRANSITION_OVERLAP = {
+    "cut": 0.0,
+    "fade": 1.0,
+    "fade_black": 1.0,
+    "crossfade": 0.5,
+}
+
+
+def _generate_srt(
+    storyboard: dict,
+    clip_durations: list[float],
+    transitions: list[str],
+) -> str:
+    """Generate SRT subtitle file using actual clip durations from ffprobe.
+
+    Uses measured clip durations instead of storyboard estimates, and accounts
+    for transition overlaps (xfade) that compress the timeline.
+    """
+    # Collect cuts that have valid clip_paths (same order as clip_durations)
+    cuts_with_clips = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            clip_path = cut.get("clip_path")
+            if clip_path and os.path.exists(clip_path):
+                cuts_with_clips.append(cut)
+
+    lines = []
+    srt_idx = 1
+    elapsed = 0.0
+    prev_duration = 0.0
+
+    for i, (cut, duration) in enumerate(zip(cuts_with_clips, clip_durations)):
+        # Advance elapsed time, accounting for transition overlap
+        if i > 0:
+            overlap = TRANSITION_OVERLAP.get(transitions[i], 0.0) if i < len(transitions) else 0.0
+            elapsed += prev_duration - overlap
+
+        dialogue = cut.get("dialogue")
+        if dialogue and dialogue.get("text"):
+            start = elapsed
+            end = elapsed + duration
+            lines.append(str(srt_idx))
+            lines.append(f"{_srt_time(start)} --> {_srt_time(end)}")
+
+            prefix = ""
+            if dialogue.get("is_inner_thought"):
+                prefix = "\u266a "  # Musical note for inner thoughts
+            elif dialogue.get("is_narration"):
+                prefix = ""
+            elif dialogue.get("speaker") and dialogue["speaker"] != "Narrator":
+                prefix = f"{dialogue['speaker']}: "
+
+            text = dialogue["text"]
+            # Wrap long lines
+            if len(text) > 60:
+                mid = len(text) // 2
+                space_pos = text.rfind(" ", 0, mid + 10)
+                if space_pos > mid - 15:
+                    text = text[:space_pos] + "\n" + text[space_pos + 1:]
+
+            lines.append(f"{prefix}{text}")
+            lines.append("")
+            srt_idx += 1
+
+        prev_duration = duration
+
+    return "\n".join(lines)
+
+
+def _srt_time(seconds: float) -> str:
+    """Convert seconds to SRT timestamp format."""
+    h = int(seconds // 3600)
+    m = int((seconds % 3600) // 60)
+    s = int(seconds % 60)
+    ms = int((seconds % 1) * 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def _build_transition_list(storyboard: dict) -> list[str]:
+    """Build a list of transitions for each clip boundary.
+
+    Scene-aware: use the scene's transition_in at scene boundaries,
+    'cut' within scenes for continuous feel.
+    """
+    transitions = []
+    prev_scene_id = None
+
+    for scene in storyboard.get("scenes", []):
+        scene_id = scene.get("scene_id", "")
+        scene_transition = scene.get("transition_in", "cut")
+        cuts = scene.get("cuts", scene.get("shots", []))
+
+        for idx, cut in enumerate(cuts):
+            if not cut.get("clip_path") or not os.path.exists(cut.get("clip_path", "")):
+                continue
+
+            if idx == 0 and prev_scene_id is not None:
+                # Scene boundary — use the scene's transition_in
+                transitions.append(scene_transition)
+            else:
+                # Within scene — use cut's transition_out or default to "cut"
+                if idx > 0:
+                    prev_cut = cuts[idx - 1]
+                    trans = prev_cut.get("transition_out", "cut")
+                    transitions.append(trans)
+                else:
+                    transitions.append("cut")  # First clip overall
+
+        prev_scene_id = scene_id
+
+    return transitions
+
+
+async def run_assembly(
+    storyboard: dict,
+    project_dir: str,
+    episode_number: int = 1,
+    on_progress: callable = None,
+    output_dir: str | None = None,
+) -> dict:
+    """Assemble all animated clips into a final episode video.
+
+    Args:
+        project_dir: Directory containing clips (episode_dir in per-episode mode).
+        output_dir: If set, final episode goes to output_dir/episodes/ instead.
+
+    Returns {video_path, duration_seconds, subtitle_path}.
+    """
+    if on_progress:
+        await on_progress("Assembling episode...", 0)
+
+    episode_dir = Path(output_dir or project_dir) / "episodes"
+    episode_dir.mkdir(parents=True, exist_ok=True)
+
+    # Collect clip paths in order
+    clip_paths = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            clip_path = cut.get("clip_path")
+            if clip_path and os.path.exists(clip_path):
+                clip_paths.append(clip_path)
+
+    if not clip_paths:
+        raise ValueError("No animated clips to assemble")
+
+    if on_progress:
+        await on_progress(f"Concatenating {len(clip_paths)} clips...", 20)
+
+    # Build scene-aware transitions
+    transitions = _build_transition_list(storyboard)
+
+    # Measure actual clip durations via ffprobe (ground truth)
+    clip_durations = []
+    for path in clip_paths:
+        dur = await get_duration(path)
+        clip_durations.append(dur if dur > 0 else 2.0)
+    logger.info("Clip durations (ffprobe): %s", [round(d, 2) for d in clip_durations])
+
+    # Generate subtitles using actual durations + transition overlaps
+    srt_content = _generate_srt(storyboard, clip_durations, transitions)
+    srt_path = str(episode_dir / f"episode_{episode_number}.srt")
+    with open(srt_path, "w", encoding="utf-8") as f:
+        f.write(srt_content)
+
+    # Concat all clips with scene-aware transitions
+    raw_output = str(episode_dir / f"episode_{episode_number}_raw.mp4")
+    await concat_clips(clip_paths, raw_output, transitions=transitions)
+
+    if on_progress:
+        await on_progress("Burning subtitles...", 50)
+
+    # Burn subtitles into video
+    subbed_output = str(episode_dir / f"episode_{episode_number}_subbed.mp4")
+    try:
+        await add_subtitles(raw_output, srt_path, subbed_output)
+        # Clean up raw
+        if os.path.exists(raw_output):
+            os.unlink(raw_output)
+    except Exception as e:
+        logger.warning("Subtitle burning failed, using raw video: %s", e)
+        subbed_output = raw_output  # fallback — no crash
+
+    if on_progress:
+        await on_progress("Adding background music...", 70)
+
+    # Select BGM based on dominant mood
+    final_output = str(episode_dir / f"episode_{episode_number}.mp4")
+    bgm_path = _select_bgm(storyboard)
+
+    if bgm_path:
+        try:
+            await mix_background_music(subbed_output, bgm_path, final_output)
+            # Clean up subbed
+            if os.path.exists(subbed_output) and subbed_output != final_output:
+                os.unlink(subbed_output)
+        except Exception as e:
+            logger.warning("BGM mixing failed, using video without BGM: %s", e)
+            if subbed_output != final_output:
+                os.rename(subbed_output, final_output)
+    else:
+        if subbed_output != final_output:
+            os.rename(subbed_output, final_output)
+
+    # Get final duration
+    duration = await get_duration(final_output)
+
+    if on_progress:
+        mins = int(duration // 60)
+        secs = int(duration % 60)
+        await on_progress(f"Episode assembled \u2014 {mins}:{secs:02d}", 100)
+
+    return {
+        "video_path": final_output,
+        "subtitle_path": srt_path,
+        "duration_seconds": duration,
+    }
+
+
+def _select_bgm(storyboard: dict) -> str | None:
+    """Select a BGM file based on the dominant mood in the storyboard."""
+    if not BGM_DIR.exists():
+        return None
+
+    # Count mood occurrences
+    mood_counts: dict[str, int] = {}
+    for scene in storyboard.get("scenes", []):
+        mood = scene.get("mood", "").lower()
+        bgm_key = BGM_MOOD_MAP.get(mood)
+        if bgm_key:
+            mood_counts[bgm_key] = mood_counts.get(bgm_key, 0) + 1
+
+    if not mood_counts:
+        # Default to calm
+        mood_counts = {"calm": 1}
+
+    # Pick the most common mood
+    dominant = max(mood_counts, key=mood_counts.get)
+
+    # Look for matching BGM file
+    for ext in (".mp3", ".wav", ".ogg", ".m4a"):
+        candidate = BGM_DIR / f"{dominant}{ext}"
+        if candidate.exists():
+            return str(candidate)
+
+    # Fallback: try any available BGM file
+    try:
+        for f in BGM_DIR.iterdir():
+            if f.suffix in (".mp3", ".wav", ".ogg", ".m4a"):
+                return str(f)
+    except Exception:
+        pass
+
+    return None

app/pipeline/stage_8_critic.py

@@ -0,0 +1,189 @@
+"""Stage 8: Critic Agent — AI review of generated storyboard/images."""
+import logging
+from pathlib import Path
+from app.services.llm import call_gemini_json, call_openrouter_vision_json
+
+logger = logging.getLogger(__name__)
+
+CRITIC_PROMPT = """You are an anime quality assurance critic. Review this storyboard for an anime episode and score it.
+
+STORYBOARD METADATA:
+- Total shots: {total_shots}
+- Total duration: {total_duration}s
+- Scenes: {scene_count}
+
+SCENE BREAKDOWN:
+{scene_summary}
+
+Score each dimension from 0.0 to 10.0 and provide specific feedback.
+
+Return JSON:
+{{
+  "visual_consistency_score": float,  // Are character descriptions consistent across shots?
+  "pacing_score": float,  // Is the pacing good? Not too fast or slow?
+  "audio_sync_score": float,  // Do dialogue durations match the content?
+  "overall_score": float,  // Overall quality
+  "feedback": {{
+    "strengths": ["list of good aspects"],
+    "issues": [
+      {{"severity": "low/medium/high", "description": "what's wrong", "shot_id": "affected shot or null", "suggestion": "how to fix"}}
+    ]
+  }}
+}}"""
+
+IMAGE_CRITIC_PROMPT = """You are an anime visual quality critic. You are reviewing {image_count} frames from an AI-generated anime episode.
+
+Evaluate these images and return a JSON score card:
+
+{{
+  "art_style_consistency": {{
+    "score": float (0-10),
+    "notes": "Are all images in a consistent anime art style?"
+  }},
+  "character_consistency": {{
+    "score": float (0-10),
+    "notes": "Do characters look the same across different shots?"
+  }},
+  "quality": {{
+    "score": float (0-10),
+    "notes": "Are there artifacts, weird anatomy, broken faces, extra fingers?"
+  }},
+  "anime_adherence": {{
+    "score": float (0-10),
+    "notes": "Does it look like anime vs photorealistic or other styles?"
+  }},
+  "overall_visual_score": float (0-10),
+  "visual_issues": [
+    {{"description": "what's wrong", "severity": "low/medium/high"}}
+  ]
+}}"""
+
+
+def _build_scene_summary(storyboard: dict) -> str:
+    """Build a text summary of the storyboard for the critic."""
+    lines = []
+    for scene in storyboard.get("scenes", []):
+        scene_id = scene.get("scene_id", "?")
+        lines.append(f"\nScene {scene_id}: {scene.get('setting', 'unknown')} ({scene.get('mood', 'neutral')})")
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            cut_id = cut.get("cut_id") or cut.get("shot_id", "?")
+            st = cut.get("shot_type", "?")
+            dur = cut.get("duration_sec", 0)
+            chars = ", ".join(cut.get("characters_present", []))
+            dialogue = cut.get("dialogue") or {}
+            text_preview = (dialogue.get("text", "")[:50] + "...") if dialogue.get("text") else "no dialogue"
+            has_image = "yes" if cut.get("image_path") else "NO"
+            beat = cut.get("emotional_beat", "")
+            beat_str = f" [{beat}]" if beat else ""
+            lines.append(f"  {cut_id}: {st}, {dur:.1f}s, chars=[{chars}], img={has_image}{beat_str}, \"{text_preview}\"")
+    return "\n".join(lines)
+
+
+def _collect_image_paths(storyboard: dict, project_dir: str) -> list[str]:
+    """Collect all existing image paths from storyboard cuts."""
+    paths = []
+    for scene in storyboard.get("scenes", []):
+        for cut in scene.get("cuts", scene.get("shots", [])):
+            img_path = cut.get("image_path")
+            if img_path:
+                p = Path(img_path)
+                if p.exists():
+                    paths.append(str(p.resolve()))
+                else:
+                    # Try relative to project_dir
+                    full = Path(project_dir) / img_path
+                    if full.exists():
+                        paths.append(str(full.resolve()))
+    return paths
+
+
+def _sample_images(paths: list[str], max_count: int = 6) -> list[str]:
+    """Evenly sample up to max_count images from the list."""
+    if len(paths) <= max_count:
+        return paths
+    step = len(paths) / max_count
+    return [paths[int(i * step)] for i in range(max_count)]
+
+
+async def _critique_images(storyboard: dict, project_dir: str) -> dict | None:
+    """Run visual critique on generated images via OpenRouter vision."""
+    all_images = _collect_image_paths(storyboard, project_dir)
+    if not all_images:
+        logger.info("No images found for visual critique")
+        return None
+
+    sampled = _sample_images(all_images)
+    logger.info("Visual critique: %d/%d images sampled", len(sampled), len(all_images))
+
+    prompt = IMAGE_CRITIC_PROMPT.format(image_count=len(sampled))
+    result = await call_openrouter_vision_json(
+        prompt,
+        sampled,
+        system_prompt="You are a professional anime art director reviewing AI-generated frames.",
+    )
+
+    if not isinstance(result, dict):
+        return None
+
+    return result
+
+
+async def run_critic(
+    storyboard: dict,
+    project_dir: str,
+    on_progress: callable = None,
+) -> dict:
+    """Run AI critic on the storyboard. Returns critic scores and feedback."""
+    if on_progress:
+        await on_progress("AI critic reviewing the episode...", 0)
+
+    metadata = storyboard.get("metadata", {})
+    scene_summary = _build_scene_summary(storyboard)
+
+    prompt = CRITIC_PROMPT.format(
+        total_shots=metadata.get("total_shots", 0),
+        total_duration=metadata.get("total_duration_estimate", 0),
+        scene_count=metadata.get("scene_count", 0),
+        scene_summary=scene_summary[:5000],
+    )
+
+    if on_progress:
+        await on_progress("Checking storyboard quality...", 20)
+
+    result = await call_gemini_json(prompt)
+
+    # Type-check the result
+    if not isinstance(result, dict):
+        result = {"overall_score": 5.0, "feedback": {"strengths": [], "issues": []}}
+
+    score = result.get("overall_score", 0)
+    if isinstance(score, (int, float)):
+        score = max(0, min(10, float(score)))
+    else:
+        score = 5.0
+    result["overall_score"] = score
+
+    # Image critique via OpenRouter vision (non-blocking on failure)
+    if on_progress:
+        await on_progress("Analyzing generated images...", 50)
+
+    try:
+        image_critique = await _critique_images(storyboard, project_dir)
+        if image_critique:
+            result["image_critique"] = image_critique
+            vis_score = image_critique.get("overall_visual_score")
+            if isinstance(vis_score, (int, float)):
+                vis_score = max(0, min(10, float(vis_score)))
+                result["visual_quality_score"] = vis_score
+                # Blend into overall: 60% storyboard, 40% visual
+                result["overall_score"] = round(score * 0.6 + vis_score * 0.4, 1)
+                score = result["overall_score"]
+            logger.info("Image critique complete: visual_score=%.1f", result.get("visual_quality_score", 0))
+    except Exception as e:
+        logger.warning("Image critique failed (non-fatal): %s", e)
+        result["image_critique_error"] = str(e)
+
+    if on_progress:
+        await on_progress(f"Quality score: {score}/10", 100)
+
+    return result

app/schemas/__init__.py

@@ -0,0 +1,19 @@
+from app.schemas.auth import (
+    UserCreate, UserLogin, UserResponse, TokenResponse, RefreshRequest,
+)
+from app.schemas.project import (
+    ProjectCreate, ProjectUpdate, ProjectResponse, ProjectListResponse,
+)
+from app.schemas.chapter import ChapterCreate, ChapterResponse
+from app.schemas.character import CharacterCreate, CharacterUpdate, CharacterResponse
+from app.schemas.episode import EpisodeCreate, EpisodeResponse
+from app.schemas.generation import GenerationJobResponse, GenerationStart
+
+__all__ = [
+    "UserCreate", "UserLogin", "UserResponse", "TokenResponse", "RefreshRequest",
+    "ProjectCreate", "ProjectUpdate", "ProjectResponse", "ProjectListResponse",
+    "ChapterCreate", "ChapterResponse",
+    "CharacterCreate", "CharacterUpdate", "CharacterResponse",
+    "EpisodeCreate", "EpisodeResponse",
+    "GenerationJobResponse", "GenerationStart",
+]

app/schemas/auth.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, EmailStr
+from datetime import datetime
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    username: str
+    password: str
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    username: str
+    role: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str

app/schemas/chapter.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class ChapterCreate(BaseModel):
+    chapter_number: int
+    title: str | None = None
+    source_text: str
+
+
+class ChapterResponse(BaseModel):
+    id: int
+    project_id: int
+    chapter_number: int
+    title: str | None
+    word_count: int
+    status: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}

app/schemas/character.py

@@ -0,0 +1,38 @@
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class CharacterCreate(BaseModel):
+    name: str
+    aliases_json: list[str] | None = None
+    role: str = "supporting"
+    gender: str | None = None
+    age_category: str | None = None
+    visual_prompt: str | None = None
+    voice_config_json: dict | None = None
+
+
+class CharacterUpdate(BaseModel):
+    name: str | None = None
+    aliases_json: list[str] | None = None
+    role: str | None = None
+    gender: str | None = None
+    age_category: str | None = None
+    visual_prompt: str | None = None
+    voice_config_json: dict | None = None
+
+
+class CharacterResponse(BaseModel):
+    id: int
+    project_id: int
+    name: str
+    aliases_json: list | None
+    role: str
+    gender: str | None
+    age_category: str | None
+    visual_prompt: str | None
+    reference_image_path: str | None
+    voice_config_json: dict | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}

app/schemas/episode.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class EpisodeCreate(BaseModel):
+    episode_number: int
+    title: str | None = None
+    chapter_ids_json: list[int] | None = None
+
+
+class EpisodeResponse(BaseModel):
+    id: int
+    project_id: int
+    episode_number: int
+    title: str | None
+    chapter_ids_json: list | None
+    duration_seconds: float | None
+    video_path: str | None
+    status: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}

app/schemas/generation.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class GenerationStart(BaseModel):
+    episode_id: int | None = None
+    chapter_ids: list[int] | None = None
+
+
+class GenerationJobResponse(BaseModel):
+    id: int
+    project_id: int
+    episode_id: int | None
+    status: str
+    current_stage: str | None
+    progress_pct: float
+    progress_detail: str | None
+    error_message: str | None
+    started_at: datetime | None
+    completed_at: datetime | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}

app/schemas/project.py

@@ -0,0 +1,39 @@
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class ProjectCreate(BaseModel):
+    title: str
+    novel_url: str | None = None
+    cover_image_url: str | None = None
+    synopsis: str | None = None
+    settings_json: dict | None = None
+
+
+class ProjectUpdate(BaseModel):
+    title: str | None = None
+    novel_url: str | None = None
+    cover_image_url: str | None = None
+    synopsis: str | None = None
+    settings_json: dict | None = None
+    status: str | None = None
+
+
+class ProjectResponse(BaseModel):
+    id: int
+    user_id: int
+    title: str
+    novel_url: str | None
+    cover_image_url: str | None
+    synopsis: str | None
+    settings_json: dict | None
+    status: str
+    created_at: datetime
+    updated_at: datetime | None
+
+    model_config = {"from_attributes": True}
+
+
+class ProjectListResponse(BaseModel):
+    projects: list[ProjectResponse]
+    total: int

app/services/auth.py

@@ -0,0 +1,66 @@
+from datetime import datetime, timedelta, timezone
+import bcrypt
+from jose import jwt, JWTError
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.config import get_settings
+from app.database import get_db
+from app.models.user import User
+
+settings = get_settings()
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return bcrypt.checkpw(plain.encode(), hashed.encode())
+
+
+def create_token(data: dict, expires_delta: timedelta) -> str:
+    to_encode = data.copy()
+    to_encode["exp"] = datetime.now(timezone.utc) + expires_delta
+    return jwt.encode(to_encode, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
+
+
+def create_access_token(user_id: int) -> str:
+    return create_token(
+        {"sub": str(user_id), "type": "access"},
+        timedelta(minutes=settings.access_token_expire_minutes),
+    )
+
+
+def create_refresh_token(user_id: int) -> str:
+    return create_token(
+        {"sub": str(user_id), "type": "refresh"},
+        timedelta(days=settings.refresh_token_expire_days),
+    )
+
+
+def decode_token(token: str) -> dict:
+    try:
+        return jwt.decode(token, settings.jwt_secret_key, algorithms=[settings.jwt_algorithm])
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+        )
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    payload = decode_token(token)
+    if payload.get("type") != "access":
+        raise HTTPException(status_code=401, detail="Invalid token type")
+    user_id = int(payload["sub"])
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user

app/services/fandom.py

@@ -0,0 +1,107 @@
+"""Fandom/MediaWiki API client for character enrichment."""
+import re
+import httpx
+
+
+async def search_fandom_wiki(
+    novel_title: str,
+    character_name: str,
+) -> dict | None:
+    """Search Fandom wikis for character appearance data.
+    Returns {description, image_url} or None."""
+
+    # Generate wiki subdomain from novel title
+    slug = re.sub(r'[^a-zA-Z0-9]', '', novel_title.lower().replace(' ', ''))
+    wiki_url = f"https://{slug}.fandom.com"
+
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            # Search for character page
+            resp = await client.get(
+                f"{wiki_url}/api.php",
+                params={
+                    "action": "query",
+                    "list": "search",
+                    "srsearch": character_name,
+                    "srnamespace": "0",
+                    "srlimit": "3",
+                    "format": "json",
+                },
+            )
+            if resp.status_code != 200:
+                return None
+
+            data = resp.json()
+            results = data.get("query", {}).get("search", [])
+            if not results:
+                return None
+
+            page_title = results[0]["title"]
+
+            # Get page content (parse for appearance section)
+            resp2 = await client.get(
+                f"{wiki_url}/api.php",
+                params={
+                    "action": "parse",
+                    "page": page_title,
+                    "prop": "wikitext|images",
+                    "format": "json",
+                },
+            )
+            if resp2.status_code != 200:
+                return None
+
+            parse_data = resp2.json().get("parse", {})
+            wikitext = parse_data.get("wikitext", {}).get("*", "")
+            images = parse_data.get("images", [])
+
+            # Extract appearance section
+            appearance = _extract_section(wikitext, ["Appearance", "Physical Description", "Description"])
+
+            # Get first image URL
+            image_url = None
+            if images:
+                img_name = images[0]
+                img_resp = await client.get(
+                    f"{wiki_url}/api.php",
+                    params={
+                        "action": "query",
+                        "titles": f"File:{img_name}",
+                        "prop": "imageinfo",
+                        "iiprop": "url",
+                        "format": "json",
+                    },
+                )
+                if img_resp.status_code == 200:
+                    pages = img_resp.json().get("query", {}).get("pages", {})
+                    for page in pages.values():
+                        ii = page.get("imageinfo", [])
+                        if ii:
+                            image_url = ii[0].get("url")
+
+            return {
+                "description": _clean_wikitext(appearance) if appearance else None,
+                "image_url": image_url,
+            }
+    except Exception:
+        return None
+
+
+def _extract_section(wikitext: str, headings: list[str]) -> str | None:
+    """Extract content under a wiki section heading."""
+    for heading in headings:
+        pattern = rf'==+\s*{re.escape(heading)}\s*==+(.*?)(?===|\Z)'
+        match = re.search(pattern, wikitext, re.DOTALL | re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+    return None
+
+
+def _clean_wikitext(text: str) -> str:
+    """Remove wiki markup, leaving plain text."""
+    text = re.sub(r'\[\[(?:[^|\]]*\|)?([^\]]*)\]\]', r'\1', text)  # [[link|text]] → text
+    text = re.sub(r'\{\{[^}]*\}\}', '', text)  # {{templates}}
+    text = re.sub(r"'''?", '', text)  # bold/italic
+    text = re.sub(r'<[^>]+>', '', text)  # HTML tags
+    text = re.sub(r'\n{3,}', '\n\n', text)
+    return text.strip()