Skip to content

saitenka

saitenka COMMAND [OPTIONS] [ARGS]

Saitenka in-mpv overlay: JP subs with FSRS coloring, hover → multi-dict tooltip, mining.

Table of Contents

Commands:

  • attach: Attach to an already-running mpv's IPC socket instead of launching mpv.
  • doctor: Check the environment: mpv/ffmpeg, config, dict cache, fonts, AnkiConnect.
  • import: Import Yomitan dictionary .zip files into the consolidated database (built once) and register them in the config by title.
  • import-dictionaries: Import a Yomitan DATABASE backup (the multi-GB dexie JSON export) directly into the consolidated database. Streamed — never full-loaded. The per-dictionary zips are reconstructed into a TEMP dir, imported, then discarded (no persistent zip copies are kept).
  • import-settings: Apply a Yomitan SETTINGS export (dictionary order + options) to your overlay config.
  • install-plugin: Install the saitenka.lua mpv user-script (plugin mode).
  • jimaku-check: Diagnose jimaku without launching a video: resolve the key and run a test search, printing the exact outcome (key found? 200 OK / 401 bad key / 400 + server message / network error).
  • reinstall: Reinstall to CHANGE your extras or source, preserving what's installed. A bare uv tool install --reinstall replaces the extras set (silently dropping deinflect/telemetry); this detects what's installed and keeps it. From PyPI, falling back to GitHub (which also carries the GPL deinflect add-on). The GitHub attempt targets the latest RELEASE tag by default — not bleeding-edge main; pass --ref main for that, or --ref vX.Y.Z to pin a release. For a plain "get the latest" with no extras change, prefer update.
  • report: Bundle diagnostics (doctor + versions + config + mpv.conf + plugin lua + log) into a single timestamped zip for bug reports. Local-only, never uploaded; secrets are redacted.
  • run: Play a video with Japanese subs; hover a word → Yomitan-like dictionary tooltip in mpv.
  • set-jimaku-key: Store your jimaku.cc API key where a plugin-mode (GUI-launched) mpv can read it.
  • setup: One-command setup (alias: install): inventory → install mpv+ffmpeg → doctor → init → import → plugin. Re-run any time to reconfigure — it's resumable and confirm-first.
  • stats: Show local immersion-session history.
  • telemetry: Turn runtime telemetry on or off without hand-editing overlay.toml.
  • uninstall: Delete saitenka's config, dictionaries, cache/logs, crash reports and mpv plugin. Leaves mpv and ffmpeg installed. Does NOT remove the saitenka binary itself — the last line tells you how.
  • uninstall-plugin: Remove the saitenka.lua mpv user-script (backs it up first).
  • update: Update saitenka to the latest, keeping your extras (wraps uv tool upgrade, which preserves the recorded extras/constraints). On Windows a running tool can't replace its own venv, so this prints the command to run in a fresh shell; --now hands off to a detached updater that waits for this process to exit. To CHANGE extras or install from GitHub, use reinstall instead.

