CLI reference¶

Everything the GUI does is also available from the terminal. I really recommend using the GUI because it's way simpler and battle-tested. Commands are run from the src/ folder (or from the project root with PYTHONPATH=src):

cd src
python -m miningcat <command> [options]
python -m miningcat --help             # every command, and `<command> --help` for its options

Audiobook pipeline¶

Unlike the GUI, the CLI reads its inputs from fixed folders. Put your files there first:

the ebook (.epub or .txt) in sources/ebook/
the audio files in sources/audiobook/

Then run the steps in order:

python -m miningcat audio             # 1. prepare audio chapters
python -m miningcat epub --range 4-9  # 2. extract the book text, one file per chapter
python -m miningcat align --language french --model tiny   # 3. align text on audio
python -m miningcat export --all --language french         # 4. render the MP4 files

Or all at once (with default options): python -m miningcat run --range 4-9.

`audio`¶

Prepares the audio chapters in output/chapters_audio/: splits a .m4b by chapter markers, or copies the audio files (one per chapter).

Option	Description
`--dry-run`	Show the detected chapters without extracting them

`epub`¶

Extracts the book text into output/chapters_text/chapter_001.txt, chapter_002.txt...

Option	Description
`--list`	List the chapters without extracting them
`--range A-B`	Extract only chapters A to B (e.g. `4-9`)
`--chapters N,M,...`	Extract a manual selection (e.g. `3,4,5`)
`--preview`	Print a text excerpt for each chapter

Use --list and --preview first to find which chapters match the audiobook.

`align`¶

Standard mode. Aligns each chapter's text on its audio and writes the subtitles to output/srt/.

Option	Default	Description
`--model`	`tiny`	Whisper model: `tiny`, `base`, `small`, `medium`, `large`, `turbo`
`--language`	`mandarin_tw`	See language ids
`--from N`		Start from chapter N
`--only N`		Process only chapter N

`transcribe`¶

Generate subtitles mode. Transcribes the audio chapters with Whisper, without an ebook. Same options as align, and --model also takes qwen3-0.6b or qwen3-1.7b to transcribe with Qwen3-ASR (make install-qwen).

`tts`¶

Generate audio mode. Generates the audio of each extracted chapter with edge-tts (default), or with OmniVoice (local) when Settings › Voice doesn't use edge-tts, along with its subtitles.

Option	Default	Description
`--voice`	required	`zh-OmniVoice` (local), `zh-ElevenLabs`, or an edge-tts voice name, e.g. `zh-TW-HsiaoChenNeural`
`--language`	`mandarin_tw`	See language ids

