SubMiner

An all-in-one sentence mining overlay for MPV with AnkiConnect and dictionary (Yomitan) integration.

Features

• Real-time subtitle display from MPV via IPC socket
• Yomitan integration for fast, on-screen lookups
• Japanese text tokenization using MeCab with smart word boundary detection
• Integrated texthooker-ui server for use with Yomitan
• Integrated websocket server (if mpv_websocket is not found) to send lines to the texthooker
• AnkiConnect integration for automatic card creation with media (audio/image)

Demo

Requirements

• mpv with IPC socket support
• mecab and mecab-ipadic (recommended for Japanese tokenization)
• Linux: Hyprland (hyprctl) or X11 (xdotool + xwininfo)
• macOS: Accessibility permission for window tracking

Optional but recommended: yt-dlp, fzf, rofi, chafa, ffmpegthumbnailer.

Install

Linux (AppImage)

wget https://github.com/sudacode/subminer/releases/download/v1.0.0/subminer-1.0.0.AppImage -O ~/.local/bin/subminer.AppImage
chmod +x ~/.local/bin/subminer.AppImage
wget https://github.com/sudacode/subminer/releases/download/v1.0.0/subminer -O ~/.local/bin/subminer
chmod +x ~/.local/bin/subminer

subminer uses a Bun shebang, so bun must be on PATH.

From source

git clone https://github.com/sudacode/subminer.git
cd subminer
make build
make install

For macOS app bundle / signing / permissions details, use docs/installation.md.

Quick Start

1. Copy and customize config.example.jsonc to $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc if XDG_CONFIG_HOME is unset).
2. Start mpv with IPC enabled:

mpv --input-ipc-server=/tmp/subminer-socket video.mkv

3. Launch SubMiner:

subminer video.mkv
# or
subminer https://youtu.be/...

Common Commands

subminer                          # pick video from current dir (fzf)
subminer -R                       # use rofi picker
subminer -d ~/Videos              # set source directory
subminer -r -d ~/Anime            # recursive search
subminer video.mkv                # launch with default mpv profile (subminer)
subminer -p gpu-hq video.mkv      # override mpv profile
subminer -T video.mkv             # disable texthooker

MPV Plugin (Optional)

cp plugin/subminer.lua ~/.config/mpv/scripts/
cp plugin/subminer.conf ~/.config/mpv/script-opts/

Requires mpv IPC: --input-ipc-server=/tmp/subminer-socket

Default chord prefix: y (y-y menu, y-s start, y-S stop, y-t toggle visible layer). Overlay Jimaku shortcut default: Ctrl+Alt+J (shortcuts.openJimaku).

Documentation

Detailed guides live in docs/:

• Installation
• Usage
• Configuration
• Development
• Architecture (includes OverlayManager state ownership and deps wiring rules)

Third-Party Components

This project includes the following third-party components:

• Yomitan - GPL-3.0
• texthooker-ui - MIT

Acknowledgments

This project was inspired by GameSentenceMiner's subtitle overlay and Yomitan integration

License

GNU General Public License v3.0. See LICENSE.