Parameters:

  • VIDEO, --video:
  • --config: settings TOML (default: platform config dir, see doctor)
  • --sub-file:
  • --slang: primary (JP) sub languages, priority order [default: ja,jpn,jp]
  • --dict: imported dictionary TITLE (repeatable; ordered — first = top of the tooltip)
  • --translate-key: mpv key to toggle the EN translation [default: t]
  • --start: mpv --start (seconds or hh🇲🇲ss) [default: 1]
  • --jimaku: fetch JP subs from jimaku.cc [default: False]
  • --jimaku-key: jimaku.cc API key (else $JIMAKU_API_KEY)
  • --jimaku-title: override the title parsed from the filename
  • --resync, --no-resync: auto-resync jimaku-sourced subtitles via alass/ffsubsync (default: on) [default: True]
  • --episode: override the episode parsed from the filename
  • --width: test-clip width (default 1080p) [default: 1920]
  • --height: [default: 1080]
  • --fullscreen: [default: False]
  • --use-config: [default: False]
  • --demo-word: force-hover the first token containing this text
  • --demo-translate: reveal the EN translation (demo) [default: False]
  • --demo-scroll: scroll the tooltip N steps (demo) [default: 0]
  • --bulk: in demo, bulk-mine the cue instead of one word [default: False]
  • --screenshot: capture the composited window to this PNG, then quit
  • --seconds: [default: 60.0]
  • --color: enable SubMiner-style word coloring [default: False]
  • --known: comma-separated known words (lemmas/readings) [default: ""]
  • --anki-decks: JSON {"Deck": ["Field"]} to build known-set via AnkiConnect
  • --freq: imported frequency-dict TITLE (repeatable; green pills + coloring bands)
  • --pitch: imported pitch-accent-dict TITLE (repeatable; purple pills)
  • --mine, --no-mine: one-key mining to Anki (default: on when [mine] is configured; --no-mine to disable) [default: True]
  • --mine-deck: [default: Saitenka::Mining]
  • --mine-model: [default: Lapis]
  • --mine-normalize-audio, --no-mine-normalize-audio: normalize mined clip loudness to −23 LUFS (EBU R128) so cards play at an even volume [default: False]
  • --mine-key: mpv key that mines the hovered word [default: Ctrl+m]
  • --mine-all-key: mpv key that bulk-mines the cue [default: Shift+m]
  • --preview-key: mpv key to replay the last card preview + audio [default: p]
  • --no-audio-play: don't auto-play the mined clip [default: False]
  • --tip-height: max BASE tooltip height as a fraction of the video height (default 0.4) [default: 0.4]
  • --pause-on-tooltip, --no-pause-on-tooltip: auto-pause playback while a tooltip is shown (resumes when it hides) [default: True]
  • --prefetch, --no-prefetch: disable background prefetch of the paused line's tooltips [default: True]
  • --auto-translate: auto-reveal the EN translation while a tooltip is shown (else press the translate key). Anti-crutch: the EN only appears when you're looking a word up [default: False]
  • --hover-switch-delay: seconds the cursor must rest on a NEW word before the tooltip switches to it (0 = instant) [default: 0.15]
  • --mpv-arg: extra raw mpv flag (repeatable; SubMiner-style passthrough). Wins over our own defaults (force-window/slang/sub-visibility/osd-level/loop-file/start) — mpv is last-flag-wins — but never over --input-ipc-server/--log-file/the anti-duplicate script-opts marker, which we always set last

saitenka run

saitenka run [OPTIONS] [ARGS]

Play a video with Japanese subs; hover a word → Yomitan-like dictionary tooltip in mpv.

Parameters:

  • VIDEO, --video:
  • --config: settings TOML (default: platform config dir, see doctor)
  • --sub-file:
  • --slang: primary (JP) sub languages, priority order [default: ja,jpn,jp]
  • --dict: imported dictionary TITLE (repeatable; ordered — first = top of the tooltip)
  • --translate-key: mpv key to toggle the EN translation [default: t]
  • --start: mpv --start (seconds or hh🇲🇲ss) [default: 1]
  • --jimaku: fetch JP subs from jimaku.cc [default: False]
  • --jimaku-key: jimaku.cc API key (else $JIMAKU_API_KEY)
  • --jimaku-title: override the title parsed from the filename
  • --resync, --no-resync: auto-resync jimaku-sourced subtitles via alass/ffsubsync (default: on) [default: True]
  • --episode: override the episode parsed from the filename
  • --width: test-clip width (default 1080p) [default: 1920]
  • --height: [default: 1080]
  • --fullscreen: [default: False]
  • --use-config: [default: False]
  • --demo-word: force-hover the first token containing this text
  • --demo-translate: reveal the EN translation (demo) [default: False]
  • --demo-scroll: scroll the tooltip N steps (demo) [default: 0]
  • --bulk: in demo, bulk-mine the cue instead of one word [default: False]
  • --screenshot: capture the composited window to this PNG, then quit
  • --seconds: [default: 60.0]
  • --color: enable SubMiner-style word coloring [default: False]
  • --known: comma-separated known words (lemmas/readings) [default: ""]
  • --anki-decks: JSON {"Deck": ["Field"]} to build known-set via AnkiConnect
  • --freq: imported frequency-dict TITLE (repeatable; green pills + coloring bands)
  • --pitch: imported pitch-accent-dict TITLE (repeatable; purple pills)
  • --mine, --no-mine: one-key mining to Anki (default: on when [mine] is configured; --no-mine to disable) [default: True]
  • --mine-deck: [default: Saitenka::Mining]
  • --mine-model: [default: Lapis]
  • --mine-normalize-audio, --no-mine-normalize-audio: normalize mined clip loudness to −23 LUFS (EBU R128) so cards play at an even volume [default: False]
  • --mine-key: mpv key that mines the hovered word [default: Ctrl+m]
  • --mine-all-key: mpv key that bulk-mines the cue [default: Shift+m]
  • --preview-key: mpv key to replay the last card preview + audio [default: p]
  • --no-audio-play: don't auto-play the mined clip [default: False]
  • --tip-height: max BASE tooltip height as a fraction of the video height (default 0.4) [default: 0.4]
  • --pause-on-tooltip, --no-pause-on-tooltip: auto-pause playback while a tooltip is shown (resumes when it hides) [default: True]
  • --prefetch, --no-prefetch: disable background prefetch of the paused line's tooltips [default: True]
  • --auto-translate: auto-reveal the EN translation while a tooltip is shown (else press the translate key). Anti-crutch: the EN only appears when you're looking a word up [default: False]
  • --hover-switch-delay: seconds the cursor must rest on a NEW word before the tooltip switches to it (0 = instant) [default: 0.15]
  • --mpv-arg: extra raw mpv flag (repeatable; SubMiner-style passthrough). Wins over our own defaults (force-window/slang/sub-visibility/osd-level/loop-file/start) — mpv is last-flag-wins — but never over --input-ipc-server/--log-file/the anti-duplicate script-opts marker, which we always set last

