title: Manhwa Recap Studio
emoji: 🎬
colorFrom: green
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
Manhwa Recap Studio
Auto-scrape manhwa/manga/webtoon chapters, transcribe panel text with
RapidOCR (PP-OCRv5, ONNXRuntime) as the primary transcriptor (no API
keys, no PaddlePaddle framework dependency) with PaddleOCR PP-OCRv4 as
a fallback tier (x86 only) and VLM as a last resort, translate to English,
and render a narrated recap video with text-to-speech audio.
Self-hosting on a VM (the current production setup)
This is how the project actually runs in production (Oracle Cloud VM, x86 or
ARM). One script does everything:
git clone <this-repo-url> manhwa-recap-studio && cd manhwa-recap-studio
SKIP_OLLAMA=1 ./setup.sh # drop SKIP_OLLAMA on an 8GB+ box if you want local LLMs
# paste secrets into .env (only if you want cloud VLM — the default OCR flow needs none)
setup.sh installs system packages, the Python venv (RapidOCR + optional
PaddleOCR), Bun deps, Piper TTS, Caddy, the systemd unit, builds the Next.js
bundle, and starts everything. It is idempotent — re-run it any time.
Moving to a fresh instance (incl. ARM): see MIGRATION.md.
It covers the aarch64 specifics (PaddleOCR skipped, RapidOCR is primary) and
what to carry over from an old box (db/custom.db, data/, .env secrets).
The Docker / Hugging Face Spaces path below still works but is not how the
current deployment runs.
Quick Deploy — Hugging Face Spaces (5 steps, ~15 min)
See DEPLOYMENT.md for the full guide. Short version:
- Create a free Hugging Face account at huggingface.co
- Create a new Space → SDK: Docker → Space name:
manhwa-recap-studio
- Upload this repo to the Space (or clone + push via git)
- Enable persistent storage (Settings → Persistent storage → 20 GB free)
- Wait ~10 min for the Docker build → your app is live at
https://yourname-manhwa-recap-studio.hf.space
No environment variables required to start. Add MEGA_EMAIL / MEGA_PASSWORD
(optional) for cloud archive to Mega (20 GB free).
What runs inside the container
| Service | Port | Purpose |
|---|
| Next.js (standalone) | 3000 | Frontend + API routes |
| Pipeline-service | 3001 | Job queue + VLM fallback + socket.io |
| PaddleOCR service | 3002 | RapidOCR PP-OCRv6 (primary) + PaddleOCR PP-OCRv4 (fallback) OCR engine |
| Caddy | 7860 | Reverse proxy (HF Spaces entry point) |
Optional env vars (Settings → Repository secrets)
| Variable | Purpose |
|---|
MEGA_EMAIL | Mega cloud archive (20 GB free) |
MEGA_PASSWORD | Mega cloud archive |
GROQ_API_KEY | Better narration/translation (free at console.groq.com/keys) |
AUTO_ARCHIVE | true (default) to auto-upload videos to Mega |
Features
- Search 6 sources: MangaHere, FanFox, Webtoons, AsuraScans, MAL, AniList
- 55 narration voices with inline preview playback
- PaddleOCR PP-OCRv4 primary transcription (no API keys)
- VLM providers (SiliconFlow, Gemini, Groq) as automatic OCR fallback
- YOLO panel detection
- edge-tts narration with clean audio (no pops/clicks)
- Mega cloud archive (auto-upload + on-demand restore)
- Full HTTP Range video streaming (seek support)
Oracle Cloud CPU-only production mode
Production mode is local-first and does not require edge-tts, OpenAI, or any cloud TTS API. The supported Oracle layout uses an isolated Python 3.10.4 runtime (do not replace /usr/bin/python3) and a dedicated virtual environment:
/opt/python3.10/bin/python3.10 -m venv /opt/manhwa-recap-studio/.venv
source /opt/manhwa-recap-studio/.venv/bin/activate
python --version # Python 3.10.4
pip install -r pipeline/requirements.txt
pip install -r mini-services/paddleocr-service/requirements.txt
pip install --no-deps rapidocr==3.9.2
Required local binaries for production are ffmpeg, ffprobe, piper, and espeak-ng (or espeak). Set a small CPU-friendly English Piper voice with PIPER_VOICE_MODEL=/opt/piper/voices/en_US-lessac-medium.onnx (or PIPER_VOICE). The production TTS cascade is Piper, Piper retry, then eSpeak NG; non-empty narration is never converted to successful silence.
Production validation commands:
PYTHONPATH=. python pipeline/production_canary.py --work-dir /tmp/mrs-canary --job-id canary
PYTHONPATH=. python pipeline/crash_resume_harness.py --work-dir /tmp/mrs-crash-tts --job-id crash-tts --stage TTS
The SQLite state database is stored under the chosen work directory as state.sqlite; temporary artifacts, promoted artifacts, and quarantined artifacts live under tmp/, artifacts/, and quarantine/ in that work directory.
