sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-09-25 05:16:19 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite docs site pages to be shorter and easier to scan

Browse Source 
- Pages now start with setup and usage, and reference material is in compact tables
- Configuration reference gives each config block a short explanation and a key/default table
- Internal detail removed from user pages, and docs that had drifted from current behavior fixed
- The status line shows today's date, set on the client, instead of the page's last-updated date
- Add changelog fragment
This commit is contained in:
sudacode
2026-09-24 16:20:42 -07:00
parent bc73a02623
commit 8825cca642
29 changed files with 2030 additions and 5392 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs-site/mpv-plugin.md
+72 -140
View File
@@ -1,155 +1,112 @@
# MPV plugin
The SubMiner mpv plugin is a small Lua script that runs _inside_ mpv. It binds in-player keys for controlling the overlay, so start, stop, toggle, and skip-intro all work without leaving the player window.
The SubMiner mpv plugin is a Lua script that runs inside mpv. It adds in-player keys to start, stop, and toggle the overlay, and it runs your SubMiner shortcuts from inside mpv.
Most people never touch it. Any SubMiner-managed launch, whether from the app, the `subminer` launcher, or the Windows shortcut, injects the bundled plugin for that session, and nothing lands in mpv's global `scripts` directory. Keep reading if you launch mpv from some other tool and still want the in-player controls, or you want to script mpv against SubMiner.
## Setup
The plugin is a modular Lua package under `plugin/subminer/`. `main.lua` is the entry point and loads `init.lua` plus its sibling modules. Earlier releases installed a single global `main.lua`; runtime loading replaced that.
You usually do not install anything. Every SubMiner-managed launch (the app, the `subminer` launcher, and the Windows SubMiner mpv shortcut) loads the bundled plugin for that session only. Regular mpv playback is not affected.
## Runtime loading
On Linux, the launcher's copy lives in `$XDG_DATA_HOME/SubMiner/plugin/subminer` (default `~/.local/share/SubMiner/plugin/subminer`), or under `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs. `subminer -u` and the tray updater keep it current.
Launch mpv through the SubMiner app, the `subminer` launcher, or the packaged Windows SubMiner mpv shortcut. These paths pass mpv a bundled plugin path for that playback session only, leaving regular mpv playback untouched.
To use the plugin when mpv is started by another program, load its `main.lua` and enable IPC:
On Linux, the launcher-managed runtime plugin copy lives under the SubMiner data dir (`$XDG_DATA_HOME/SubMiner/plugin/subminer` by default, plus `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs). `subminer -u` and the tray updater keep that managed copy current. This is separate from mpv's global `scripts/` directory.
```bash
mpv --script="$HOME/.local/share/SubMiner/plugin/subminer/main.lua" \
--input-ipc-server=/tmp/subminer-socket video.mkv
```
If setup detects an older global SubMiner plugin in mpv's `scripts` directory, use **Remove legacy mpv plugin** in first-run setup. The global plugin is not needed once runtime loading is available.
mpv must have IPC enabled for SubMiner to connect:
To enable IPC for every mpv session, add it to `mpv.conf`:
```ini
# ~/.config/mpv/mpv.conf
input-ipc-server=/tmp/subminer-socket
```
On Windows, use a named pipe instead:
On Windows, use a named pipe:
```ini
input-ipc-server=\\.\pipe\subminer-socket
```
## Configuration (script-opts)
The plugin reads options from `script-opts` with the `subminer-` prefix (for example `--script-opts=subminer-backend=hyprland`). Managed launches inject these automatically from your SubMiner config; the shipped `subminer.conf` is intentionally empty so command-line opts always win.
| Option | Default | Description |
| -------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `binary_path` | `""` | Path to the SubMiner binary; empty enables [auto-detection](#binary-auto-detection) |
| `socket_path` | platform default | mpv IPC socket path (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows) |
| `texthooker_enabled` | `no` | Start the texthooker server with the overlay |
| `texthooker_port` | `5174` | Texthooker server port |
| `backend` | `auto` | Window backend (`auto`, `hyprland`, `sway`, `x11`, `macos`) |
| `auto_start` | `no` | Start the overlay app on `file-loaded` (managed launches set this from `mpv.autoStartSubMiner`) |
| `auto_start_visible_overlay` | `no` | Show the visible overlay on auto-start (from `auto_start_overlay` in config) |
| `overlay_loading_osd` | `no` | Show an OSD loading spinner while the overlay starts |
| `auto_start_pause_until_ready` | `yes` | Keep mpv paused until the overlay reports tokenization-ready |
| `auto_start_pause_until_ready_timeout_seconds` | `30` | Timeout before resuming playback anyway |
| `osd_messages` | `yes` | Show plugin OSD status messages |
| `log_level` | `info` | Plugin log verbosity |
If first-run setup finds an old SubMiner plugin in mpv's global `scripts` directory, click **Remove legacy mpv plugin**. It is no longer needed.
## Keybindings
Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "chord"):
Most plugin keys are chords: press `y`, then the second key.
| Chord | Action |
| --------------- | -------------------------------------- |
| `y-y` | Open menu |
| `y-s` | Start overlay |
| `y-S` | Stop overlay |
| `y-t` | Toggle visible overlay |
| `y-o` | Open settings window |
| `y-r` | Restart overlay |
| `y-c` | Check status |
| `y-h` | Open session help / keybinding modal |
| `v` | Toggle primary subtitle bar visibility |
| `TAB` (default) | Skip intro (AniSkip) |
| Key | Action |
| ----- | -------------------------------------- |
| `y-y` | Open the SubMiner menu |
| `y-s` | Start the overlay |
| `y-S` | Stop the overlay |
| `y-t` | Toggle the visible overlay |
| `y-o` | Open the settings window |
| `y-r` | Restart the overlay |
| `y-c` | Check status |
| `y-h` | Open the session help modal |
| `v` | Toggle SubMiner's primary subtitle bar |
The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback. See [AniSkip Integration](/aniskip-integration) for setup and details.
`v` replaces mpv's own subtitle visibility toggle.
The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.
The skip-intro key (`TAB` by default) comes from the SubMiner app, not the plugin. See [AniSkip integration](/aniskip-integration).
## Shared shortcuts (session bindings)
The `y-y` menu lists Start overlay, Stop overlay, Toggle overlay, Open options, Restart overlay, Check status, and Stats. Press an item's number to run it. Stats only reminds you to press `` ` `` in the overlay.
The `y-*` chords above are built into the plugin. Everything else you configure under [`shortcuts.*`](/shortcuts) - plus any custom [`keybindings`](/configuration) and the stats toggle/mark-watched keys - is **injected into mpv at runtime**, so the same shortcut works both inside mpv and in the SubMiner overlay. You do not edit any mpv config to enable them.
## Your shortcuts in mpv
How it works:
Everything you set under [`shortcuts`](/shortcuts), your custom `keybindings`, and the stats keys also work while mpv has focus. SubMiner writes them to `session-bindings.json` in its config directory, and the plugin registers them as mpv keys. When you change a shortcut, mpv picks it up immediately.
1. The SubMiner app compiles your configured shortcuts, custom keybindings, and stats keys into a normalized list and writes it to `session-bindings.json` in the SubMiner config directory.
2. On load, the plugin reads that file and registers each entry as a forced mpv key binding, translating each accelerator into the matching mpv key name.
3. When a binding fires, the plugin either runs a SubMiner action (by invoking the SubMiner binary with the corresponding CLI flag, e.g. `--mine-sentence`) or runs a raw mpv command, depending on what the shortcut maps to.
`CommandOrControl` becomes `Cmd` on macOS and `Ctrl` elsewhere. Multi-line copy and mine shortcuts wait for a digit key `1` to `9`, and `Esc` cancels. If two shortcuts map to the same key, or a key has no mpv equivalent, SubMiner logs a warning and skips it.
Because the bindings come from the same configuration the overlay uses, you maintain one set of shortcuts for both surfaces.
## Script options
Live updates: changing a shortcut in the app rewrites `session-bindings.json` and sends the plugin a `subminer-reload-session-bindings` script message, so mpv re-registers the bindings immediately - no mpv restart required.
The plugin reads `script-opts` with the `subminer-` prefix, for example `--script-opts=subminer-backend=hyprland`. Managed launches set these from your SubMiner config, so edit the config instead. The shipped `plugin/subminer.conf` is empty on purpose, so it never overrides those values.
Notes:
| Option | Default | SubMiner config key | What it does |
| ---------------------------------------------- | ---------------- | ---------------------------- | --------------------------------------------------------------------- |
| `binary_path` | `""` | `mpv.subminerBinaryPath` | SubMiner binary. Empty uses [auto-detection](#binary-auto-detection). |
| `socket_path` | platform default | `mpv.socketPath` | mpv IPC socket |
| `backend` | `auto` | `mpv.backend` | Window backend: `auto`, `hyprland`, `sway`, `x11`, `macos` |
| `auto_start` | `no` | `mpv.autoStartSubMiner` | Start SubMiner when a file loads |
| `auto_start_visible_overlay` | `no` | `auto_start_overlay` | Show the overlay when auto-starting |
| `auto_start_pause_until_ready` | `yes` | `mpv.pauseUntilOverlayReady` | Keep mpv paused until subtitles are ready |
| `auto_start_pause_until_ready_timeout_seconds` | `30` | | Resume anyway after this many seconds |
| `overlay_loading_osd` | `no` | | Show a loading message while the overlay starts |
| `texthooker_enabled` | `no` | | Start the texthooker with the overlay |
| `texthooker_port` | `5174` | | Texthooker port |
| `osd_messages` | `yes` | | Show plugin status messages in mpv |
| `log_level` | `info` | | Plugin log level |
- Accelerators are normalized per platform - `CommandOrControl` resolves to `Cmd` on macOS and `Ctrl` elsewhere.
- Multi-line actions (`copySubtitleMultiple`, `mineSentenceMultiple`) register temporary `1`–`9` digit follow-up bindings after the trigger key, with `Esc` to cancel.
- If two shortcuts compile to the same key, or an accelerator can't be mapped to an mpv key, the app logs a warning and skips that binding instead of registering a broken one.
Without script options, `socket_path` is `/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows. On Windows, the plugin also rewrites `/tmp/subminer-socket` to the named pipe.
## Menu
Press `y-y` to open an interactive menu (rendered with mpv's console selector):
```text
SubMiner:
1. Start overlay
2. Stop overlay
3. Toggle overlay
4. Open options
5. Restart overlay
6. Check status
7. Stats
```
Select an item by pressing its number.
The table's defaults are the plugin's own. Managed launches override them from your config; see [Configuration](/configuration#mpv-launcher).
## Binary auto-detection
When `binary_path` is empty, the plugin searches platform-specific locations:
With `binary_path` empty, the plugin looks in these places:
**Linux:**
1. `~/.local/bin/SubMiner.AppImage`
2. `/opt/SubMiner/SubMiner.AppImage`
3. `/usr/local/bin/SubMiner` / `/usr/local/bin/subminer`
4. `/usr/bin/SubMiner` / `/usr/bin/subminer`
**macOS:**
1. `/Applications/SubMiner.app/Contents/MacOS/SubMiner`
2. `~/Applications/SubMiner.app/Contents/MacOS/SubMiner`
**Windows:**
A PowerShell system lookup runs first (running SubMiner process, registry App Paths, `Get-Command`), then static paths:
1. `%LOCALAPPDATA%\Programs\SubMiner\SubMiner.exe` (the default per-user install location)
2. `C:\Program Files\SubMiner\SubMiner.exe`
3. `C:\Program Files (x86)\SubMiner\SubMiner.exe`
4. `C:\SubMiner\SubMiner.exe`
On Windows the plugin also normalizes a Unix-style `socket_path` (`/tmp/subminer-socket`) to the named pipe `\\.\pipe\subminer-socket` at runtime.
| Platform | Locations |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linux | `~/.local/bin/SubMiner.AppImage`, `/opt/SubMiner/SubMiner.AppImage`, `/usr/local/bin/SubMiner` or `subminer`, `/usr/bin/SubMiner` or `subminer` |
| macOS | `/Applications/SubMiner.app`, `~/Applications/SubMiner.app` |
| Windows | A running SubMiner process, the App Paths registry entry, `SubMiner.exe` on `PATH`, then `%LOCALAPPDATA%\Programs\SubMiner`, `C:\Program Files\SubMiner`, `C:\Program Files (x86)\SubMiner`, `C:\SubMiner` |
## Backend detection
When `backend=auto`, the plugin detects the window manager:
With `backend=auto`, the plugin picks the first match:
1. **macOS** - detected via platform or `OSTYPE`.
2. **Hyprland** - detected via `HYPRLAND_INSTANCE_SIGNATURE`.
3. **Sway** - detected via `SWAYSOCK`.
4. **X11** - detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
5. **Fallback** - defaults to X11 with a warning.
1. macOS
2. Hyprland (`HYPRLAND_INSTANCE_SIGNATURE` is set)
3. Sway (`SWAYSOCK` is set)
4. X11 (`XDG_SESSION_TYPE=x11` or `DISPLAY` is set)
5. Otherwise X11, with a warning
::: tip Wayland is compositor-specific
Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 - both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
:::
Native Wayland support covers only Hyprland and Sway. On other Wayland compositors, run both mpv and SubMiner under Xwayland and install `xdotool` and `xwininfo`.
## Script messages
The plugin can be controlled from other mpv scripts or the mpv command line using script messages:
Other mpv scripts, `input.conf`, or the mpv console can control the plugin:
```
```text
script-message subminer-start
script-message subminer-stop
script-message subminer-toggle
@@ -157,46 +114,21 @@ script-message subminer-menu
script-message subminer-options
script-message subminer-restart
script-message subminer-status
script-message subminer-autoplay-ready
script-message subminer-stats-toggle
script-message subminer-visible-overlay-shown
script-message subminer-visible-overlay-hidden
script-message subminer-managed-subtitles-loading
script-message subminer-overlay-loading-ready
script-message subminer-reload-session-bindings
```
The last five are primarily used by the SubMiner app to notify the plugin of overlay/loading state and to trigger session-binding reloads.
`subminer-start` accepts overrides:
The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) still exist, but they are handled by the SubMiner app over the IPC socket rather than by the plugin - see [AniSkip Integration](/aniskip-integration#triggering-from-mpv).
The `subminer-start` message accepts overrides:
```
```text
script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
```
`log-level` here controls only logging verbosity passed to SubMiner.
`--debug` is a separate app/dev-mode flag in the main CLI and should not be used here for logging.
`log-level` sets SubMiner's log verbosity. Do not use `--debug` for this; it turns on the app's dev mode.
## Lifecycle
The plugin also handles messages the SubMiner app sends it (`subminer-autoplay-ready`, `subminer-visible-overlay-shown`, `subminer-visible-overlay-hidden`, `subminer-managed-subtitles-loading`, `subminer-overlay-loading-ready`, `subminer-reload-session-bindings`). You do not need to send these yourself. The AniSkip messages are listed on the [AniSkip page](/aniskip-integration#triggering-from-mpv).
For how the plugin's auto-start fits into the full launch sequence - including when the launcher starts the overlay instead of the plugin - see [Playback Startup Flow](./architecture#playback-startup-flow).
## Auto-start behavior
- **File loaded**: If `auto_start=yes`, the plugin starts the overlay.
- **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused. On cold managed background startup, SubMiner opens the tray and visible overlay shell before tokenization warmups finish, then the plugin resumes playback after SubMiner reports tokenization-ready (with a 30-second timeout fallback).
- **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
- **MPV shutdown**: The plugin clears its hover/OSD/gate state on shutdown; the overlay app notices the closed IPC socket and shuts itself down.
- **Texthooker**: When `texthooker_enabled=yes`, the plugin appends `--texthooker` to the overlay start command so the app starts the texthooker server alongside the overlay.
## Using with the `subminer` wrapper
The `subminer` wrapper script handles mpv launch, socket setup, and overlay lifecycle automatically. You do not need the plugin if you always use the wrapper.
The plugin is useful when you:
- Launch mpv from other tools (file managers, media centers).
- Want on-demand overlay control without the wrapper.
- Use mpv's built-in file browser or playlist features.
You can install both - the plugin provides chord keybindings for convenience, while the wrapper handles the full lifecycle.
- With `auto_start=yes`, the plugin starts SubMiner on each file load. Repeated loads while SubMiner is running do not start it again.
- With `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, mpv stays paused until SubMiner reports that subtitles are ready, or until the timeout passes.
- With `texthooker_enabled=yes`, the texthooker starts with the overlay.
- When mpv quits, SubMiner sees the closed socket and shuts down its overlay.