saitenka doctor

saitenka doctor [OPTIONS]

Check the environment: mpv/ffmpeg, config, dict cache, fonts, AnkiConnect.

Parameters:

  • --json: emit the report as JSON [default: False]
  • --summary, --quiet: collapse passing checks to a count; show only warnings/failures in full [default: False]
  • --mine-deck: [default: Saitenka::Mining]
  • --mine-model: [default: Lapis]

saitenka telemetry

saitenka telemetry [ARGS]

Turn runtime telemetry on or off without hand-editing overlay.toml.

enable/disable flip [telemetry] enabled (comment-preserving, prior file backed up). The OTel SDK it needs is a SEPARATE telemetry extra — enable prints the install command if it's missing (config flag and dependency are two switches). status (default) reports both.

Parameters:

  • ACTION, --action: flip [telemetry] enabled in overlay.toml, or show status [choices: status, enable, disable] [default: status]

saitenka stats

saitenka stats [ARGS]

Show local immersion-session history.

Parameters:

  • LIMIT, --limit: number of recent sessions to show [default: 20]

saitenka import

saitenka import [OPTIONS] PATHS

Import Yomitan dictionary .zip files into the consolidated database (built once) and register them in the config by title.

Accepts individual .zip files and/or directories to scan for them. Each is classified by content (definition / frequency / pitch) and imported into data_dir()/dictionaries.sqlite. The source zips are read in place — no copy is kept — so you can delete or move them afterwards.

Parameters:

  • PATHS, --paths, --empty-paths: Yomitan dictionary .zip files and/or folders of them [required]
  • --yes: write the config without prompting [default: False]

saitenka set-jimaku-key

saitenka set-jimaku-key [ARGS]

Store your jimaku.cc API key where a plugin-mode (GUI-launched) mpv can read it.

Uses the OS keyring when available, else an owner-only file beside overlay.toml. Either beats a shell env var, which a GUI-launched mpv can't see. Get a free key at https://jimaku.cc/account (API docs: https://jimaku.cc/api/docs).

Windows paste tip: the hidden prompt does NOT accept Ctrl+V (it captures one control char), so a pasted key can silently truncate to a single character. Right-click to paste at the prompt, or pass the key as an argument on the normal command line where Ctrl+V works: set-jimaku-key <key>.

Parameters:

  • KEY, --key: the key (omit to be prompted with hidden input)

saitenka jimaku-check

saitenka jimaku-check [ARGS]

Diagnose jimaku without launching a video: resolve the key and run a test search, printing the exact outcome (key found? 200 OK / 401 bad key / 400 + server message / network error).

Parameters:

  • QUERY, --query: anime title to test-search [default: Spy x Family]

saitenka import-settings

saitenka import-settings [OPTIONS] [ARGS]

Apply a Yomitan SETTINGS export (dictionary order + options) to your overlay config.

Reads the small Yomitan → Settings → Backup → Export Settings file and matches its dictionary titles against the .zip files under --scan-dir. For a full Yomitan DATABASE backup (the multi-GB export), use import-dictionaries instead — it unpacks that into .zip dicts. (Alias: import-settings.)

Parameters:

  • SETTINGS, --settings:
  • --scan-dir: dir holding your Yomitan dictionary .zip files (repeatable; opt-in — no personal folder is scanned unless you name it). Titles are matched against these dirs.
  • --yes: write the config without prompting [default: False]

saitenka import-dictionaries

