diff --git a/README.md b/README.md index d2dfcfda..b1840b5a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # SubMiner -Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv. +Integrates Yomitan with mpv - look up words, mine to Anki, and track your immersion without leaving the player. [Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe) @@ -110,65 +110,35 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open ## Requirements -| | Required | Recommended | Optional | -| -------------- | --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| **Player** | [`mpv`](https://mpv.io) with IPC socket | — | — | -| **Processing** | — | `ffmpeg` (audio clips & screenshots) | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) | -| **Media** | — | — | `yt-dlp`, `chafa`, `ffmpegthumbnailer` | -| **Selection** | — | — | `fzf` / `rofi` | +Only **mpv** is required. Everything else is optional but enhances the experience. -> [!TIP] -> `ffmpeg` is not strictly required to run SubMiner, but without it audio clips and screenshots will not be attached to Anki cards. Most users will want it installed. - -> [!NOTE] -> [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it. - -**Platform-specific:** - -| Linux | macOS | Windows | -| ------------------------------------------------------------ | ------------------------ | ------------- | -| Hyprland (`hyprctl`) · X11/Xwayland (`xdotool` + `xwininfo`) | Accessibility permission | No extra deps | - -> [!NOTE] -> **Wayland support is compositor-specific.** Wayland has no universal API for window positioning and each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Hyprland is the only native Wayland backend supported currenlty. All other Linux compositors require both mpv and SubMiner to run under X11 or Xwayland. The launcher detects your compositor and configures this automatically. +| Dependency | Status | What it does | +| -------------------- | ----------- | ------------------------------------------------- | +| mpv | Required | The video player SubMiner overlays on | +| ffmpeg | Recommended | Audio clips & screenshots for Anki cards | +| MeCab + mecab-ipadic | Recommended | More precise N+1, JLPT, and frequency annotations | +| yt-dlp | Optional | YouTube playback | +| fzf / rofi | Optional | Video picker in the launcher | +| alass / ffsubsync | Optional | Subtitle sync |
-Arch Linux +Platform-specific install commands + +**Arch Linux:** ```bash -paru -S --needed mpv ffmpeg -# Optional -paru -S --needed mecab-git mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo -# Optional: subtitle sync (install at least one for subtitle syncing to work) -paru -S --needed alass python-ffsubsync -# X11 / Xwayland (required for non-Hyprland compositors) -paru -S --needed xdotool xorg-xwininfo +sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic ``` -
- -
-macOS +**macOS:** ```bash -brew install mpv ffmpeg -# Optional -brew install mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer -# Optional: subtitle sync (install at least one for subtitle syncing to work) -brew install alass -pip install ffsubsync +brew install mpv ffmpeg mecab mecab-ipadic ``` -Grant Accessibility permission to SubMiner in **System Settings > Privacy & Security > Accessibility**. +**Windows:** Install [mpv](https://mpv.io/installation/) and [ffmpeg](https://ffmpeg.org/download.html) and ensure both are on `PATH`. -
- -
-Windows - -Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`. - -Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary for additional metadata enrichment. +See the [full requirements list](https://docs.subminer.moe/installation#1-install-requirements) for optional dependencies.
@@ -176,7 +146,7 @@ Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download ## Quick Start -### 1. Install +### 1. Install SubMiner
Arch Linux (AUR) @@ -185,12 +155,6 @@ Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download paru -S subminer-bin ``` -Or manually: - -```bash -git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si -``` -
@@ -199,40 +163,24 @@ git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makep ```bash mkdir -p ~/.local/bin wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \ - && chmod +x ~/.local/bin/SubMiner.AppImage + && chmod +x ~/.local/bin/SubMiner.AppImage wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \ - && chmod +x ~/.local/bin/subminer + && chmod +x ~/.local/bin/subminer ``` -> [!NOTE] -> The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. First-run setup can optionally install Bun and the launcher into an existing writable PATH directory. -
-macOS +macOS (DMG) -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 -mkdir -p ~/.local/bin -curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o ~/.local/bin/subminer \ - && chmod +x ~/.local/bin/subminer -``` - -> [!NOTE] -> The `subminer` launcher uses a [Bun](https://bun.sh) shebang. First-run setup can optionally install Bun and the launcher into an existing writable PATH directory. Make sure `~/.local/bin` is on your PATH before installing there. +Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
Windows -Download the latest installer (`.exe`) [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`. - -**Note:** On Windows the recommended way to run playback is with the **SubMiner mpv** shortcut created during first-run setup. First-run setup can also optionally install Bun and a `subminer.cmd` command shim to your user PATH, so new terminals can run `subminer` without adding `SubMiner.exe` to PATH. +Download and run the latest installer (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest).
@@ -243,28 +191,28 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so -### 2. First Launch +### 2. Launch & Set Up + +Run SubMiner and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. ```bash -subminer app --setup # launch the first-run setup wizard +# Linux (AUR) +subminer app --setup + +# macOS — open SubMiner.app, or: +subminer app --setup ``` -SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing Yomitan dictionaries. The setup popup can also optionally install Bun and the `subminer` command-line launcher; those choices do not block setup completion. +On **Windows**, just run `SubMiner.exe` — setup opens automatically on first launch. -> [!NOTE] -> On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch. - -### 3. Mine +### 3. Play ```bash subminer video.mkv # play video with overlay -subminer --start video.mkv # explicit overlay start subminer stats # open immersion dashboard -subminer stats -b # stats daemon in background -subminer stats -s # stop background stats daemon ``` -On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup — double-click it to open mpv, or drag a video file onto it. You can also run `SubMiner.exe --launch-mpv` from a terminal. +On **Windows**, use the **SubMiner mpv** shortcut created during setup — double-click it or drag a video file onto it. ## Documentation diff --git a/docs-site/installation.md b/docs-site/installation.md index b2232ba9..98562b33 100644 --- a/docs-site/installation.md +++ b/docs-site/installation.md @@ -1,34 +1,33 @@ # Installation -## How the Pieces Fit Together +Three steps to get started: -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. +1. **Install requirements** — mpv and a few optional extras +2. **Install SubMiner** — from the AUR, or download from GitHub Releases +3. **Launch the app** — first-run setup walks you through dictionaries, the launcher, and everything else -To get a working setup you need: +## 1. Install Requirements -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 +Only **mpv** is strictly required to run SubMiner. Everything else enhances the experience but is optional. -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. +| Dependency | Status | What it does | +| -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- | +| mpv | Required | The video player SubMiner overlays on. Must support `--input-ipc-server`. | +| ffmpeg | Recommended | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty. | +| MeCab + mecab-ipadic | Recommended | Part-of-speech filtering for more precise N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less accurate. | +| yt-dlp | Optional | YouTube playback and subtitle extraction. | +| fzf | Optional | Terminal-based video picker in the launcher. | +| rofi | Optional | GUI-based video picker (Linux). | +| chafa | Optional | Thumbnail previews in fzf. | +| ffmpegthumbnailer | Optional | Video thumbnail generation for the picker. | +| guessit | Optional | Better AniSkip title/season/episode parsing. | +| alass | Optional | Subtitle sync engine (preferred). Disabled without alass or ffsubsync. | +| ffsubsync | Optional | Subtitle sync engine (fallback). Disabled without alass or ffsubsync. | +| fuse2 | Linux only | Required to run the AppImage. | -## Requirements +### Linux -### 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 window backends: +**Window backend** — you need one of these depending on your compositor: - **Hyprland** — native Wayland support (uses `hyprctl`) - **Sway** — native Wayland support (uses `swaymsg`) @@ -43,8 +42,10 @@ Wayland has no universal API for window positioning — each compositor exposes ```bash sudo pacman -S --needed mpv ffmpeg +# Recommended +sudo pacman -S --needed mecab mecab-ipadic # Optional -sudo pacman -S --needed mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer +sudo pacman -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer # Optional: subtitle sync (at least one needed for subtitle syncing) paru -S --needed alass python-ffsubsync # X11 / Xwayland (required for non-Hyprland/Sway compositors) @@ -58,8 +59,10 @@ sudo pacman -S --needed xdotool xorg-xwininfo ```bash sudo apt install mpv ffmpeg +# Recommended +sudo apt install mecab libmecab-dev mecab-ipadic-utf8 # Optional -sudo apt install mecab libmecab-dev mecab-ipadic-utf8 fzf rofi chafa ffmpegthumbnailer yt-dlp +sudo apt install yt-dlp fzf rofi chafa ffmpegthumbnailer # X11 / Xwayland (required for non-Hyprland/Sway compositors) sudo apt install xdotool x11-utils # Optional: subtitle sync @@ -74,8 +77,10 @@ pip install ffsubsync ```bash sudo dnf install mpv ffmpeg +# Recommended +sudo dnf install mecab mecab-ipadic # Optional -sudo dnf install mecab mecab-ipadic fzf rofi chafa ffmpegthumbnailer yt-dlp +sudo dnf install yt-dlp fzf rofi chafa ffmpegthumbnailer # X11 / Xwayland (required for non-Hyprland/Sway compositors) sudo dnf install xdotool xorg-x11-utils # Optional: subtitle sync @@ -85,38 +90,32 @@ pip install ffsubsync -**macOS** — macOS 10.13 or later. Accessibility permission required for window tracking. +### macOS + +macOS 10.13 or later. Accessibility permission is required for window tracking (see [step 2](#macos-dmg)). ```bash brew install mpv ffmpeg -# Optional but recommended for annotations +# Recommended brew install mecab mecab-ipadic # Optional -brew install yt-dlp fzf rofi chafa ffmpegthumbnailer +brew install yt-dlp fzf chafa ffmpegthumbnailer # Optional: subtitle sync brew install alass pip install ffsubsync ``` -**Windows** — Windows 10 or later. Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) 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](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary. +### Windows -### Optional Tools +Windows 10 or later. Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on `PATH`. Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary. -| 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 | +No compositor tools or window helpers are needed — native window tracking is built in. -## Linux +## 2. Install SubMiner -### Arch Linux (AUR) +### Arch Linux (AUR) {#arch-aur} -Install [`subminer-bin`](https://aur.archlinux.org/packages/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. +Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. The package includes the SubMiner AppImage and the `subminer` launcher. ```bash paru -S subminer-bin @@ -130,127 +129,73 @@ cd subminer-bin makepkg -si ``` -### AppImage (Recommended) +### Linux (AppImage) {#linux-appimage} -Download the latest AppImage and the `subminer` launcher from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). - -**Step 1 — Install Bun** (required for the launcher): - -```bash -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:** +Download the latest AppImage 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 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 - -# Download the optional Linux rofi theme -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 ~/.local/share/SubMiner/themes -cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi ``` -The `subminer` launcher is the recommended way to use SubMiner on Linux. It ensures mpv is launched with the correct IPC socket, SubMiner defaults, and the bundled runtime plugin so you don't need to configure `mpv.conf` or install a global mpv plugin. +::: tip Launcher install is optional +First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately. -The first-run setup window can also install Bun and the packaged `subminer` launcher into an existing writable PATH directory. Both steps are optional. +If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-linux). +::: -To check for updates later: +### macOS (DMG) {#macos-dmg} + +Download the DMG 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. + +**Gatekeeper:** If macOS blocks SubMiner on first launch, right-click the app and select **Open** to bypass the warning. Alternatively: ```bash -subminer -u -# or -subminer --update +xattr -d com.apple.quarantine /Applications/SubMiner.app ``` -SubMiner verifies AppImage, launcher, and Linux rofi theme downloads against `SHA256SUMS.txt`. If the AppImage or launcher is installed in a protected path, SubMiner does not elevate itself; it shows the exact sudo command to run instead. +**Accessibility permission:** Grant accessibility permission so the overlay can track the mpv window: -On Linux, `subminer -u` performs the AppImage update from the launcher process, so it does not need to start or IPC into the tray app. +1. Open **System Settings** → **Privacy & Security** → **Accessibility** +2. Enable SubMiner in the list (add it if it does not appear) + +::: tip Launcher install is optional +First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately. + +If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-macos). +::: + +### Windows (Installer) {#windows-installer} + +Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest): + +- `SubMiner-.exe` — installer (recommended) +- `SubMiner-.zip` — portable fallback + +Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup. ### From Source +
+Linux + ```bash 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 +# Optional: build AppImage 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](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`. - -After the first updater-enabled install, tray update checks can update the macOS app automatically through Electron's standard macOS updater. The updater uses the release ZIP as its payload even when the DMG remains the normal first-install artifact. - -Install dependencies using Homebrew: - -```bash -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. - -First-run setup can install Bun and the packaged launcher into a writable directory that is already on PATH. It does not edit shell profiles. - -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 -``` - -To check for updates later: - -```bash -subminer -u -# or -subminer --update -``` - -SubMiner verifies launcher downloads against `SHA256SUMS.txt`. If `/usr/local/bin/subminer` is protected, SubMiner shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead of elevating itself. - -::: 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) +
+macOS ```bash git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git @@ -259,122 +204,19 @@ git submodule update --init --recursive make build-macos ``` -The built app will be available in the `release` directory (`.dmg` and `.zip`). +The built app will be in the `release` directory (`.dmg` and `.zip`). For unsigned local builds: `bun run build:mac:unsigned`. -For unsigned local builds: +
-```bash -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. 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: - -```bash -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):** - -```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 -``` - -**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 - -### Prerequisites - -1. Install [`mpv`](https://mpv.io/installation/) 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`](https://ffmpeg.org/download.html) 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](https://taku910.github.io/mecab/#download) 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](https://github.com/ksyasuda/SubMiner/releases/latest): - -- `SubMiner-.exe` installs the app, Start menu shortcut, and default files under `Program Files` -- `SubMiner-.zip` is available as a portable fallback - -### Getting Started on Windows - -1. **Run `SubMiner.exe` once** — first-run setup creates `%APPDATA%\SubMiner\config.jsonc` and opens Yomitan settings for dictionary import. The global mpv plugin install is optional for compatibility; the SubMiner mpv shortcut injects the bundled runtime plugin. -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. **Optional: install the command-line launcher** — first-run setup can install Bun with winget/Scoop/the official installer and add `%LOCALAPPDATA%\SubMiner\bin\subminer.cmd` to your user PATH. Open a new terminal and type `subminer`. -4. **Play a video** — double-click the shortcut, drag a video file onto it, or run from a terminal: - -```powershell -& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv" -``` - -The shortcut and `--launch-mpv` pass SubMiner's default IPC socket, subtitle args, and bundled runtime plugin directly — no `mpv.conf` profile or global mpv plugin install is needed. - -### Windows-Specific Notes - -- The **SubMiner mpv** shortcut created during first-run setup is the recommended way to launch playback on Windows. -- The optional command-line launcher installs a `subminer.cmd` shim, but users type `subminer`; Windows resolves `.cmd` through `PATHEXT`. -- First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` or the app install directory to PATH. -- 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) +
+Windows ```powershell 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`). +# Windows requires building texthooker-ui manually before the main build Set-Location vendor/texthooker-ui bun install --frozen-lockfile bun run build @@ -383,86 +225,52 @@ 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 +## 3. Launch & First-Run Setup -SubMiner-managed playback loads the bundled mpv plugin at runtime. No separate global mpv plugin install is required when launching from the app, the launcher, or the packaged Windows SubMiner mpv shortcut. - -::: warning Important -If first-run setup detects an older global SubMiner mpv plugin under mpv's `scripts` directory, use **Remove legacy mpv plugin** so regular mpv playback stops loading SubMiner. -::: - -See [MPV Plugin](/mpv-plugin) for the keybindings, script messages, and runtime configuration reference. - -## Anki Setup (Recommended) - -If you plan to mine Anki cards (the primary use case for most users): - -1. Install [Anki](https://apps.ankiweb.net/). -2. Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) 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](/anki-integration). - -## First-Run Setup - -Run the setup wizard to create a default config and finish initial configuration. You do **not** need to create the config manually — SubMiner handles it. +Launch SubMiner and the setup wizard will open automatically: ```bash +# Linux (AUR install) +subminer app --setup + +# Linux (AppImage directly) +~/.local/bin/SubMiner.AppImage --setup + +# macOS — launch SubMiner.app from /Applications, or: subminer app --setup ``` -> [!NOTE] -> On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch. +On **Windows**, just run `SubMiner.exe` — the setup wizard opens automatically on first launch. -The setup popup walks you through: +The setup wizard 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 -- **Command line launcher**: optionally install Bun and the `subminer` launcher to your command-line PATH +- **Config file** — auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows) +- **Yomitan dictionaries** — import at least one dictionary so word lookups work +- **Bun + `subminer` launcher** _(optional)_ — installs the command-line launcher into a writable PATH directory +- **Windows shortcut** _(Windows only)_ — create a `SubMiner mpv` Start Menu/Desktop shortcut -The `Finish setup` button follows the normal config/Yomitan readiness checks. Bun and the command-line launcher are optional and never block setup completion. +The `Finish setup` button requires a config file and at least one Yomitan dictionary. Bun and the launcher are optional and never block setup completion. > [!TIP] -> You can re-open the setup popup at any time with `subminer app --setup` or `SubMiner.AppImage --setup`. +> You can re-open the setup wizard at any time with `subminer app --setup` or `SubMiner.AppImage --setup`. -Once setup is complete, play a video to verify everything works: +### Play a Video + +Once setup is complete: ```bash subminer video.mkv ``` -You should see the overlay appear over mpv. If subtitles are loaded in the video, they will appear as interactive text in the overlay. +You should see the overlay appear over mpv. If subtitles are loaded, they will appear as interactive text in the overlay. -
-More launch examples +On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup — double-click it, or drag a video file onto it. -```bash -# Optional explicit overlay start for setups with plugin auto_start=no -subminer --start video.mkv +### Verify Setup -# 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 -``` - -
- -## Verify Setup - -After completing first-run setup, run the built-in diagnostic to confirm everything is in place: +Run the built-in diagnostic to confirm everything is working: ```bash subminer doctor @@ -470,19 +278,90 @@ subminer doctor This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing. -> [!NOTE] -> On Windows, run `SubMiner.exe` directly. Replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below. +## Anki Setup (Recommended) + +If you plan to mine Anki cards: + +1. Install [Anki](https://apps.ankiweb.net/) +2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) — open Anki → **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 connects automatically with no extra config needed. + +For enrichment configuration (sentence, audio, screenshot fields), see [Anki Integration](/anki-integration). + +## Updates + +```bash +subminer -u +# or +subminer --update +``` + +SubMiner verifies AppImage, launcher, and rofi theme downloads against `SHA256SUMS.txt`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself. + +On Linux, `subminer -u` performs the AppImage update from the launcher process directly. + +On macOS, tray update checks can also update the app automatically through Electron's built-in updater. + +## How It All Fits 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. + +The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) — without it the overlay starts but subtitles won't appear. + +The bundled mpv plugin is injected at runtime automatically — you don't need to install it separately. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference. + +## Platform Notes + +### macOS + +**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. + +### Windows + +- The **SubMiner mpv** shortcut is the recommended way to launch playback. It starts `mpv.exe` with the right IPC socket and subtitle defaults. +- First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` to PATH. +- IPC socket on Windows is `\\.\pipe\subminer-socket` — do not use `/tmp/subminer-socket`. +- Config is stored at `%APPDATA%\SubMiner\config.jsonc`. + +## Manual Launcher Install + +The `subminer` launcher uses a [Bun](https://bun.sh) shebang, so Bun must be installed. First-run setup can handle this automatically, but if you prefer to do it yourself: + +### Linux {#manual-launcher-install-linux} + +```bash +# Install Bun +curl -fsSL https://bun.sh/install | bash + +# Download the launcher +wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer +chmod +x ~/.local/bin/subminer +``` + +### macOS {#manual-launcher-install-macos} + +```bash +# Install Bun +curl -fsSL https://bun.sh/install | bash + +# Download the launcher +sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer +sudo chmod +x /usr/local/bin/subminer +``` ## Optional Extras ### Rofi Theme (Linux Only) -SubMiner ships a custom rofi theme bundled in the release assets tarball. - -Install path (default auto-detected by `subminer`): - -- Linux: `~/.local/share/SubMiner/themes/subminer.rasi` -- macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi` +SubMiner ships a custom rofi theme in the release assets: ```bash wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz diff --git a/docs-site/usage.md b/docs-site/usage.md index 531a1aa0..fd5acef2 100644 --- a/docs-site/usage.md +++ b/docs-site/usage.md @@ -1,11 +1,23 @@ # Usage +## Quick Start + +Play a video with SubMiner: + +```bash +subminer video.mkv +``` + +On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup — double-click it, or drag a video file onto it. + +That's the simplest way to get started. The `subminer` launcher handles mpv, the IPC socket, and the overlay automatically. + > [!IMPORTANT] > SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work. > See [Yomitan setup](#yomitan-setup) for details. -::: tip Just finished first-run setup? -If you want Anki card enrichment (sentence, audio, screenshot), the only config you need is `ankiConnect` with your deck name and field names. Here is a minimal working example: +::: tip Anki card enrichment +If you want sentence, audio, and screenshot fields on your Anki cards, add this to your config: ```jsonc { @@ -27,25 +39,22 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I ## How It Works 1. SubMiner starts the overlay app in the background -2. MPV runs with an IPC socket at `/tmp/subminer-socket` +2. mpv runs with an IPC socket at `/tmp/subminer-socket` 3. The overlay connects and subscribes to subtitle changes 4. Subtitles are tokenized with Yomitan's internal parser 5. Words are displayed as interactive spans in the overlay 6. Hover a word, then trigger Yomitan lookup with your configured lookup key/modifier to open the Yomitan popup 7. Optional [subtitle annotations](/subtitle-annotations) (N+1, character-name, frequency, JLPT) highlight useful cues in real time -There are several ways to use SubMiner: - -> [!TIP] -> **New users on Linux/macOS: start with the `subminer` wrapper script.** On Windows, use the **SubMiner mpv** shortcut created during first-run setup. Both handle mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`. +### Ways to Launch | Approach | Use when | How | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| **`subminer` script** | You want SubMiner to handle everything — launch mpv, set up the socket, start the overlay. **The simplest path and recommended starting point.** | `subminer video.mkv` | -| **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 | +| **`subminer` launcher** | You want SubMiner to handle everything — launch mpv, set up the socket, start the overlay. **Recommended for most users.** | `subminer video.mkv` | +| **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults. | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` | +| **mpv plugin** (all platforms) | Bundled and injected at runtime. Provides `y` chord keybindings for controlling the overlay from within mpv. No manual install needed. | Automatic when using the launcher or shortcut | -You can use both — the plugin provides in-player controls, while the `subminer` script (Linux/macOS) or the SubMiner mpv shortcut (Windows) is convenient for direct playback. +The mpv plugin is always available — it's bundled with SubMiner and injected at runtime. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect. ## Live Config Reload @@ -72,8 +81,8 @@ subminer # Current directory (uses fzf) subminer -R # Use rofi instead of fzf subminer -d ~/Videos # Specific directory subminer -r -d ~/Anime # Recursive search -subminer video.mkv # Play specific file (default plugin config auto-starts visible overlay) -subminer --start video.mkv # Optional explicit overlay start (use when plugin auto_start=no) +subminer video.mkv # Play specific file (overlay auto-starts) +subminer --start video.mkv # Explicit overlay start (use when auto_start=no in config) subminer -S video.mkv # Same as above via --start-overlay subminer https://youtu.be/... # Play a YouTube URL subminer ytsearch:"jp news" # Play first YouTube search result @@ -128,7 +137,7 @@ SubMiner.AppImage --jellyfin-login --jellyfin-server http://127.0.0.1:8096 --jel SubMiner.AppImage --jellyfin-logout # Clear stored Jellyfin token/session data SubMiner.AppImage --jellyfin-libraries SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search anime --jellyfin-limit 20 -SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2 # Requires connected mpv IPC (--start or plugin workflow) +SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2 # Requires connected mpv IPC (--start) SubMiner.AppImage --jellyfin-remote-announce # Force cast-target capability announce + visibility check SubMiner.AppImage --dictionary # Generate character dictionary ZIP for current anime SubMiner.AppImage --dictionary-candidates # List AniList candidates for current character dictionary series @@ -153,7 +162,7 @@ Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for sta ### Windows mpv Shortcut -First-run setup creates the config file, then requires Yomitan dictionaries before it can finish. The global mpv plugin install is optional because SubMiner-managed mpv launches inject the bundled runtime plugin. +First-run setup creates the config file, then requires Yomitan dictionaries before it can finish. If you enabled the optional Windows shortcut during install, SubMiner creates a `SubMiner mpv` shortcut in the Start menu and/or on the desktop. On Windows, that shortcut is the recommended way to launch local files with SubMiner because it starts `mpv.exe` with the right defaults directly. After setup completes, the shortcut is the normal Windows playback entry point. @@ -197,13 +206,12 @@ SubMiner.AppImage --setup Setup flow: - config file: create the default config directory and prefer `config.jsonc` -- plugin compatibility: optionally install the legacy global mpv plugin; managed launches use the bundled runtime plugin without it -- legacy plugin cleanup: remove detected global SubMiner mpv plugin files from mpv script directories via the OS trash when you do not want regular mpv to load SubMiner +- legacy plugin cleanup: remove detected older global SubMiner mpv plugin files if present (the bundled plugin is injected at runtime automatically) - Yomitan shortcut: open bundled Yomitan settings directly from the setup window - dictionary check: ensure at least one bundled Yomitan dictionary is available, unless an external Yomitan profile is configured - Windows: optionally create or remove `SubMiner mpv` Start Menu/Desktop shortcuts (`SubMiner.exe --launch-mpv`) - Windows: optionally set `mpv.executablePath` if `mpv.exe` is not on `PATH` -- refresh: re-check plugin + dictionary state without restarting +- refresh: re-check dictionary state without restarting - `Finish setup` stays disabled until the config and dictionary gates are satisfied - finish action writes setup completion state and suppresses future auto-open prompts @@ -336,9 +344,9 @@ See [Keyboard Shortcuts](/shortcuts) for the full reference, including mining sh Useful overlay-local default keybinding: `Ctrl+Alt+P` opens the playlist browser for the current video's parent directory and the live mpv queue so you can append, reorder, remove, or jump between episodes without leaving playback. -Press `V` to hide or restore the primary SubMiner subtitle bar. The mpv plugin also binds bare `v` to the same action, overriding mpv's native primary subtitle visibility toggle. +Press `V` to hide or restore the primary SubMiner subtitle bar. The bundled mpv plugin also binds bare `v` to the same action (injected at runtime). -`Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. If you use the mpv plugin, the same help view is also available through the `y-h` chord. +`Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. The same help view is also available through the `y-h` chord in mpv. Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan popups also pause playback by default. Set `subtitleStyle.autoPauseVideoOnHover: false` or `subtitleStyle.autoPauseVideoOnYomitanPopup: false` to disable either behavior.