imajin 1.4.0b1

Search tool for Japanese text in EPUB and Mokuro files

imajin.py

imajin.py is a search tool for .epub, .mokuro, .srt and .ass files, designed to help you find example sentences in your Japanese media.

---

Index

• Features
• Installation
  • Install with pip (preferred method)
  • Download and install script
  • Dependencies
• Usage
  • Positional Arguments
  • Options
• Examples
  • Installed
  • As a script
• Saving Results
• Notes
• License

---

Features

• Search across unencrypted .epub (ebooks), .mokuro (manga), and .srt and .ass (subtitled) files
• Supports smart matching for Japanese conjugations (optional)
• Supports searching individual words or phrases
• Structured output: text, markdown, or JSON
• Recursively search directories of books, manga, and subtitles
• Clean highlighted snippets showing surrounding context

---

Installation

Install with pip (preferred method)

Recommended because it will be easier to update going forward, especially if you prefer to have the script installed.

1. Install Python 3.9+ if not allready installed

2. Install imajin using pip:

   pip install imajin
   

   You should be all set up to use imajin directly from the command line.

Download and install script

Not recommended, because it's harder to update.

1. Install Python 3.9+ if not already installed.

2. Download the source folder, either by downloading the Source code from the Latest Release or using git clone https://github.com/YonKuma/imajin.py.git

3. Install dependencies:

   pip install -r requirements.txt
   

   You can now use imajin.py as a python script. For example, if you're in the source directory, you can use python imajin.py -r 蹴散らす ~/Documents/Manga, but you'll need to use a qualified path to the files you want to search

4. (Optional) You can install imajin by copying the script to somewhere in your PATH and making it executable

   sudo cp imajin.py /usr/local/bin/imajin
   sudo chmod +x /usr/local/bin/imajin
   

Dependencies

Dependencies:

• beautifulsoup4
• lxml
• mecab-python3 (optional; smart matching will be disabled if MeCab is not available)
• unidic-lite (optional; used for smart matching. Other dictionaries should work but are harder to install)

---

Usage

Installed:

imajin [options] <search_word> <file_or_directory>

As a script:

python imajin.py [options] <search_word> <file_or_directory>

Positional Arguments

Argument	Description
<search_word>	The word or phrase you want to find.
<file_or_directory>	A single .epub or .mokuro file, or a directory containing them.

Options

Option	Description
--match {exact, smart, both}	Choose whether to use exact match only search (faster), smart search only (slower, less false positives, matches different conjucations), or the union of both (default: both).
-r, --recursive	Recursively search subdirectories if a directory is specified.
--format {text,markdown,md,json}	Choose output format (default: text).
-h, --help	Show help message and exit.

---

Examples

Installed

Search for the word "慌ただしい" inside your book collection:

imajin 慌ただしい ./books/

Find exact matches only, searching all subdirectories:

imajin --match=exact -r 慌ただしい ./novel-library/

Get markdown-formatted results:

imajin 慌ただしい ./books/ --format md

Save the results in a JSON file for further processing:

imajin 慌ただしい ./manga-collection/ --format json > results.json

As a script

Search for the word "慌ただしい" inside your book collection:

python imajin.py 慌ただしい ./books/

Find smart matches only, searching all subdirectories:

python imajin.py --match=smart -r 慌ただしい ./novel-library/

Get markdown-formatted results:

python imajin.py 慌ただしい ./books/ --format markdown

Save the results in a JSON file for further processing:

python imajin.py 慌ただしい ./manga-collection/ --format json > results.json

---

Saving Results

To save your search results to a file, redirect the output:

imajin 慌ただしい ./books/ --format md > examples.md

This method works for all output formats (text, markdown/md, or JSON).

---

Notes

• If MeCab is not installed, smart matching will be automatically disabled.

---

License

This project is released under the CC0 1.0 Universal Public Domain Dedication.