From 7a64488ed58814e788bbc853303831aff67ea33e Mon Sep 17 00:00:00 2001 From: sudacode Date: Mon, 6 Apr 2026 01:19:15 -0700 Subject: [PATCH] docs: refresh README and docs site guidance --- README.md | 11 +++--- docs-site/.vitepress/config.ts | 1 - docs-site/.vitepress/theme/tui-theme.css | 2 ++ docs-site/anilist-integration.md | 22 ------------ docs-site/anki-integration.md | 4 +++ docs-site/character-dictionary.md | 41 --------------------- docs-site/configuration.md | 2 -- docs-site/installation.md | 22 +++++++----- docs-site/jimaku-integration.md | 25 ------------- docs-site/jlpt-vocab-bundle.md | 45 ------------------------ docs-site/launcher-script.md | 34 +++++++++--------- docs-site/mining-workflow.md | 32 +++++------------ docs-site/mpv-plugin.md | 4 +++ docs-site/subtitle-annotations.md | 4 --- docs-site/subtitle-sidebar.md | 2 -- docs-site/troubleshooting.md | 9 +++-- docs-site/usage.md | 12 +++---- 17 files changed, 65 insertions(+), 207 deletions(-) delete mode 100644 docs-site/jlpt-vocab-bundle.md diff --git a/README.md b/README.md index b2a5f535..969bcf9c 100644 --- a/README.md +++ b/README.md @@ -125,9 +125,12 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open **Platform-specific:** -| Linux | macOS | Windows | -| ----------------------------------- | ------------------------ | ------------- | -| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps | +| 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.
Arch Linux @@ -138,7 +141,7 @@ paru -S --needed mpv ffmpeg 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 +# X11 / Xwayland (required for non-Hyprland compositors) paru -S --needed xdotool xorg-xwininfo ``` diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts index f3d282b6..42a3c326 100644 --- a/docs-site/.vitepress/config.ts +++ b/docs-site/.vitepress/config.ts @@ -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' }, ], }, diff --git a/docs-site/.vitepress/theme/tui-theme.css b/docs-site/.vitepress/theme/tui-theme.css index 1ff3b2f1..3776257b 100644 --- a/docs-site/.vitepress/theme/tui-theme.css +++ b/docs-site/.vitepress/theme/tui-theme.css @@ -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 { diff --git a/docs-site/anilist-integration.md b/docs-site/anilist-integration.md index a9cdd5a6..bec91aff 100644 --- a/docs-site/anilist-integration.md +++ b/docs-site/anilist-integration.md @@ -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. diff --git a/docs-site/anki-integration.md b/docs-site/anki-integration.md index faf4b8f8..cf1deb9a 100644 --- a/docs-site/anki-integration.md +++ b/docs-site/anki-integration.md @@ -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": { diff --git a/docs-site/character-dictionary.md b/docs-site/character-dictionary.md index 01fe8ec5..26d82277 100644 --- a/docs-site/character-dictionary.md +++ b/docs-site/character-dictionary.md @@ -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:` 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: diff --git a/docs-site/configuration.md b/docs-site/configuration.md index 7a3bad57..2e7c543a 100644 --- a/docs-site/configuration.md +++ b/docs-site/configuration.md @@ -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: diff --git a/docs-site/installation.md b/docs-site/installation.md index 82512c96..ce8345b1 100644 --- a/docs-site/installation.md +++ b/docs-site/installation.md @@ -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. +:::
Arch Linux @@ -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 ``` diff --git a/docs-site/jimaku-integration.md b/docs-site/jimaku-integration.md index 2c6e9b00..48d67b7c 100644 --- a/docs-site/jimaku-integration.md +++ b/docs-site/jimaku-integration.md @@ -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`: diff --git a/docs-site/jlpt-vocab-bundle.md b/docs-site/jlpt-vocab-bundle.md deleted file mode 100644 index 4e5f09bb..00000000 --- a/docs-site/jlpt-vocab-bundle.md +++ /dev/null @@ -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. diff --git a/docs-site/launcher-script.md b/docs-site/launcher-script.md index f5efa4b6..c6813b07 100644 --- a/docs-site/launcher-script.md +++ b/docs-site/launcher-script.md @@ -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 -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`) | diff --git a/docs-site/mining-workflow.md b/docs-site/mining-workflow.md index 683f65e1..e2905c2c 100644 --- a/docs-site/mining-workflow.md +++ b/docs-site/mining-workflow.md @@ -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: diff --git a/docs-site/mpv-plugin.md b/docs-site/mpv-plugin.md index 90502281..8b24476c 100644 --- a/docs-site/mpv-plugin.md +++ b/docs-site/mpv-plugin.md @@ -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: diff --git a/docs-site/subtitle-annotations.md b/docs-site/subtitle-annotations.md index 1f00422e..d6ddc7f7 100644 --- a/docs-site/subtitle-annotations.md +++ b/docs-site/subtitle-annotations.md @@ -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: diff --git a/docs-site/subtitle-sidebar.md b/docs-site/subtitle-sidebar.md index 5028d884..44df6feb 100644 --- a/docs-site/subtitle-sidebar.md +++ b/docs-site/subtitle-sidebar.md @@ -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 | diff --git a/docs-site/troubleshooting.md b/docs-site/troubleshooting.md index e3a599cd..a6f9f255 100644 --- a/docs-site/troubleshooting.md +++ b/docs-site/troubleshooting.md @@ -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` diff --git a/docs-site/usage.md b/docs-site/usage.md index 42250e9a..96e4b583 100644 --- a/docs-site/usage.md +++ b/docs-site/usage.md @@ -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