mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-04-06 22:19:22 -07:00
docs: refresh README and docs site guidance
This commit is contained in:
@@ -76,7 +76,6 @@ export default {
|
||||
{ text: 'Subtitle Annotations', link: '/subtitle-annotations' },
|
||||
{ text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
|
||||
{ text: 'Immersion Tracking', link: '/immersion-tracking' },
|
||||
{ text: 'JLPT Vocabulary Bundle', link: '/jlpt-vocab-bundle' },
|
||||
{ text: 'Troubleshooting', link: '/troubleshooting' },
|
||||
],
|
||||
},
|
||||
|
||||
@@ -220,6 +220,7 @@ button,
|
||||
color: var(--vp-c-brand-1);
|
||||
font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
|
||||
monospace;
|
||||
font-variant-ligatures: none;
|
||||
}
|
||||
|
||||
/* === Code blocks === */
|
||||
@@ -229,6 +230,7 @@ button,
|
||||
background: var(--vp-c-bg-alt) !important;
|
||||
font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
|
||||
monospace;
|
||||
font-variant-ligatures: none;
|
||||
}
|
||||
|
||||
.vp-doc div[class*='language-']::before {
|
||||
|
||||
@@ -41,28 +41,6 @@ The update flow:
|
||||
3. **Progress check** -- SubMiner fetches your current list entry for the matched media. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
|
||||
4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef ext fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
|
||||
Play["Media Plays"]:::step
|
||||
Detect["Episode Detected"]:::action
|
||||
Queue["Update Queue"]:::action
|
||||
Rate["Rate Limiter"]:::enrich
|
||||
GQL["GraphQL Mutation"]:::ext
|
||||
Done["Progress Updated"]:::result
|
||||
|
||||
Play --> Detect
|
||||
Detect --> Queue
|
||||
Queue --> Rate
|
||||
Rate --> GQL
|
||||
GQL --> Done
|
||||
```
|
||||
|
||||
## Update Queue and Retry
|
||||
|
||||
Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
|
||||
|
||||
@@ -250,6 +250,10 @@ The built-in translation request asks for English output by default. Customize t
|
||||
|
||||
SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.
|
||||
|
||||
::: warning Required config
|
||||
Sentence card creation and audio card marking both require `ankiConnect.isLapis.enabled: true` and a valid `sentenceCardModel` pointing to your Lapis/Kiku note type. Without this, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
|
||||
:::
|
||||
|
||||
```jsonc
|
||||
"ankiConnect": {
|
||||
"isLapis": {
|
||||
|
||||
@@ -4,23 +4,6 @@ SubMiner can build a Yomitan-compatible character dictionary from AniList metada
|
||||
|
||||
The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
|
||||
|
||||
## Stats Dashboard
|
||||
|
||||
The character dictionary and stats dashboard both read from the same local immersion data.
|
||||
|
||||
- Open the dashboard from overlay: press your configured `stats.toggleKey` (default: `` ` `` / `Backquote`).
|
||||
- Open from launcher/CLI: run `subminer stats`.
|
||||
- Open directly: visit `http://127.0.0.1:<stats.serverPort>` when the local server is running.
|
||||
|
||||
Useful config keys:
|
||||
|
||||
- `stats.autoStartServer` — start the local stats server automatically once immersion tracking starts.
|
||||
- `stats.serverPort` — local HTTP port for dashboard and API.
|
||||
- `stats.toggleKey` — key binding for overlay dashboard toggle.
|
||||
- `stats.autoOpenBrowser` — auto-open dashboard browser for `subminer stats`.
|
||||
|
||||
The dashboard gives quick visibility into episode summaries, watch-time rollups, session timelines, and vocabulary/kanji drill-down from the same DB used by character matching.
|
||||
|
||||
## How It Works
|
||||
|
||||
The feature has three stages: **snapshot**, **merge**, and **match**.
|
||||
@@ -31,30 +14,6 @@ The feature has three stages: **snapshot**, **merge**, and **match**.
|
||||
|
||||
3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. Tokens that match a character entry are flagged with `isNameMatch` and highlighted in the overlay with a distinct color.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
classDef api fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef store fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef build fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef dict fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef render fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
|
||||
AL["AniList API"]:::api
|
||||
Snap["Snapshot JSON"]:::store
|
||||
Merge["Merge"]:::build
|
||||
ZIP["Yomitan ZIP"]:::dict
|
||||
Yomi["Yomitan Import"]:::dict
|
||||
Sub["Subtitle Scan"]:::render
|
||||
HL["Name Highlight"]:::render
|
||||
|
||||
AL -->|"GraphQL"| Snap
|
||||
Snap --> Merge
|
||||
Merge --> ZIP
|
||||
ZIP --> Yomi
|
||||
Yomi --> Sub
|
||||
Sub --> HL
|
||||
```
|
||||
|
||||
## Enabling the Feature
|
||||
|
||||
Character dictionary sync is disabled by default. To turn it on:
|
||||
|
||||
@@ -324,8 +324,6 @@ See `config.example.jsonc` for detailed configuration options.
|
||||
| `jlptColors` | object | JLPT level underline colors object (`N1`..`N5`) |
|
||||
| `secondary` | object | Override any of the above for secondary subtitles (optional) |
|
||||
|
||||
JLPT underlining is powered by offline term-meta bank files at runtime. See [`docs/jlpt-vocab-bundle.md`](jlpt-vocab-bundle.md) for required files, source/version refresh steps, and deterministic fallback behavior.
|
||||
|
||||
Frequency dictionary highlighting uses the same dictionary file format as JLPT bundle lookups (`term_meta_bank_*.json` under discovered dictionary directories). A token is highlighted when it has a positive integer `frequencyRank` (lower is more common) and the rank is within `topX`.
|
||||
|
||||
Lookup behavior:
|
||||
|
||||
@@ -28,11 +28,15 @@ The `subminer` launcher script handles step 1 automatically. If you launch mpv y
|
||||
|
||||
### Platform-Specific
|
||||
|
||||
**Linux** — one of the following compositors:
|
||||
**Linux** — one of the following window backends:
|
||||
|
||||
- Hyprland (uses `hyprctl`)
|
||||
- Sway (uses `swaymsg`)
|
||||
- X11 (uses `xdotool` and `xwininfo`)
|
||||
- **Hyprland** — native Wayland support (uses `hyprctl`)
|
||||
- **Sway** — native Wayland support (uses `swaymsg`)
|
||||
- **X11 / Xwayland** — for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
|
||||
|
||||
::: warning Wayland support is compositor-specific
|
||||
Wayland has no universal API for window positioning — each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
|
||||
:::
|
||||
|
||||
<details>
|
||||
<summary><b>Arch Linux</b></summary>
|
||||
@@ -43,7 +47,7 @@ sudo pacman -S --needed mpv ffmpeg
|
||||
sudo pacman -S --needed mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
|
||||
# Optional: subtitle sync (at least one needed for subtitle syncing)
|
||||
paru -S --needed alass python-ffsubsync
|
||||
# X11 / XWAYLAND
|
||||
# X11 / Xwayland (required for non-Hyprland/Sway compositors)
|
||||
sudo pacman -S --needed xdotool xorg-xwininfo
|
||||
```
|
||||
|
||||
@@ -56,7 +60,7 @@ sudo pacman -S --needed xdotool xorg-xwininfo
|
||||
sudo apt install mpv ffmpeg
|
||||
# Optional
|
||||
sudo apt install mecab libmecab-dev mecab-ipadic-utf8 fzf rofi chafa ffmpegthumbnailer yt-dlp
|
||||
# X11
|
||||
# X11 / Xwayland (required for non-Hyprland/Sway compositors)
|
||||
sudo apt install xdotool x11-utils
|
||||
# Optional: subtitle sync
|
||||
pip install ffsubsync
|
||||
@@ -72,7 +76,7 @@ pip install ffsubsync
|
||||
sudo dnf install mpv ffmpeg
|
||||
# Optional
|
||||
sudo dnf install mecab mecab-ipadic fzf rofi chafa ffmpegthumbnailer yt-dlp
|
||||
# X11
|
||||
# X11 / Xwayland (required for non-Hyprland/Sway compositors)
|
||||
sudo dnf install xdotool xorg-x11-utils
|
||||
# Optional: subtitle sync
|
||||
pip install ffsubsync
|
||||
@@ -456,7 +460,7 @@ This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix a
|
||||
|
||||
### Rofi Theme (Linux Only)
|
||||
|
||||
SubMiner ships a default rofi theme at `assets/themes/subminer.rasi`.
|
||||
SubMiner ships a custom rofi theme bundled in the release assets tarball.
|
||||
|
||||
Install path (default auto-detected by `subminer`):
|
||||
|
||||
@@ -464,6 +468,8 @@ Install path (default auto-detected by `subminer`):
|
||||
- macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
@@ -26,31 +26,6 @@ If no files match the current episode filter, a "Show all files" button lets you
|
||||
| `Arrow Up` / `Arrow Down` | Navigate entries or files |
|
||||
| `Escape` | Close modal |
|
||||
|
||||
### Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
|
||||
Open["Open Jimaku modal (Ctrl+Shift+J)"]:::step
|
||||
Parse["Auto-fill title, season, episode from filename"]:::enrich
|
||||
Search["Search Jimaku API"]:::action
|
||||
Entries["Browse matching entries"]:::action
|
||||
Files["Browse subtitle files"]:::action
|
||||
Download["Download selected file"]:::action
|
||||
Load["Load subtitle into mpv"]:::result
|
||||
|
||||
Open --> Parse
|
||||
Parse --> Search
|
||||
Search --> Entries
|
||||
Entries --> Files
|
||||
Files --> Download
|
||||
Download --> Load
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Add a `jimaku` section to your `config.jsonc`:
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# JLPT Vocabulary Bundle (Offline)
|
||||
|
||||
## Bundle location
|
||||
|
||||
SubMiner expects the JLPT term-meta bank files to be available locally at:
|
||||
|
||||
- `vendor/yomitan-jlpt-vocab`
|
||||
|
||||
At runtime, SubMiner also searches these derived locations:
|
||||
|
||||
- `vendor/yomitan-jlpt-vocab`
|
||||
- `vendor/yomitan-jlpt-vocab/vendor/yomitan-jlpt-vocab`
|
||||
- `vendor/yomitan-jlpt-vocab/yomitan-jlpt-vocab`
|
||||
|
||||
and user-data/config fallback paths (see `getJlptDictionarySearchPaths` in `src/main.ts`).
|
||||
|
||||
## Required files
|
||||
|
||||
The expected files are:
|
||||
|
||||
- `term_meta_bank_1.json`
|
||||
- `term_meta_bank_2.json`
|
||||
- `term_meta_bank_3.json`
|
||||
- `term_meta_bank_4.json`
|
||||
- `term_meta_bank_5.json`
|
||||
|
||||
Each bank maps terms to frequency metadata; only entries with a `frequency.displayValue` are considered for JLPT tagging.
|
||||
|
||||
SubMiner also reuses the same `term_meta_bank_*.json` format for frequency-based subtitle highlighting, using installed/default `frequency-dictionary` locations or an explicit `subtitleStyle.frequencyDictionary.sourcePath`.
|
||||
|
||||
## Source and update process
|
||||
|
||||
For reproducible updates:
|
||||
|
||||
1. Obtain the JLPT term-meta bank archive from the same upstream source that supplies the bundled Yomitan dictionary data.
|
||||
2. Extract the five `term_meta_bank_*.json` files.
|
||||
3. Place them into `vendor/yomitan-jlpt-vocab/`.
|
||||
4. Commit the update with the source URL/version in the task notes.
|
||||
|
||||
This repository currently ships the folder path in `electron-builder` `extraResources` as:
|
||||
`vendor/yomitan-jlpt-vocab -> yomitan-jlpt-vocab`.
|
||||
|
||||
## Fallback Behavior
|
||||
|
||||
If bank files are missing, malformed, or lack expected metadata, SubMiner skips them gracefully. When no usable entries are found, JLPT underlining is silently disabled and subtitle rendering remains unchanged.
|
||||
@@ -13,9 +13,9 @@ When you run `subminer` without specifying a file, it opens an interactive video
|
||||
### fzf (default)
|
||||
|
||||
```bash
|
||||
subminer # pick from current directory
|
||||
subminer -d ~/Videos # pick from a specific directory
|
||||
subminer -r -d ~/Anime # recursive search
|
||||
subminer # pick from current directory
|
||||
subminer -d ~/Videos # pick from a specific directory
|
||||
subminer -r -d ~/Anime # recursive search
|
||||
```
|
||||
|
||||
fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you get thumbnail previews in the right pane. Thumbnails are sourced from the freedesktop thumbnail cache first, then generated on the fly with `ffmpegthumbnailer` or `ffmpeg` as fallback.
|
||||
@@ -28,14 +28,17 @@ fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you g
|
||||
### rofi
|
||||
|
||||
```bash
|
||||
subminer -R # rofi picker, current directory
|
||||
subminer -R -d ~/Videos # rofi picker, specific directory
|
||||
subminer -R -r -d ~/Anime # rofi picker, recursive
|
||||
subminer -R # rofi picker, current directory
|
||||
subminer -R -d ~/Videos # rofi picker, specific directory
|
||||
subminer -R -r -d ~/Anime # rofi picker, recursive
|
||||
subminer -R /directory # rofi picker, directory shortcut
|
||||
```
|
||||
|
||||
rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme that can be installed from the release assets:
|
||||
rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme bundled in the release assets tarball:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
@@ -57,15 +60,11 @@ SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
subminer video.mkv # play a specific file (default plugin config auto-starts visible overlay)
|
||||
subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no
|
||||
subminer -S video.mkv # same as above via --start-overlay
|
||||
subminer https://youtu.be/... # YouTube playback (requires yt-dlp)
|
||||
subminer ytsearch:"jp news" # YouTube search
|
||||
subminer stats # open immersion dashboard
|
||||
subminer stats -b # start background stats daemon
|
||||
subminer stats -s # stop background stats daemon
|
||||
subminer --setup # Open first-run setup popup
|
||||
subminer video.mkv # play a specific file (default plugin config auto-starts visible overlay)
|
||||
subminer https://youtu.be/... # YouTube playback (requires yt-dlp)
|
||||
subminer --backend x11 video.mkv # Force x11 backend for a specific file
|
||||
subminer stats # open immersion dashboard
|
||||
subminer stats -b # start background stats daemon
|
||||
```
|
||||
|
||||
## Subcommands
|
||||
@@ -75,7 +74,6 @@ subminer --setup # Open first-run setup popup
|
||||
| `subminer jellyfin` / `jf` | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login) |
|
||||
| `subminer stats` | Start stats server and open immersion dashboard in browser |
|
||||
| `subminer stats -b` | Start or reuse background stats daemon (non-blocking) |
|
||||
| `subminer stats -s` | Stop the background stats daemon |
|
||||
| `subminer stats cleanup` | Backfill vocabulary metadata and prune stale rows |
|
||||
| `subminer doctor` | Dependency + config + socket diagnostics |
|
||||
| `subminer config path` | Print active config file path |
|
||||
@@ -100,7 +98,7 @@ Use `subminer <subcommand> -h` for command-specific help.
|
||||
| `--start` | Explicitly start overlay after mpv launches |
|
||||
| `-S, --start-overlay` | Explicitly start overlay after mpv launches |
|
||||
| `-T, --no-texthooker` | Disable texthooker server |
|
||||
| `-p, --profile` | mpv profile name (default: `subminer`) |
|
||||
| `-p, --profile` | mpv profile name (no default; omitted unless set) |
|
||||
| `-a, --args` | Pass additional mpv arguments as a quoted string |
|
||||
| `-b, --backend` | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`) |
|
||||
| `--log-level` | Logger verbosity (`debug`, `info`, `warn`, `error`) |
|
||||
|
||||
@@ -6,30 +6,6 @@ This guide walks through the sentence mining loop — from watching a video to c
|
||||
|
||||
SubMiner runs as a transparent overlay on top of mpv. As subtitles play, the overlay displays them as interactive text. You hover a word, trigger Yomitan lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, audio clip, and screenshot.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
|
||||
|
||||
Watch["Watch Video"]:::step
|
||||
Sub["Subtitle Appears"]:::step
|
||||
Hover["Hover Word"]:::action
|
||||
Lookup["Trigger Lookup"]:::action
|
||||
Yomi["Yomitan Popup"]:::result
|
||||
Add["Add to Anki"]:::result
|
||||
|
||||
Watch --> Sub --> Hover --> Lookup --> Yomi --> Add
|
||||
|
||||
Add --> Enrich["SubMiner Enriches"]:::enrich
|
||||
|
||||
Enrich --> S["Sentence"]:::enrich
|
||||
Enrich --> A["Audio Clip"]:::enrich
|
||||
Enrich --> I["Screenshot"]:::enrich
|
||||
Enrich --> T["Translation"]:::enrich
|
||||
```
|
||||
|
||||
## Subtitle Delivery Path (Startup + Runtime)
|
||||
|
||||
SubMiner prioritizes subtitle responsiveness over heavy initialization:
|
||||
@@ -141,10 +117,18 @@ Create a standalone sentence card without going through Yomitan:
|
||||
|
||||
The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.
|
||||
|
||||
::: warning Requires Lapis/Kiku note type
|
||||
Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
|
||||
:::
|
||||
|
||||
### 4. Mark as Audio Card
|
||||
|
||||
After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.
|
||||
|
||||
::: warning Requires Lapis/Kiku note type
|
||||
Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
|
||||
:::
|
||||
|
||||
## Secondary Subtitles
|
||||
|
||||
SubMiner can display a secondary subtitle track (typically English) alongside the primary Japanese subtitles. This is useful for:
|
||||
|
||||
@@ -183,6 +183,10 @@ When `backend=auto`, the plugin detects the window manager:
|
||||
4. **X11** — detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
|
||||
5. **Fallback** — defaults to X11 with a warning.
|
||||
|
||||
::: tip Wayland is compositor-specific
|
||||
Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 — both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
|
||||
:::
|
||||
|
||||
## Script Messages
|
||||
|
||||
The plugin can be controlled from other mpv scripts or the mpv command line using script messages:
|
||||
|
||||
@@ -113,10 +113,6 @@ All colors are customizable via the `subtitleStyle.jlptColors` object.
|
||||
| `subtitleStyle.enableJlpt` | `false` | Enable JLPT underline styling |
|
||||
| `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors |
|
||||
|
||||
::: tip
|
||||
JLPT tagging requires the offline vocabulary bundle. See [JLPT Vocabulary Bundle](jlpt-vocab-bundle) for setup instructions and file locations.
|
||||
:::
|
||||
|
||||
## Runtime Toggles
|
||||
|
||||
All annotation layers can be toggled at runtime via the mpv command menu without restarting:
|
||||
|
||||
@@ -60,8 +60,6 @@ Enable and configure the sidebar under `subtitleSidebar` in your config file:
|
||||
| `activeLineBackgroundColor` | string | — | Active cue background color |
|
||||
| `hoverLineBackgroundColor` | string | — | Hovered cue background color |
|
||||
|
||||
Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like a solid overlay.
|
||||
|
||||
## Keyboard Shortcut
|
||||
|
||||
| Key | Action | Config key |
|
||||
|
||||
@@ -136,7 +136,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo
|
||||
**Overlay does not appear**
|
||||
|
||||
- Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
|
||||
- On Linux, the overlay requires a compositor. Hyprland and Sway are supported natively; X11 requires `xdotool` and `xwininfo`.
|
||||
- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool` and `xwininfo` must be installed).
|
||||
- On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
|
||||
|
||||
**Overlay appears but clicks pass through / cannot interact**
|
||||
@@ -232,7 +232,7 @@ Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applicat
|
||||
|
||||
- Check your DE/WM keybinding settings for conflicts.
|
||||
- Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
|
||||
- On Wayland, global shortcut registration has limitations depending on the compositor.
|
||||
- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively — see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
|
||||
|
||||
**Overlay keybindings not working**
|
||||
|
||||
@@ -289,8 +289,8 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
|
||||
|
||||
### Linux
|
||||
|
||||
- **Wayland (Hyprland/Sway)**: Window tracking uses compositor-specific commands. If `hyprctl` or `swaymsg` are not on `PATH`, tracking will fail silently.
|
||||
- **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position.
|
||||
- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors are not supported — both mpv and SubMiner must run under X11 or Xwayland instead.
|
||||
- **X11 / Xwayland**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway — both mpv and SubMiner must be running under X11/Xwayland for window tracking to work.
|
||||
- **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath.
|
||||
|
||||
### Hyprland
|
||||
@@ -329,5 +329,4 @@ For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.l
|
||||
### macOS
|
||||
|
||||
- **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
|
||||
- **Font rendering**: macOS uses a 0.87x font compensation factor for subtitle alignment between mpv and the overlay. If text alignment looks off, adjust subtitle offset by right-click dragging subtitle text.
|
||||
- **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`
|
||||
|
||||
@@ -37,7 +37,7 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I
|
||||
There are several ways to use SubMiner:
|
||||
|
||||
> [!TIP]
|
||||
> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`. You can add the mpv plugin later for in-player keybindings.
|
||||
> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`.
|
||||
|
||||
| Approach | Use when | How |
|
||||
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
||||
@@ -85,8 +85,8 @@ subminer --args '--fs=opengl-hq --ytdl-format=bestvideo*+bestaudio/best' video.m
|
||||
# Options
|
||||
subminer -T video.mkv # Disable texthooker server
|
||||
subminer -b x11 video.mkv # Force X11 backend
|
||||
subminer video.mkv # Uses mpv profile "subminer" by default
|
||||
subminer -p gpu-hq video.mkv # Override mpv profile
|
||||
subminer video.mkv # No mpv profile passed by default
|
||||
subminer -p gpu-hq video.mkv # Use a specific mpv profile
|
||||
subminer jellyfin # Open Jellyfin setup window (subcommand form)
|
||||
subminer jellyfin -l --server http://127.0.0.1:8096 --username me --password 'secret'
|
||||
subminer jellyfin --logout # Clear stored Jellyfin token/session data
|
||||
@@ -157,7 +157,7 @@ You can use it three ways:
|
||||
& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
|
||||
```
|
||||
|
||||
This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback. On Windows, `--launch-mpv` does not require an `mpv.conf` profile named `subminer`.
|
||||
This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback.
|
||||
|
||||
### Launcher Subcommands
|
||||
|
||||
@@ -172,7 +172,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
|
||||
|
||||
### First-Run Setup
|
||||
|
||||
SubMiner auto-opens the setup popup on fresh installs when launched with `--start` or `--background` and setup is incomplete.
|
||||
Setup popup appears on first launch, or when setup has not been completed.
|
||||
|
||||
You can also open it manually:
|
||||
|
||||
@@ -262,7 +262,7 @@ Notes:
|
||||
- Secondary target languages come from `secondarySub.secondarySubLanguages` (defaults to English if unset).
|
||||
- Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.
|
||||
|
||||
For local video files, SubMiner now uses those same config-driven language priorities after mpv finishes reporting subtitle tracks. That means mixed internal/external subtitle sets can correct an initial `sid=auto` guess and settle onto the expected primary and secondary tracks without manual cycling.
|
||||
For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
|
||||
|
||||
## Controller Support
|
||||
|
||||
|
||||
Reference in New Issue
Block a user