sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-04-05 00:12:06 -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
| | Required | Optional |
| -------------- | --------------------------------------- | ---------------------------------------------------------- |
| **Player** | [`mpv`](https://mpv.io) with IPC socket | — |
| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic` | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
| **Media** | — | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
| **Selection** | — | `fzf` / `rofi` |
| | 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` |
> [!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.
@@ -132,9 +135,9 @@ Managed local playback now reapplies your configured subtitle language prioritie
<summary><b>Arch Linux</b></summary>
```bash
paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
paru -S --needed mpv ffmpeg
# 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)
paru -S --needed alass python-ffsubsync
# X11 / XWAYLAND
@@ -147,9 +150,9 @@ paru -S --needed xdotool xorg-xwininfo
<summary><b>macOS</b></summary>
```bash
brew install mpv ffmpeg mecab mecab-ipadic
brew install mpv ffmpeg
# 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)
brew install alass
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`.
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>
@@ -226,11 +229,17 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
</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.
### 3. Mine
### 4. Mine
```bash
subminer video.mkv # play video with overlay

43
docs-site/installation.md
View File

@@ -5,11 +5,11 @@
### System Dependencies
| Dependency | Required | Notes |
| -------------------- | ---------- | -------------------------------------------------------- |
| Bun | Yes | Required for `subminer` wrapper and source workflows |
| -------------------- | ----------- | -------------------------------------------------------- |
| mpv | Yes | Must support IPC sockets (`--input-ipc-server`) |
| ffmpeg | For media | Audio extraction and screenshot generation |
| MeCab + mecab-ipadic | No | Optional Japanese metadata enrichment (not the primary tokenizer) |
| 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 |
@@ -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
@@ -103,7 +105,9 @@ A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.
Install dependencies using Homebrew:
```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)
@@ -123,13 +127,20 @@ For unsigned local builds:
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
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
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.
@@ -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>.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
@@ -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
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
```
@@ -240,7 +255,13 @@ See [MPV Plugin](/mpv-plugin) for the full configuration reference, keybindings,
## 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.

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.
> 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
1. SubMiner starts the overlay app in the background