MangaOCR-Overlay

Read Japanese manga in your browser and look words up with Yomitan as if the art were normal, selectable web text.

A Tampermonkey userscript grabs the manga page image, sends it to a small local Python OCR server, gets back text + bounding boxes, and draws invisible, selectable text boxes on top of the page. Hover a box and Yomitan pops up just like on any normal web page.

 browser page image  ->  userscript  ->  POST /ocr  ->  Python server
                                                          (detect + OCR)
      overlay boxes  <-  userscript  <-  JSON items  <-  back to browser

The default OCR uses mokuro's trained text-block detector with manga-ocr to find and read Japanese text. An optional second OCR model; "Baberu" is selectable from the panel.

Everything runs locally. Image bytes go only to 127.0.0.1:8766; nothing is uploaded anywhere.

---

Features

• Selectable overlay invisible text boxes so Yomitan (and normal text selection) work.
• Two scripts one tuned for mangafire.to, one universal script for any site that serves plain <img> pages.
• CPU or GPU should work on any PC on CPU; optionally ~5–6× faster on an NVIDIA (CUDA) or AMD (ROCm) GPU.
• Two OCR models use the default Manga OCR, or try optional Baberu OCR from the panel.
• No manual Python setup the setup script installs a project-local Python 3.12 if you don't have one, and all dependencies. Model weights download themselves on first run.

---

Examples:

MangaOCR.mp4

Usable with Yomitan:

OCR overlay:

Outline toggle:

---

Before you start (one-time)

You need a Chromium or Firefox-based browser with two extensions:

1. Tampermonkey runs the userscript.
2. Yomitan the pop-up dictionary. After installing it, import at least one Japanese→(your language) dictionary in Yomitan's settings, or pop-ups will be empty.

That's the only thing you install by hand. Everything on the Python side is automated by the setup script in Step 2.

---

Installation

Step 1 Get the project

Click Code ▸ Download ZIP at the top of this page, then extract it to a folder you'll keep (e.g. C:\MangaOCR-Overlay).

Step 2 Download dependencies and run

From the extracted folder choose which .bat installer depending on your GPU, or lack thereof:

NVIDIA (CUDA)

setup-cuda.bat     ::  one-time: creates .venv-cuda with a CUDA build of PyTorch
run-gpu.bat        ::  start the server on the GPU

If PyTorch doesn't see your card, edit the CUDA_INDEX line at the top of setup-cuda.bat to match your driver (e.g. cu121, cu126; options at https://pytorch.org/get-started/locally/).

The CUDA and AMD paths share the exact same device-detection code, and that path is exercised in testing via ROCm (which PyTorch also reports as "cuda"). The CUDA installer is a standard PyTorch CUDA install but hasn't been tested on real NVIDIA hardware. Reports/PRs welcome.

AMD (ROCm)

powershell -ExecutionPolicy Bypass -File .\setup-rocm-windows.ps1
run-gpu.bat

Requires an AMD Adrenalin driver new enough for the ROCm release (26.2.2 or newer for ROCm 7.2.1).

Full runbook, benchmarks, and troubleshooting: README-ROCM.txt.

A Linux path for AMD GPUs also exists setup-rocm-wsl.sh (WSL2 + Ubuntu). It's untested, so treat it as a starting point and expect to update the ROCm version URLs inside it.

⚠️ Note: run-cpu.bat can reuse an AMD ROCm env for CPU mode, but AMD's ROCm torch build does CPU math with OpenBLAS and is ~10–18× slower than a real CPU install. For fast CPU, run setup-cpu.bat. (run-cpu.bat warns you about this if it falls back to the ROCm env.)

CPU

setup-cpu.bat      ::  run once, builds the environment and installs everything
run-cpu.bat        ::  start the server on http://127.0.0.1:8766

Just double-click each .bat (or run it from a terminal).

• setup-cpu.bat is a one-time step. It finds Python 3.12 or downloads a project-local copy, creates .venv, and installs the Python packages.
• run-cpu.bat starts the server. The very first launch downloads the OCR model weights (a few hundred MB), so wait until you see a line like BatchedMangaPageOcr ready (device=cpu, ...). Leave this window open while you read, it is the server.

---

Step 3 Install the userscript

Pick the script for the site you read:

Site	Script
mangafire.to	MangaFireOCR.user.js
Any other site that serves plain <img> manga pages	MangaOCR.user.js

To install one: open the Tampermonkey dashboard, then drag the .user.js file from the extracted folder onto it and click Install. (Alternative: Tampermonkey ▸ Create a new script, delete the template, paste the file's contents, and press Ctrl+S.)

Don't run both scripts on the same site. The universal MangaOCR.user.js ships with an empty whitelist and stays dormant until you add the current site: open its panel with Ctrl+Shift+Y and click "Add current site".

Step 4 Read and look up

1. Open a manga chapter.
2. Click "OCR visible page(s) now" (or press Ctrl+Shift+O), or enable auto-OCR from the panel.
3. Hover the dashed boxes → Yomitan pops up. Select text as normal.

---

Optional: Baberu OCR

Choose Model: Baberu OCR beside the OCR button. The first selection opens a confirmation dialog; accepting it downloads the ~121 MB model. It runs with no separate installer or server restart needed.

---

Responsible use

This is a personal reading aid. Respect each website's terms and copyright.

License & credits

Released under the MIT License (see LICENSE).

The mangafire tile-descramble algorithm is derived from the Apache-2.0-licensed Tachiyomi/Mihon MangaFire extension (keiyoushi/extensions-source) attributed in NOTICE. Detection/OCR is powered by mokuro, manga-ocr, or Baberu OCR, and comic-text-detector weights from manga-image-translator, each installed/downloaded separately under its own license.