diff --git a/README.md b/README.md
index 4ae49572..9b0ede9f 100644
--- a/README.md
+++ b/README.md
@@ -4,25 +4,21 @@
# SubMiner
-## Turn mpv into a sentence-mining workstation.
-
Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.
-[](https://www.gnu.org/licenses/gpl-3.0)
-[](https://github.com/ksyasuda/SubMiner)
-[](https://docs.subminer.moe)
+[Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
+
+[](https://github.com/ksyasuda/SubMiner/releases)
+[](https://github.com/ksyasuda/SubMiner/releases/latest)
[](https://aur.archlinux.org/packages/subminer-bin)
+[](https://github.com/ksyasuda/SubMiner)
+[](https://www.gnu.org/licenses/gpl-3.0)
+[](https://www.typescriptlang.org)
[](https://github.com/user-attachments/assets/89e61895-e2b7-4b47-8d50-a35afe4132b2)
-## How It Works
-
-SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
-
-First-run setup requires the mpv plugin before it can finish. On Windows, the optional `SubMiner mpv` shortcut created during setup is the recommended playback entry point because it launches `mpv` with SubMiner's defaults directly, so you do not need an `mpv.conf` profile just to use it.
-
## Features
### Dictionary Lookups
@@ -69,8 +65,6 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
-Managed local playback now reapplies your configured subtitle language priorities after mpv loads track metadata, so mixed subtitle sets can settle onto the expected primary and secondary tracks instead of staying on mpv's initial `sid=auto` guess.
-
### Integrations
@@ -213,6 +207,16 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~
Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
+Also download the `subminer` launcher (recommended):
+
+```bash
+sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer \
+ && sudo chmod +x /usr/local/bin/subminer
+```
+
+> [!NOTE]
+> The `subminer` launcher uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.
+
@@ -220,6 +224,12 @@ Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasud
Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
+> [!WARNING]
+> **Windows support is experimental.** Core features such as mining, annotations, and dictionary lookups work, but some functionality may be missing or unstable. Bug reports welcome.
+
+> [!NOTE]
+> On Windows the `subminer` launcher requires [`bun`](https://bun.sh) and must be invoked with `bun run subminer` instead of running the script directly. The recommended alternative is the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag files onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See the [Windows mpv Shortcut](https://docs.subminer.moe/usage#windows-mpv-shortcut) section for details.
+
@@ -235,6 +245,9 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
subminer doctor # verify mpv, ffmpeg, config, and socket
```
+> [!NOTE]
+> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly — first-run setup will guide you through dependency checks.
+
### 3. First Launch
Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to finish config, install the mpv plugin, and configure Yomitan dictionaries.
@@ -249,6 +262,8 @@ subminer stats -b # stats daemon in background
subminer stats -s # stop background stats daemon
```
+On **Windows**, the `subminer` script must be run with `bun run subminer` (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut (created during setup) or `SubMiner.exe --launch-mpv`. Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.
+
## Documentation
Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**
diff --git a/docs-site/installation.md b/docs-site/installation.md
index b2ea4a6e..8a83fd1e 100644
--- a/docs-site/installation.md
+++ b/docs-site/installation.md
@@ -57,21 +57,24 @@ makepkg -si
### AppImage (Recommended)
-Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
+Download the latest AppImage and the `subminer` launcher from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
```bash
+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 subminer wrapper script
+# 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
-
```
-::: warning Bun required for the wrapper
-The `subminer` wrapper uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) 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.
+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.
+
+::: warning Bun required for the launcher
+The `subminer` launcher uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) 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` launcher does.
:::
### From Source
@@ -110,6 +113,28 @@ brew install mpv ffmpeg
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](https://github.com/ksyasuda/SubMiner/releases/latest) page:
+
+```bash
+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:
+
+```bash
+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](https://bun.sh) must be installed and available on `PATH`. Install Bun if you haven't already: `curl -fsSL https://bun.sh/install | bash`.
+:::
+
### From Source (macOS)
```bash
@@ -127,6 +152,18 @@ For unsigned local builds:
bun run build:mac:unsigned
```
+Build and install the launcher alongside the app:
+
+```bash
+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`):
+
+```bash
+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:
@@ -146,7 +183,13 @@ Without this permission, window tracking will not work and the overlay won't fol
### macOS Usage Notes
-**Launching MPV with IPC:**
+**Launching with the `subminer` launcher (recommended):**
+
+```bash
+subminer video.mkv
+```
+
+The launcher handles the IPC socket and SubMiner defaults automatically. If you prefer to launch mpv manually:
```bash
mpv --input-ipc-server=/tmp/subminer-socket video.mkv
@@ -171,6 +214,9 @@ 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.
+
### Installer (Recommended)
Download the latest Windows installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
@@ -182,6 +228,9 @@ Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is recommen
### Windows Usage Notes
+> [!TIP]
+> On Windows the `subminer` launcher script must be invoked with `bun run subminer` instead of running directly. The recommended alternative is the **SubMiner mpv** shortcut — double-click it, drag files onto it, or run `SubMiner.exe --launch-mpv` from a terminal.
+
- 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`.
diff --git a/docs-site/launcher-script.md b/docs-site/launcher-script.md
index d543227c..f5efa4b6 100644
--- a/docs-site/launcher-script.md
+++ b/docs-site/launcher-script.md
@@ -1,6 +1,10 @@
# Launcher Script
-The `subminer` wrapper script is an all-in-one launcher that handles video selection, mpv startup, and overlay management. It's a Bun script distributed alongside the AppImage.
+The `subminer` launcher is an all-in-one script that handles video selection, mpv startup, and overlay management. It is the recommended way to use SubMiner on Linux and macOS because it guarantees mpv is launched with the correct IPC socket and SubMiner defaults. It's a Bun script distributed as a release asset alongside the AppImage and DMG.
+
+::: tip Windows users
+On Windows the `subminer` script cannot run directly via shebang — use `bun run subminer` instead (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut created during first-run setup, or `SubMiner.exe --launch-mpv`. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
+:::
## Video Picker
diff --git a/docs-site/usage.md b/docs-site/usage.md
index be1aa5e3..f3fa6d42 100644
--- a/docs-site/usage.md
+++ b/docs-site/usage.md
@@ -39,9 +39,10 @@ There are two ways to use SubMiner:
| Approach | Use when | How |
| -------- | -------- | --- |
| **`subminer` script** | You want SubMiner to handle everything — launch mpv, set up the socket, start the overlay. The simplest path. | `subminer video.mkv` |
-| **MPV plugin** | You launch mpv yourself or from another tool (file manager, Jellyfin, etc.). Requires `--input-ipc-server=/tmp/subminer-socket` in your mpv config. | Use `y` chord keybindings inside mpv |
+| **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults directly. | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` |
+| **MPV plugin** (all platforms) | You launch mpv yourself or from another tool (file manager, Jellyfin, etc.). Requires `--input-ipc-server=/tmp/subminer-socket` in your mpv config. | Use `y` chord keybindings inside mpv |
-You can use both — the plugin provides in-player controls, while the `subminer` script is convenient for direct playback. The `subminer` script runs directly via shebang (no `bun run` needed).
+You can use both — the plugin provides in-player controls, while the `subminer` script (or the Windows shortcut) is convenient for direct playback. The `subminer` script runs directly via shebang on Linux and macOS (no `bun run` needed); on Windows it must be invoked with `bun run subminer` since the shebang is not supported.
## Live Config Reload