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
Files
8825cca642cdf18366772ccb97c2048f19dc37a9
SubMiner/docs-site/mpv-plugin.md
T
sudacode 8825cca642 docs: rewrite docs site pages to be shorter and easier to scan 
- 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
2026-09-24 16:20:42 -07:00

135 lines
8.8 KiB
Markdown
Raw Blame History

# MPV plugin
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.
## Setup
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.
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.
To use the plugin when mpv is started by another program, load its `main.lua` and enable IPC:
```bash
mpv --script="$HOME/.local/share/SubMiner/plugin/subminer/main.lua" \
--input-ipc-server=/tmp/subminer-socket video.mkv
```
To enable IPC for every mpv session, add it to `mpv.conf`:
```ini
input-ipc-server=/tmp/subminer-socket
```
On Windows, use a named pipe:
```ini
input-ipc-server=\\.\pipe\subminer-socket
```
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 keys are chords: press `y`, then the second key.
| 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 |
`v` replaces mpv's own subtitle visibility toggle.
The skip-intro key (`TAB` by default) comes from the SubMiner app, not the plugin. See [AniSkip integration](/aniskip-integration).
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.
## Your shortcuts in mpv
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.
`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.
## Script options
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.
| 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 |
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.
The table's defaults are the plugin's own. Managed launches override them from your config; see [Configuration](/configuration#mpv-launcher).
## Binary auto-detection
With `binary_path` empty, the plugin looks in these places:
| 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
With `backend=auto`, the plugin picks the first match:
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
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
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
script-message subminer-menu
script-message subminer-options
script-message subminer-restart
script-message subminer-status
```
`subminer-start` accepts overrides:
```text
script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
```
`log-level` sets SubMiner's log verbosity. Do not use `--debug` for this; it turns on the app's dev mode.
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).
## Auto-start behavior
- 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.
Reference in New Issue View Git Blame Copy Permalink