Installation

Requirements

System Dependencies

Dependency	Required	Notes
mpv	Yes	Must support IPC sockets (--input-ipc-server)
ffmpeg	For media	Audio extraction and screenshot generation
MeCab + mecab-ipadic	No	Optional fallback tokenizer for Japanese
fuse2	Linux only	Required for AppImage
yt-dlp	No	Recommended for YouTube playback and subtitle extraction

Platform-Specific

Linux — one of the following compositors:

• Hyprland (uses hyprctl)
• Sway (uses swaymsg)
• X11 (uses xdotool and xwininfo)

macOS — macOS 10.13 or later. Accessibility permission required for window tracking.

Optional Tools

Tool	Purpose
fzf	Terminal-based video picker (default)
rofi	GUI-based video picker
chafa	Thumbnail previews in fzf
ffmpegthumbnailer	Generate video thumbnails for picker
alass	Subtitle sync engine (preferred)
ffsubsync	Subtitle sync engine (fallback)
Bun	Required for the subminer wrapper script

Linux

AppImage (Recommended)

Download the latest AppImage from GitHub Releases:

# Download and install AppImage
wget https://github.com/ksyasuda/SubMiner/releases/download/v0.1.0/SubMiner-0.1.0.AppImage -O ~/.local/bin/SubMiner.AppImage
chmod +x ~/.local/bin/SubMiner.AppImage

# Download subminer wrapper script
wget https://github.com/ksyasuda/SubMiner/releases/download/v0.1.0/subminer -O ~/.local/bin/subminer
chmod +x ~/.local/bin/subminer

The subminer wrapper uses a Bun shebang (#!/usr/bin/env bun), so Bun must be installed and available on PATH.

From Source

git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
make build

# Install platform artifacts (wrapper + theme + AppImage)
make install

macOS

DMG (Recommended)

Download the DMG artifact from GitHub Releases. Open it and drag SubMiner.app into /Applications.

A ZIP artifact is also available as a fallback — unzip and drag SubMiner.app into /Applications.

Install dependencies using Homebrew:

brew install mpv mecab mecab-ipadic

From Source (macOS)

git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
pnpm install
cd vendor/texthooker-ui && pnpm install && pnpm build && cd ../..
pnpm run build:mac

The built app will be available in the release directory (.dmg and .zip).

For unsigned local builds:

pnpm run build:mac:unsigned

Accessibility Permission

After launching SubMiner for the first time, grant accessibility permission:

1. Open System Preferences → Security & Privacy → Privacy tab
2. Select Accessibility from the left sidebar
3. Add SubMiner to the list

Without this permission, window tracking will not work and the overlay won't follow the mpv window.

macOS Usage Notes

Launching MPV with IPC:

mpv --input-ipc-server=/tmp/subminer-socket video.mkv

Config location: $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc).

MeCab paths (Homebrew):

• Apple Silicon (M1/M2): /opt/homebrew/bin/mecab
• Intel: /usr/local/bin/mecab

Ensure mecab is available on your PATH when launching SubMiner.

Fullscreen: The overlay should appear correctly in fullscreen. If you encounter issues, check that accessibility permissions are granted.

mpv plugin binary path:

binary_path=/Applications/SubMiner.app/Contents/MacOS/subminer

Windows

Windows support is available through the mpv plugin. Set the binary and socket path in subminer.conf:

binary_path=C:\\Program Files\\subminer\\subminer.exe
socket_path=\\\\.\\pipe\\subminer-socket

Launch mpv with:

mpv --input-ipc-server=\\\\.\\pipe\\subminer-socket video.mkv

MPV Plugin (Optional)

The Lua plugin provides in-player keybindings to control the overlay from mpv. It communicates with SubMiner by invoking the binary with CLI flags.

Important

mpv must be launched with --input-ipc-server=/tmp/subminer-socket for SubMiner to connect.

# Copy plugin files
cp plugin/subminer.lua ~/.config/mpv/scripts/
cp plugin/subminer.conf ~/.config/mpv/script-opts/
# or: make install-plugin

All keybindings use a y chord prefix — press y, then the second key:

Chord	Action
y-y	Open SubMiner menu (fuzzy-searchable)
y-s	Start overlay
y-S	Stop overlay
y-t	Toggle visible overlay
y-i	Toggle invisible overlay
y-I	Show invisible overlay
y-u	Hide invisible overlay
y-o	Open Yomitan settings
y-r	Restart overlay
y-c	Check overlay status

See MPV Plugin for the full configuration reference, script messages, and binary auto-detection details.

Verify Installation

After installing, confirm SubMiner is working:

# Start the overlay (connects to mpv IPC)
subminer video.mkv

# Or with direct AppImage control
SubMiner.AppImage --start
SubMiner.AppImage --help    # Show all CLI options

You should see the overlay appear over mpv. If subtitles are loaded in the video, they will appear as interactive text in the overlay.

Next: Usage — learn about the subminer wrapper, keybindings, and YouTube playback.