Turn manhwa & webtoon chapters into narrated recap videos — fully automated.

_{The AniFlow web UI — pick a recap mode and run the pipeline end to end in your browser.}

_{Real output: frames from clips rendered by both pipelines — AI narration on clean panels, dialogue read with the original speech bubbles.}

AniFlow downloads manhwa/webtoon chapters, detects and crops panels using YOLO, extracts speech-bubble text, generates AI narration, converts it to speech, and renders video clips — all through a browser-based UI.

• 🌐 Web Scraper — download chapters from manhuaus, manhwatop, MangaDex, and more
• 🔍 YOLO Panel Detection — custom-trained models detect panels and speech bubbles
• 🧹 Text Removal — automatically clean speech bubbles from art panels
• 🤖 AI Narration — local (Ollama) or cloud (Gemini / Claude) narration
• 🎙️ Multi-TTS — Edge TTS (free), Kokoro (local), or ElevenLabs (cloud)
• 🎬 Video Rendering — Ken Burns animation, blur backgrounds, BGM, watermarks
• 👥 Character Casting — import from MyAnimeList or scan faces from chapters
• 📦 Batch Mode — process dozens of chapters unattended

📂 See it in action! Check the example_output/ folder for sample clips from both modes.

GPU recommended but not required. Apple Silicon Macs and NVIDIA GPUs will significantly speed up panel detection and Kokoro TTS.

git clone https://github.com/aashish254/Aniflow.git
cd AniFlow
chmod +x setup.sh
./setup.sh

The setup script will check dependencies, create a virtual environment, install packages, pull Ollama models, and start the app.

# 1. Clone the repository
git clone https://github.com/aashish254/Aniflow.git
cd AniFlow

# 2. Create a virtual environment (Python 3.12 recommended)
py -3.12 -m venv venv             # Windows
# python3 -m venv venv            # macOS / Linux

# 3. Activate virtual environment
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# macOS / Linux:
# source venv/bin/activate

# 4. Install Python dependencies (~10-20 min, torch is large)
pip install --upgrade pip
pip install -r requirements.txt

# 5. Configure 9router (Alternative to Ollama)
# If you use 9router, set these environment variables before running:
# Windows (PowerShell):
# $env:USE_NINE_ROUTER="1"
# $env:NINE_ROUTER_HOST="http://127.0.0.1:20128"
# $env:VISION_MODEL="Free-Tier"
# $env:WRITER_MODEL="Free-Tier"
# $env:TEXT_WRITER_MODEL="Free-Tier"

# 6. Pull Ollama models (Skip if using 9router)
# ollama pull qwen2.5vl:3b
# ollama pull qwen2.5:14b

# 7. Run the app
python app.py

# 8. Open UI in browser:
# http://localhost:8080

# 1. Clone and enter the project
git clone https://github.com/aashish254/Aniflow.git
cd AniFlow

# 2. Run the setup script
setup.bat

Or follow the manual steps above using venv\Scripts\activate instead.

9router exposes models through an OpenAI-compatible local endpoint, so you can run the narrator without pulling multi-gigabyte Ollama models. It replaces Ollama for AI narration only — speech-bubble text extraction still needs Ollama.

