SubMiner/docs-site/installation.md

Installation

Requirements

System Dependencies

Dependency	Required	Notes
mpv	Yes	Must support IPC sockets (--input-ipc-server)
Bun	For wrapper	Required for subminer CLI wrapper and source builds. Pre-built releases (AppImage, DMG, installer) work without it — only the subminer wrapper script needs Bun on PATH.
ffmpeg	Recommended	Audio extraction and screenshot generation. Without it SubMiner still runs, but audio and image fields on Anki cards will be empty.
MeCab + mecab-ipadic	No	Adds part-of-speech data used to filter particles out of N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less precise.
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.

Windows — Windows 10 or later. Install mpv; keep it on PATH for auto-discovery or set mpv.executablePath in config if mpv.exe lives elsewhere. SubMiner's packaged build handles window tracking directly.

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) — must be on PATH or set subsync.alass_path in config; subtitle syncing is disabled without it or ffsubsync
ffsubsync	Subtitle sync engine (fallback) — must be on PATH or set subsync.ffsubsync_path in config; subtitle syncing is disabled without it or alass

Linux

Arch Linux (AUR)

Install subminer-bin from the AUR if you want the packaged Linux release managed by pacman. The package installs the official SubMiner AppImage plus the subminer wrapper.

paru -S subminer-bin

Or manually:

git clone https://aur.archlinux.org/subminer-bin.git
cd subminer-bin
makepkg -si

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

::: warning Bun required for the wrapper The subminer wrapper uses a Bun shebang (#!/usr/bin/env bun), so Bun must be installed and available on PATH. If you see /usr/bin/env: 'bun': No such file or directory when running subminer, install Bun first: curl -fsSL https://bun.sh/install | bash. The AppImage itself does not need Bun — only the subminer convenience wrapper does. :::

From Source

git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
cd SubMiner
# if you cloned without --recurse-submodules:
git submodule update --init --recursive

bun install
bun run build

# Optional packaged Linux artifact
bun run build:appimage

Bundled Yomitan is built during bun run build. If you prefer Make wrappers for local install flows, make build-launcher still generates dist/launcher/subminer and make install still installs the wrapper/theme/AppImage when those artifacts exist.

make build also builds the bundled Yomitan Chrome extension from the vendor/subminer-yomitan submodule into build/yomitan using Bun.

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 ffmpeg
# Optional but recommended if you use N+1, JLPT, or frequency annotations
brew install mecab mecab-ipadic

From Source (macOS)

git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
cd SubMiner
git submodule update --init --recursive
make build-macos

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

For unsigned local builds:

bun run build:mac:unsigned

Gatekeeper

If macOS blocks SubMiner on first launch, right-click the app and select Open to bypass the warning. Alternatively, remove the quarantine attribute:

xattr -d com.apple.quarantine /Applications/SubMiner.app

Accessibility Permission

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

1. Open System Settings → Privacy & Security → Accessibility
2. Enable SubMiner in the list (add it if it does not appear)

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

Installer (Recommended)

Download the latest Windows installer from GitHub Releases:

• SubMiner-<version>.exe installs the app, Start menu shortcut, and default files under Program Files
• SubMiner-<version>.zip is available as a portable fallback

Install mpv separately and ensure mpv.exe is on PATH. ffmpeg is recommended for audio/screenshot extraction (without it, media fields on Anki cards will be empty). MeCab is optional.

Windows Usage Notes

• Launch SubMiner.exe once to let the first-run setup flow seed %APPDATA%\\SubMiner\\config.jsonc, require mpv plugin installation, and open bundled Yomitan settings. The optional SubMiner mpv Start Menu/Desktop shortcut can also be created during setup, and on Windows it is the recommended way to launch mpv playback with SubMiner defaults.
• If mpv.exe is not on PATH, set mpv.executablePath in config.jsonc or use the first-run setup field to point at the executable. Leave it blank to keep PATH auto-discovery.
• SubMiner.exe --launch-mpv and the optional SubMiner mpv shortcut pass SubMiner's default mpv socket/subtitle args directly and do not require an mpv.conf profile named subminer.
• First-run mpv plugin installs pin binary_path to the current SubMiner.exe automatically. Manual plugin configs can leave binary_path empty unless SubMiner is installed in a non-standard location.
• Windows plugin installs rewrite socket_path to \\.\pipe\subminer-socket; do not keep /tmp/subminer-socket on Windows.
• Native window tracking is built in on Windows; no xdotool, xwininfo, or compositor-specific helper is required.

From Source (Windows)

git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
bun install

# Windows requires building the texthooker-ui submodule manually before
# the main build (Linux/macOS handle this automatically during `bun run build`).
Set-Location vendor/texthooker-ui
bun install --frozen-lockfile
bun run build
Set-Location ../..

bun run build:win

Windows installer builds already get the required NSIS WinShell helper through electron-builder's cached nsis-resources bundle. No extra repo-local WinShell plugin install step is required.

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.

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

On Windows, the packaged plugin config is rewritten to socket_path=\\.\pipe\subminer-socket. First-run setup also pins binary_path to the current app binary so mpv launches the same SubMiner build that installed the plugin.

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

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

Verify Installation

After installing, run the built-in diagnostic to confirm dependencies are in place:

subminer doctor

This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.

On Windows, replace SubMiner.AppImage with SubMiner.exe in the direct app commands below.

# Play a file (default plugin config auto-starts visible overlay and waits for annotation readiness; first launch may open first-run setup popup)
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.