YomiNinja Setup Guide: From Download to First Lookup

Before you start

YomiNinja works by rendering a transparent overlay above your game window. This requires your game to run in Borderless Windowed or regular Windowed mode, not exclusive fullscreen. Before anything else, change your game's display setting to Borderless Windowed. This is a one-time change and the game will look identical to fullscreen.

Step 1 — Download and install YomiNinja

Go to the download page and download the package for your platform:

• Windows: run the .exe installer. If Windows SmartScreen blocks it, click "More info → Run anyway". This is normal for unsigned apps.
• Linux: download the .AppImage, then chmod +x YomiNinja-*.AppImage and run it.
• macOS: open the .dmg, drag YomiNinja to Applications, and grant Accessibility + Screen Recording permissions when prompted.

No additional runtime is required for the default OCR path. PaddleOCR is bundled, and the rest of the setup is about dictionaries, permissions, and choosing the right capture mode.

Step 2 — Choose your OCR engine

When YomiNinja first opens, it defaults to PaddleOCR. For most games this is the right choice. The quick decision:

• Most JRPG / action game text → keep PaddleOCR (default)
• Visual novels, manga, or artistic fonts → switch to MangaOCR
• macOS or vertical text → Apple Vision Framework is a strong local alternative
• Nothing works on a specific game → try Google Cloud Vision or Google Lens

You can switch engines at any time from the OCR settings panel. See the full engine comparison for detailed guidance.

Step 3 — Import Yomitan dictionaries

Yomitan ships pre-installed but needs dictionary files to show definitions. This is a one-time setup that takes 3 to 5 minutes and solves the most common first-run confusion: the app works, but hover popups do nothing.

Opening Yomitan settings inside YomiNinja

Click the Yomitan icon in YomiNinja's extension toolbar (puzzle piece or Yomitan logo). A new panel opens — this is the real Yomitan extension, running inside YomiNinja's Chromium context. Go to Settings → Dictionaries.

Minimum required: JMdict

Click Import and select a dictionary file. Start with JMdict (English) — the standard Japanese–English dictionary. Download it from the jmdict-yomitan releases page. Import the .zip file directly — Yomitan will unpack it.

Recommended additional dictionaries

All files are available for free from the jmdict-yomitan GitHub repository.

Verify Yomitan is working

After importing JMdict, hover any Japanese text in a browser tab or YomiNinja's test area. If a popup appears, Yomitan is working. If not, check that the "Enable" toggle in Yomitan settings is on and that scanning is not set to require a held modifier key such as Shift.

Step 4 — Select your game window

In YomiNinja's main window, find the Source selector — a searchable list of all open application windows. Type the game's name to filter, then click it to select.

YomiNinja will now target that window for all captures. If the game is not in the list, make sure it is running, visible to the OS window manager, and not in exclusive fullscreen mode. On Linux, missing windows often means a Wayland-related limitation rather than a game issue.

Step 5 — Create an OCR Template (recommended)

An OCR Template tells YomiNinja to only capture a specific region of the window, rather than the entire screen. For dialogue-based games, this means capturing only the dialogue box — eliminating OCR noise from health bars, maps, and decorative UI.

Drawing your first OCR Template

1. In YomiNinja, click OCR Templates (or the crop icon).
2. A selection interface appears over your game. Draw a rectangle over the area where dialogue text appears — typically the bottom 20% of the screen.
3. Give the template a name (e.g., "Dragon Quest XI — Dialogue") and save.
4. Activate the template. Future OCR captures will use this region only.

Step 6 — Enable Auto OCR

Toggle Auto OCR in YomiNinja's settings or toolbar. In this mode, YomiNinja continuously monitors the capture region for changes. When the game displays a new line of dialogue, the OCR runs automatically — you never need to press a hotkey.

If Auto OCR fires too often, for example on animated backgrounds or flashing UI, adjust the sensitivity threshold, tighten the OCR Template, or switch to manual hotkey mode for that specific game.

Step 7 — Your first lookup

Launch your game and navigate to a scene with Japanese dialogue. The overlay text should appear within half a second of the dialogue box rendering.

Move your cursor over a word in the overlay. Yomitan's popup should appear immediately with the reading and definitions. If it doesn't, see the troubleshooting section below.

If the popup appears — you're set up. You now have Yomitan dictionary lookups working inside any Japanese game.

Optional: VOICEVOX TTS and Anki mining

Enabling VOICEVOX text-to-speech

In YomiNinja settings, find the TTS section and enable VOICEVOX. Select a voice character. When OCR captures text, it will be read aloud in a natural Japanese voice. This is useful for reinforcing pronunciation, especially for vocabulary you're encountering for the first time.

Setting up the Anki mining pipeline

YomiNinja streams every OCR result over a local WebSocket at ws://localhost:7331. To connect it to Anki:

1. Open a texthooker page in your browser.
2. Set the WebSocket URL to ws://localhost:7331 and connect.
3. As YomiNinja captures game text, sentences appear on the page.
4. Hover any word with Yomitan in your browser, then use Yomitan's Anki export to create a flashcard.

See the Anki mining guide for a detailed walkthrough.

Troubleshooting common issues

Overlay isn't appearing

• Confirm the game is in Borderless Windowed (not exclusive fullscreen)
• Check that the correct window is selected in YomiNinja's source list
• Try pressing the manual OCR hotkey — if OCR finds text, the overlay will appear
• macOS: confirm Screen Recording permission is granted in System Settings
• Linux: if you are on Wayland, retry under X11 or XWayland

Yomitan popup doesn't appear on hover

• Check that JMdict is imported: Yomitan Settings → Dictionaries
• Verify Yomitan's "Enable" toggle is on in settings
• Check the scanning key: by default Yomitan may require holding Shift. Disable this in Yomitan Settings → Scanning → Modifier Keys
• Hover the overlay text specifically (the text YomiNinja rendered), not the original game text underneath

OCR is reading the wrong text or making errors

• Draw a tighter OCR Template over just the dialogue box
• Switch from PaddleOCR to MangaOCR if the game uses a stylized font
• Adjust the furigana threshold if furigana is being captured with kanji
• Try Apple Vision on macOS for vertical text or difficult native layouts
• Try Google Cloud Vision for games that both local engines struggle with
• If the game uses an unusually decorative font, search for a font replacement mod