OmniVoice's voice of a language is its key followed by -OmniVoice (fr-OmniVoice, yue-OmniVoice...): it needs make install-omnivoice. List Edge's voices with edge-tts --list-voices: OmniVoice takes over when Edge fails. Taigi has no Edge voice: use nan-TW-MmsTaigi or nan-OmniVoice, local voices (see Taigi). zh-ElevenLabs (the language's key followed by -ElevenLabs) reads with the ElevenLabs voice of Settings › Voice, using your credits (see ElevenLabs).

`convert`¶

Converts every subtitle file in output/srt/ between Chinese scripts with OpenCC, or writes Taigi subtitles in another writing system.

Option	Values	Description
`--source`	`s`, `tw`, `hk`, `nan`	Source script: `s` = simplified, `tw` = traditional (Taiwan), `hk` = traditional (Hong Kong), `nan` = Taigi in any writing system
`--target`	`s`, `tw`, `t`, `hk`, `hanji`, `tailo`, `poj`	Target script: `t` = traditional, `hk` = traditional (Hong Kong); for Taigi, Hanji, Tâi-lô or Pe̍h-ōe-jī

`export`¶

Renders the final videos into output/final/chapter_001.mp4... Each video shows the book and chapter title over the audio, with the subtitles embedded.

Option	Default	Description
`--chapter N`		Export only chapter N
`--all`		Export all chapters
`--language`	`mandarin_tw`	Sets the subtitle language metadata
`--preset`	`ultrafast`	ffmpeg encoding preset: `ultrafast`, `superfast`, `veryfast`, `faster`, `fast`, `medium`

`run`¶

Runs audio, epub, align and export --all in sequence with default options.

Option	Description
`--range A-B`	Ebook chapter range (e.g. `4-9`)

`video`¶

Downloads an online video, or uses a local file, and generates its subtitles. See Videos for the details.

python -m miningcat video --url <URL> [options]
python -m miningcat video --file <PATH> [options]

Option	Default	Description
`--url` / `--file`	one required	Video URL, or path to a local video file
`--model`	`tiny`	Whisper model, or `qwen3-0.6b` / `qwen3-1.7b` for Qwen3-ASR (`make install-qwen`)
`--language`	`mandarin_tw`	See language ids
`--convert-to`		Convert the generated subtitles to `s`, `tw`, `t` or `hk`
`--audio-track`	container default	0-based index of the audio stream to transcribe, for videos with several dubs
`--ocr`		Read burned-in subtitles with OCR instead of transcribing the audio
`--ocr-region`	bottom third	Subtitle area as `X,Y,W,H` fractions between 0 and 1, e.g. `0,0.75,1,0.25`
`--ocr-fps`	`4`	Frames sampled per second for OCR (2 to 12)
`--second-subs`		Add second subtitles translated to the settings' translation language, from `main` (the generated subtitles) or the 0-based index of a subtitle track of the video
`--app-id`	`web`	Instagram only: `X-IG-App-ID` header (`web`, `ios` or a numeric id), if downloads start failing

`install-translation`¶

Installs a model translating the sentences and subtitles: the packages of its engine (requirements-nllb.txt for NLLB-200, requirements-qwen.txt for Qwen3), then the model.

python -m miningcat install-translation [--model nllb-600m|nllb-1.3b|qwen3-4b]

Option	Default	Description
`--model`	`nllb-600m`	`nllb-600m` (630 MB), `nllb-1.3b` (1.4 GB, more accurate) or `qwen3-4b` (8 GB, with context)

Then choose it in Settings › Translation.

`game`¶

Video game / screen share OCR: captures a window (or a webcam / capture card), reads its text area with OCR, and pushes the screenshot + text to a local web page. See Video games & screen share for the details.

python -m miningcat game setup [options]   # 1. pick the window, then draw the screenshot and text areas
python -m miningcat game serve [options]   # 2. capture until Ctrl+C

The selection is saved in sources/game_ocr.json, so setup is only needed once per game.

`game setup`¶

Asks for the window (GNOME's sharing dialog on Linux, a numbered list on macOS and Windows) or, with --webcam, the camera (a numbered list), then opens two pages in your browser, one after the other, to draw the screenshot area and the text area.

Option	Description
`--webcam`	Capture a webcam or capture card (console, other computer...) instead of a window
`--window TEXT`	macOS, Windows, `--webcam`: pick the first window (or camera) whose name contains `TEXT`, instead of asking
`--areas-only`	Keep the saved window, only draw the areas again

`game serve`¶

Serves the page on http://127.0.0.1:6677/ and opens it in the browser. Captures when the capture key is pressed, or continuously with --continuous. curl -X POST http://127.0.0.1:6677/capture also captures right away.

Option	Default	Description
`--language`	`mandarin_tw`	See language ids
`--convert-to`		Convert the text to `s`, `tw`, `t` or `hk` (Chinese only)
`--port`	`6677`	Port of the web page
`--hotkey`	`F9`	Global capture key, `F1` to `F12` (works even with the game focused)
`--continuous`		Capture whenever the text changes, instead of with the capture key
`--interval`	`0.5`	Seconds between two looks at the text area, in continuous mode
`--keep-line-breaks`		Keep the text's line breaks instead of joining the lines of the dialog box
`--no-browser`		Don't open the page in the browser

Language ids¶

Id	Language
`mandarin_tw`	Mandarin - Taiwan (Traditional)
`mandarin_cn`	Mandarin - China (Simplified)
`cantonese_hk`	Cantonese - Hong Kong (Traditional)
`taigi`	Taiwanese Hokkien - Taigi (transcribed with Qwen3-ASR: `--model qwen3-0.6b` or `qwen3-1.7b`)
`japanese`	Japanese
`korean`	Korean
`vietnamese`	Vietnamese
`russian`	Russian
`english_us`	English - United States
`english_uk`	English - United Kingdom
`french`	French
`german`	German
`italian`	Italian
`spanish`	Spanish
`portuguese`	Portuguese
`polish`	Polish

Make shortcuts¶

The Makefile wraps the most common commands. Variables can be overridden on the command line.

Command	Equivalent
`make gui [PORT=5050]`	Launch the GUI in your browser
`make reader [PORT=5050]`	Open the ebook reader in your browser
`make player [PORT=5050]`	Open the video player in your browser
`make audio`	`audio`
`make epub [RANGE=4-9]`	`epub [--range 4-9]`
`make align [CHAPTER=1\\|all]`	`align --only 1` (or all chapters)
`make export [CHAPTER=1\\|all]`	`export --chapter 1` (or `--all`)
`make chapter N=5`	`align` + `export` for chapter 5
`make chapter1`	`align` + `export` for chapter 1
`make run [RANGE=4-9]`	`run [--range 4-9]`
`make video URL=...`	`video --url ...`
`make video FILE=...`	`video --file ...`
`make install-translation [TRANSLATION=qwen3-4b]`	`install-translation [--model qwen3-4b]`
`make game-setup`	`game setup`
`make game [HOTKEY=F9]`	`game serve --language ... --hotkey F9`
`make clean`	Delete generated files in `output/` and `temp/`

Available variables and their defaults: MODEL=tiny, LANGUAGE=mandarin_tw, PRESET=ultrafast, CHAPTER=1, APP_ID=web, HOTKEY=F9.

make align CHAPTER=all MODEL=base LANGUAGE=japanese
make export CHAPTER=all PRESET=superfast LANGUAGE=japanese
make video URL="https://www.instagram.com/reel/xxxxx/" LANGUAGE=korean

Warning

make export doesn't pass LANGUAGE, so the subtitle language metadata defaults to Mandarin. Use python -m miningcat export --all --language <id> if the metadata matters to your player.

CLI reference¶

Audiobook pipeline¶

audio¶

epub¶

align¶

transcribe¶

tts¶

convert¶

export¶

run¶

video¶

install-translation¶

game¶

game setup¶

game serve¶