Hover to look up — Yomitan dictionary popups directly on subtitles
Keyboard-driven lookup mode — Navigate token-by-token, keep lookup open across tokens, and control popup scrolling/audio/mining without leaving the overlay
One-key mining — Creates Anki cards with sentence, audio, screenshot, and translation
Instant auto-enrichment — Optional local AnkiConnect proxy enriches new Yomitan cards immediately
Reading annotations — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read
Hover-aware playback — By default, hovering subtitle text pauses mpv and resumes on mouse leave (subtitleStyle.autoPauseVideoOnHover)
Subtitle tools — Download from Jimaku, sync with alass/ffsubsync
Immersion tracking — SQLite-powered stats on your watch time and mining activity
Custom texthooker page — Built-in custom texthooker page and websocket, no extra setup
Annotated websocket API — Dedicated annotation feed can serve bundled texthooker or external clients with rendered sentence HTML plus structured tokens
Jellyfin integration — Remote playback setup, cast device mode, and direct playback launch
AniList progress — Track episode completion and push watching progress automatically

Quick start

1. Install

Linux (AppImage):

wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
chmod +x ~/.local/bin/SubMiner.AppImage
wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
chmod +x ~/.local/bin/subminer

Note

The subminer wrapper uses a Bun shebang. Make sure bun is on your PATH.

macOS (DMG/ZIP): download the latest packaged build from GitHub Releases and drag SubMiner.app into /Applications.

Windows (Installer/ZIP): download the latest SubMiner-<version>.exe installer or portable .zip from GitHub Releases. Keep mpv installed and available on PATH.

From source — initialize submodules first (git submodule update --init --recursive). Bundled Yomitan is built from the vendor/subminer-yomitan submodule into build/yomitan during bun run build, so source builds only need Bun for the JS toolchain. Packaged macOS and Windows installs do not require Bun. Windows installer builds go through electron-builder; its bundled app-builder-lib NSIS templates already use the third-party WinShell plugin for shortcut AppUserModelID assignment, and the WinShell.dll binary is supplied by electron-builder's cached nsis-resources bundle, so bun run build:win does not need a separate repo-local plugin install step. Full install guide: docs.subminer.moe/installation#from-source.

2. Launch the app once

# Linux
SubMiner.AppImage

On macOS, launch SubMiner.app. On Windows, launch SubMiner.exe from the Start menu or install directory.

On first launch, SubMiner now:

starts in the tray/background
creates the default config directory and config.jsonc
opens a compact setup popup
can install the mpv plugin to the default mpv scripts location for you
links directly to Yomitan settings so you can install dictionaries before finishing setup

Existing installs that already have a valid config plus at least one Yomitan dictionary are auto-detected as complete and will not be re-prompted.

3. Finish setup

click Install mpv plugin if you want the default plugin auto-start flow
click Open Yomitan Settings and install at least one dictionary
click Refresh status
click Finish setup

The mpv plugin step is optional. Yomitan must report at least one installed dictionary before setup can be completed.

4. Mine

subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready
subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no

Requirements

Required	Optional
`bun` (source builds, Linux `subminer`)
`mpv` with IPC socket	`yt-dlp`
`ffmpeg`	`guessit` (better AniSkip title/episode detection)
`mecab` + `mecab-ipadic`	`fzf` / `rofi`
Linux: `hyprctl` or `xdotool` + `xwininfo`	`chafa`, `ffmpegthumbnailer`
macOS: Accessibility permission

Windows builds use native window tracking and do not require the Linux compositor helper tools.

Documentation

For full guides on configuration, Anki, Jellyfin, and more, see docs.subminer.moe.

Testing

Run bun run test or bun run test:fast for the default fast lane: config/core coverage plus representative entry/runtime, Anki integration, and main runtime checks.
Run bun run test:full for the maintained test surface: Bun-compatible src/** coverage, Bun-compatible launcher unit coverage, and the maintained dist compatibility slice for ipc, anki-jimaku-ipc, overlay-manager, config-validation, startup-config, and runtime registry coverage.
Run bun run test:node:compat directly when you only need that dist compatibility slice. The command name is legacy; it now runs under Bun.
Run bun run test:env for environment-specific verification: launcher smoke/plugin checks plus the SQLite-backed immersion tracker lane.
Run bun run test:immersion:sqlite when you specifically need the dist SQLite persistence coverage.
Run bun run test:subtitle for the maintained alass/ffsubsync subtitle surface.

The Bun-managed discovery lanes intentionally exclude a small set of suites from the source-file discovery pass and keep them in the maintained dist compatibility slice instead: Electron-focused tests in src/core/services/ipc.test.ts, src/core/services/anki-jimaku-ipc.test.ts, and src/core/services/overlay-manager.test.ts, plus runtime/config tests in src/main/config-validation.test.ts, src/main/runtime/startup-config.test.ts, and src/main/runtime/registry.test.ts. bun run test:node:compat keeps those suites in the standard workflow instead of leaving them untracked.

Acknowledgments

Built on the shoulders of GameSentenceMiner, Renji's Texthooker Page, mpvacious, Anacreon-Script, and Bee's Character Dictionary. Subtitles powered by Jimaku.cc. Dictionary lookups via Yomitan.

License

GNU General Public License v3.0

Languages

TypeScript 94.9%

Lua 2.2%

CSS 1%

Shell 0.8%

JavaScript 0.3%

Other 0.6%