SubMiner

Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.

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

	Required	Recommended	Optional
Player	mpv with IPC socket	—	—
Processing	—	ffmpeg (audio clips & screenshots)	mecab + mecab-ipadic (annotation POS filtering), guessit (AniSkip), alass / ffsubsync (subtitle sync)
Media	—	—	yt-dlp, chafa, ffmpegthumbnailer
Selection	—	—	fzf / rofi

Tip

ffmpeg is not strictly required to run SubMiner, but without it audio clips and screenshots will not be attached to Anki cards. Most users will want it installed.

Note

bun is required if building from source or using the CLI wrapper: subminer. Pre-built releases (AppImage, DMG, installer) do not require it.

Platform-specific:

Linux	macOS	Windows
Hyprland (hyprctl) · X11/Xwayland (xdotool + xwininfo)	Accessibility permission	No extra deps

Note

Wayland support is compositor-specific. Wayland has no universal API for window positioning and each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Hyprland is the only native Wayland backend supported currenlty. All other Linux compositors require both mpv and SubMiner to run under X11 or Xwayland. The launcher detects your compositor and configures this automatically.

Arch Linux

paru -S --needed mpv ffmpeg
# Optional
paru -S --needed mecab-git mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
# Optional: subtitle sync (install at least one for subtitle syncing to work)
paru -S --needed alass python-ffsubsync
# X11 / Xwayland (required for non-Hyprland compositors)
paru -S --needed xdotool xorg-xwininfo

macOS

brew install mpv ffmpeg
# Optional
brew install mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
# Optional: subtitle sync (install at least one for subtitle syncing to work)
brew install alass
pip install ffsubsync

Grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.

Windows

Install mpv and ffmpeg and ensure both are on your PATH.

Optionally install MeCab for Windows with the UTF-8 dictionary for additional metadata enrichment.

---

Quick Start

1. Install

Arch Linux (AUR)

paru -S subminer-bin

Or manually:

git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si

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

Note

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

macOS

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

Also download the subminer launcher (recommended):

sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer \
	&& sudo chmod +x /usr/local/bin/subminer

Note

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

Windows

Download the latest installer or portable .zip from GitHub Releases. Make sure mpv is on your PATH.

Windows support is experimental. Core features such as mining, annotations, and dictionary lookups work, but some functionality may be missing or unstable. Bug reports welcome.

Note: On Windows the subminer launcher requires bun and must be invoked with bun run subminer instead of running the script directly. The recommended alternative is the SubMiner mpv shortcut created during first-run setup — double-click it, drag files onto it, or run SubMiner.exe --launch-mpv from a terminal. See the Windows mpv Shortcut section for details.

From source

See the build-from-source guide.

2. First Launch

subminer app --setup            # launch the first-run setup wizard

SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing the mpv plugin and configuring Yomitan dictionaries. Follow the on-screen steps to complete setup.

Jellyfin setup is available from the tray or subminer jellyfin; once Jellyfin is enabled with a server URL, the tray can toggle Jellyfin Discovery for the current app session.

Note

On Windows, run SubMiner.exe directly — it opens the setup wizard automatically on first launch.

3. Verify Setup

subminer doctor                 # verify mpv, ffmpeg, config, and socket

Note

On Windows, use bun run subminer doctor or run SubMiner.exe directly — first-run setup will guide you through dependency checks.

4. Mine

subminer video.mkv          # play video with overlay
subminer --start video.mkv  # explicit overlay start
subminer stats              # open immersion dashboard
subminer stats -b           # stats daemon in background
subminer stats -s           # stop background stats daemon

On Windows, the subminer script must be run with bun run subminer (e.g. bun run subminer video.mkv). The recommended alternative is the SubMiner mpv shortcut (created during setup) or SubMiner.exe --launch-mpv. Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.

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

License

GNU General Public License v3.0