Skip to content

Matcha Reader v1.6.0

Choose a tag to compare

View all tags
@eszter007 eszter007 released this 20 Sep 20:24
· 222 commits to master since this release
1.6.0
a1b987b

What's new in 1.6.0

This is the first Latest release since 1.5.0, and it gathers everything from the 1.6.0 nightlies and release candidates into one stable build.

Three new devices

1.6.0 is the first release supporting the X4 Pro, the X4 Classic and the Sticky (Seeed Studio), alongside the X4 (old), X3 and Papermono.

Each board has its own firmware file, so please double-check which one you flash:

  • Papermono: papermono-firmware.bin
  • X3 + X4 (old): x4old-x3-firmware.bin
  • X4C (new): x4c-firmware.bin
  • X4Pro: x4pro-firmware.bin
  • Sticky: sticky-firmware.bin

Look up a word anywhere

The dictionary was rebuilt around one idea: you should be able to point at a word and get an answer, whatever you happen to be reading.

  • Long-press a word to look it up. On touch devices like the X4 Pro, Papermono and Sticky, press and hold any word in a book and the dictionary opens on it.
  • On button devices, pick the word first. Walk the words with the buttons and then look the selected one up. This works in Japanese vertical text and in ordinary horizontal text.
  • The dictionary is now a floating panel over the page, with much better formatted entries, multiple readings, grammar notes, and far fewer empty results.
  • Words split across a page are found. That covers a Japanese word broken over a page boundary, and in other languages a word broken by hyphenation, so any- one is looked up as anyone.
  • Swipe up or down to scroll a long entry. Left and right turn the page instead, so the two never fight each other.
  • French verbs are deinflected, so a conjugated form finds its entry.

Word lookup in manga

This is the big new feature of 1.6.0, and it is worth converting your manga again for.

  • Long-press anywhere on the page to look a word up. On touch devices you no longer have to aim at a speech bubble. Press and hold any word printed on the image, wherever it sits, and the dictionary opens on it.
  • On button devices, walk the words on the page with the buttons. The selected word is outlined, and a short power-button click opens the lookup.

Important

Manga lookup reads word positions that only the current converter writes into the file. Manga you already have still reads perfectly, it simply has no words to find.
If you want to look up words by clicking on or selecting from the image: Manga converted before 1.6.0 has to be converted again before lookup works in it.

Manga, comics and 4-koma

The converter tools (web and the Python tool) learned several new page layouts:

  • Western comics and webtoons / manhwa. The panel model was trained on manga, so expect it to be less accurate on these.
  • 4-koma (yonkoma) strips, read down the right column and then down the left, plus a left-to-right variant for Western strips.
  • Panel detection retries at a higher resolution on sparse pages that used to come out as a single panel.

These are add-on tools, not firmware. The small converter built into the device's web interface does not have these options and won't get them.

Library, settings and files

  • Rename files and folders on the device and in the web browser, without losing your reading progress. Folders and system files can be deleted too.
  • The covers library view is the default. If you prefer the upstream list, it is under Settings > Library > Crosspoint List.
  • Settings were re-grouped and re-ordered, so library, sleep and shortcut settings now sit together. The user guide was updated to match.
  • Insights > Details is reachable by touch on the X4 Pro, Papermono and Sticky, and the calendar and tabs take touch too.
  • More side-button shortcuts on the X4 (old) and X3, and more options for the short power-button click.

Reading and appearance

  • Reversed page turns for Japanese vertical text and manga, which swaps left/right and up/down round for those books. It is a global setting, under Settings > Controls > Reversed page turn (Vertical & manga).
  • Better drop caps, with improved placement and anti-aliasing.
  • Larger font sizes (above 20) work properly for English and Japanese books now.
  • More font sizes for the Noto family via SD card.

Languages

English, Japanese, French, German and Spanish are built into the firmware. Every other UI language now loads from the SD card, which keeps the firmware small.

To use one: download language-packs.zip below, unzip it, create a lang folder on your SD card and put the .cplang file for your language in it.

Translations were completed or updated across the board this cycle, German among them.

Fixes and performance

  • The transparent sleep screen no longer goes black when you sleep from inside a book.
  • Wi-Fi is properly torn down when you leave the Settings network screen.
  • Accented characters render correctly in the File Browser again.
  • Word spacing is restored on partial cache misses.
  • Large folders open faster, because the File Browser no longer builds every row up front.
  • Going back to home from a book is faster, Japanese books render faster, and the buttons follow the reader's orientation.

NO CHANGE IN THE FONTS & DICTIONARIES. You do not need to re-upload books if you have them from the 1.5.0 public release or any 1.6.0 nightly/RC.

About integrating dictionaries

Dictionaries detect book language, e.g. to auto-select the right dictionary for the language, put your dictionaries into the dictionaries/lang_identifier folder. Replace lang_identifier with your language shorthand, e.g. de for German, en for English, fr for French, etc. To get this automatic dictionary switch, use the following structure:

dictionaries/

