SubMiner/README.md

SubMiner

Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersion without leaving the player

Installation · Requirements · Usage · Documentation

Features

Dictionary Lookups

Hover over any word and trigger a lookup to get the full Yomitan popup - definitions, pitch accent, and frequency data - without ever leaving mpv.

Instant Anki Mining

Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.

Reading Annotations

Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Grammar-only tokens and particles render as plain text so you focus on what matters.

Immersion Dashboard

Local stats dashboard tracking watch time, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.

Playlist Browser

Browse sibling episode files and the active mpv queue in one overlay modal. Open it with Ctrl+Alt+P to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.

Integrations

YouTube	Auto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (Ctrl+Alt+C)
AniList	Automatic episode tracking and progress sync
Jellyfin	Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray
Jimaku	Search and download Japanese subtitles
TsukiHime	Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (Ctrl+Shift+T) — no API key, requires xz on your PATH
AniSkip	Automatic intro detection with chapter markers and a one-key skip (TAB by default)
alass / ffsubsync	Manual subtitle retiming — requires alass or ffsubsync on your PATH (optional; subtitle syncing is disabled without them)
WebSocket	Plain subtitle feed plus a dedicated annotated feed for texthooker pages and custom tools

---

Requirements

Only mpv is required to run SubMiner. Anki + AnkiConnect are required to mine cards, which is the point of the app, but everything else is optional.

Dependency	Status	What it does
mpv	Required	The video player SubMiner overlays on
Anki + AnkiConnect	Required to mine	Card creation from the Yomitan popup
ffmpeg	Recommended	Audio clips & screenshots for Anki cards
MeCab + mecab-ipadic	Recommended	More precise annotations and filtering
yt-dlp	Optional	YouTube playback
xz	Optional	TsukiHime subtitle downloads (not on Windows by default)
alass / ffsubsync	Optional	Subtitle sync
guessit	Optional	Better anime title and episode detection
fzf / rofi	Optional	Video picker in the subminer launcher (Linux/macOS)

Platform-specific install commands

Arch Linux:

sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic

macOS:

brew install mpv ffmpeg mecab mecab-ipadic

Windows:

winget install shinchiro.mpv
winget install Gyan.FFmpeg

Then reopen your terminal and check mpv --version and ffmpeg -version. winget puts ffmpeg on PATH automatically; mpv uses a regular installer that may not, so if mpv is not found, either add its folder (usually %LOCALAPPDATA%\Programs\mpv) to PATH or set mpv.executablePath during first-run setup.

Scoop is the alternative if you want one package manager for everything, since it is the only one that also carries xz:

scoop bucket add extras
scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz

See the full requirements list for optional dependencies.

---

Quick Start

1. Install SubMiner

Arch Linux (AUR)

paru -S subminer-bin

Linux (AppImage)

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

The AppImage is all you need. The optional subminer command-line launcher runs on Bun, and first-run setup can install both for you. To grab it manually instead, install Bun first, then:

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

macOS (DMG)

Download the latest DMG from GitHub Releases and drag SubMiner.app into /Applications.

Windows

Download and run the latest installer (.exe) from GitHub Releases.

From source

See the build-from-source guide.

2. Launch & Set Up

Run SubMiner and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the subminer command-line launcher.

# Linux
subminer app --setup

# macOS — open SubMiner.app, or:
subminer app --setup

On Windows, just run SubMiner.exe and the setup will open automatically on first launch.

3. Mine

subminer video.mkv          # launch mpv with SubMiner
subminer /path/to/dir       # pick a file with fzf
subminer -R /path/to/dir    # pick a file with rofi (Linux only)
subminer -H                 # browse history, then previous / replay / next / select / quit

On Windows, use the SubMiner mpv shortcut created during setup. Double-click it or drag a video file onto it.

Documentation

Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: docs.subminer.moe

---

Acknowledgments

SubMiner builds on the work of these open-source projects:

Project	Role
ani-skip	AniSkip API client for anime intro/outro skip timestamps
Anacreon-Script	Inspiration for the mining workflow
asbplayer	Inspiration for subtitle sidebar and logic for YouTube subtitle parsing
Bee's Character Dictionary	Character name recognition in subtitles
GameSentenceMiner	Inspiration for Electron overlay with Yomitan integration
jellyfin-mpv-shim	Jellyfin integration
Jimaku.cc	Japanese subtitle search and downloads
Renji's Texthooker Page	Base for the WebSocket texthooker integration
Yomitan	Dictionary engine powering all lookups and the morphological parser
yomitan-jlpt-vocab	JLPT level tags for vocabulary

License

GNU General Public License v3.0