{"id":19592892,"url":"https://github.com/fauu/kamite","last_synced_at":"2025-04-27T14:33:59.843Z","repository":{"id":45008374,"uuid":"511974499","full_name":"fauu/Kamite","owner":"fauu","description":"Japanese immersion assistant for learners (Windows/Linux)","archived":false,"fork":false,"pushed_at":"2024-02-22T22:42:28.000Z","size":15748,"stargazers_count":104,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-07-31T20:30:32.707Z","etag":null,"topics":["anime","deepl","immersion","japanese","japanese-language","japanese-study","java","language-learning","languages","linux","manga","mpv","ocr","solidjs","tesseract","textractor","typescript","visual-novel","visual-novels","yomichan"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fauu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/definitions/pmd-ruleset.xml","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-08T17:25:55.000Z","updated_at":"2024-07-26T18:33:09.000Z","dependencies_parsed_at":"2023-09-23T20:35:33.143Z","dependency_job_id":"86903ac9-067e-4751-a331-ac517b7a9e16","html_url":"https://github.com/fauu/Kamite","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2FKamite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2FKamite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2FKamite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2FKamite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fauu","download_url":"https://codeload.github.com/fauu/Kamite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251154846,"owners_count":21544566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anime","deepl","immersion","japanese","japanese-language","japanese-study","java","language-learning","languages","linux","manga","mpv","ocr","solidjs","tesseract","textractor","typescript","visual-novel","visual-novels","yomichan"],"created_at":"2024-11-11T08:37:19.116Z","updated_at":"2025-04-27T14:33:54.824Z","avatar_url":"https://github.com/fauu.png","language":"Java","readme":"\u003c!-- vim: set textwidth=80 colorcolumn=80: --\u003e\n\u003c!-- markdownlint-configure-file\n{\n  \"line-length\": { \"code_blocks\": false },\n  \"no-inline-html\": false\n}\n--\u003e\n# Kamite\n\n\u003e A desktop language immersion companion for learners of Japanese\n\n\u003c!-- --\u003e\n\n\u003e [!NOTE]\n\u003e This is alpha software.\n\nKamite is desktop software to aid learning Japanese through immersion in native\nmedia. It brings Japanese text from those media into a web browser interface,\nenabling lookup with pop-up dictionaries (such as [Yomichan](#pop-up-dictionary))\nand websites (such as [DeepL Translate](#lookups)), and more.\n\n\u003c!-- markdownlint-capture --\u003e\u003c!-- markdownlint-disable --\u003e\nhttps://user-images.githubusercontent.com/4130634/178029301-075cb207-a154-42d2-adb5-ce8fdbcd722f.mp4\n\u003c!-- markdownlint-restore --\u003e\n\n*(Featured in the above demo video: [All shots] Firefox, [Sway]. [Shot 1] [Gomics-v]\nmanga reader (Kaguya-sama wa Kokurasetai, ch. 140); [Yomichan] (dictionaries:\nJMDict, Kanjium Pitch Accents, Narou Freq, VN Freq). [Shot 2] [mpv]\n(Suzumiya Haruhi no Yuuutsu (2006), ep. 9). [Shot 3] Summer Pockets;\n[Textractor];\n[`contrib/kamite-toggle-visibility.sh`](contrib/kamite-toggle-visibility.sh)\nscript; [waycorner][waycorner-icxes].)*\n\n## Highlights\n\n* Use your existing installation of your favourite [pop-up dictionary\n  extension](#pop-up-dictionary) (e.g., Yomichan, rikaikun,\n  10ten Japanese Reader).\n\n* [Extract text from images on screen](#mangavisual-text-extraction)\n  (e.g., manga) with several third-party online and offline OCR solutions\n  (e.g., “MangaOCR”, EasyOCR, Tesseract).\n\n  Includes advanced features such as automatic text block detection and\n  derotation of rotated text before further processing.\n\n* Extract text from video subtitles as it is playing ([mpv player integration](#animevideo-text-extraction)).\n\n* Extract text from games, visual novels, and other programs as they are running\n  ([Textractor and Agent texthookers integration](#visual-novel--game-text-extraction)).\n\n* Have the text [filtered and transformed using custom rules](#filtering-and-transforming-incoming-text)\n  before it is displayed in the program.\n\n* Freely [edit and transform the text manually](#editing-and-transforming-the-text)\n  once it is displayed.\n\n* Use the text for lookups on external websites (e.g., DeepL Translate, Google\n  Images).\n\n  You can have the websites embedded directly into Kamite’s UI, so that\n    lookups do not require constant clicking around and switching windows/tabs.\n\n* Easily [run external programs and scripts](#custom-commands-launching-external-executables),\n  providing them the text as input.\n\n  This enables countless custom integrations, e.g., [reading the text aloud\n  using Microsoft’s text-to-speech service][wiki-linux-edge-tts].\n\n* Send text and commands to Kamite from the oustide using [the provided\n  API](#command-api).\n\n  This enables still more custom integrations, e.g.:\n\n  * [Gomics-v](#linux-manga-viewer-with-kamite-integration): A Linux manga\n    reader able to send images to Kamite for OCR through a convenient\n    one-mouse-key shortuct.\n\n  * [kamite-watch-clipboard](#watcher-script): A system script that\n    automatically sends clipboard contents as text to Kamite.\n\nKamite supports Linux\\* and Windows (macOS support planned for the beta release).\n\n*(\\*Linux: Xorg, wlroots, GNOME Wayland, Plasma Wayland. OCR-ing arbitrary screen\nareas not supported on GNOME Wayland and Plasma Wayland.)*\n\nKamite is cost-free and is licensed under the GNU AGPL v3 or later.\n\n[deepl]: https://deepl.com/\n[mpv]: https://mpv.io/\n[Textractor]: https://github.com/Artikash/Textractor\n[Agent]: https://github.com/0xDC00/agent\n[waycorner-icxes]: https://github.com/icxes/waycorner\n[wiki-linux-edge-tts]: https://github.com/fauu/Kamite/wiki/Linux-recipes#read-text-from-kamite-aloud-using-microsofts-tts\n\n## Table of contents\n\n1. [Installing Kamite](#installing-kamite)\n    * [Linux](#linux)\n    * [Windows](#windows)\n1. [Updating Kamite](#updating-kamite)\n    * [Linux Generic and Windows](#linux-generic-and-windows)\n1. [Launching Kamite](#launching-kamite)\n1. [Troubleshooting](#troubleshooting)\n1. [User interface overview](#user-interface-overview)\n1. [Text extraction](#text-extraction)\n    * [Anime/video text extraction](#animevideo-text-extraction)\n    * [Manga/visual text extraction](#mangavisual-text-extraction)\n    * [Visual novel / game text extraction](#visual-novel--game-text-extraction)\n    * [Clipboard](#clipboard)\n    * [Custom source / alternative method text extraction](#custom-source--alternative-method-text-extraction)\n    * [Filtering and transforming incoming text](#filtering-and-transforming-incoming-text)\n1. [Text use](#text-use)\n    * [Editing and transforming the text](#editing-and-transforming-the-text)\n    * [Pop-up dictionary](#pop-up-dictionary)\n    * [Lookups](#lookups)\n    * [Auto-generated furigana](#auto-generated-furigana)\n    * [Saving text to a file for external use](#saving-text-to-a-file-for-external-use)\n    * [Custom text use](#custom-text-use)\n1. [Custom commands (Launching external executables)](#custom-commands-launching-external-executables)\n1. [Keyboard shortcuts](#keyboard-shortcuts)\n    * [Client-only keyboard shortcuts](#client-only-keyboard-shortcuts)\n    * [Global keyboard shortcuts](#global-keyboard-shortcuts)\n1. [Launch options](#launch-options)\n1. [Config](#config)\n    * [Live reload](#live-reload)\n    * [Full config example](#full-config-example)\n    * [Substitution (variables)](#substitution-variables)\n    * [Config profiles](#config-profiles)\n1. [Style customization](#style-customization)\n    * [Styling recipes](#styling-recipes)\n1. [Command API](#command-api)\n    * [Sending commands](#sending-commands)\n    * [Command listing](#command-listing)\n1. [Privacy](#privacy)\n1. [Development](#development)\n1. [License](#license)\n    * [Third-party components](#third-party-components)\n\n## Installing Kamite\n\n### Linux\n\n#### Arch User Repository\n\nAn AUR package is available under the name [kamite-bin] (installs to\n`/opt/kamite`).\n\n[kamite-bin]: https://aur.archlinux.org/packages/kamite-bin\n\n#### Debian/Ubuntu-based\n\nA Debian (`.deb`) package is available among the files on the [Releases] page.\nInstall with:\n\n```sh\nsudo apt install /path/to/[package-file].deb\n```\n\nUninstall with:\n\n```sh\nsudo apt remove kamite-bin\n```\n\n#### Generic\n\nDownload the latest release package from the [Releases] page and extract it\nto the location where you want to keep the program files. You can now launch\nKamite with the `bin/kamite` executable inside the extracted directory.\n\nAn optional `install.sh` script is provided in the release package that can\ncreate a link to `bin/kamite` in the `/usr/bin/` directory, as well as install a\nDesktop entry and program icons for application launchers. The files created by\nthe installation script can be removed by running:\n\n```sh\ninstall.sh --uninstall\n```\n\n### Windows\n\nDownload the latest release package from the [Releases] page and extract it\nto the location where you want to keep the program files. You can now launch\nKamite using `Kamite.exe` inside the extracted directory.\n\n[Releases]: https://github.com/fauu/Kamite/releases\n\n## Updating Kamite\n\n**When updating, please check [the Changelog](CHANGELOG.md) for breaking chages\nin the newer versions.**\n\n### Linux Generic and Windows\n\nTo update, remove the old `kamite` directory and extract the new release package\nin its place.\n\n## Launching Kamite\n\nKamite can be launched:\n\n* \u003cins\u003eLinux\u003c/ins\u003e: either direclty using the `bin/kamite` executable in the\n  program directory or through a desktop launcher (assuming the `.desktop` file\n  was installed);\n\n* \u003cins\u003eWindows\u003c/ins\u003e: using one of: `Kamite.exe`, `Kamite.com` (provides console\n  output), or `Kamite (Debug).bat` (enables Debug mode and provides console\n  output).\n\nBesides the [config file](#config), Kamite supports configuration through\nlaunch options. See [Launch options](#launch-options).\n\nKamite’s main user interface is a webpage served by a local server that should\nbe opened in your web browser. The default address is \u003chttp://localhost:4110\u003e.\n\n**The web client is only guaranteed to work without issues on the most recent\nversions of Firefox and Chrome**.\n\nUpon launch, Kamite will, by default: 1) navigate to the above address in the\ndefault web browser, 2) open an auxiliary “Control” window, which lets you\nmonitor the program’s status as well as exit it. Both those behaviours can be\ndisabled by setting the [config keys](#config) `launchBrowser` and\n`controlWindow`, respectively,  to `no`. Disabling the latter is useful when\nKamite is run from the command line, making the control window redundant.\n\nMultiple config profiles can be prepared for Kamite and chosen between at the\ntime of its launch. See [Config profiles](#config-profiles).\n\n## Troubleshooting\n\nTo better diagnose problems, launch Kamite from a console window with the\n[launch option](#launch-options) `--debug`. (On Windows, this can be done simply\nby double-clicking the provided `Kamite (Debug).bat` script). This will make\nKamite print detailed error messages and add a Debug tab to the client (the bug\nicon) where image snapshots of OCR operations appear for inspection.\n\nIf something does not seem to work properly or is confusing in a way that is not\ndispelled by what is written in this README, do not hesitate to [create a GitHub\nIssue](https://github.com/fauu/Kamite/issues/new).\n\n## User interface overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/docs/ui-overview.png\" title=\"Kamite’s user interface overview\"\u003e\n\u003c/p\u003e\n\nBelow are some non-obvious tips regarding the interface that might come useful.\n\n* Double-clicking on the *current chunk* activates the chunk edit mode. To exit\n  it, either click away or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n* The *notebook* can be temporarily resized by dragging its edge with the mouse\n  (in order for the setting to persist, however, it must be set in the [config\n  file](#config)).\n\n* You can have incoming text chunk inserted into the current chunk instead of\n  entirely replacing it. To do that, enter the chunk edit mode as described\n  above and either: 1) place the caret where you want the incoming chunk to be\n  inserted or 2) select the part of the current chunk that you wish replaced\n  with it.\n\n* The *character counter* and the *session timer* can be frozen/paused and\n  restarted by, respectively, short-clicking and long-clickng on them.\n\n* The *session timer* can be set up to pause automatically after a period of\n  inactivity. For example, add `sessionTimer.autoPause.after: 45s` to auto-pause\n  after 45 seconds of inactivity.\n\n* The *session timer* can be set to be paused initially after launching the\n  program (`sessionTimer.startPaused: yes` to enable).\n\n## Text extraction\n\nThe first task when using Kamite is to get text from the immersion material into\nthe program. In Kamite’s terminology, a single incoming piece of text is called\na **chunk**.\n\nThe method of getting text chunks into Kamite will depend on the kind of the\nsource material:\n\n### Anime/video text extraction\n\nExtracting text chunks from video is by default supported through integration\nwith the **[mpv]** video player. *Primary* video subtitles from mpv are treated\nby Kamite as incoming chunks. If *secondary* subtitles are present, they are\ntreated as **chunk translations**.\n\nTo enable the connection between Kamite and mpv, the latter must be launched\nwith the following exact value for the `input-ipc-server` parameter:\n\n\u003cins\u003eLinux\u003c/ins\u003e:\n\n```sh\nmpv file.mkv --input-ipc-server=/tmp/kamite-mpvsocket\n```\n\n\u003cins\u003eWindows\u003c/ins\u003e (PowerShell):\n\n```powershell\nC:\\Program` Files\\mpv\\mpv file.mkv --input-ipc-server=\\\\.\\pipe\\kamite-mpvsocket\n```\n\n\u003cbr\u003e\n\nAlternatively, the line\n\n```sh\ninput-ipc-server=\u003cabove_path\u003e\n```\n\ncan be put into the [mpv config file][mpv-ref-config].\n\nIn the former case, mpv will only be open for communication with Kamite when\nlaunched with the specified parameter. In the latter—it will be open always.\n\n\u003e For more on the communication mechanism used, see the\n[mpv reference for JSON IPC][mpv-ref-json-ipc].\n\nTo run mpv with an external subtitle file, use the `--sub-file` launch\nparameter (it can be repeated for multiple subtitle files). To assign a given\nsubtitle track as *primary* (assumed by Kamite to be the Japanese subtitles) and\n*secondary* (assumed to be the translations), respectively, use the `--sid` and\n`--secondary-sid` mpv launch parameters. Which subtitle IDs to specify can be\nglanced by pressing \u003ckbd\u003eF9\u003c/kbd\u003e in mpv while the video file is opened and the\nsubtitles loaded.\n\n\u003e [!NOTE]\n\u003e Subtitles hidden within mpv will still be recognized by Kamite.\n\n\u003c!-- --\u003e\n\n\u003e [!WARNING]\n\u003e The subtitle extraction functionality will not work with subtitles that\n\u003e are stored as images, not as text.\n\n\u003c!-- --\u003e\n\n\u003e See also: [mpv reference: Subtitle options][mpv-ref-sub-options].\n\nBelow are excerpts from example scripts used to quickly launch an anime episode\nin mpv in such a way that it is immediately set up to work with Kamite.\n\n\u003cins\u003eLinux\u003c/ins\u003e:\n\n\u003c!-- markdownlint-capture --\u003e\u003c!-- markdownlint-disable --\u003e\n```sh\nmpv \"/path/to/video/\"*\"Some Anime Name\"*\"E$1\"*\".mkv\" \\ # Episode no. passed as an argument to the script\n  --input-ipc-server=/tmp/kamite-mpvsocket \\\n  --sub-file=\"/path/to/external/subtitles/$1.jp.srt\" \\\n  --sid=2 \\ # ID of the Japanese subtitles provided externally\n  --secondary-sid=1 \\ # ID of the English subtitles embedded in the video file (to be used as translations)\n  --secondary-sub-visibility=no \\\n  --save-position-on-quit \\\n  --profile=jpsub # An optional custom profile that can set a special subtitle font and size, etc. It must be defined separately in the mpv config file: see https://mpv.io/manual/stable/#profiles\n```\n\u003c!-- markdownlint-restore --\u003e\n\n\u003cins\u003eWindows\u003c/ins\u003e (PowerShell):\n\n```powershell\n# See the Linux example above for more information\nparam ([String] $ep) # $ep will be replaced with the first parameter to the\n                     # script (here assumed to be the episode number)\nC:\\Program` Files\\mpv\\mpv \"\\path\\to\\video\\*Some Anime Name*E$ep.mkv\" `\n  --input-ipc-server=\\\\.\\pipe\\kamite-mpvsocket `\n  --sub-file=\"\\path\\to\\external\\subtitles\\$ep.jp.srt\" `\n  --sid=2 `\n  --secondary-sid=1 `\n  --secondary-sub-visibility=no `\n  --save-position-on-quit `\n  --profile=jpsub\n```\n\n---\n\n#### Tip: Auto-pausing at the start/end of subtitles\n\nThis can be useful for beginners whose comprehension is not yet at the level\nneeded to follow even simple video content at natural pace. The\n[sub-pause-advanced] mpv script can be used for this purpose. Here are some\nexample learning workflows enabled by that script:\n\n* Pause at the end of each Japanese subtitle in order to read it in Kamite.\n  (Useful when you cannot read proper texts yet and it is advantageous to\n  substitute with short anime dialogues.)\n\n* Do the above, but only when you stumble while reading the subtitle live and\n  you explicitly request pause at the end of the subtitle by pressing a defined\n  request key. (Useful once you progress to the level at which you can often\n  read easier lines live.)\n\n* Pause at the start of each {known language} subtitle and automatically unpause\n  after the time sufficient to read it (calculated by the script based on the\n  subtitle’s length), so that you can then fully concentrate on understandning\n  the Japanese spoken line, with the comprehension “training wheel” in the form\n  of knowing roughly what it’s supposed to say. (Useful for beginner listening\n  practice.)\n\nFor more information, see the script’s README in its GitHub repository linked\nabove.\n\n---\n\nKamite can be useful even when viewing media without Japanese subtitles, for\nexample as an area where heard words and phrases can be typed in and looked up.\n\nWhen viewing media with translated subtitles only, Kamite can be instructed to\ntreat them as translations for unknown chunks and display them as such, by\nenabling “Translation-only mode” in the Settings tab or by launching with the\nconfig key `chunk.translationOnlyMode` set to `yes`.\n\n[mpv-ref-config]: https://mpv.io/manual/stable/#configuration-files\n[mpv-ref-json-ipc]: https://mpv.io/manual/stable/#json-ipc\n[mpv-ref-sub-options]: https://mpv.io/manual/stable/#subtitles\n[sub-pause-advanced]: https://github.com/fauu/mpv-sub-pause-advanced\n\n---\n\n**Related Wiki sections:**\n\n* [Mining anime/video with Anacreon’s mpv script](https://github.com/fauu/Kamite/wiki/Mining-recipes#anacreons-mpv-script)\n* [Alternative software for anime/video](https://github.com/fauu/Kamite/wiki/Alternative-software#animevideo)\n\n### Manga/visual text extraction\n\nKamite integrates with several alternative OCR (Optical Character Recognition)\nsolutions to enable visual extraction of text from manga pages and other\ncontent displayed on screen. The available OCR engines are:\n\n* “Manga OCR” Online (a Hugging Face Space by Detomo)\n\n    \u003chttps://github.com/kha-white/manga-ocr\u003e\\\n    \u003chttps://huggingface.co/spaces/Detomo/Japanese-OCR\u003e\n\n* “Manga OCR” (Local)\n\n    \u003chttps://github.com/kha-white/manga-ocr\u003e\n\n* Hive OCR Online (a Hugging Face Space by seaoctopusredchicken)\n\n    **(horizontal text only)**\n\n    \u003chttps://huggingface.co/spaces/seaoctopusredchicken/Hive-OCR-simple\u003e\\\n    \u003chttps://thehive.ai/demos?case_study=text_recognition\u003e\n\n* EasyOCR Online (a Hugging Face Space by tomofi)\n  \n    **(horizontal text only)**\n\n    \u003chttps://huggingface.co/spaces/tomofi/EasyOCR\u003e\\\n    \u003chttps://github.com/JaidedAI/EasyOCR\u003e\n\n* OCR.space (Online)\n\n    \u003chttps://ocr.space/\u003e\n\n* Tesseract OCR (Local)\n\n    \u003chttps://github.com/tesseract-ocr/tesseract\u003e\n\n**“Manga OCR” in either variant is the recommended choice for manga**.\nThe online version requires practically no special setup, but involves\nscreenshots of portions of your screen being sent to a third party. The local\nversion, on the other hand, requires a somewhat involved setup and extra system\nresources.\n\n**By default, OCR is disabled.** The necessary setup steps are:\n\n1. Set the [config](#config) key `ocr.engine` to one of: `mangaocr_online`,\n   `mangaocr`, `hiveocr_online`, `easyocr_online`, `ocrspace`, or `tesseract`.\n\n1. Set up the selected engine:\n\n    * [Setting up “Manga OCR” Online](#setting-up-manga-ocr-online)\n    * [Setting up “Manga OCR”](#setting-up-manga-ocr-local)\n    * [Setting up Hive OCR Online](#setting-up-hive-ocr-online)\n    * [Setting up EasyOCR Online](#setting-up-easyocr-online)\n    * [Setting up OCR.space](#setting-up-ocrspace)\n    * [Setting up Tesseract OCR](#setting-up-tesseract-ocr)\n\n1. (Linux/Xorg and wlroots platforms only)\n[Set up extra OCR dependencies](#setting-up-extra-ocr-dependencies)\n\n#### Setting up “Manga OCR” Online\n\n\u003e [!WARNING]\n\u003e The “Manga OCR” Online engine depends on a third-party online service\n\u003e ([a Hugging Face Space by Detomo][manga-ocr-hf])—using it involves sending\n\u003e screenshots of portions of your screen to third parties. (See\n\u003e [Privacy](#privacy))\n\nThe “Manga OCR” Online does not require any extra setup.\n\nRemember to [set up extra OCR dependencies](#setting-up-extra-ocr-dependencies)\nif necessary, and to launch Kamite with the config key `ocr.engine` set to\n`mangaocr_online`.\n\n#### Setting up “Manga OCR” (Local)\n\n\u003e [!NOTE]\n\u003e “Manga OCR” will use up to 2.5 GB of disk space. During launch, it will use up\n\u003e to 1 GB of additional RAM.\n\n##### Recommended option: installation using pipx\n\n1. Install [Python][installing-python] and [pip] (the Windows Python installer\n   already includes pip)\n\n1. Install [pipx]\n\n    \u003cins\u003eWindows\u003c/ins\u003e:\n\n    ```powershell\n    C:\\Users\\\u003cuser\u003e\\AppData\\Local\\Programs\\Python\\Python310\\python.exe -m pip\n    install --user pipx\n    ```\n\n    The `python.exe` location will vary depending on the installer and the\n    installation options.\n\n1. Install [manga-ocr]\n\n    \u003cins\u003eLinux\u003c/ins\u003e:\n\n    ```sh\n    pipx install manga-ocr\n    ```\n\n    \u003cins\u003eWindows\u003c/ins\u003e:\n\n    ```powershell\n    C:\\Users\\\u003cuser\u003e\\AppData\\Local\\Programs\\Python\\Python310\\python.exe -m pipx\n    install manga-ocr\n    ```\n\nKamite will now be able to use “Manga OCR”. On the first launch of Kamite with\n`ocr.engine` set to `mangaocr`, “Manga OCR” will take some time to download its\nmodel (around 450 MB). If there are issues, try running the (\u003cins\u003eLinux\u003c/ins\u003e)\n`manga_ocr`, (\u003cins\u003eWindows\u003c/ins\u003e)\n`C:\\Users\\\u003cuser\u003e\\.local\\pipx\\venvs\\manga-ocr\\Scripts\\manga_ocr.exe` executable\ninstalled by pipx and examining its output.\n\n###### Deinstallation\n\n1. Run `pipx uninstall`\n\n    \u003cins\u003eLinux\u003c/ins\u003e:\n\n    ```sh\n    pipx uninstall manga-ocr\n    ```\n\n    \u003cins\u003eWindows\u003c/ins\u003e:\n\n    ```powershell\n    C:\\Users\\\u003cuser\u003e\\AppData\\Local\\Programs\\Python\\Python310\\python.exe -m pipx\n    uninstall manga-ocr\n    ```\n\n1. Delete leftover Hugging Face Hub files:\n\n(\u003cins\u003eLinux\u003c/ins\u003e) `~/.cache/huggingface/hub/models--kha-white--manga-ocr-base`\nor a ~450 MB file in `~/.cache/huggingface/transformers/`.\n\n(\u003cins\u003eWindows\u003c/ins\u003e)\n`C:\\Users\\\u003cuser\u003e\\.cache\\huggingface\\hub\\models--kha-white--manga-ocr-base` or a\n~450 MB file in `C:\\Users\\\u003cuser\u003e\\.cache\\huggingface\\transformers`.\n\n###### Troubleshooting “pipx \"Manga OCR\" installation absent…”\n\nIf pipx did not install to the default path expected by Kamite, you will have to\nspecify the path manually in the [config file](#config):\n\n```sh\nocr: {\n  mangaocr: {\n    # Linux default\n    pythonPath: \"/home/\u003cuser\u003e/.local/pipx/venvs/manga-ocr/bin/python\"\n    # Windows default\n    pythonPath: \"\"\"C:\\Users\\\u003cuser\u003e\\.local\\pipx\\venvs\\manga-ocr\\Scripts\\python.exe\"\"\"\n  }\n}\n```\n\n**The above paths are the defaults, which you will need to modify** according to\nthe output you get from running\n\n\u003cins\u003eLinux\u003c/ins\u003e:\n\n```sh\npipx list\n```\n\n\u003cins\u003eWindows\u003c/ins\u003e:\n\n```powershell\nC:\\Users\\\u003cuser\u003e\\AppData\\Local\\Programs\\Python\\Python310\\python.exe -m pipx\nlist\n```\n\n[installing-python]: https://realpython.com/installing-python/\n[pip]: https://pip.pypa.io/en/stable/installation/\n[pipx]: https://pypa.github.io/pipx/\n\n##### Custom installation\n\nIf you install “Manga OCR” not through pipx, you will need to manually specify a\npath to a Python main executable (or a wrapper for it) that runs within an\nenvironment where the `manga_ocr` module is available. For example, if installed\nglobally and the system Python executable is on `PATH` under the name `python`,\nthen the appropriate configuration will be simply:\n\n```sh\nocr: {\n  mangaocr: {\n    pythonPath: python\n  }\n}\n```\n\n\u003e [!NOTE]\n\u003e After deinstallation, there will be a ~450 MB leftover model file in\n\u003e (\u003cins\u003eLinux\u003c/ins\u003e) `~/.cache/huggingface/transformers/`, (\u003cins\u003eWindows\u003c/ins\u003e)\n\u003e `C:\\Users\\\u003cuser\u003e\\.cache\\huggingface\\transformers`.\n\n#### Setting up Hive OCR Online\n\n\u003e [!WARNING]\n\u003e The Hive OCR Online engine depends on a third-party online service ([a Hugging\n\u003e Face Space by seaoctopusredchicken][hiveocr-hf])—using it involves sending\n\u003e screenshots of portions of your screen to third parties. (See\n\u003e [Privacy](#privacy))\n\nThe Hive OCR Online engine does not require any extra setup.\n\nRemember to [set up extra OCR dependencies](#setting-up-extra-ocr-dependencies)\nif necessary, and to launch Kamite with the config key `ocr.engine` set to `hiveocr_online`.\n\n#### Setting up EasyOCR Online\n\n\u003e [!WARNING]\n\u003e The EasyOCR Online engine depends on a third-party online service ([a Hugging\n\u003e Face Space by tomofi][easyocr-hf])—using it involves sending screenshots\n\u003e of portions of your screen to third parties. (See [Privacy](#privacy))\n\nThe EasyOCR Online engine does not require any extra setup.\n\nRemember to [set up extra OCR dependencies](#setting-up-extra-ocr-dependencies)\nif necessary, and to launch Kamite with the config key `ocr.engine` set to\n`easyocr_online`.\n\n#### Setting up OCR.space\n\n\u003e [!WARNING]\n\u003e OCR.space is an online service—using it involves sending screenshots of\n\u003e portions of your screen to a third party. (See [Privacy](#privacy))\n\nThe usage of the [OCR.space] free API is limited. The limits are defined by the\nprovider as “Requests/month: 25000, Rate Limit: 500 calls/DAY”.\n\n1. Register for a free API key\n\n    Fill the form at \u003chttps://ocr.space/ocrapi/freekey\u003e. You will need to\n    provide your email address, to which the key will be sent.\n\n1. Put the API key in Kamite’s [config file](#config):\n\n    \u003e [!WARNING]\n    \u003e This is unsafe plain-text storage. Do not do this if you deem your key too\n    \u003e sensitive for this kind of storage.\n\n    ```sh\n    secrets: {\n      ocrspace: \"THE KEY GOES HERE\"\n    }\n    ```\n\n1. (Optional—for games) Change the subengine from the default (“1”)\n\n    The OCR.space service itself provides multiple OCR engines. Japanese is\n    supported by engines “1” and “3”. Kamite uses engine “1” by default. If you\n    wish to use engine “3”, specify the following configuration:\n\n    ```sh\n    ocr: {\n      ocrspace: {\n        engine: 3\n      }\n    }\n    ```\n\n    Engine “3” is useless for manga and slower than engine “1”, but it may be\n    more accurate for, e.g., particular games.\n\nRemember to [set up extra OCR dependencies](#setting-up-extra-ocr-dependencies)\nif necessary, and to launch Kamite with the config key `ocr.engine` set to\n`ocrspace`.\n\n[ocrspace-privacy-policy]: https://ocr.space/privacypolicy\n\n#### Setting up Tesseract OCR\n\n1. Install Tesseract\n\n    \u003cins\u003eLinux\u003c/ins\u003e: Tesseract is available in the default repositories of most\n    distributions. For example, under `tesseract-ocr` on Ubuntu or under\n    `tesseract` on Arch Linux.\n\n    \u003cins\u003eWindows\u003c/ins\u003e: It is recommended to use [the installer provided by\n    UB Mannheim][tesseract-ub-mannheim].\n\n1. Install Tesseract models selected for use with Kamite\n\n    Download\n    [`tesseract_traineddata_jpn_Kamite.zip`](https://mega.nz/file/1TMXxApD#zHdgnXmbuMc5TRTcBlT7a5_8t2E1ziSxnhf9c2PbtP4)\n    and extract the `.traineddata` files from the archive *directly* into\n    Tesseract’s `tessdata` directory:\n\n    * \u003cins\u003eLinux\u003c/ins\u003e: usually `/usr/[local/]share/tessdata` or\n    `/usr/share/tesseract-ocr/\u003cVERSION\u003e/tessdata`;\n\n    * \u003cins\u003eWindows\u003c/ins\u003e: the default for the UB Mannheim installer is\n      `C:\\Program Files\\Tesseract-OCR\\tessdata`.\n\n1. If Tesseract is not available on `PATH` under the executable name\n   `tesseract` (which it will not on Windows), set the [config](#config) key\n   `ocr.tesseract.path` to its executable’s path:\n\n   \u003cins\u003eWindows\u003c/ins\u003e (UB Mannheim installer default):\n\n   ```sh\n   ocr: {\n     tesseract: {\n       path: \"\"\"C:\\Program Files\\Tesseract-OCR\\tesseract.exe\"\"\" # Note the triple quotes\n     }\n   }\n   ```\n\nOnce the setup has been completed, you can launch Kamite with the config key\n`ocr.engine` set to `tesseract`.\n\n[tesseract-ub-mannheim]: https://github.com/UB-Mannheim/tesseract/wiki\n\n#### Setting up extra OCR dependencies\n\nOn some platforms, external programs are needed for text recognition related\ntasks. You need to install them on your own.\n\n##### Linux/Xorg extra OCR dependencies\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ca href=\"https://github.com/naelstrof/slop\"\u003eslop\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eUsed for selecting a screen region or point.\u003c/dd\u003e\n\u003c/dl\u003e\n\n##### Linux/wlroots extra OCR dependencies\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ca href=\"https://github.com/emersion/slurp\"\u003eslurp\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eUsed for selecting a screen region or point.\u003c/dd\u003e\n  \u003cdt\u003e\u003ca href=\"https://sr.ht/~emersion/grim/\"\u003egrim\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eUsed for taking screenshots for OCR.\u003c/dd\u003e\n  \u003cdt\u003e\u003ca href=\"https://git.sr.ht/%7Ebrocellous/wlrctl\"\u003ewlrctl\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003e(Optional) Necessary to trigger a mouse click for OCR Auto Block Instant\n  mode.\u003c/dd\u003e\n\u003c/dl\u003e\n\n#### OCR usage\n\nText recognition can be initiated by:\n\n* Issuing an OCR command through:\n  * clicking the corresponding button in the command\n    palette,\n  * pressing the configured [keyboard shortcut](#keyboard-shortcuts), or\n  * [sending the command through the API](#command-api).\n* Adding or modifying an image in a directory provided to the [OCR directory\n  watcher](#ocr-directory-watcher).\n\n\u003e [!WARNING]\n\u003e **On Linux / GNOME Wayland and Plasma Wayland**, only the following of\n\u003e the above are available:\n\u003e\n\u003e * the [`ocr_image` command](#ocr_-commands) (including external software that\n\u003e   uses it, for example [Gomics-v]),\n\u003e * the [OCR directory watcher](#ocr-directory-watcher).\n\nThe OCR commands directly available to the user are the following:\n\n##### Manual block OCR\n\n\u003c!-- markdownlint-capture --\u003e\u003c!-- markdownlint-disable --\u003e\n![OCR manual block button](media/docs/ocr_manual-block.png) ![OCR manual block vertical button](media/docs/ocr_manual-block-vertical.png) ![OCR manual block horizontal button](media/docs/ocr_manual-block-horizontal.png)\n\u003c!-- markdownlint-restore --\u003e\n\nSelect an area around a block of text and Kamite will OCR the area as is.\n\nFor the `tesseract` engine, this command has separate vertical and horizontal\nvariants that must be chosen manually depending on the orientation of the text\nblock.\n\n##### Auto block OCR\n\n![OCR auto block button](media/docs/ocr_auto-block.png)\n\nSelect a point within a block of text; Kamite will try to infer the extent of\nthe block and then OCR the resulting area.\n\n*This should be good enough for \u003e 90% of typical manga text blocks, but the\nblock detection algorithm has a lot of room for improvement.*\n\n\u003e [!NOTE]\n\u003e (Linux/Xorg) On Xorg, the point selection mechanism cannot be restricted to\n\u003e just a point, meaning that when the mouse is pressed and dragged, a rectangle\n\u003e area will be selected instead of a point. If this happens, Kamite will\n\u003e consider the center of this area as the selected point.\n\n##### Manual rotated block OCR\n\n![OCR manual block rotated button](media/docs/ocr_manual-block-rotated.png)\n\nDelimit a rotated block of text; Kamite will derotate the resulting area\nselection and OCR it.\n\nThe delimitation of a rotated block is made with three mouse clicks in\ndetermined spots, as shown in the following illustrations:\n\n![OCR rotated block reference](media/docs/rotated-ocr-reference.png)\n\nClicks 1 and 2 must be made at the start and end of the initial edge of the text\nrespectively. Click 3 can be anywhere along the closing edge (pictured as green\nabove).\n\n\u003e [!NOTE]\n\u003e The current implementation of rotated block OCR guesses the text orientation\n\u003e based on the rotation angle. This means the feature will fail in unusual cases,\n\u003e such as a block of horizontal text positioned vertically. The current\n\u003e assumption is that those cases are very rare, but if you find use-cases where\n\u003e they are not, please [create a GitHub Issue](https://github.com/fauu/Kamite/issues/new)\n\u003e so that the assumption can be updated and the implementation reconsidered.\n\n##### Region OCR\n\n![OCR region button](media/docs/ocr_region.png)\n\nDefine a screen area in the config file and Kamite will OCR it as is [using the\nconfigured OCR engine](#mangavisual-text-extraction).\n\nThis is intended as an alternative for games that do not work with\n[Textractor](#textractor-integration) or [Agent](#agent-integration).\n\nHere it is recommended to try OCR engines in the following order: Hive OCR,\nEasyOCR, OCR.space, and “Manga OCR” (in terms of the likelihood that they are\ngoing to be up to the task). (For OCR.space, be sure to try\n[OCR.space engine “3”](#setting-up-ocrspace) specifically).\n\nBelow is an illustration of setting up a region in the [config file](#config).\n\n```sh\nocr: {\n  regions: [\n    ${REGIONS.exampleGameTextbox}\n    ${REGIONS.someOtherRegionOmittedBelow}\n  ]\n}\n\nREGIONS: [\n  exampleGameTextbox: {\n    # (1 character) This symbol will appear on the region’s button\n    symbol: E\n\n    # This description will appear in the region’s button tooltip\n    description: \"OCR Example Game's textbox\"\n\n    # The screen coordinates of the region’s top-left corner\n    x: 350\n    y: 800\n\n    # The screen dimensions of the region\n    width: 1000\n    height: 150\n\n    # Try to automatically narrow the region’s screenshot to just text before\n    # OCR-ing it.\n    # NOTE: The implementation of this function is currently very basic. It\n    #       might not prove helpful in most use-cases\n    autoNarrow: no\n  }\n]\n\nkeybindings: {\n  global: {\n    ocr: {\n      region: [\n        # Global keybinding for the above-defined region\n        { symbol: E, key: meta shift E }\n      ]\n    }\n  }\n}\n```\n\n###### Obtaining region parameters\n\nTo obtain the desired region coordinates and dimensions, use Kamite’s Region\nHelper mode: Launch Kamite from console with the launch option `--regionHelper`,\nselect the desired areas, and copy the resulting region specifications from the\nconsole output.\n\n\u003e [!NOTE]\n\u003e (Windows) To get console output on Windows, you must launch Kamite using the\n\u003e `Kamite.com` executable, not `Kamite.exe`.\n\n###### Region OCR quality\n\nSome of the engines that can potentially handle this specific task work much more\nreliably when the screenshot they are provided with is narrowed to just the text.\nAnd since the current auto-narrowing algorithm is poor, for now it might be\nbest—when necessary—to create separate regions for each possible line count of\nthe target text box (i.e., first region encompassing just one line of text,\nsecond region encompassing the first and the second line, and so on) and choose\nbetween them on the fly.\n\nSee also: [Config](#config), [Visual novel / game text extraction](#visual-novel--game-text-extraction),\n[Alternative software for visual novels / games](https://github.com/fauu/Kamite/wiki/Alternative-software#visual-novels--games).\n\n---\n\n##### Using alternative OCR variants (Tesseract OCR only)\n\nWhen using the Tesseract OCR engine, Kamite executes Tesseract multiple times\nfor each OCR request on modified versions of the input image. This is in order\nto somewhat compensate for the inferior results Tesseract gives.\n\nWhen all the resulting text variants are identical, they are simply merged and\npresented as one. When there are differing alternative variants, however, the\none determined the most likely to be the most accurate is displayed normally as\nthe *current chunk*, whereas the remaining variants appear under a new *OCR\nVariants* tab placed at the left edge of the notebook’s tab bar.\n\nThrough the OCR Variants view, you can replace the current chunk with one of the\nother variants by clicking the Pick button next to the corresponding variant.\nYou can also make text selections within both the current chunk and the\nvariants, which, upon clicking the Pick button, will lead to a partial text\nreplacement.\n\nThe OCR Variants view highlights characters that are unique to its variant to\nmake it easier to identify potential replacements for a misrecognized character\nin the current chunk.\n\n#### OCR directory watcher\n\nKamite can watch a specified directory for new/modified images and perform text\nrecognition on them automatically. This is especially useful for platforms that\ndo not support global OCR commands (Linux / GNOME Wayland and Plasma Wayland).\n\nTo enable the directory watcher, specify the directory path in the [config\nfile](#config):\n\n```sh\nocr: {\n  watchDir: \"/full/path/to/the/directory\" # Linux variant\n  watchDir: \"\"\"C:\\path\\to\\the\\directory\"\"\" # Windows variant\n}\n```\n\nThis can be used in conjunction with a platform-specific screenshot tool, for\nexample [GNOME Screenshot] on GNOME Wayland and [Spectacle] on Plasma Wayland.\n\nNote that Kamite treats the entire input image as a single text block.\nConsequently, the provided images should be area screenshots containing just the\ntext block to be recognized—not the entire screen or application window.\n\n[GNOME Screenshot]: https://en.wikipedia.org/wiki/GNOME_Screenshot\n[Spectacle]: https://apps.kde.org/spectacle/\n\n#### Web browser userscript for convenient OCR\n\n*Kamite One-Click OCR* is a simple browser userscript that enables convenient\nshortcuts for issuing OCR commands to Kamite (useful when reading manga directly\nin the browser):\n\n* *Middle-click* on a text block to automatically recognize it.\n\n* *Middle-hold-click* anywhere within the webpage to initiate a manual block\n  recognition selection.\n\nTo install the script, first install a userscript browser extension such as\n[Violentmonkey] or [Tampermonkey], and then follow this link: [Kamite One-Click OCR.user.js][oneclick-ocr-userscript].\n\nThen **you need to specify on which websites the script will be active**:\n\n1. Open your userscript browser extension.\n\n1. Click on the cog icon (“Open dashboard”).\n\n1. Find *Kamite One-Click OCR* and edit it:\n\n    Tampermonkey: Click on the script name.\\\n    Violentmonkey: Click the `\u003c/\u003e` (“Edit”) icon below the script name.\n\n1. Switch to the `Settings` tab.\n\n1. Add user match rules for desired websites.\n\n    Example configuration enabling the script on two specific websites:\n\n    Enter under `User matches` (Tampermonkey) or `@match rules` (Violentmonkey):\n\n    ```txt\n    https://twitter.com/*\n    https://metaurl.app/*\n    ```\n\nOn first use, you might be prompted to confirm that you allow the script to make\nweb requests to Kamite’s backend server.\n\nYou can switch to using the right mouse button instead of the middle by going to\nthe `Code` tab and changing `const MOUSE_BUTTON = 1` to say `= 2`. Note that\nthis will disable the browser context menu that normally opens on right-click.\n\n[oneclick-ocr-userscript]: https://github.com/fauu/Kamite/raw/master/extra/userscripts/Kamite%20One-Click%20OCR.user.js\n\n#### Linux manga viewer with Kamite integration\n\n[Gomics-v] is a manga viewer for Linux that includes simple Kamite integration:\n\n* *Right-click* on a text block to automatically recognize it.\n\n* *Right-hold-click* anywhere in the area where images are displayed to\n  initiate a manual block recognition selection.\n\nThe integration must be enabled in Gomics-v under `Preferences › Kamite`.\n\n---\n\n**Related Wiki sections:**\n\n* [Anki mining screenshot script (Linux/wlroots and Xorg)](https://github.com/fauu/Kamite/wiki/Mining-recipes#screenshot-script-linuxwlroots-and-xorg)\n* [Quickly trigger OCR with mouse hot corners (Linux/wlroots)](https://github.com/fauu/Kamite/wiki/OCR-recipes#quickly-trigger-ocr-with-mouse-hot-corners-linuxwlroots)\n* [Alternative software for manga](https://github.com/fauu/Kamite/wiki/Alternative-software#manga)\n\n### Visual novel / game text extraction\n\nKamite can receive text extracted from other programs through **[Textractor]**\nand **[Agent]** text extractor programs:\n\n* [Textractor integration](#textractor-integration)\n* [Agent integration](#agent-integration)\n\nThere is also a RPG Maker MV/MZ plugin that can directly extract text from games\nusing those engines: see\n[`contrib/KamiteSendRPGMaker.js`](https://github.com/fauu/Kamite/raw/master/contrib/KamiteSendRPGMaker.js)\n(usage instructions are in the plugin file).\n\nOther integrations can be created using the [Command API](#command-api).\n\n\u003e [!TIP]\n\u003e For games that cannot be integrated using the above means, the\n\u003e [Region OCR](#region-ocr) feature might prove an alternative.\n\n#### Textractor integration\n\nAn extension for [Textractor] is available that sends lines of text\nextracted by it from other programs to Kamite.\n\nTo install the *Kamite Send* Textractor extension:\n\n1. Copy `Kamite Send.xdll` from either the `extra/textractor/x86` (32-bit\n   Textractor) or `extra/textractor/x64` (64-bit Textractor) within the release\n   package to the main Textractor directory (the one containing\n   `Textractor.exe`).\n\n   \u003e [!NOTE]\n   \u003e If you installed Kamite from AUR, the files will be in `/opt/kamite`.\n\n2. In Textractor, press the `Extensions` button, right-click in the extension\n   list, choose `Add extension` and select the `Kamite Send.xdll` file copied\n   earlier.\n\nFor Textractor’s text processing extensions (such as Remove Repeated Characters)\nto be executed before sending the text to Kamite, position Kamite Send *below*\nthem on the extensions list.\n\n\u003e Want to prevent Textractor from inserting unnecessary hooks? Check out\n\u003e [Textractor-HookAllowlist](https://github.com/fauu/Textractor-HookAllowlist/).\n\n##### Changing the default Textractor extension endpoint\n\nBy default, the extension expects Kamite to listen for commands at the address\n`localhost:4110`. If it is running on a different address (e.g., because you\nhave Textractor in a virtual machine and Kamite on the host), the extension\nneeds to be configured correspondingly. To do so, create a `Kamite Send.txt`\nfile next to `Kamite Send.xdll` in the Textractor directory, containing Kamite’s\nnetwork address from the perspective of the machine running Textractor, e.g.:\n\n```txt\nhost=192.0.0.10:4110\n```\n\n#### Agent integration\n\nTo receive text (and, optionally, machine translations) from the [Agent] text\nextractor:\n\n1. Add `integrations.agent.enable: yes` to [config](#config).\n\n2. In Agent, go to `Translate` tab and enable the option `WebSocketServer` (you\n   can then browse to \u003chttp://127.0.0.1:9001/\u003e to confirm that it is enabled).\n\nWith this setup, Kamite should receive text from Agent.\n\n\u003e [!TIP]\n\u003e (Linux) To hook Wine games, you can run the Windows version of Agent through\n\u003e Wine (you might need an older version of Wine, such as 6.14).\n\n---\n\n**Related Wiki sections:**\n\n* [Anki mining screenshot script (Linux/wlroots and Xorg)](https://github.com/fauu/Kamite/wiki/Mining-recipes#screenshot-script-linuxwlroots-and-xorg)\n* [Alternative software for visual novels / games](https://github.com/fauu/Kamite/wiki/Alternative-software#visual-novels--games)\n\n### Clipboard\n\nText can be pasted from clipboard by pressing \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eV\u003c/kbd\u003e in\nKamite’s browser tab.\n\nThe Kamite browser client can automatically pick up clipboard text with a\nclipboard inserter browser extension ([Firefox][clipboard-inserter-ff],\n[Chrome][clipboard-inserter-chrome]) (assumes default extension settings).\n\n#### Watcher script\n\nClipboard can also be watched automatically without the Clipboard Inserter\nextension, but with a clipboard watcher script that sends changed clipboard\ncontent to Kamite:\n\n* \u003cins\u003eLinux\u003c/ins\u003e (except GNOME Wayland):\n[`contrib/kamite-watch-clipboard.sh`](contrib/kamite-watch-clipboard.sh).\n\n* \u003cins\u003eWindows\u003c/ins\u003e:\n[`contrib/Kamite-Watch-Clipboard.ps1`](contrib/Kamite-Watch-Clipboard.ps1) (run\nwith `Right click › Run with PowerShell`).\n\n[clipboard-inserter-ff]: https://addons.mozilla.org/en-US/firefox/addon/lap-clipboard-inserter\n[clipboard-inserter-chrome]: https://chrome.google.com/webstore/detail/clipboard-inserter/deahejllghicakhplliloeheabddjajm\n\n### Custom source / alternative method text extraction\n\nCustom sources and alternative text extraction methods can be integrated using\nthe [Command API](#command-api).\n\n### Filtering and transforming incoming text\n\nKamite has the ability to discard incoming chunks that match a user-provided\npattern and to perform text replacements on incoming chunks according to\nuser-provided rules.\n\nBoth features are based on *regular expressions*, which can be learned using the\nfollowing resources:\n\n* [RegexOne] — interactive regular expression tutorial.\n* [regex101] — regular expression tester and explainer.\n\n\u003e [!NOTE]\n\u003e The particular regular expression engine used by Kamite is Java’s, which\n\u003e has some particularities. Therefore, [Java’s own regular expression reference][java-regex]\n\u003e might also come useful (note that [regex101] can be instructed to use the Java\n\u003e flavour of regex through the menu on the left side of the page).\n\n[RegexOne]: https://regexone.com/\n[regex101]: https://regex101.com/\n[java-regex]: https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/regex/Pattern.html#sum\n\n#### Filtering chunks\n\nTo enable the chunk filter, specify chunk reject patterns in the [config](#config)\n(`chunk.filter.rejectPatterns`). The patterns are regular expressions against\nwhich incoming chunks will be tested. If any part of the chunk matches against\nany of the patterns, the entire chunk will be discarded. For exmple, the\nfollowing configuration:\n\n```sh\nchunk: {\n  filter.rejectPatterns: [\n    \"^Textractor\"\n    \"(?s).{91}\"\n  ]\n}\n```\n\nwill discard both chunks beginning with the string of characters `Textractor`\nand chunks that are above 90 characters in length. *The first of those filters is\nalready included in the [default config] that is created automatically when no\nconfig file exists.*\n\n\u003e [!WARNING]\n\u003e Regular expressions containing the backslash (`\\`) character must (generally)\n\u003e be specified within triple instead of single quotes (that is, `\"\"\"` instead of\n\u003e `\"`). See the section Transforming chunks (following) for an example.\n\n\u003c!-- --\u003e\n\n\u003e [!NOTE]\n\u003e **Kamite will automatically reload the patterns once a config file is\n\u003e modified.** There is no need to restart the program. The simplest way to test\n\u003e the filter is by pasting (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eV\u003c/kbd\u003e) prepared chunks into\n\u003e the client’s browser tab and observing whether they are allowed through.\n\n[default config]: https://github.com/fauu/Kamite/blob/master/config/config.default.hocon\n\n#### Transforming chunks\n\nTo enable the chunk transformer, specify chunk transform rules in the\n[config](#config) (`chunk.transforms`). The rules are objects consisting of: 1)\na regular expression defining the replacement target, 2) a string specifying\nthe replacement text. For example, the following configuration:\n\n```sh\nchunk: {\n  transforms: [\n    { replace:  \"\"\"\\R\"\"\", with: \"\" }\n    { replace: \".+?「(.+?)」$\", with: \"$1\" }\n  ]\n}\n```\n\nwill remove (replace with an empty string) any line break characters as well as\nremove the names of speakers and quotation marks from dialogue lines formatted\nas `\u003cname\u003e「\u003cdialogue\u003e」` (this will be replaced with just `\u003cdialogue\u003e`. The\n`$1` in the `with` field is a special reference that will be replaced with the\ntext captured in the first and only [match group][regex-match-groups] defined\nwithin the `replace` field). The rules will be applied in the specified order.\n\n\u003e [!WARNING]\n\u003e Regular expressions containing the backslash (`\\`) character must (generally)\n\u003e be specified within triple instead of single quotes (that is, `\"\"\"` instead of\n\u003e `\"`). See the first transform in the example above for illustration.\n\n\u003c!-- --\u003e\n\n\u003e [!NOTE]\n\u003e **Kamite will automatically reload the transform definitions once a config\n\u003e file is modified.** There is no need to restart the program. The simplest way\n\u003e to test the transforms is by pasting (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eV\u003c/kbd\u003e) prepared\n\u003e chunks into the client’s browser tab and observing whether they come out\n\u003e modified as expected.\n\n[regex-match-groups]: https://regexone.com/lesson/capturing_groups\n\n## Text use\n\nWhat can be done with the text once it has been collected into the program?\n\n### Editing and transforming the text\n\nDepending on the source and the extraction method, the text coming into the\nprogram might contain mistakes or other features that need to be changed for it\nto be usable further. Kamite offers various text editing and transformation\nfeatures that might be useful for that task.\n\nThe main chunk text can be selected character by character using the mouse and\ntransformed using actions that appear in the *action palette* near it, which are\nmade available depending on the existence and the content of the selection.\nCharacters can also be deleted by pressing \u003ckbd\u003eDelete\u003c/kbd\u003e or\n\u003ckbd\u003eBackspace\u003c/kbd\u003e.\n\nTo enter chunk edit mode, which allows for direct insertion of typed text,\ndouble-click the main area or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e\n(+ \u003ckbd\u003eShift\u003c/kbd\u003e to clear). To exit it, click away from the input field or\npress \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n### Pop-up dictionary\n\nThe basic task around which Kamite is designed is using a third-party pop-up\ndictionary browser extension to learn through deciphering text you understand\nonly partially. The examples of such extensions are [Yomichan], [rikaikun], and\n[10ten Japanese Reader][10ten].\n\nFor Yomichan, [its website][Yomichan] contains a basic installation and usage\nguide. Additional dictionaries and setup tips for can be found in other places,\nsuch as [Animecards: Setting up Yomichan][animecards-yomichan],\n[TheMoeWay: Yomichan Setup Tutorial][themoeway-yomichan], or [Anacreon DJT:\nYomichan Frequency Dictionaries][anacreon-yomichan-freq].\n\n[animecards-yomichan]: https://animecards.site/yomichansetup/\n[themoeway-yomichan]: https://learnjapanese.moe/yomichan/\n[anacreon-yomichan-freq]: https://anacreondjt.gitlab.io/docs/freq/\n\n### Lookups\n\nYou can use the text chunks within Kamite as inputs for lookups on external\nwebsites. The text that will be used as the lookup input normally corresponds to\nthe selection in the *chunk history* window, which, absent user intervention, is\nthe entire current chunk. If instead there is an active text selection within\nthe current chunk, it is only the selection that will be used for lookups.\n\nBy default, Kamite embeds the following sites for quick lookups:\n\u003chttps://www.deepl.com/\u003e, \u003chttps://ichi.moe/\u003e, \u003chttps://jpdb.io/\u003e. It also by\ndefault provides a button for Google Images lookup in a new browser tab.\n\n\u003e [!TIP]\n\u003e A faster and more robust alternative to using DeepL as a Kamite lookup is to\n\u003e use a scripting-friendly DeepL API client in combination with Kamite’s custom\n\u003e command mechanism.\\\n\u003e The Wiki contains [a Linux recipe][wiki-deeplx-linux] for how to use the\n\u003e [DeepLX][deeplx] program to get DeepL translations into Kamite’s chunk\n\u003e translation component on button click.\n\nOptional userscripts are provided for the embedded sites that modify their look\nwhen embedded into Kamite to improve their user experience. To install or update\nthe scripts, first install a userscript browser extension such as [Violentmonkey]\nor [Tampermonkey], and then open the links below and follow the prompt.\n\n* [Kamite DeepL mod](https://github.com/fauu/Kamite/raw/master/extra/userscripts/Kamite%20DeepL%20mod.user.js)\n\n* [Kamite ichi.moe mod](https://github.com/fauu/Kamite/raw/master/extra/userscripts/Kamite%20ichi.moe%20mod.user.js)\n\n* [Kamite jpdb mod](https://github.com/fauu/Kamite/raw/master/extra/userscripts/Kamite%20jpdb%20mod.user.js)\n\n[deeplx]: https://github.com/OwO-Network/DeepLX\n\n[wiki-deeplx-linux]:\nhttps://github.com/fauu/Kamite/wiki/Linux-recipes#translate-text-with-deepl-through-deeplx\n\n**DeepL and jpdb require yet another intervention to work**. A browser extension\nto slightly modify the responses from those sites is required to make them available\nfor embedding.\n\n1. Install the SimpleModifyHeaders browser extension\n([Firefox][modify-headers-ff], [Chrome][modify-headers-chrome])\n\n1. In the extension’s configuration screen, set the field *Url Patterns* to\n   `https://www.deepl.com/*;https://jpdb.io/*`\n\n1. Below that, enter the following parameters (for DeepL):\n\n    | Field              | Value                     |\n    |--------------------|---------------------------|\n    | Action             | `Delete`                  |\n    | Header Field Name  | `content-security-policy` |\n    | Apply on           | `Response`                |\n\n1. Click *New line* and enter the following into the second line of fields (for\n   jpdb):\n\n    | Field              | Value                     |\n    |--------------------|---------------------------|\n    | Action             | `Delete`                  |\n    | Header Field Name  | `X-Frame-Options`         |\n    | Apply on           | `Response`                |\n\n1. **Click *Save***.\n\n1. **Click *START*** in the top-right corner.\n\n   DeepL and jpdb embeds should now work.\n\nAlternatively, you can have DeepL and jpdb lookups open in a new browser tab by\nsimply adding the line `newTab: yes` to the corresponding lookup [config\nentries](#config).\n\n#### Custom lookups\n\nKamite supports adding custom lookups. Below is an illustration of the process\nusing the website [Immersion Kit] as an example lookup target.\n\n1. Add an object describing the target to the `LOOKUP_TARGETS` object in the\nmain config file:\n\n    ```sh\n    LOOKUP_TARGETS: {\n      # This key can be anything\n      immersionKit: {\n        # (1-3 characters) The symbol will appear on the lookup button\n        symbol: IMK\n    \n        # The name will appear in the lookup button’s tooltip\n        name: Immersion Kit\n    \n        # {} is a placeholder that will be replaced with the lookup text\n        url: \"https://www.immersionkit.com/dictionary?keyword={}\"\n    \n        # (Optional) Whether to open the lookup in a new browser tab or embedded\n        newTab: yes\n      }\n    }\n    ```\n\n2. Add the above-created lookup target to the `lookup.targets` list:\n\n    ```sh\n    lookup: {\n      targets: [\n        ${LOOKUP_TARGETS.immersionKit} # Has to match the key defined above\n      ]\n    }\n    ```\n\n[Violentmonkey]: https://violentmonkey.github.io/\n[Tampermonkey]: https://tampermonkey.net\n[modify-headers-ff]: https://addons.mozilla.org/firefox/addon/simple-modify-header/\n[modify-headers-chrome]: https://chrome.google.com/webstore/detail/simple-modify-headers/gjgiipmpldkpbdfjkgofildhapegmmic\n[Immersion Kit]: https://www.immersionkit.com\n\n### Auto-generated furigana\n\nKamite can add auto-generated [furigana] annotations to the current chunk.\nPlease keep in mind that the auto-generated annotations will frequently be\nincorrect. To enable this feature:\n\n1. **Get the necessary library file** (a morphological analyzer with an\n   included dictionary).\n\n   Download [kuromoji-unidic-kanaaccent-e18ff911fd.jar][kuromoji-jar] and put it\n   *directly* in:\n\n    * \u003cins\u003eLinux\u003c/ins\u003e: either `$XDG_DATA_HOME/kamite` or, if that is not set,\n        `$HOME/.local/share/kamite`;\n\n    * \u003cins\u003eWindows\u003c/ins\u003e: same directory as the [config file](#config) (usually\n      `C:\\Users\\\u003cuser\u003e\\AppData\\Roaming\\kamite`).\n\n1. Set `chunk.furigana.enable: yes` in the config file and start Kamite; or, to\n   enable temporarily, start Kamite and switch on the “Enable furigana” setting\n   in the Settings tab.\n\nThere is an option to hide the generated furigana annotations until the base\ntext is hovered with the mouse (`chunk.furigana.conceal: yes`).\n\n[furigana]: https://en.wikipedia.org/wiki/Furigana\n[kuromoji-jar]: https://jitpack.io/com/github/atilika/kuromoji/kuromoji-unidic-kanaaccent/e18ff911fd/kuromoji-unidic-kanaaccent-e18ff911fd.jar\n\n### Saving text to a file for external use\n\nKamite can be instructed to save all chunks that appear in the client into a\ntext file for further use (for example, for purposes of statistical analysis of\nthe texts you read). To enable chunk logging, specify the path (in the\n[config](#config)) of the directory where the text files ought to be saved:\n\n```sh\nchunk: {\n  log.dir: \"/path/to/the/directory\" # Linux variant\n  log.dir: \"\"\"C:\\path\\to\\the\\directory\"\"\" # Windows variant\n}\n```\n\nKamite will then create a dated log text file in that directory for each session\n(that is, one each time the program is started), to which chunks appearing in\nthe client will be appended live, one chunk per line (note: to that end, line\nbreaks within chunks will be replaced with their literal representation, `\\n`,\nso that actual line break characters demarcate chunks).\n\nTo disable logging, either remove the `log.dir` definition before starting\nKamite or simply comment it out by putting the `#` character in front of it.\n\n### Custom text use\n\nText from Kamite can be forwarded to external programs using Custom commands\n(see below). Example uses:\n\n* [Read text from Kamite aloud using Microsoft’s TTS (Linux recipe)][wiki-linux-edge-tts]\n\n## Custom commands (Launching external executables)\n\nYou can add buttons to the *command palette* that execute specified system\nexecutables. Those executables can optionally receive data from Kamite as\narguments.\n\nBelow is an excerpt from a config file illustrating how to define a custom\ncommand.\n\n```sh\ncommands: {\n  custom: [\n    ${CUSTOM_COMMANDS.exampleCustomCommand}\n    ${CUSTOM_COMMANDS.anotherExampleCustomCommand}\n  ]\n}\n\nCUSTOM_COMMANDS: {\n  exampleCustomCommand: {\n    # (1-3 characters) The symbol that will appear on the command's button\n    symbol: CMD\n\n    # The name that will appear in the command button's tooltip\n    name: Example command\n\n    # (String list) The system command to execute.\n    # The first element in the list is the executable, the rest are the\n    # arguments. The arguments can be specific placeholders to be filled by\n    # Kamite at execution time.\n    command: [\"/path/to/the/executable.sh\", \"some argument\", \"{effectiveText}\"]\n  }\n}\n```\n\n\u003e [!NOTE]\n\u003e (Windows) To execute a PowerShell script, set `command` to, e.g.,\n\u003e `[\"powershell.exe\", \"\"\"C:\\path\\to\\the\\script.ps1\"\"\", \"first argument\"]` (note\n\u003e the triple quotes). The execution of PowerShell scripts is disabled by default\n\u003e in the system. To enable it, start PowerShell with the Run as Administrator\n\u003e option and execute the command `Set-ExecutionPolicy RemoteSigned`. Be aware\n\u003e that this lowers system security.\n\nThe supported placeholder arguments for custom commands are:\n\n`{effectiveText}`\\\nEquivalent to the text used for lookups at the given moment. If there is a\nselection in the current chunk, just the selection will be used. Otherwise,\nthe text selected in the *chunk history* view will be used.\n\n`{originalEffectiveText}`\\\nSame as `{effectiveText}`, except yields the *original text* for chunks that\nhave it. Chunks have original text if their text was modified by Kamite’s\nautomatic correction procedure or user-provided transforms.\n\n## Keyboard shortcuts\n\nKamite is designed under the assumption that the user’s main activity in the\nprogram will be hovering over the current chunk text with the mouse for\ndictionary lookups. Support for keyboard shortcuts is therefore very basic, for\nthe time being.\n\n### Client-only keyboard shortcuts\n\nThe following shortcuts apply only within the Kamite’s browser tab.\n\n\u003ckbd\u003eBackspace\u003c/kbd\u003e, \u003ckbd\u003eDelete\u003c/kbd\u003e\\\nDelete selected text from the current chunk.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e\\\nSelect the entire current chunk text.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e\\\nCopy text depending on what is selected in the current chunk, the current chunk\ntranslation and chunk history.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e\\\nCopy *original* text depending on what is selected in the current chunk or chunk\nhistory. Original text is available in the case when Kamite’s built-in\ncorrections or user-specified transforms have been applied to the text.\nOtherwise, this acts the same as `Ctrl+c`.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eV\u003c/kbd\u003e\\\nPaste text from clipboard.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e\\\nEnter chunk edit mode.\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e\\\nEnter chunk edit mode erasing the current chunk text.\n\n#### Chunk edit mode keyboard shortcuts\n\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eEnter\u003c/kbd\u003e\\\nExit chunk edit mode.\n\n#### Media player keyboard shortcuts (client)\n\nThe following shortcuts work only when a media player is connected.\n\n\u003ckbd\u003eSpace\u003c/kbd\u003e\\\nPause/unpause the playback.\n\n\u003ckbd\u003e◄\u003c/kbd\u003e\\\nSeek -1 seconds.\n\n\u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003e◄\u003c/kbd\u003e\\\nSeek to the start of the current subtitle.\n\n\u003ckbd\u003e►\u003c/kbd\u003e\\\nSeek +1 seconds.\n\n### Global keyboard shortcuts\n\n#### Linux/Xorg and Windows\n\nBelow is an excerpt from a [config file](#config) illustrating how to set up\nglobal keyboard shortcuts and what actions are available for binding.\n\n```sh\nkeybindings: {\n  global: {\n    ocr: {\n      manualBlock: …\n      manualBlockRotated: …\n      autoBlock: … # Instant detection under mouse cursor\n      autoBlockSelect: … # Must click to select a point\n\n      region: [\n        { symbol: …, key: … }\n      ]\n    }\n  }\n}\n```\n\nThe values must be strings in the [Java Swing’s\n`getKeyStroke()`][swing-get-keystroke] format describing the key combinations to\nbe assigned to the corresponding actions. Some examples of such strings are:\n\n* `meta S` (means \u003ckbd\u003eWin\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e),\n* `ctrl shift 1`,\n* `INSERT`.\n\n[swing-get-keystroke]: https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/KeyStroke.html#getKeyStroke(java.lang.String)\n\n#### Linux/wlroots\n\nGlobal shortcuts on the Linux/wlroots platform must be created manually with the\nuse of the [Command API](#command-api). The details of the process will differ\ndepending on the compositor used.\n\nBelow is an example of setting up global keyboard shortcuts in Sway’s config\nfile:\n\n```sh\nbindsym $mod+s exec \"dbus-send --type=method_call --dest=io.github.kamitejp /Receiver io.github.kamitejp.Receiver.command string:'ocr_manual-block'\"\nbindsym $mod+d exec \"dbus-send --type=method_call --dest=io.github.kamitejp /Receiver io.github.kamitejp.Receiver.command string:'ocr_auto-block'\"\n```\n\n## Launch options\n\n\u003e \u003cb\u003e\u003cins\u003eWindows\u003c/ins\u003e\u003c/b\u003e: To launch Kamite with extra options, either: 1)\n\u003e create a shortcut to `Kamite.exe`, open its Properties, and append the options\n\u003e to the Target string after `…\\Kamite.exe` (e.g.,\n\u003e `…\\Kamite.exe[space]--profile=myprofile`) or 2) append them when invoking\n\u003e `Kamite.exe` or `Kamite.com` from a console window.\n\nFirst, there are the basic launch options that are read before the config file:\n\n`--help`\\\nPrints the usage message and exits.\n\n`--version`\\\nPrints the program version and exits.\n\n`--profile=\u003cprofile-id\u003e[,\u003csecond-profile-id\u003e]+`\\\nInstructs Kamite to load the profile config files with the specified IDs. See\n[Config profiles](#config-profiles).\n\n`--debug[=all]`\\\nInstructs Kamite to print debug messages to console as well as to enable\ncertain extra features in the client that are useful for debugging purporses.\\\nSetting the value to `all` will instruct Kamite to additionally display debug\nmessages from the third-party dependencies.\n\n`--regionHelper`\\\nLaunches Kamite in Region Helper mode used to obtain coordinates of screen\nregions. Useful for [Region OCR](#region-ocr).\n\nBeyond that, **all simple config settings can be overridden through\ncorrespondingly-named launch options**. For example, launching Kamite with the\noption `--ocr.engine=none` will give that value precedence over whatever the\nvalue of the key `ocr.engine` in the effective config is.\n\n## Config\n\nKamite is configured through a config file placed in the directory:\n\n* \u003cins\u003eLinux\u003c/ins\u003e: either `$XDG_CONFIG_HOME/kamite` or, if that is not set,\n    `$HOME/.config/kamite`;\n\n* \u003cins\u003eWindows\u003c/ins\u003e: `%AppData%\\kamite` (usually\n  `C:\\Users\\\u003cuser\u003e\\AppData\\Roaming\\kamite`).\n\nThe main config file must have the name `config.hocon`.\n\nThe config file’s format is [HOCON], which is a superset of JSON.\n\nA default config file is automatically placed by Kamite in the expected\ndirectory if absent on launch.\n\n\u003e [!WARNING]\n\u003e (Windows) On unupdated Windows 10 installations as well as earlier Windows\n\u003e versions, the system Notepad will not be able to properly display the config\n\u003e file. In that case, please use another text editor.\n\n\u003c!-- --\u003e\n\n\u003e [!WARNING]\n\u003e When providing values that containin backslashes (`\\`), for example Windows\n\u003e paths, you must enclose them within triple quote marks (`\"\"\"`). For example:\n\u003e `ocr.tesseract.path: \"\"\"C:\\Program Files\\Tesseract-OCR\\tesseract.exe\"\"\"`.\n\n### Live reload\n\nThe config will be automatically reloaded if one of the files is modified.\nHowever, **only select changes will be applied immediately**. To apply others,\nKamite will still have to be restarted. **The config keys for which the relevant\nchanges are applied immediately are marked with `[RELOADABLE]` in the following\nsection**.\n\n### Full config example\n\nBelow is an example config file illustrating all the possible options with their\n**default** values (`…` represents no default value):\n\n```sh\n# Whether to launch Kamite with the control window or in console only\ncontrolWindow: yes\n\n# Whether to open the client in the default web browser upon launching Kamite\nlaunchBrowser: yes\n\nchunk: {\n  # (Milliseconds) The minimum allowed delay between successive incoming chunks\n  # before they begin to be throttled\n  throttleMS: 1000\n\n  # [RELAODABLE] Perform slight formatting corrections on incoming chunks\n  correct: yes\n\n  # [RELOADABLE] Allow flashing backgrounds of chunk texts in the client's\n  # interface when they are changed or copied\n  flash: yes\n\n  # [RELOADABLE] Treat incoming chunks as translations and create a new chunk\n  # for each translation. Useful when watching media with just the translation\n  # subtitles\n  translationOnlyMode: no\n\n  # [RELOADABLE]\n  furigana: {\n    # Add auto-generated furigana annotations to the current chunk. Note that\n    # this feature requires an extra download (see the Auto-generated furigana\n    # section in the README).\n    # WARNING: The auto-generated furigana will frequently be incorrect\n    enable: no\n\n    # Hide the furigana annotations behind rectangles, reveal on mouse hover\n    conceal: no\n  }\n\n  # [RELOADABLE]\n  log: {\n    # A path of the directory where text files with chunks appearing in the\n    # client should be saved. Chunk logging is disabled when this key is absent\n    dir: …\n  }\n\n  # [RELOADABLE]\n  filter: {\n    # A comma-delimited list of strings representing regular expressions against\n    # which incoming chunks will be matched. If there is at least one match, the\n    # matching chunk will be rejected entirely. See the \"Filtering chunks\"\n    # section of the Readme\n    rejectPatterns: […]\n  }\n\n  # [RELOADABLE] A *list* of objects describing text replacement rules for\n  # incoming chunks. See the \"Transforming chunks\" section of the Readme\n  transforms: [\n    {\n      # A regular expression whose match will be replaced in incoming chunk texts.\n      # Enclose in triple quotes to avoid problems with special characters\n      replace: …\n\n      # The replacement text. Supports match groups (`$1` stands in for the 1st\n      # capture group in the `replace` regular expression, and so on)\n      with: …\n    }\n  ]\n}\n\ncommands: {\n  # [RELOADABLE]\n  player: {\n    # Show extra media player controls (seek -+1 second, seek to the start of\n    # the current subtitle)\n    showExtra: yes\n  }\n\n  # [RELOADABLE] A *list* of custom commands that allow launching system\n  # executables through buttons in Kamite's command palette. See the\n  # \"Custom commands\" section of the Readme\n  custom: [\n    {\n      # (1-3 characters) The symbol that will appear on the command's button\n      symbol: …\n\n      # The name that will appear in the command button's tooltip\n      name: …\n\n      # (String list) The system command to execute. Can contain certain\n      # placeholders which will be filled in by Kamite at the moment of the\n      # command’s activation\n      command: …\n    }\n  ]\n}\n\n# For development only. See the \"Development\" page in the Wiki\ndev: {\n  serveStaticInDevMode: no\n}\n\nintegrations: {\n  # [RELOADABLE]\n  agent: {\n    # Whether to receive text from a running instance of Agent (the option\n    # `WebSocketServer` must be enabled in Agent)\n    enable: no\n\n    # The address of the Agent's WebSocket server through which text is\n    # received by Kamite. (There should be no need to override the default\n    # value unless you run Agent and Kamite on different network hosts)\n    host: \"127.0.0.1:9001\"\n  }\n}\n\nkeybindings: {\n  # Global keybindings. See the \"Keyboard shortcuts\" section of the Readme.\n  # WARNING: Not all platforms support global keybindings\n  global: {\n    ocr: {\n      # A key combination to assign to the command. See the \"Keyboard shortcuts\"\n      # section of the Readme for the format specification.\n      manualBlock: …\n      manualBlockRotated: …\n      autoBlock: … # Instant detection under mouse cursor\n      autoBlockSelect: … # Must click to select a point\n\n      # Bindings for user-defined OCR regions by symbol\n      region: [\n        { symbol: …, key: … }\n      ]\n    }\n  }\n}\n\n# [RELOADABLE]\nlookup: {\n  # A list of lookup targets that will be displayed in the notebook’s tab bar.\n  # Consult the default config for further illustration of configuring lookups\n  targets: [\n    {\n      symbol: … # (1-3 characters) The symbol will appear on the lookup button\n      name: … # The name will appear in the lookup button's tooltip\n\n      # The lookup's URL that should contain the placeholder {} which will be\n      # replaced with the lookup text by Kamite\n      url: …\n\n      # Open the lookup in a new browser tab or embed it into Kamite’s notebook\n      newTab: no\n    }\n  ]\n}\n\nocr: {\n  # The OCR engine to use: none, tesseract, mangaocr, mangaocr_online, ocrspace,\n  #                        easyocr_online, hiveocr_online\n  engine: none\n  # (Directory path) Watch the specified directory for new/modified images and\n  # OCR them automatically\n  watchDir: …\n\n  tesseract: {\n    # (File path) The path to Tesseract’s executable\n    path: \"tesseract\"\n  }\n  \n  mangaocr: {\n    # (File path) A path to a python executable that provides access to the\n    # `manga_ocr` module. If absent, a system-dependent default is used which\n    # assumes that manga-ocr was installed through pipx into the default\n    # location\n    pythonPath: …\n  }\n\n  ocrspace: {\n    # (1, 3) The OCR.space engine to use (see # https://ocr.space/OCRAPI#ocrengine)\n    engine: 1\n  }\n\n  # [RELOADABLE] A *list* of OCR regions, for each of which a region recognition\n  # command button will be displayed in the command palette. See the\n  # \"OCR region\" section of the Readme for details\n  regions: [\n    {\n      symbol: … # (1 character) The symbol will appear on the region’s button\n      description: … # The description will appear in the region’s button tooltip\n\n      # (Numbers) The screen coordinates of the regions’s top-left corner\n      x: …\n      y: …\n\n      # (Numbers) The screen dimensions of the region\n      width: …\n      height: …\n\n      # Try to automatically narrow the region’s screenshot to just text before\n      # OCR-ing it.\n      # NOTE: The implementation of this function is currently very basic. It\n      #       might not prove helpful in most use-cases\n      autoNarrow: no\n    }\n  ]\n}\n\nserver: {\n  # The port on which to run the client and the API\n  port: 4110\n}\n\n# [RELOADABLE]\nsessionTimer: {\n  autoPause: {\n    # Whether to enable auto-pausing the session timer after a period of\n    # inactivity. (Overriding this particular option is only useful for\n    # disabling auto-pausing from a profile config or from the command-line in\n    # case the `after` option has been set in an earlier config)\n    enable: yes\n\n    # (Time duration) The inactivity time interval after which to pause the\n    # session timer. Example valid values: `30s`, `5m`. (If this option is set,\n    # auto-pausing can still be disabled by setting `enable` to `no`)\n    after: …\n  }\n\n  # Whether to pause the session timer initially at program launch\n  startPaused: no\n}\n\n# [RELOADABLE]\nui: {\n  # The client's user interface layout (standard, standard_flipped)\n  layout: standard\n\n  # Hide non-essential interface elements until mouse hover\n  focusMode: no\n\n  notebook: {\n    # Automatically collapse the client's notebook to just its tab bar,\n    # expanding only when it's being interacted with\n    collapse: no\n\n    # (25-90) The height of the client's notebook as a percentage of the total\n    # browser inner window height\n    height: 60\n  }\n}\n\nupdate: {\n  # Whether to check for updates on program launch and, if one is available,\n  # print a notification to the Control GUI and the console\n  check: yes\n}\n\n# Secrets used for authentication to third-party services.\n# WARNING: This is unsafe plain-text storage. Do not put data here that you deem\n#          too sensitive for this kind of storage\nsecrets: {\n  # The OCR.space API key\n  ocrspace: …\n}\n```\n\n### Substitution (variables)\n\nThe config format supports substitution. You can define your own keys and then\nuse them when specifying values for the keys read by Kamite, listed above. For\nexample, the following configuration:\n\n```sh\nchunk.log.dir: ${MY_HOME_DIRECTORY}\"documents/kamite-chunk-logs\"\nocr.mangaocr.pythonPath: ${MY_HOME_DIRECTORY}\".local/pipx/venvs/manga-ocr/bin/python\"\n\nMY_HOME_DIRECTORY: \"/home/my-username/\"\n```\n\nwill be resolved to:\n\n```sh\nchunk.log.dir: \"/home/my-username/documents/kamite-chunk-logs\"\nocr.mangaocr.pythonPath: \"/home/my-username/.local/pipx/venvs/manga-ocr/bin/python\"\n```\n\nKamite will warn you if you specify an unknown key in a config file, since\nmistyping their names is a common source of mistakes. But it will at the same\ntime ignore keys whose names start with a capital letter, under the assumption\nthey are your own keys, like `MY_HOME_DIRECTORY` in the example above. For this\nreason, **it is advised to name your own keys using capital letters to avoid\nconfusion and false positive warnings**.\n\n[HOCON]: https://github.com/lightbend/config#using-hocon-the-json-superset\n\n### Config profiles\n\nKamite supports having a set of different config files for different use-cases.\n\nCreating in the config directory a file named `config.example-profile.hocon`\nand then launching Kamite with the [launch option](#launch-options)\n`--profile=example-profile` will instruct Kamite to take into account both the\nmain `config.hocon` file and the `config.example-profile.hocon` file, with\nvalues from the latter taking precedence.\n\nThe values from all config files are resolved within a common context, which\nmeans that the files share the objects defined in them. For example, this works\nas expected:\n\n`config.hocon`\n\n```sh\nlookup: {\n  targets: [\n    ${LOOKUP_TARGETS.deepl}\n    ${LOOKUP_TARGETS.jpdb}\n    ${LOOKUP_TARGETS.googleImages}\n  ]\n}\n\nLOOKUP_TARGETS: {\n  deepl: {\n    symbol: DEP\n    name: DeepL\n    url: \"https://www.deepl.com/translator#ja/en/{}\"\n  }\n  jpdb: {\n    symbol: JDB\n    name: jpdb\n    url: \"https://jpdb.io/search?q={}\"\n  }\n  googleImages: {\n    symbol: GLI\n    name: Google Images\n    url: \"https://www.google.com/search?q={}\u0026tbm=isch\"\n    newTab: yes\n  }\n}\n```\n\n`config.no-translations.hocon`\n\n```sh\nlookup: {\n  targets: [\n    ${LOOKUP_TARGETS.googleImages}\n  ]\n}\n```\n\nGiven the above configuration, launching normally shows `deepl`, `jpdb`, and\n`googleImages` lookups, whereas launching with `--profile=no-translations` shows\nonly `googleImages` lookup.\n\n#### Combined profile (multiple extra config files)\n\nSeveral extra config files can be loaded at once. To achieve that, specify\nmultiple profile IDs with the `--profile` launch option, separating them by\ncommas, e.g., `--profile=first-profile,second-profile`. The values from the\nleftmost profile’s config file will have the highest precedence.\n\n## Style customization\n\nIf present, Kamite loads the `custom.css` file from the root of the [config\ndirectory](#config), which can contain style customizations for the client.\nRefer to your web browser’s Inspector view to see what CSS variables can be\noverridden and what ids and class names the various elements on the page can be\nreferred to with.\n\nBelow is an example `custom.css` file to illustrate how to go about the\ncustomization.\n\n```css\n:root {\n  --color-bg: navy;\n  --color-bg-hl: navy;\n  --color-bg2: blue;\n  --color-fg: fuchsia;\n}\n#character-counter * {\n  font-size: 28px;\n}\n.notebook-tab {\n  border: 3px dashed green;\n}\n#chunk-label:after {\n  content: \"Design is my passion edition\";\n  color: yellow;\n}\n```\n\nThe root client element is assigned CSS classes `profile-X`, where `X` stands\nfor each profile specified at launch. Style customizations can therefore be\ndefined per profile. For example, the following `custom.css`:\n\n```css\n.profile-vn {\n  --color-bg: purple;\n}\n```\n\nwill recolor the background to purple only when the program was launched with\nthe profile named `vn`.\n\n### Styling recipes\n\n\u003c!-- markdownlint-capture --\u003e\u003c!-- markdownlint-disable --\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Kamite black theme\" src=\"https://user-images.githubusercontent.com/4130634/197248754-96468c44-fd58-479c-8bd5-c7e20668269a.png\" /\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-restore--\u003e\n\nExamples of ready-made style customizations, including a black color theme, can\nbe found on the [Styling recipes] Wiki page.\n\n[Styling recipes]: https://github.com/fauu/Kamite/wiki/Styling-recipes\n\n## Command API\n\nKamite can receive commands sent programmatically, which makes it simple to\nit integrate with all kinds of custom workflows.\n\nAvailable commands are distinguished by *command kind*, which is made up of two\nsegments: *command group* and *command name*. For example, kind `ocr_region`\ncorresponds to the group `ocr` and the name `region`.\n\nThe command parameters are required unless they are marked as optional or a\ndefault value is specified.\n\n### Sending commands\n\nBelow are examples illustrating the available means of issuing commands to\nKamite through its API.\n\n#### DBus (Linux)\n\n```sh\ndbus-send --type=method_call \\\n  --dest=io.github.kamitejp /Receiver io.github.kamitejp.Receiver.command\n  string:\"chunk_show\" \\ # command kind, i.e. \"{command_group}_{command_name}\"\n  string:'{\"chunk\": \"This is the chunk text\"}' # JSON object of command parameters\n```\n\n#### HTTP\n\n\u003cins\u003eLinux\u003c/ins\u003e:\n\n```sh\ncurl -i -X POST \\\n  -d '{\"chunk\": \"This is the chunk text\"}' \\\n  localhost:4110/cmd/chunk/show # {kamite_host}/cmd/{command_group}/{command_name}\n```\n\n\u003cins\u003eWindows\u003c/ins\u003e (PowerShell):\n\n```powershell\n$body = @{\n  \"chunk\" = \"This is the chunk test\"\n}\nInvoke-RestMethod -Method 'Post' `\n  -Uri 'http://localhost:4110/cmd/chunk/show' `\n  -Body \"$($body | ConvertTo-Json)\"\n```\n\n### Command listing\n\nSee the\n[Command API listing](https://github.com/fauu/Kamite/wiki/Command-API-listing)\npage in the Wiki.\n\n## Privacy\n\nKamite never saves your data to disk.\n\nKamite only sends data through the internet in the following circumstances:\n\n* When `update.check` **is not** set to `no`, a connection to `github.com` is\n  made on every launch in order to check for the availability of a newer version\n  of Kamite.\n\n* When `ocr.engine` is set to `mangaocr_online`, screenshots of portions of your\n  screen are sent to [a Hugging Face Space by detomo][manga-ocr-hf] for text\n  recognition.\n\n* When `ocr.engine` is set to `hiveocr_online`, screenshots of portions of your\n  screen are sent to a [Hugging Face Space by seaoctopusredchicken][hiveocr-hf]\n  for text recognition.\n\n* When `ocr.engine` is set to `easyocr_online`, screenshots of portions of your\n  screen are sent to a [Hugging Face Space by tomofi][easyocr-hf] for text\n  recognition.\n\n* When `ocr.engine` is set to `ocrspace`, screenshots of portions of your screen\n  are sent to [OCR.space] for text recognition.\n\nScreenshots sent to third parties can be inspected in the client’s Debug tab\n(see [Troubleshooting](#troubleshooting)). They are labelled as “Remote OCR”.\n\n## Development\n\nKamite is built mainly with Java and [SolidJS][Solid] (TypeScript).\n\nFor more information see the\n[Development](https://github.com/fauu/Kamite/wiki/Development) page in the Wiki.\n\n## License\n\nKamite\\\nCopyright (C) 2021-2023 Piotr Grabowski\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU Affero General Public License as published by the Free\nSoftware Foundation, either version 3 of the License, or (at your option) any\nlater version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along\nwith this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n### Third-party components\n\nThe Kamite repository and the Kamite release package include the following\nthird-party components (as well as their subcomponents):\n\n| Component                       | License    |\n|---------------------------------|------------|\n| [Apache Log4j][log4j]           | Apache-2.0 |\n| [hypfvieh/dbus-java]            | MIT        |\n| [Jackson]                       | Apache-2.0 |\n| [Javalin]                       | Apache-2.0 |\n| [jkeymaster]                    | LGPL-3.0   |\n| [Java Native Access (JNA)][JNA] | Apache-2.0 |\n| [jsoup]                         | MIT        |\n| [Kuromoji UniDic Kana Accent]   | Apache-2.0 |\n| [Noto Sans Japanese]            | OFL        |\n| [Roboto]                        | Apache-2.0 |\n| [SLF4J]                         | MIT        |\n| [Solid]                         | MIT        |\n| [Solid Styled Components]       | MIT        |\n| [tscfg]                         | Apache-2.0 |\n| [Typesafe Config][ts-config]    | Apache-2.0 |\n\nKamite also includes components adapted from third-party code. See\n\u003chttps://github.com/fauu/Kamite/search?q=adapted\u003e for the listing, including\nthe original license notices.\n\n[tscfg]: https://github.com/carueda/tscfg\n[hypfvieh/dbus-java]: https://github.com/hypfvieh/dbus-java\n[Javalin]: https://github.com/javalin/javalin\n[Jackson]: https://github.com/FasterXML/jackson-core\n[jkeymaster]: https://github.com/tulskiy/jkeymaster\n[JNA]: https://github.com/java-native-access/jna\n[SLF4J]: https://www.slf4j.org/\n[log4j]: https://github.com/apache/logging-log4j2\n[ts-config]: https://github.com/lightbend/config\n[jsoup]: https://github.com/jhy/jsoup\n[Solid]: https://www.solidjs.com/\n[Solid Styled Components]: https://github.com/solidjs/solid-styled-components\n[Kuromoji UniDic Kana Accent]: https://github.com/atilika/kuromoji\n[Roboto]: https://fonts.google.com/specimen/Roboto\n[Noto Sans Japanese]: https://fonts.google.com/noto/specimen/Noto+Sans+JP\n\n[Yomichan]: https://foosoft.net/projects/yomichan/\n[rikaikun]: https://github.com/melink14/rikaikun\n[10ten]: https://github.com/birchill/10ten-ja-reader\n[Gomics-v]: https://github.com/fauu/gomicsv\n[Sway]: https://swaywm.org/\n[manga-ocr]: https://github.com/kha-white/manga-ocr\n[manga-ocr-hf]: https://huggingface.co/spaces/Detomo/Japanese-OCR\n[easyocr-hf]: https://huggingface.co/spaces/tomofi/EasyOCR\n[hiveocr-hf]: https://huggingface.co/spaces/seaoctopusredchicken/Hive-OCR-simple\n[OCR.space]: https://ocr.space/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauu%2Fkamite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffauu%2Fkamite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauu%2Fkamite/lists"}