en/your_dictionary_name/ # English dict
[stardict files, e.g. stardict.dict, stardict.idx, etc.]

fr/your_dictionary_name/ # French dict
[stardict files, e.g. stardict.dict, stardict.idx, etc.]

dictionaries/jp/ # Japanese dicts
  vocab.idx    vocab.dat    vocab.spx      # vocabulary (required)
  names.idx    names.dat    names.spx      # names (recommended)
  grammar.idx  grammar.dat  grammar.spx    # grammar reference ① (optional)

(Replace fr, en with your language). The dictionary you select in the settings becomes the fallback language

Upgrade Notes

  • Flash the bin (or update via SD/OTA as usual).
  • If you used any language on the device for the UI (not book language) other than English, Japanese, French, Spanish or German, you need to install a language pack: download language-packs.zip below, unzip it, create a lang folder on your SD card and put the .cplang file for your language in it.
  • If you want to use the new lookup feature for manga to look up words by clicking on an image, you need to run the manga again through the OCR tool (either the python tool or web tool).
  • Current dictionaries, fonts & books unaffected.

👀 Issues?

If you have to see any issue with this release, you can reach me by either opening a GitHub issue or via e-mail.

Please attach the following:

  • Crashes: Crash Report from the SD card and a log
  • Anything else (perceived slowness, etc): a log

You can get a log by connecting your device with your computer with a cable and then using the logging tool in a Chrome-based browser.

💡Ideas or features requests?

Open an issue or contact me via e-mail.

If you want to contribute yourself, you can do that too. Please be aware that this software should stay reading focused, so I won’t add games, etc. Changes to lower level code such as the freeink SDK and partition tables also shouldn’t be made as this might cause issues with future crosspoint updates and risks bricking users.

General Overview about Matcha Reader

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 — candidates are validated against the entry's part of speech, so 勇気はありませんでした resolves to ある rather than はあり
  • JMnedict name recognition and an optional grammar reference surfaced alongside vocabulary
  • The book's own furigana — where the book annotated a reading, the entry opens with "In this book: はやし", remembered for the rest of the book even where it isn't annotated again
  • 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, panel-by-panel zoom, per-panel dictionary lookup, pre-extracted translations shown offline, bookmarks, and full Library/Insights integration. Easy manga conversion using the web based conversion tool.

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

⚙️ Per-book settings — Font, size, line spacing, margins, alignment and orientation are remembered per book. The global settings page holds the defaults for books you haven't opened yet, so bumping the font size in a Japanese novel leaves your other books alone. Reader settings are reachable from the book menu without leaving the page.

🌏 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, found at any folder depth on the card. Progress is a badge on the cover ("New", "Read", or the percentage) with the title below. Books can be organized into shelves with folders, and manga sits alongside EPUBs with its own cover, title and author.

🌙 Transparent sleep screens — Select "Transparent" under Settings → Sleep Screen and put the overlays in a transparent folder inside your sleep-images folder. The page you were reading shows through underneath.

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

Installation

Everything below can be prepared in your browser.
Matcha Reader Tools converts dictionaries, fonts and manga and hands back a zip already laid out for the SD card — no Python, no command line. Your files stay on your device; the one exception is manga OCR, where panel images go to Gemini under your own API key. The tools/ scripts described below do the same thing for anyone who prefers a terminal. (source)

1. Flash the firmware

Flash the 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)

Convert them in the browser tool, or unzip the dictionary archive ① from this release into the SD card root, so you have:

/dictionaries/jp/
  vocab.idx    vocab.dat    vocab.spx      # vocabulary (required)
  names.idx    names.dat    names.spx      # names (recommended)
  grammar.idx  grammar.dat  grammar.spx    # grammar reference ① (optional)

The .spx files are speed indexes — keep them next to their dictionaries. Cards set up before the rename, with jmdict.* and jmnedict.*, keep working: the firmware falls back to those names when the new ones aren't present. You can also generate everything 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 yourself — the browser tool takes any Yomitan dictionary.

3. Install the Japanese font (recommended)

Unzip the NotoSansJP archive into the SD card's font folder — or convert any TTF/OTF you like with the browser tool:

/.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, drop a CBZ, EPUB or PDF into Matcha Reader Tools in your browser, pick your device (X3 or X4), and copy the resulting folder anywhere on the SD card — the Library finds it automatically.

Converting Manga

The browser tool is the easy path and needs nothing installed. Pick your device (X3 or X4) — pages are then scaled to the screen, which makes files smaller and page turns noticeably faster without losing anything you could have seen.

For the command line, the same converter ships in the repo (tools/manga_convert/). Please refer to the readme for instructions.

Known limitations

  • Sunlight fading fix ON on the X3 leads to increased ghosting & grain. This issue exists in upstream crosspoint too.
  • 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.
  • Furigana can only be displayed for books that have Furigana in the book. If the book you load has no Furigana embedded, it won't work. If you are not sure if this is enabled or not, open the epub on any epub reader of your choice on your computer or smartphone. If there are no Furigana there, they won't show up on Matcha either.
Assets 10
Loading