sudacode
887de056c5
- Consolidate requirements into a single table with status column - Rewrite installation.md as a numbered 3-step guide - Remove verbose platform-specific notes; fold essentials into platform sections - Trim README quick-start to minimal install/launch commands
9.6 KiB
SubMiner
Integrates Yomitan with mpv - look up words, mine to Anki, and track your immersion without leaving the player.
Installation · Requirements · Usage · Documentation
Features
Dictionary Lookups
Yomitan runs inside the overlay. Trigger a lookup on any word for full dictionary popups — definitions, pitch accent, 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. Known words fade back; new words stand out. Grammar-only tokens render as plain text so you focus on what matters.
Immersion Dashboard
Local stats dashboard — watch time, anime library, 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 |
| alass / ffsubsync | Automatic subtitle retiming — requires alass or ffsubsync on your PATH (optional; subtitle syncing is disabled without them) |
| WebSocket | Annotated subtitle feed for external clients (texthooker pages, custom tools) |
Requirements
Only mpv is required. Everything else is optional but enhances the experience.
| Dependency | Status | What it does |
|---|---|---|
| mpv | Required | The video player SubMiner overlays on |
| ffmpeg | Recommended | Audio clips & screenshots for Anki cards |
| MeCab + mecab-ipadic | Recommended | More precise N+1, JLPT, and frequency annotations |
| yt-dlp | Optional | YouTube playback |
| fzf / rofi | Optional | Video picker in the launcher |
| alass / ffsubsync | Optional | Subtitle sync |
Platform-specific install commands
Arch Linux:
sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic
macOS:
brew install mpv ffmpeg mecab mecab-ipadic
Windows: Install mpv and ffmpeg and ensure both are on PATH.
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
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 (AUR)
subminer app --setup
# macOS — open SubMiner.app, or:
subminer app --setup
On Windows, just run SubMiner.exe — setup opens automatically on first launch.
3. Play
subminer video.mkv # play video with overlay
subminer stats # open immersion dashboard
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 |
|---|---|
| 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 |