`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).

![the opened card for 食べさせられなかった](docs/card.png)

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).

[kagome]: https://github.com/ikawaha/kagome
[JMdict]: https://www.edrdg.org/jmdict/j_jmdict.html
[KANJIDIC2]: https://www.edrdg.org/wiki/index.php/KANJIDIC_Project
[JMnedict]: https://www.edrdg.org/enamdict/enamdict_doc.html
[jmdict-simplified]: https://github.com/scriptin/jmdict-simplified
[JmdictFurigana]: https://github.com/Doublevil/JmdictFurigana
[kanjium]: https://github.com/mifunetoshiro/kanjium
[WanaKana]: https://github.com/WaniKani/WanaKana
[Yomitan]: https://github.com/yomidevs/yomitan
[meikiocr]: https://github.com/rtr46/meikiocr
[manga-ocr]: https://github.com/kha-white/manga-ocr