Installation

Requirements

System Dependencies

Dependency	Required	Notes
Bun	Yes	Required for subminer wrapper and source workflows
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
guessit	Better AniSkip title/season/episode parsing for file playback
alass	Subtitle sync engine (preferred)
ffsubsync	Subtitle sync engine (fallback)

Linux

AppImage (Recommended)

Download the latest AppImage from GitHub Releases:

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

# Download subminer wrapper script
wget https://github.com/ksyasuda/SubMiner/releases/latest/download/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
make build-launcher

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

make build-launcher generates the wrapper at dist/launcher/subminer. The checked-in launcher source remains launcher/*.ts. Do not use a repo-root ./subminer artifact when building from source; workflow checks enforce dist/launcher/subminer as the only generated path.

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
bun install
cd vendor/texthooker-ui && bun install --frozen-lockfile && bun run build && cd ../..
bun run build:mac

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

For unsigned local builds:

bun 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

MPV Plugin (Recommended)

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.

# Option 1: install from release assets bundle
wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
mkdir -p ~/.config/SubMiner
cp /tmp/config.example.jsonc ~/.config/SubMiner/config.jsonc
mkdir -p ~/.config/mpv/scripts/subminer
mkdir -p ~/.config/mpv/script-opts
cp -R /tmp/plugin/subminer/. ~/.config/mpv/scripts/subminer/
cp /tmp/plugin/subminer.conf ~/.config/mpv/script-opts/

# Option 2: from source checkout
# make install-plugin

Rofi Theme (Linux Only)

SubMiner ships a default rofi theme at assets/themes/subminer.rasi.

Install path (default auto-detected by subminer):

• Linux: ~/.local/share/SubMiner/themes/subminer.rasi
• macOS: ~/Library/Application Support/SubMiner/themes/subminer.rasi

mkdir -p ~/.local/share/SubMiner/themes
cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi

Override with SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi.

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-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:

# Play a file (default plugin config auto-starts visible overlay and waits for annotation readiness)
subminer video.mkv

# Optional explicit overlay start for setups with plugin auto_start=no
subminer --start video.mkv

# Useful launch modes for troubleshooting
subminer --log-level debug video.mkv
SubMiner.AppImage --start --log-level debug

# Or with direct AppImage control
SubMiner.AppImage --background  # Background tray service mode
SubMiner.AppImage --start
SubMiner.AppImage --start --dev
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.