saitenka import-dictionaries [OPTIONS] EXPORT

Import a Yomitan DATABASE backup (the multi-GB dexie JSON export) directly into the consolidated database. Streamed — never full-loaded. The per-dictionary zips are reconstructed into a TEMP dir, imported, then discarded (no persistent zip copies are kept).

This is for when you DON'T have the dictionary .zip files. If you already have them, use import / import-settings (faster, no unpacking).

Parameters:

  • EXPORT, --export: [required]
  • --yes: write the config without prompting [default: False]

saitenka install-plugin

saitenka install-plugin

Install the saitenka.lua mpv user-script (plugin mode).

saitenka uninstall-plugin

saitenka uninstall-plugin

Remove the saitenka.lua mpv user-script (backs it up first).

saitenka update

saitenka update [OPTIONS]

Update saitenka to the latest, keeping your extras (wraps uv tool upgrade, which preserves the recorded extras/constraints). On Windows a running tool can't replace its own venv, so this prints the command to run in a fresh shell; --now hands off to a detached updater that waits for this process to exit. To CHANGE extras or install from GitHub, use reinstall instead.

Parameters:

  • --now: on Windows, hand off to a detached updater instead of printing the cmd [default: False]

saitenka reinstall

saitenka reinstall [OPTIONS]

Reinstall to CHANGE your extras or source, preserving what's installed. A bare uv tool install --reinstall replaces the extras set (silently dropping deinflect/telemetry); this detects what's installed and keeps it. From PyPI, falling back to GitHub (which also carries the GPL deinflect add-on). The GitHub attempt targets the latest RELEASE tag by default — not bleeding-edge main; pass --ref main for that, or --ref vX.Y.Z to pin a release. For a plain "get the latest" with no extras change, prefer update.

Parameters:

  • --source: where to reinstall from (auto = PyPI, fall back to GitHub) [choices: auto, pypi, github] [default: auto]
  • --ref: GitHub tag/branch to install (e.g. v0.5.0 or main); implies --source github. Default: the latest RELEASE tag, falling back to main
  • --now: on Windows, hand off to a detached updater instead of printing the cmd [default: False]
  • --yes: don't prompt; just run the reinstall [default: False]

saitenka uninstall

saitenka uninstall [OPTIONS]

Delete saitenka's config, dictionaries, cache/logs, crash reports and mpv plugin. Leaves mpv and ffmpeg installed. Does NOT remove the saitenka binary itself — the last line tells you how.

Parameters:

  • --yes: don't prompt; delete without confirming [default: False]
  • --keep-dicts: keep the (expensive) dictionary DB; remove everything else [default: False]

saitenka report

saitenka report [OPTIONS]

Bundle diagnostics (doctor + versions + config + mpv.conf + plugin lua + log) into a single timestamped zip for bug reports. Local-only, never uploaded; secrets are redacted.

Parameters:

  • --out: directory to write the zip into (default: the data dir's reports/)
  • --no-log: exclude the overlay log (may contain video filenames / mined sentences) [default: False]

saitenka setup

saitenka setup [OPTIONS]

One-command setup (alias: install): inventory → install mpv+ffmpeg → doctor → init → import → plugin. Re-run any time to reconfigure — it's resumable and confirm-first.

Parameters:

  • --yes: answer yes to every prompt [default: False]
  • --dry-run: show what would happen, change nothing [default: False]

saitenka attach

saitenka attach [OPTIONS] [ARGS]

Attach to an already-running mpv's IPC socket instead of launching mpv.

mpv accepts multiple concurrent IPC clients, so we JOIN a socket shared with mpv_websocket/animecards rather than take it over. On attach we actively select the Japanese subtitle track (the user's mpv may prefer English), fetching from jimaku when asked.

Parameters:

  • SOCKET, --socket:
  • --config:
  • --slang: preferred (JP) sub languages, priority order [default: ja,jpn,jp]
  • --sub-file: external subtitle file to add + select
  • --jimaku: fetch JP subs from jimaku.cc when none present [default: False]
  • --jimaku-force: force jimaku.cc subs AHEAD of the embedded JP track (for mistimed/wrong baked-in subs); falls back to the embedded track if the fetch fails. Implies --jimaku [default: False]
  • --jimaku-key: jimaku.cc API key (else $JIMAKU_API_KEY)
  • --jimaku-title: override the title parsed from the filename
  • --episode: override the episode parsed from the filename
  • --resync, --no-resync: resync jimaku subs (default: on) [default: True]