Skip to content

Matcha Reader (Beta) v1.4.1-matcha-reader

Latest
Latest

Choose a tag to compare

View all tags
@eszter007 eszter007 released this 05 Jul 18:59
beta
e348cfb

Matcha Reader — v1.4.1-matcha-reader

First release of the Japanese language learning fork of CrossPoint Reader for the Xteink X4. Read native Japanese novels and manga with instant dictionary lookup, verb deinflection, grammar references, furigana, and AI-powered page translation — all on an e-ink device.

Fully compatible with any Xteink X4 that runs upstream CrossPoint. Try it in the desktop emulator before flashing.

Highlights

📖 Vertical Japanese text (tategaki) — Japanese EPUBs are auto-detected and rendered in right-to-left vertical columns with proper kinsoku line breaking, furigana (ruby) positioning, bold/emphasis marks, and a per-book vertical/horizontal toggle.

🔍 Word Lookup — Look up any word on the current page directly from the reader menu:

  • Full JMdict vocabulary (via Jitendex) with readings, POS tags, and example sentences
  • Verb deinflection: 食べませんでした → 食べる, 読まれた → 読む, compound auxiliaries too
  • JMnedict name recognition (with honorific grouping: 根岸さん as one unit) and an optional grammar reference surfaced alongside vocabulary
  • Opens in under half a second, remembers your position per page, and wraps around at the ends of the word list

💬 Page Translation — Translate the current page to English via Gemini (free API key required, see setup).

📚 Manga reader — Real panel detection (YOLO, converted on your PC with the included tool), panel-by-panel zoom, per-panel dictionary lookup, pre-extracted translations, bookmarks, and full Library/Insights integration.

🈶 Fonts — Built-in fonts cover all jōyō + jinmeiyō kanji (2,999 total). Install the included NotoSansJP .cpfont set for complete JIS coverage — while an SD Japanese font is loaded it also serves as an on-demand fallback, so rare kanji in dictionary entries never render blank.

🌏 Localized UI — All UI, including the fork's additions, translated into all 27 supported languages (Japanese UI included).

📊 Reading Insights — Statistics on your reading time, finished books and a streak to maintain consistency

📚 Library with covers — Recent books becomes library: It shows all your books with covers. The books can be organized into shelves with folders. The books are sorted by recently read.

Plus everything from upstream CrossPoint 1.4.x: non-Japanese books support, OPDS, web file transfer, sleep-screen covers, and more.

Installation

1. Flash the firmware

Flash matcha-reader-1.4.1.bin using the standard CrossPoint flashing process (see the upstream instructions or the upstream flash tools). Coming from stock or upstream CrossPoint, no data is lost — books and progress live on the SD card.

2. Install the dictionaries (required for Word Lookup)

Unzip the dictionary archive ① from this release into the SD card root so you have:

/dict/
  jmdict.idx    jmdict.dat    jmdict.spx     # vocabulary (required)
  jmnedict.idx  jmnedict.dat  jmnedict.spx   # names (recommended)
  grammar.idx   grammar.dat   grammar.spx    # grammar reference① (optional)

The .spx files are speed indexes — keep them next to their dictionaries. You can also generate the files yourself from Yomitan-format dictionaries with tools/dict_convert/ (see the README).

① the grammar reference is excluded from the zip due to copyright reasons as the license doesn't allow public distribution. If you want a grammar dictionary, find it and convert it on your computer using the above toolchain.

3. Install the Japanese font (recommended)

Unzip the NotoSansJP archive into the SD card's font folder:

/.fonts/
  NotoSansJP/
    NotoSansJP_12.cpfont
    NotoSansJP_14.cpfont
    NotoSansJP_16.cpfont
    NotoSansJP_18.cpfont

Then select it under Settings → Font. Any installed SD Japanese font also acts as the rare-kanji fallback for the whole UI.

4. Set up translation (optional)

Get a free API key from Google AI Studio and save it as the only content of /system/gemini.key on the SD card. WiFi is required for translation.

Usage in 30 seconds

Open a Japanese EPUB — vertical layout and furigana come on automatically. Press Confirm for the reader menu → Word Lookup; move between words with Left/Right, scroll long definitions with Up/Down, Back to return to the page. Translate Page is in the same menu. For manga, convert a volume with tools/manga_convert/ on your PC and copy the output folder anywhere on the SD card.

Converting Manga

Manga is prepared on your PC with the included converter (tools/manga_convert/ in the repo), which detects panel rectangles with a YOLO model and optionally extracts each panel's text and an English translation via Gemini. Copy the output folder anywhere onto the SD card — the Library finds it automatically.
Replace ./MyManga.cbz with the path to your manga (epub, pdf or cbz).

Panels only (no text — navigation and panel zoom, no lookup/translation):

python3 tools/manga_convert/convert_manga.py \
    --input ./MyManga.cbz \
    --output-dir /path/to/sd/manga/MyManga/ \
    --no-ocr

Full conversion with Gemini (adds per-panel Japanese text for Word Lookup and pre-extracted English translations, shown on-device without any network call)

python3 tools/manga_convert/convert_manga.py \
    --input ./MyManga.cbz \
    --output-dir /path/to/sd/manga/MyManga/ \
    --gemini-key-file ./gemini.key

Licenses & Attribution

Known limitations

  • Word Lookup and vertical text require the dictionary files / are only offered for Japanese books.
  • Rare (hyōgai) kanji render via the SD font fallback — without an SD Japanese font installed, they may appear blank in dictionary text.
  • Page translation requires WiFi and a Gemini API key.

A note on this first release

This is the very first release of this fork — it has been tested extensively on real hardware, but with brand-new features some rough edges may still occur. To make any issue easy to report and fix, this build includes diagnostic logging:

  • Nothing to do for normal use — logging runs silently and doesn't affect reading, battery, or performance.
  • If something goes wrong, the device writes a crash_report.txt to the root of the SD card, including the last log lines before the problem. Attaching that file to a GitHub issue is usually all that's needed to pin down the cause.
  • Live logs (optional): connect the device to a computer via USB-C and open the serial port at 115200 baud (e.g. screen /dev/cu.usbmodem* 115200 on macOS/Linux, or PuTTY on Windows) to watch the logs in real time.

So: if the reader ever restarts unexpectedly, it's not broken — grab crash_report.txt from the SD card and open an issue. That's exactly what this build is instrumented for.

Assets 5
Loading