# Usage > [!IMPORTANT] > SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work. > See [Yomitan setup](#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 ```bash # 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=` 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 ...`): ```ini [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](/configuration) for customization. By default, hovering over subtitle text pauses mpv playback. Playback resumes as soon as the cursor leaves subtitle text. Set `subtitleStyle.autoPauseVideoOnHover` to `false` to disable this behavior. If you want playback to stay paused while a Yomitan popup is open, set `subtitleStyle.autoPauseVideoOnYomitanPopup` to `true`. When enabled, SubMiner auto-resumes on popup close only if SubMiner paused playback for that popup. Keyboard-driven lookup mode is available with fixed shortcuts: `Ctrl/Cmd+Shift+Y` toggles token-selection mode, `ArrowLeft/Right` (or `H/L`) moves the selected token, and `Ctrl/Cmd+Y` opens or closes lookup for that token. If the Yomitan popup is open, you can control it directly from the overlay without moving focus into the popup: `J/K` or `ArrowUp/ArrowDown` scroll definitions, `M` mines/adds the selected term, `P` plays term audio, `[` plays the previous available audio, and `]` plays the next available audio in the selected source. While lookup stays open, `ArrowLeft/Right` (or `H/L`) moves to the previous or next token and refreshes the definition for the new token. If you move past the start or end of the current subtitle line, SubMiner jumps to the previous or next subtitle line, moves the selector to the edge token on that line, and keeps playback paused if it was already paused. ### 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