MiracleEye

MiracleEye is an offline-first desktop overlay for Japanese study. It captures the visible screen area inside a transparent viewfinder window, runs Japanese OCR, translates to English, and shows per-token dictionary/kanji details on hover.

Build a real app executable

macOS

./scripts/build-macos.sh

Output:

• dist/MiracleEye.app (double-click to run)
• dist/MiracleEye-macos.zip

Linux (X11)

Run this on a Linux machine:

./scripts/build-linux.sh

Output:

• dist/MiracleEye/MiracleEye (executable)
• dist/MiracleEye-linux.tar.gz

First run behavior

• No manual setup command required.
• On first launch, MiracleEye automatically prepares offline translation assets if missing.
• OCR model files are downloaded/cached automatically on first use.

Features

• Transparent always-on-top viewfinder window
• OCR pipeline: EasyOCR (text region detection) + MangaOCR (recognition)
• Offline Japanese -> English translation via Argos Translate
• Hover details via fugashi tokenization + Jamdict/JMdict/KANJIDIC
• Speech-bubble style translation panel anchored to the main window

Platform target

• macOS
• Linux X11

Wayland is intentionally out of scope in this build.

Controls

• Drag window by title bar
• Resize from bottom-right size grip
• Pause/Resume button controls capture loop
• Hover recognized text in the viewfinder to see token definitions/kanji data

Environment overrides

Useful variables:

• MIRACLEEYE_CAPTURE_INTERVAL_MS
• MIRACLEEYE_MIN_DETECTION_CONFIDENCE
• MIRACLEEYE_MANGA_FORCE_CPU
• MIRACLEEYE_EASYOCR_GPU
• MIRACLEEYE_WINDOW_WIDTH
• MIRACLEEYE_WINDOW_HEIGHT

Test

uv run pytest
uv run ruff check