Start 9router first (default http://127.0.0.1:20128), then point AniFlow at it:

# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

$env:USE_NINE_ROUTER = "1"
$env:NINE_ROUTER_HOST = "http://127.0.0.1:20128"
$env:VISION_MODEL = "Free-Tier"
$env:WRITER_MODEL = "Free-Tier"
$env:TEXT_WRITER_MODEL = "Free-Tier"

# Only if your 9router instance requires one:
# $env:NINE_ROUTER_API_KEY = "your_key"

python app.py

# macOS / Linux
source venv/bin/activate

export USE_NINE_ROUTER=1
export NINE_ROUTER_HOST=http://127.0.0.1:20128
export VISION_MODEL=Free-Tier
export WRITER_MODEL=Free-Tier
export TEXT_WRITER_MODEL=Free-Tier

python app.py

The same variables can live in .env instead — uncomment the 9router block in .env.example. Once USE_NINE_ROUTER=1 is set, the app's model health check queries 9router's /v1/models endpoint instead of Ollama's /api/tags.

1. Source — Paste a manhwa URL → Analyze → pick chapters → Download (or point to a local folder of images)
2. Cast (optional) — Import characters from MyAnimeList, or scan chapter faces and assign names. The narrator uses real names ("Jin-Woo…") instead of "the dark-haired guy."
3. Stitch — Stitch → Detect (bubble panels) → Crop → Stitch → Detect (art panels) → Crop. Boxes are editable — drag, resize, or draw new ones.
4. Review — Check cropped panels; delete junk or re-crop.
5. Extract — AI reads speech-bubble text.
6. Narrate — Choose your AI backend:
   • 🦙 Ollama (local) — free & offline. qwen2.5vl:7b (vision) or qwen2.5:14b (text-only).
   • ✨ Gemini API — paste multiple API keys (auto-rotation on quota). Free keys at aistudio.google.com.
   • 🤖 Claude API — single key.
7. Review Text — Edit any narration line or re-narrate individual panels.
8. Audio — TTS with Edge (free), Kokoro (local), or ElevenLabs.
9. Video — Renders clips with Ken Burns animation, blur backgrounds, BGM.
10. Review Clips / Sort Clips — Preview, download, or batch-merge.

Same flow minus the cast/narrate steps — extracted dialogue becomes the audio, panels keep their original speech bubbles.

Download chapters 1–68, enable Batch Mode, hit Run Full Batch — every step runs across all chapters automatically. Progress is streamed live.

AniFlow/
├── app.py                  # Flask web app + API routes
├── config.py               # All configuration & path settings
├── requirements.txt        # Python dependencies
├── setup.sh / setup.bat    # One-command setup scripts
├── start.sh                # Quick-start script (macOS/Linux)
│
├── pipeline/               # Core processing modules
│   ├── web_scraper.py      #   Chapter downloading (multi-site)
│   ├── stitcher.py         #   Image stitching
│   ├── panel_extractor_yolo.py  # YOLO panel detection
│   ├── cropper.py          #   Panel cropping
│   ├── text_extractor.py   #   OCR / text extraction
│   ├── text_remover.py     #   Speech bubble cleaning
│   ├── narrator.py         #   Local AI narration (Ollama)
│   ├── gemini_narrator.py  #   Cloud narration (Gemini API)
│   ├── scene_narrator.py   #   Scene-level narration
│   ├── tts_engine.py       #   Edge TTS engine
│   ├── kokoro_tts.py       #   Kokoro local TTS
│   ├── elevenlabs_tts.py   #   ElevenLabs cloud TTS
│   ├── compositor.py       #   Video rendering
│   ├── orchestrator.py     #   Pipeline orchestration
│   ├── cast_system.py      #   Character management
│   ├── character_builder.py #  Face detection & grouping
│   ├── mal_character_importer.py # MAL character import
│   ├── script_rewriter.py  #   Narration style rewriter
│   ├── capcut_director.py  #   CapCut export
│   └── panel_filter.py     #   Panel quality filtering
│
├── models/                 # YOLO model weights (committed)
│   ├── manhwa_panel_cropped.pt      # Art panel detector
│   └── panel_with_bubble_text.pt    # Bubble panel detector
│
├── templates/              # HTML templates
├── static/                 # CSS, JS, logos
├── assets/                 # BGM, watermarks, intros, outros
└── tests/                  # Test & diagnostic scripts

All generated data is regenerable — delete any folder and re-run the pipeline.

Copy .env.example to .env and fill in keys only for services you want to use:

cp .env.example .env

Ollama + Edge TTS work completely offline — no API keys needed for the core pipeline.

Override any of these with the VISION_MODEL, WRITER_MODEL and TEXT_WRITER_MODEL environment variables. With 9router you will want to — it addresses models by its own tier names (e.g. Free-Tier) rather than Ollama tags, and the health check only reports the model as available when the name matches one 9router returns.

AniFlow is built on the shoulders of many incredible open-source projects. Huge thanks to:

• Ollama — Local LLM runtime for AI narration and text extraction
• Qwen 2.5 VL by Alibaba Cloud — Vision-language model for panel understanding
• Ultralytics YOLOv8 — Object detection framework for panel detection
• Magi v2 by Ragav Sachdeva — Manga/comic page understanding and speaker-aware transcription
• EasyOCR by JaidedAI — Text detection for speech bubble cleaning
• Manga OCR by kha-white — OCR tuned for manga/manhwa text
• Google Gemini API — Cloud AI narration alternative
• Anthropic Claude API — Cloud AI narration alternative

• Edge TTS by rany2 — Free Microsoft Edge TTS (default engine)
• Kokoro TTS by hexgrad — High-quality local text-to-speech
• ElevenLabs — Premium cloud TTS

• MoviePy by Zulko — Python video editing
• FFmpeg — The backbone of all media processing
• OpenCV — Computer vision operations
• Pillow — Image manipulation

• Beautiful Soup by Leonard Richardson — HTML parsing
• curl_cffi — Cloudflare-friendly HTTP with TLS fingerprinting
• CloudScraper by VeNoMouS — Cloudflare challenge bypass
• DrissionPage by g1879 — Headless browser fallback for protected sites

• Flask — Python web framework
• Flask-SocketIO — Real-time progress streaming

• lbpcascade_animeface by nagadomi — Anime/manga face detection cascade
• PyTorch — Deep learning framework
• Hugging Face Transformers — Model loading for Magi v2
• MyAnimeList — Character data source for the cast system

This project is licensed under the MIT License.

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Made with ❤️ for the manhwa community