mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-05-26 00:55:16 -07:00

Files

T

add app control server for launcher-to-app attachment

- Launcher detects a running app via control socket and attaches without spawning a new process
- Own-lifecycle app launches now pass --background --managed-playback; borrowed apps skip --background
- Separate plain subtitle websocket (tokens: []) from annotation websocket
- Default pauseVideoOnHover to true; update docs and config.example.jsonc
- Setup: remove plugin readiness card, add Open SubMiner Settings button

2026-05-21 01:32:58 -07:00

9.6 KiB

Raw Blame History

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.

Anki card created from SubMiner with sentence, audio, and screenshot

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.

Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets

Immersion Dashboard

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

Stats dashboard showing watch time, cards mined, streaks, and tracking data

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	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

Texthooker page receiving annotated subtitle lines via WebSocket

Requirements

Only mpv and Anki+AnkiConnect is required. Everything else is optional but enhances the experience

Dependency	Status	What it does
mpv	Required	The video player SubMiner overlays on
Anki + AnkiConnect	Required	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
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
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)

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

License

GNU General Public License v3.0

9.6 KiB Raw Blame History