SubMiner/docs/usage.md

Usage

Important

SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work. See Yomitan setup for details.

There are two ways to use SubMiner — the subminer wrapper script or the mpv plugin:

Approach	Best For
subminer script	All-in-one solution. Handles video selection, launches MPV with the correct socket, and manages app commands. With default plugin settings, overlay auto-starts visible and playback resumes after annotation readiness.
MPV plugin	When you launch MPV yourself or from other tools. Provides in-MPV chord keybindings (e.g. y-y for menu) to control overlay visibility. Requires --input-ipc-server=/tmp/subminer-socket.

You can use both together—install the plugin for on-demand control, but use subminer when you want the streamlined workflow.

subminer is implemented as a Bun script and runs directly via shebang (no bun run needed), for example: subminer video.mkv.

Live Config Reload

While SubMiner is running, it watches your active config file and applies safe updates automatically.

Live-updated settings:

• subtitleStyle
• keybindings
• shortcuts
• secondarySub.defaultMode
• ankiConnect.ai

Invalid config edits are rejected; SubMiner keeps the previous valid runtime config and shows an error notification. For restart-required sections, SubMiner shows a restart-needed notification.

Commands

# Browse and play videos
subminer                          # Current directory (uses fzf)
subminer -R                       # Use rofi instead of fzf
subminer -d ~/Videos              # Specific directory
subminer -r -d ~/Anime            # Recursive search
subminer video.mkv                # Play specific file (default plugin config auto-starts visible overlay)
subminer --start video.mkv        # Optional explicit overlay start (use when plugin auto_start=no)
subminer -S video.mkv             # Same as above via --start-overlay
subminer https://youtu.be/...     # Play a YouTube URL
subminer ytsearch:"jp news"       # Play first YouTube search result
subminer --log-level debug video.mkv # Enable verbose logs for launch/debugging
subminer --log-level warn video.mkv  # Set logging level explicitly

# Options
subminer -T video.mkv             # Disable texthooker server
subminer -b x11 video.mkv         # Force X11 backend
subminer video.mkv                # Uses mpv profile "subminer" by default
subminer -p gpu-hq video.mkv      # Override mpv profile
subminer jellyfin                 # Open Jellyfin setup window (subcommand form)
subminer jellyfin -l --server http://127.0.0.1:8096 --username me --password 'secret'
subminer jellyfin --logout        # Clear stored Jellyfin token/session data
subminer jellyfin -p              # Interactive Jellyfin library/item picker + playback
subminer jellyfin -d              # Jellyfin cast-discovery mode (background tray app)
subminer app --stop               # Stop background app (including Jellyfin cast broadcast)
subminer doctor                   # Dependency + config + socket diagnostics
subminer config path              # Print active config path
subminer config show              # Print active config contents
subminer mpv socket               # Print active mpv socket path
subminer mpv status               # Exit 0 if socket is ready, else exit 1
subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
subminer texthooker               # Launch texthooker-only mode
subminer app --anilist            # Pass args directly to SubMiner binary (example: AniList login flow)
subminer yt -o ~/subs https://youtu.be/...  # YouTube subcommand: output directory shortcut
subminer yt --mode preprocess --whisper-bin /path/to/whisper-cli --whisper-model /path/to/model.bin https://youtu.be/...  # Pre-generate subtitle tracks before playback

# Direct AppImage control
SubMiner.AppImage --background             # Start in background (tray + IPC wait, minimal logs)
SubMiner.AppImage --start --texthooker   # Start overlay with texthooker
SubMiner.AppImage --texthooker           # Launch texthooker only (no overlay window)
SubMiner.AppImage --stop                  # Stop overlay
SubMiner.AppImage --start --toggle        # Start MPV IPC + toggle visibility
SubMiner.AppImage --show-visible-overlay              # Force show visible overlay
SubMiner.AppImage --hide-visible-overlay              # Force hide visible overlay
SubMiner.AppImage --start --dev                         # Enable app/dev mode only
SubMiner.AppImage --start --debug                       # Alias for --dev
SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
SubMiner.AppImage --settings              # Open Yomitan settings
SubMiner.AppImage --jellyfin              # Open Jellyfin setup window
SubMiner.AppImage --jellyfin-login --jellyfin-server http://127.0.0.1:8096 --jellyfin-username me --jellyfin-password 'secret'
SubMiner.AppImage --jellyfin-logout       # Clear stored Jellyfin token/session data
SubMiner.AppImage --jellyfin-libraries
SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search anime --jellyfin-limit 20
SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2  # Requires connected mpv IPC (--start or plugin workflow)
SubMiner.AppImage --jellyfin-remote-announce  # Force cast-target capability announce + visibility check
SubMiner.AppImage --help                  # Show all options

Logging and App Mode

• --log-level controls logger verbosity.
• --dev and --debug are app/dev-mode switches; they are not log-level aliases.
• --background defaults to quieter logging (warn) unless --log-level is set.
• --background launched from a terminal detaches and returns the prompt; stop it with tray Quit or SubMiner.AppImage --stop.
• Linux desktop launcher starts SubMiner with --background by default (via electron-builder linux.executableArgs).
• On Linux, the app now defaults safeStorage to gnome-libsecret for encrypted token persistence. Launcher pass-through commands also support --password-store=<backend> and forward it to the app when present. Override with e.g. --password-store=basic_text.
• Use both when needed, for example SubMiner.AppImage --start --dev --log-level debug.

