SubMiner
Look up words with Yomitan, mine them to Anki, and track your immersion without leaving mpv
Installation · Requirements · Usage · Documentation
Features
Dictionary Lookups
Hover over any word in the subtitles to open the full Yomitan popup with definitions, pitch accent, and frequency data. SubMiner bundles its own Yomitan, separate from any browser install.
Instant Anki Mining
Create an Anki card from the exact playback moment with one key press, click, or controller input. SubMiner fills in the sentence, an audio clip, and a screenshot or animated image.
Reading Annotations
Subtitles are annotated as they play with frequency highlighting, JLPT tags, N+1 targeting, and character names from a generated dictionary. Particles and grammar-only tokens stay plain so the words worth learning stand out.
Immersion Dashboard
A stats dashboard tracks watch time, vocabulary growth, mining throughput, session history, and trends. Everything stays on your machine, with no third-party tracking.
Integrations
| YouTube | Play YouTube URLs with subtitle tracks picked by your language priorities, or choose tracks yourself in the overlay picker (Ctrl+Alt+C). Requires yt-dlp |
| AniList | Automatic episode tracking and progress sync |
| Jellyfin | Browse your Jellyfin library, or cast to SubMiner from any Jellyfin client. Setup and discovery live in the tray menu |
| Jimaku | Search and download Japanese subtitles. Requires a free Jimaku API key |
| TsukiHime | Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (Ctrl+Shift+T). Requires xz on your PATH |
| Subtitle generation | Transcribe a video's audio into Japanese subtitles locally from the generation modal (Ctrl+Shift+G), the subtitle sidebar, or the launcher. SubMiner can download models for you; optional Silero speech detection helps focus on dialogue. Requires whisper.cpp and FFmpeg. Setup guide |
| AniSkip | Automatic intro detection with chapter markers and a one-key skip (TAB by default) |
| alass / ffsubsync | Retime a subtitle against the audio or another subtitle track (Ctrl+Alt+S). Requires alass or ffsubsync; set subsync.alass_path or subsync.ffsubsync_path if they are not in /usr/bin |
| WebSocket | Plain subtitle feed plus a dedicated annotated feed for texthooker pages and custom tools |
Requirements
SubMiner runs on Linux, macOS 11+, and Windows 10+. Only mpv is required to run it (plus fuse2 for the Linux AppImage). Mining cards also needs Anki with the AnkiConnect add-on. Everything else is optional.
| Dependency | Status | What it does |
| ------------------------ | ---------------- | -------------------------------------------------------------------- |
| mpv | Required | The video player SubMiner draws over |
| fuse2 | Required (Linux) | Running the AppImage |
| Anki + AnkiConnect | Required to mine | Card creation from the Yomitan popup |
| ffmpeg | Recommended | Audio clips and screenshots on cards |
| MeCab + mecab-ipadic | Recommended | More accurate N+1, JLPT, and frequency highlighting |
| xdotool + xwininfo | Required (X11) | Window tracking on desktops other than Hyprland or Sway |
| yt-dlp | Optional | YouTube playback |
| xz | Optional | TsukiHime subtitle downloads (most Linux distros already have it) |
| alass / ffsubsync | Optional | Subtitle sync |
| whisper.cpp | Optional | Subtitle generation |
| guessit | Optional | Better title, season, and episode detection for AniSkip and AniList |
| fzf / rofi | Optional | Video picker in the subminer launcher (rofi is Linux only) |
| chafa, ffmpegthumbnailer | Optional | Thumbnail previews in the launcher pickers |
Platform-specific install commands
Arch Linux:
sudo pacman -S --needed mpv ffmpeg
paru -S --needed mecab-git mecab-ipadic # MeCab is only in the AUROn desktops other than Hyprland or Sway, also install xdotool and xorg-xwininfo.
macOS:
brew install mpv ffmpeg mecab mecab-ipadicWindows:
winget install shinchiro.mpv
winget install Gyan.FFmpegThen reopen your terminal and check mpv --version and ffmpeg -version. ffmpeg must be on PATH; mpv does not have to be. If mpv is not found, either add its folder (usually %LOCALAPPDATA%\Programs\mpv) to PATH or enter the full path to mpv.exe during first-run setup.
Scoop is the alternative if you want one package manager for everything. It is the only one that also carries xz:
scoop bucket add extras
scoop install extras/mpv main/ffmpeg main/yt-dlp main/xzSee the installation guide for Ubuntu, Debian, and Fedora commands and the full optional package lists.
Quick Start
1. Install SubMiner
Arch Linux (AUR)
paru -S subminer-binIncludes the AppImage and the subminer command.
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.AppImageThe AppImage is all you need. First-run setup can install the optional subminer command, which runs on a copy of Bun bundled with the app, so you do not need Bun installed.
macOS (DMG)
Download the latest DMG from GitHub Releases and drag SubMiner.app into /Applications.
Then enable SubMiner under System Settings > Privacy & Security > Accessibility, or the overlay cannot follow the mpv window. If macOS blocks the first launch, right-click the app and choose Open.
Windows
Download and run the latest installer (SubMiner-) from GitHub Releases. A portable .zip is also available.
From source
See the build-from-source guide.
2. Launch & Set Up
Start SubMiner and the setup window opens on first launch. It creates your config file, imports Yomitan dictionaries (you need at least one for lookups), and can install the subminer command. On Windows it also creates a SubMiner mpv shortcut.
subminer app --setup # AUR
~/.local/bin/SubMiner.AppImage --setup # AppImageOn macOS, open SubMiner.app from /Applications. On Windows, run SubMiner from the Start menu. To reopen setup later, run subminer app --setup.
For card creation, keep Anki open with AnkiConnect installed. SubMiner connects to it at its default address with no extra setup.
3. Mine
subminer video.mkv # play a video 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 # watch history: replay, next, or previous episode
subminer doctor # check your setupOn Windows, double-click the SubMiner mpv shortcut or drag a video file onto it.
Starting mpv some other way? See Launching mpv yourself for the IPC socket option the overlay needs.
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 |
| Bun | Bundled runtime for the subminer command-line launcher |
| 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
SubMiner is released under the GNU General Public License v3.0.
Release packages also bundle an unmodified copy of Bun, which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under resources/bun/licenses, and each release publishes bun-v1.3.5-source.tar.gz with the corresponding source. See Bundled Bun runtime.