# 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](https://github.com/ksyasuda/SubMiner/releases/latest):

```bash
# 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](https://bun.sh) must be installed and available on `PATH`.

### From Source

```bash
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](https://github.com/ksyasuda/SubMiner/releases/latest). 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:

```bash
brew install mpv mecab mecab-ipadic
```

### From Source (macOS)

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

```bash
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:**

```bash
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:**

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

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

Launch mpv with:

```bash
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.

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

```bash
# 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](/mpv-plugin) for the full configuration reference, script messages, and binary auto-detection details.

## Verify Installation

After installing, confirm SubMiner is working:

```bash
# 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](/usage) — learn about the `subminer` wrapper, keybindings, and YouTube playback.