sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-04-05 12:12:05 -07:00
Code Issues Packages Projects Releases Wiki Activity

Clarify install requirements and dependency checks

Browse Source 
- Reclassify ffmpeg and MeCab as recommended or optional
- Add `subminer doctor` install verification step
- Refresh platform-specific install guidance and first-run tips
This commit is contained in:
Kyle Yasuda
2026-04-04 12:51:37 -07:00
parent a784091ecb
commit 6530d2ccbc
3 changed files with 78 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -112,12 +112,15 @@ Managed local playback now reapplies your configured subtitle language prioritie
## Requirements ## Requirements
| | Required | Optional | | | Required | Recommended | Optional |
| -------------- | --------------------------------------- | ---------------------------------------------------------- | | -------------- | --------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
| **Player** | [`mpv`](https://mpv.io) with IPC socket | — | | **Player** | [`mpv`](https://mpv.io) with IPC socket | — | — |
| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic` | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) | | **Processing** | — | `ffmpeg` (audio clips & screenshots) | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
| **Media** | — | `yt-dlp`, `chafa`, `ffmpegthumbnailer` | | **Media** | — | — | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
| **Selection** | — | `fzf` / `rofi` | | **Selection** | — | — | `fzf` / `rofi` |
> [!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] > [!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. > [`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.
@@ -132,9 +135,9 @@ Managed local playback now reapplies your configured subtitle language prioritie
<summary><b>Arch Linux</b></summary> <summary><b>Arch Linux</b></summary>
```bash ```bash
paru -S --needed mpv ffmpeg mecab-git mecab-ipadic paru -S --needed mpv ffmpeg
# Optional # Optional
paru -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo 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) # Optional: subtitle sync (install at least one for subtitle syncing to work)
paru -S --needed alass python-ffsubsync paru -S --needed alass python-ffsubsync
# X11 / XWAYLAND # X11 / XWAYLAND
@@ -147,9 +150,9 @@ paru -S --needed xdotool xorg-xwininfo
<summary><b>macOS</b></summary> <summary><b>macOS</b></summary>
```bash ```bash
brew install mpv ffmpeg mecab mecab-ipadic brew install mpv ffmpeg
# Optional # Optional
brew install yt-dlp fzf rofi chafa ffmpegthumbnailer brew install mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
# Optional: subtitle sync (install at least one for subtitle syncing to work) # Optional: subtitle sync (install at least one for subtitle syncing to work)
brew install alass brew install alass
pip install ffsubsync pip install ffsubsync
@@ -164,7 +167,7 @@ Grant Accessibility permission to SubMiner in **System Settings > Privacy & Secu
Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`. Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`.
For MeCab, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary. Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary for additional metadata enrichment.
</details> </details>
@@ -226,11 +229,17 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
</details> </details>
### 2. First Launch ### 2. Check Dependencies
```bash
subminer doctor # verify mpv, ffmpeg, config, and socket
```
### 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. 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.
### 3. Mine ### 4. Mine
```bash ```bash
subminer video.mkv # play video with overlay subminer video.mkv # play video with overlay

51
docs-site/installation.md
View File

@@ -4,14 +4,14 @@
### System Dependencies ### System Dependencies
| Dependency | Required | Notes | | Dependency | Required | Notes |
| -------------------- | ---------- | -------------------------------------------------------- | | -------------------- | ----------- | -------------------------------------------------------- |
| Bun | Yes | Required for `subminer` wrapper and source workflows | | mpv | Yes | Must support IPC sockets (`--input-ipc-server`) |
| 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 | For media | Audio extraction and screenshot generation | | 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 | Optional Japanese metadata enrichment (not the primary tokenizer) | | 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 | | fuse2 | Linux only | Required for AppImage |
| yt-dlp | No | Recommended for YouTube playback and subtitle extraction | | yt-dlp | No | Recommended for YouTube playback and subtitle extraction |
### Platform-Specific ### Platform-Specific
@@ -70,7 +70,9 @@ 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`. ::: 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.
:::
### From Source ### From Source
@@ -103,7 +105,9 @@ A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.
Install dependencies using Homebrew: Install dependencies using Homebrew:
```bash ```bash
brew install mpv mecab mecab-ipadic brew install mpv ffmpeg
# Optional but recommended if you use N+1, JLPT, or frequency annotations
brew install mecab mecab-ipadic
``` ```
### From Source (macOS) ### From Source (macOS)
@@ -123,13 +127,20 @@ For unsigned local builds:
bun run build:mac:unsigned 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:
```bash
xattr -d com.apple.quarantine /Applications/SubMiner.app
```
### Accessibility Permission ### Accessibility Permission
After launching SubMiner for the first time, grant accessibility permission: After launching SubMiner for the first time, grant accessibility permission:
1. Open **System Preferences** → **Security & Privacy** → **Privacy** tab 1. Open **System Settings** → **Privacy & Security** → **Accessibility**
2. Select **Accessibility** from the left sidebar 2. Enable SubMiner in the list (add it if it does not appear)
3. Add SubMiner to the list
Without this permission, window tracking will not work and the overlay won't follow the mpv window. Without this permission, window tracking will not work and the overlay won't follow the mpv window.
@@ -167,7 +178,7 @@ Download the latest Windows installer from [GitHub Releases](https://github.com/
- `SubMiner-<version>.exe` installs the app, Start menu shortcut, and default files under `Program Files` - `SubMiner-<version>.exe` installs the app, Start menu shortcut, and default files under `Program Files`
- `SubMiner-<version>.zip` is available as a portable fallback - `SubMiner-<version>.zip` is available as a portable fallback
Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is still required for media extraction, and MeCab remains optional. 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 ### Windows Usage Notes
@@ -184,10 +195,14 @@ Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is still re
git clone https://github.com/ksyasuda/SubMiner.git git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner cd SubMiner
bun install 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 Set-Location vendor/texthooker-ui
bun install --frozen-lockfile bun install --frozen-lockfile
bun run build bun run build
Set-Location ../.. Set-Location ../..
bun run build:win bun run build:win
``` ```
@@ -240,7 +255,13 @@ See [MPV Plugin](/mpv-plugin) for the full configuration reference, keybindings,
## Verify Installation ## Verify Installation
After installing, confirm SubMiner is working: After installing, run the built-in diagnostic to confirm dependencies are in place:
```bash
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. On Windows, replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.

20
docs-site/usage.md
View File

@@ -4,6 +4,26 @@
> SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work. > SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work.
> See [Yomitan setup](#yomitan-setup) for details. > 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:
```jsonc
{
"ankiConnect": {
"enabled": true,
"deck": "Mining",
"fields": {
"sentence": "Sentence",
"audio": "SentenceAudio",
"image": "Picture"
}
}
}
```
Field names must match your Anki note type exactly (case-sensitive). See [Anki Integration](/anki-integration) for the full reference.
:::
## How It Works ## How It Works
1. SubMiner starts the overlay app in the background 1. SubMiner starts the overlay app in the background