SubMiner/docs-site/installation.md

Installation

How the Pieces Fit Together

SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IPC socket, renders subtitles as interactive text using a bundled Yomitan dictionary engine, and optionally creates Anki flashcards via AnkiConnect.

To get a working setup you need:

1. mpv launched with an IPC socket so SubMiner can read subtitle data
2. SubMiner (the Electron overlay app)
3. Dictionaries imported into the bundled Yomitan instance (lookups won't work without at least one)
4. Anki + AnkiConnect (optional but recommended) for card creation and enrichment

The subminer launcher script handles step 1 automatically. If you launch mpv yourself or from another tool, you must pass --input-ipc-server=/tmp/subminer-socket (or the equivalent named pipe on Windows) — without it the overlay will start but subtitles will never appear.

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)

Arch Linux

sudo pacman -S --needed mpv ffmpeg
# Optional
sudo pacman -S --needed mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
# Optional: subtitle sync (at least one needed for subtitle syncing)
paru -S --needed alass python-ffsubsync
# X11 / XWAYLAND
sudo pacman -S --needed xdotool xorg-xwininfo

Ubuntu / Debian

sudo apt install mpv ffmpeg
# Optional
sudo apt install mecab libmecab-dev mecab-ipadic-utf8 fzf rofi chafa ffmpegthumbnailer yt-dlp
# X11
sudo apt install xdotool x11-utils
# Optional: subtitle sync
pip install ffsubsync
# alass is not in apt — install via cargo: cargo install alass-cli

Fedora

sudo dnf install mpv ffmpeg
# Optional
sudo dnf install mecab mecab-ipadic fzf rofi chafa ffmpegthumbnailer yt-dlp
# X11
sudo dnf install xdotool xorg-x11-utils
# Optional: subtitle sync
pip install ffsubsync
# alass: cargo install alass-cli

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

brew install mpv ffmpeg
# Optional but recommended for annotations
brew install mecab mecab-ipadic
# Optional
brew install yt-dlp fzf rofi chafa ffmpegthumbnailer
# Optional: subtitle sync
brew install alass
pip install ffsubsync

Windows — Windows 10 or later. Install mpv and ffmpeg and ensure both are on PATH. Keep mpv.exe on PATH for auto-discovery or set mpv.executablePath in config if it lives elsewhere. SubMiner's packaged build handles window tracking directly. Optionally install MeCab for Windows with the UTF-8 dictionary.

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 and the subminer launcher from GitHub Releases.

Step 1 — Install Bun (required for the launcher):

curl -fsSL https://bun.sh/install | bash

The subminer launcher uses a Bun shebang. The AppImage itself does not need Bun — only the launcher does. If you skip the launcher and run the AppImage directly (for example SubMiner.AppImage --start), you can skip this step, but you will need to configure mpv.conf with input-ipc-server=/tmp/subminer-socket manually.

Step 2 — Download and install:

mkdir -p ~/.local/bin

# 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 and install the subminer launcher (recommended)
wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
chmod +x ~/.local/bin/subminer

The subminer launcher is the recommended way to use SubMiner on Linux. It ensures mpv is launched with the correct IPC socket and SubMiner defaults so you don't need to configure mpv.conf manually.

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

Install the subminer launcher (recommended)

The subminer launcher is the recommended way to use SubMiner on macOS. It launches mpv with the correct IPC socket and SubMiner defaults so you don't need to set up an mpv.conf profile manually.

Download it from the same GitHub Releases page:

sudo wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O /usr/local/bin/subminer
sudo chmod +x /usr/local/bin/subminer

Or with curl:

sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer
sudo chmod +x /usr/local/bin/subminer

::: warning Bun required for the launcher The subminer launcher uses a Bun shebang (#!/usr/bin/env bun), so Bun must be installed and available on PATH. Install Bun if you haven't already: curl -fsSL https://bun.sh/install | bash. :::

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

Build and install the launcher alongside the app:

make install-macos

This builds the subminer launcher into dist/launcher/subminer and installs it to ~/.local/bin/subminer along with the app bundle and rofi theme. To install to /usr/local/bin instead (already on the default macOS PATH):

sudo make install-macos PREFIX=/usr/local

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 with the subminer launcher (recommended):

subminer video.mkv

The launcher handles the IPC socket and SubMiner defaults automatically. If you prefer to launch mpv manually:

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

Warning

Windows support is experimental. Core features — mining, annotations, and dictionary lookups — work, but some functionality may be missing or unstable. Bug reports welcome.

Prerequisites

1. Install mpv and ensure mpv.exe is on PATH. If mpv is installed elsewhere, you can set mpv.executablePath in config.jsonc or use the first-run setup field to point at the executable.
2. Install ffmpeg and add it to PATH — recommended for audio/screenshot extraction (without it, media fields on Anki cards will be empty).
3. (Optional) Install MeCab for Windows with the UTF-8 dictionary for annotation POS filtering.

No compositor tools or window helpers are needed — native window tracking is built in on 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

Getting Started on Windows

1. Run SubMiner.exe once — first-run setup creates %APPDATA%\SubMiner\config.jsonc, installs the mpv plugin, and opens Yomitan settings for dictionary import.
2. Create the SubMiner mpv shortcut (recommended) — the setup popup offers to create a SubMiner mpv Start Menu and/or Desktop shortcut. This is the recommended way to launch playback on Windows.
3. Play a video — double-click the shortcut, drag a video file onto it, or run from a terminal:

& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"

The shortcut and --launch-mpv pass SubMiner's default IPC socket and subtitle args directly — no mpv.conf profile is needed.

Windows-Specific Notes

• The subminer launcher script requires Bun and must be invoked with bun run subminer on Windows since the shebang is not supported. The SubMiner mpv shortcut or SubMiner.exe --launch-mpv is the simpler alternative.
• First-run plugin installs pin binary_path to the current SubMiner.exe automatically. Manual plugin configs can leave binary_path empty unless SubMiner is in a non-standard location.
• Plugin installs rewrite socket_path to \\.\pipe\subminer-socket — do not keep /tmp/subminer-socket on Windows.
• Config is stored at %APPDATA%\SubMiner\config.jsonc.

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

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

Anki Setup (Recommended)

If you plan to mine Anki cards (the primary use case for most users):

1. Install Anki.
2. Install the AnkiConnect add-on — open Anki, go to Tools → Add-ons → Get Add-ons, enter code 2055492159.
3. Restart Anki and keep it running while using SubMiner.

AnkiConnect listens on http://127.0.0.1:8765 by default. SubMiner will connect to it automatically with no extra config needed for basic card creation.

For enrichment configuration (sentence, audio, screenshot fields), see Anki Integration.

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.

Note

On Windows, use bun run subminer doctor or run SubMiner.exe directly. 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.

First-Run Setup

On first launch SubMiner creates a default config file automatically and opens a setup popup. You do not need to create the config manually — SubMiner handles it.

The setup popup walks you through:

• Config file: auto-created at ~/.config/SubMiner/config.jsonc (Linux/macOS) or %APPDATA%\SubMiner\config.jsonc (Windows)
• mpv plugin: install the bundled Lua plugin for in-player keybindings
• Yomitan dictionaries: import at least one dictionary so lookups work
• Windows shortcut (Windows only): optionally create a SubMiner mpv Start Menu/Desktop shortcut

The Finish setup button stays disabled until the plugin is installed and at least one dictionary is imported. Once you finish, SubMiner will not show the popup again.

Tip

You can re-open the setup popup at any time with subminer --setup or SubMiner.AppImage --setup.

Optional Extras

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.

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