SubMiner

Look up words, mine to Anki, and enrich cards with context — without leaving mpv.

What it does

SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:

• 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
• 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:

• 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

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.

Acknowledgments

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

License

GNU General Public License v3.0