SubMiner/docs-site/mpv-plugin.md

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:

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:

input-ipc-server=/tmp/subminer-socket

On Windows, use a named pipe:

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.

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

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:

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:

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.

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.