Launcher Subcommands

• subminer jellyfin / subminer jf: Jellyfin-focused workflow aliases.
• subminer yt / subminer youtube: YouTube-focused shorthand flags (-o, -m).
• subminer doctor: health checks for core dependencies and runtime paths.
• subminer config: config helpers (path, show).
• subminer mpv: mpv helpers (status, socket, idle).
• subminer texthooker: texthooker-only shortcut (same behavior as --texthooker).
• subminer app / subminer bin: direct passthrough to the SubMiner binary/AppImage.
• Subcommand help pages are available (for example subminer jellyfin -h, subminer yt -h).

Use subcommands for Jellyfin/YouTube command families (subminer jellyfin ..., subminer yt ...). Top-level launcher flags like --jellyfin-* and --yt-subgen-* are intentionally rejected.

MPV Profile Example (mpv.conf)

subminer passes the following MPV options directly on launch by default:

• --input-ipc-server=/tmp/subminer-socket (or your configured socket path)
• --alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
• --slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
• --sub-auto=fuzzy
• --sub-file-paths=.;subs;subtitles
• --sid=auto
• --secondary-sid=auto
• --secondary-sub-visibility=no

You can define a matching profile in ~/.config/mpv/mpv.conf for consistency when launching mpv manually or from other tools. subminer launches with --profile=subminer by default (or override with subminer -p <profile> ...):

[subminer]
# IPC socket (must match SubMiner config)
input-ipc-server=/tmp/subminer-socket

# Prefer JP/EN audio + subtitle language variants
alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us

# Auto-load external subtitles
sub-auto=fuzzy
sub-file-paths=.;subs;subtitles

# Select primary + secondary subtitle tracks automatically
sid=auto
secondary-sid=auto
secondary-sub-visibility=no

secondary-slang is not an mpv option; use slang with sid=auto / secondary-sid=auto instead.

Yomitan setup

SubMiner includes a bundled Yomitan extension for overlay word lookup. This bundled extension is separate from any Yomitan browser extension you may have installed.

For SubMiner overlay lookups to work, open Yomitan settings (subminer app --settings or SubMiner.AppImage --settings) and import at least one dictionary in the bundled Yomitan instance.

If you also use Yomitan in a browser, configure that browser profile separately; it does not inherit dictionaries or settings from the bundled instance.

YouTube Playback

subminer accepts direct URLs (for example, YouTube links) and ytsearch: targets, and forwards them to mpv.

Notes:

• Install yt-dlp so mpv can resolve YouTube streams and subtitle tracks reliably.
• subminer supports three subtitle-generation modes for YouTube URLs:
  • automatic (default): starts playback immediately, generates subtitles in the background, and loads them into mpv when ready.
  • preprocess: generates subtitles first, then starts playback with generated .srt files attached.
  • off: disables launcher generation and leaves subtitle handling to mpv/yt-dlp.
• Primary subtitle target languages come from youtubeSubgen.primarySubLanguages (defaults to ["ja","jpn"]).
• Secondary target languages come from secondarySub.secondarySubLanguages (defaults to English if unset).
• subminer prefers subtitle tracks from yt-dlp first, then falls back to local whisper.cpp (whisper-cli) when tracks are missing.
• Whisper translation fallback currently only supports English secondary targets; non-English secondary targets rely on yt-dlp subtitle availability.
• Configure defaults in $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) under youtubeSubgen and secondarySub, or override mode/tool paths via CLI flags/environment variables.

Keybindings

Global Shortcuts

Keybind	Action
Alt+Shift+O	Toggle visible overlay
Alt+Shift+Y	Open Yomitan settings

Alt+Shift+Y is a fixed global shortcut; it is not part of shortcuts config.

Overlay Controls (Configurable)

Input	Action
Space	Toggle MPV pause
ArrowRight	Seek forward 5 seconds
ArrowLeft	Seek backward 5 seconds
ArrowUp	Seek forward 60 seconds
ArrowDown	Seek backward 60 seconds
Shift+H	Jump to previous subtitle
Shift+L	Jump to next subtitle
Ctrl+Shift+H	Replay current subtitle (play to end, then pause)
Ctrl+Shift+L	Play next subtitle (jump, play to end, then pause)
Q	Quit mpv
Ctrl+W	Quit mpv
Right-click	Toggle MPV pause (outside subtitle area)
Right-click + drag	Move subtitle position (on subtitle)
Ctrl/Cmd+A	Append clipboard video path to MPV playlist

These keybindings only work when the overlay window has focus. See Configuration for customization.

By default, hovering over subtitle text pauses mpv playback and leaving the subtitle area resumes playback. Set subtitleStyle.autoPauseVideoOnHover to false to disable this behavior.

Drag-and-drop Queueing

• Drag and drop one or more video files onto the overlay to replace current playback (loadfile ... replace for first file, then append remainder).
• Hold Shift while dropping to append all dropped files to the current MPV playlist.

How It Works

1. MPV runs with an IPC socket at /tmp/subminer-socket
2. The overlay connects and subscribes to subtitle changes
3. Subtitles are tokenized with Yomitan's internal parser
4. Words are displayed as clickable spans
5. Clicking a word triggers Yomitan popup for dictionary lookup
6. Texthooker server runs at http://127.0.0.1:5174 for external tools