chirami pops up a little card at your pointer whenever you select japanese text, with furigana, romaji, pitch accent, dictionary entries and kanji. it works offline, on macos and linux (wayland).

at first the card only tells you how to read what you selected: furigana, romaji and a speaker button. click it to open it up: the word split into its parts and what each one does, the dictionary form with its pitch accent and up to three meanings, and the word's kanji, each opening a page with readings, parts and other words that use it. point at a part and an explanation shows up right next to it. when a whole phrase is in the dictionary, the card opens on the phrase and each word stays clickable.

the small card closes when your pointer leaves it. an opened one stays until you press escape, click its ×, or select something else (on macos clicking anywhere else closes it too).

jisho.org is only asked when the offline dictionary has nothing for a word with kanji, never for kana, and -offline turns that off too.

ocr #

take a screenshot of some japanese with your usual shortcut and the card pops up for the text in it. copying an image never does that, only screenshots.

on macos chirami watches for your screenshot shortcuts (remapped ones too) and reads the image with live text. on niri it follows niri's screenshot event and reads the image with meikiocr and manga-ocr on the cpu, after chirami setup -ocr downloads the models (~500 MB). other wayland compositors don't say when you took a screenshot, so there's no ocr for those yet, there can probably be for some but i didn't bother looking :p

requirements #

• macos 13 or newer, 14 for vertical text in screenshots. chirami asks for accessibility to read the selection, and for input monitoring to see the screenshot shortcut.
• linux: a wayland compositor with layer-shell and data-control (niri, sway, hyprland, river, kde, ...). gnome and x11 aren't supported.
• the speaker uses say on macos and speech-dispatcher or espeak-ng on linux.

installation #

there is a nix flake, so just do nix profile add git+https://tangled.org/ptr.pet/chirami, or nix-env -f . -i from a checkout. it comes with the ocr helper.

otherwise get go and compile it:

go build ./cmd/chirami                                         # CGO_ENABLED=0 is fine on linux
swiftc -parse-as-library -O -o chirami-ocr macos/ocr/main.swift  # macos, for screenshots
go build ./cmd/chirami-ocr                                     # linux, for screenshots

keep chirami-ocr next to chirami. the linux one needs onnxruntime, point CHIRAMI_ORT_LIB at libonnxruntime.so if it isn't somewhere usual.

then run chirami setup once. it builds the tokenizer data and downloads the dictionaries (~90 MB) into ~/Library/Application Support/chirami or $XDG_DATA_HOME/chirami (CHIRAMI_DATA overrides), and then chirami runs it.

setting up as a service #

with home-manager, import the flake's homeManagerModules.default and set services.chirami.enable = true; (and services.chirami.extraArgs for flags). that's a systemd user service on linux and a launchd agent on macos.

otherwise on linux copy contrib/chirami.service into ~/.config/systemd/user and systemctl --user enable --now chirami. it runs the chirami on your PATH, so after an update systemctl --user restart chirami is enough.

on macos copy contrib/dev.dawn.chirami.plist into ~/Library/LaunchAgents, point it at your chirami (with nix that's /Users/you/.nix-profile/bin/chirami) and launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.dawn.chirami.plist. chirami then asks for accessibility and input monitoring for itself instead of your terminal, and again after every update, since macos ties them to the exact binary.

usage #

chirami [flags]          watch the selection
chirami setup [-names] [-ocr]
                        build the data; -names adds JMnedict (+70 MB),
                        -ocr the linux ocr models
chirami show TEXT        pop up the card for TEXT at the pointer
chirami render TEXT      draw the card into a png (-o, -expanded, -scale)
chirami lookup TEXT      print the analysis and dictionary entries
chirami ocr FILE         print the japanese read from an image

-romaji macron|wapuro|plain|none picks the romaji (tōkyō, toukyou, tokyo), -theme night|day|auto the colours, -zoom how much bigger the card is drawn on 1x displays (1.25 by default). CHIRAMI_FONT=/path/font.ttc[:index] swaps the font, and CHIRAMI_DEBUG=1 logs what chirami sees (including your selections).

acknowledgements #

chirami ports a lot of other people's work and tests against it:

• the tokenizer is a port of kagome's lattice (MIT) over IPADIC
• JMdict, KANJIDIC2, JMnedict and KRADFILE/RADKFILE (EDRDG, CC BY-SA), via jmdict-simplified
• JmdictFurigana (CC BY-SA) and pitch accents from kanjium (CC BY-SA)
• JLPT levels from Jonathan Waller's lists (CC BY)
• kana → romaji from WanaKana (MIT), conjugations and their explanations from Yomitan (GPL-3.0-or-later)
• ocr models: meikiocr (LGPL-3.0 weights, Apache-2.0 code) and manga-ocr (Apache-2.0)
• fonts on linux: M PLUS Rounded 1c and Source Sans 3 (SIL OFL 1.1)

llms made this with feedback (thank you opus 5.5 and gemini 3.8 flash).