From 9fadbc8cdd9d8266ba059870ee048f4ed8c40703 Mon Sep 17 00:00:00 2001 From: sudacode Date: Wed, 30 Sep 2026 23:45:53 -0700 Subject: [PATCH] docs: align README with installation guide and fix Arch MeCab install - Install MeCab from the AUR (mecab-git) on Arch, since it is not in the official repos - Rewrite the README feature blurbs, requirements table, and quick start so they match docs-site/installation.md - Add fuse2, X11 window tools, whisper.cpp, and the thumbnail tools to the README requirements - Drop the playlist browser and texthooker sections and the standalone launcher download steps - Mention AniList as a guessit consumer in the installation guide --- README.md | 120 ++++++++++++++++------------------ changes/docs-site-simplify.md | 1 + docs-site/installation.md | 28 ++++---- 3 files changed, 70 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 3437e354..c07a02c4 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # SubMiner -Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersion without leaving the player +Look up words with Yomitan, mine them to Anki, and track your immersion without leaving mpv [Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe) @@ -23,7 +23,7 @@ Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersio ### Dictionary Lookups -Hover over any word and trigger a lookup to get the full Yomitan popup - definitions, pitch accent, and frequency data - without ever leaving mpv. +Hover over any word in the subtitles to open the full Yomitan popup with definitions, pitch accent, and frequency data. SubMiner bundles its own Yomitan, separate from any browser install.
Yomitan dictionary popup over annotated subtitles in mpv @@ -33,7 +33,7 @@ Hover over any word and trigger a lookup to get the full Yomitan popup - definit ### Instant Anki Mining -Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input. +Create an Anki card from the exact playback moment with one key press, click, or controller input. SubMiner fills in the sentence, an audio clip, and a screenshot or animated image.
Anki card created from SubMiner with sentence, audio, and screenshot @@ -43,7 +43,7 @@ Create an Anki card with the sentence, audio clip, screenshot, and machine trans ### Reading Annotations -Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Grammar-only tokens and particles render as plain text so you focus on what matters. +Subtitles are annotated as they play with frequency highlighting, JLPT tags, N+1 targeting, and character names from a generated dictionary. Particles and grammar-only tokens stay plain so the words worth learning stand out.
Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets @@ -53,7 +53,7 @@ Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targe ### Immersion Dashboard -Local stats dashboard tracking watch time, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking. +A stats dashboard tracks watch time, vocabulary growth, mining throughput, session history, and trends. Everything stays on your machine, with no third-party tracking.
Stats dashboard showing watch time, cards mined, streaks, and tracking data @@ -61,22 +61,12 @@ Local stats dashboard tracking watch time, vocabulary growth, mining throughput,
-### Playlist Browser - -Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback. - -
- Playlist browser modal showing sibling episode files beside the active mpv queue -
- -
- ### Integrations - + @@ -84,19 +74,19 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open - + - - - - - + - + + + + + @@ -104,7 +94,7 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open - + @@ -112,29 +102,29 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
YouTubeAuto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (Ctrl+Alt+C)Play YouTube URLs with subtitle tracks picked by your language priorities, or choose tracks yourself in the overlay picker (Ctrl+Alt+C). Requires yt-dlp
AniList
JellyfinBrowse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app trayBrowse your Jellyfin library, or cast to SubMiner from any Jellyfin client. Setup and discovery live in the tray menu
JimakuSearch and download Japanese subtitles
Local Subtitle GenerationGenerate Japanese subtitles from local audio in a standalone modal (Ctrl+Shift+G), the sidebar button, or launcher, with progress and optional managed model downloads. Requires whisper.cpp and FFmpeg. Optional Silero speech detection prioritizes dialogue in separately timed passages. Setup guideSearch and download Japanese subtitles. Requires a free Jimaku API key
TsukiHimeSearch and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (Ctrl+Shift+T) — no API key, requires xz on your PATHSearch and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (Ctrl+Shift+T). Requires xz on your PATH
Subtitle generationTranscribe a video's audio into Japanese subtitles locally from the generation modal (Ctrl+Shift+G), the subtitle sidebar, or the launcher. SubMiner can download models for you; optional Silero speech detection helps focus on dialogue. Requires whisper.cpp and FFmpeg. Setup guide
AniSkip
alass / ffsubsyncManual subtitle retiming — requires alass or ffsubsync on your PATH (optional; subtitle syncing is disabled without them)Retime a subtitle against the audio or another subtitle track (Ctrl+Alt+S). Requires alass or ffsubsync; set subsync.alass_path or subsync.ffsubsync_path if they are not in /usr/bin
WebSocket
-
- Texthooker page receiving annotated subtitle lines via WebSocket -
-
--- ## Requirements -Only **mpv** is required to run SubMiner. Anki + AnkiConnect are required to mine cards, which is the point of the app, but everything else is optional. +SubMiner runs on Linux, macOS 11+, and Windows 10+. Only **mpv** is required to run it (plus `fuse2` for the Linux AppImage). Mining cards also needs Anki with the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on. Everything else is optional. -| Dependency | Status | What it does | -| -------------------- | ---------------- | -------------------------------------------------------- | -| mpv | Required | The video player SubMiner overlays on | -| Anki + AnkiConnect | Required to mine | Card creation from the Yomitan popup | -| ffmpeg | Recommended | Audio clips & screenshots for Anki cards | -| MeCab + mecab-ipadic | Recommended | More precise annotations and filtering | -| yt-dlp | Optional | YouTube playback | -| xz | Optional | TsukiHime subtitle downloads (not on Windows by default) | -| alass / ffsubsync | Optional | Subtitle sync | -| guessit | Optional | Better anime title and episode detection | -| fzf / rofi | Optional | Video picker in the `subminer` launcher (Linux/macOS) | +| Dependency | Status | What it does | +| ------------------------ | ---------------- | -------------------------------------------------------------------- | +| mpv | Required | The video player SubMiner draws over | +| fuse2 | Required (Linux) | Running the AppImage | +| Anki + AnkiConnect | Required to mine | Card creation from the Yomitan popup | +| ffmpeg | Recommended | Audio clips and screenshots on cards | +| MeCab + mecab-ipadic | Recommended | More accurate N+1, JLPT, and frequency highlighting | +| xdotool + xwininfo | Required (X11) | Window tracking on desktops other than Hyprland or Sway | +| yt-dlp | Optional | YouTube playback | +| xz | Optional | TsukiHime subtitle downloads (most Linux distros already have it) | +| alass / ffsubsync | Optional | Subtitle sync | +| whisper.cpp | Optional | [Subtitle generation](https://docs.subminer.moe/subtitle-generation) | +| guessit | Optional | Better title, season, and episode detection for AniSkip and AniList | +| fzf / rofi | Optional | Video picker in the `subminer` launcher (rofi is Linux only) | +| chafa, ffmpegthumbnailer | Optional | Thumbnail previews in the launcher pickers |
Platform-specific install commands @@ -142,9 +132,12 @@ Only **mpv** is required to run SubMiner. Anki + AnkiConnect are required to min **Arch Linux:** ```bash -sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic +sudo pacman -S --needed mpv ffmpeg +paru -S --needed mecab-git mecab-ipadic # MeCab is only in the AUR ``` +On desktops other than Hyprland or Sway, also install `xdotool` and `xorg-xwininfo`. + **macOS:** ```bash @@ -158,16 +151,16 @@ winget install shinchiro.mpv winget install Gyan.FFmpeg ``` -Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. winget puts `ffmpeg` on `PATH` automatically; mpv uses a regular installer that may not, so if `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or set `mpv.executablePath` during first-run setup. +Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. ffmpeg must be on `PATH`; mpv does not have to be. If `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or enter the full path to `mpv.exe` during first-run setup. -[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything, since it is the only one that also carries `xz`: +[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything. It is the only one that also carries `xz`: ```powershell scoop bucket add extras scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz ``` -See the [full requirements list](https://docs.subminer.moe/installation#_1-install-requirements) for optional dependencies. +See the [installation guide](https://docs.subminer.moe/installation#_1-install-requirements) for Ubuntu, Debian, and Fedora commands and the full optional package lists.
@@ -184,6 +177,8 @@ See the [full requirements list](https://docs.subminer.moe/installation#_1-insta paru -S subminer-bin ``` +Includes the AppImage and the `subminer` command. +
@@ -195,14 +190,7 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppI && chmod +x ~/.local/bin/SubMiner.AppImage ``` -The AppImage is all you need. First-run setup can install the optional `subminer` command-line launcher. Every current launcher uses Bun included with the app, so you do not need Bun installed or on `PATH`. - -You can also download the launcher wrapper directly: - -```bash -wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \ - && chmod +x ~/.local/bin/subminer -``` +The AppImage is all you need. First-run setup can install the optional `subminer` command, which runs on a copy of Bun bundled with the app, so you do not need Bun installed.
@@ -211,14 +199,14 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~ Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`. +Then enable SubMiner under **System Settings > Privacy & Security > Accessibility**, or the overlay cannot follow the mpv window. If macOS blocks the first launch, right-click the app and choose **Open**. +
Windows -Download and run the latest installer (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). - -For terminal use, download `subminer.cmd`. It locates the installed app and uses its private Bun runtime. +Download and run the latest installer (`SubMiner-.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). A portable `.zip` is also available.
@@ -231,28 +219,30 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so ### 2. Launch & Set Up -Run the installed app and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. Setup records a custom app location when needed, and the wrapper runs with the app's private Bun runtime. +Start SubMiner and the setup window opens on first launch. It creates your config file, imports Yomitan dictionaries (you need at least one for lookups), and can install the `subminer` command. On Windows it also creates a **SubMiner mpv** shortcut. ```bash -# Linux -~/.local/bin/SubMiner.AppImage --setup - -# macOS -open -a SubMiner --args --setup +subminer app --setup # AUR +~/.local/bin/SubMiner.AppImage --setup # AppImage ``` -On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch. +On **macOS**, open `SubMiner.app` from `/Applications`. On **Windows**, run SubMiner from the Start menu. To reopen setup later, run `subminer app --setup`. + +For card creation, keep Anki open with AnkiConnect installed. SubMiner connects to it at its default address with no extra setup. ### 3. Mine ```bash -subminer video.mkv # launch mpv with SubMiner +subminer video.mkv # play a video with SubMiner subminer /path/to/dir # pick a file with fzf subminer -R /path/to/dir # pick a file with rofi (Linux only) -subminer -H # browse history, then previous / replay / next / select / quit +subminer -H # watch history: replay, next, or previous episode +subminer doctor # check your setup ``` -On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it. +On **Windows**, double-click the **SubMiner mpv** shortcut or drag a video file onto it. + +Starting mpv some other way? See [Launching mpv yourself](https://docs.subminer.moe/installation#launching-mpv-yourself) for the IPC socket option the overlay needs. ## Documentation diff --git a/changes/docs-site-simplify.md b/changes/docs-site-simplify.md index 542271e8..5ee27e0c 100644 --- a/changes/docs-site-simplify.md +++ b/changes/docs-site-simplify.md @@ -4,3 +4,4 @@ area: docs - Rewrote the docs site to be shorter and easier to scan: pages lead with setup and use, reference material lives in compact tables, and internal detail was cut from user pages. - The configuration reference now has a short explanation and a key/default table for each config block. - Fixed docs that no longer matched current behavior. +- Fixed the Arch Linux install command for MeCab, which is only in the AUR (`mecab-git`), and brought the README requirements and quick start in line with the installation guide. diff --git a/docs-site/installation.md b/docs-site/installation.md index 20ac38d5..64d5d879 100644 --- a/docs-site/installation.md +++ b/docs-site/installation.md @@ -14,18 +14,18 @@ Getting started takes three steps: Only mpv is required. Install ffmpeg too unless you are fine with cards that have no audio or screenshot. -| Dependency | Needed for | Platforms | -| ------------------------ | ------------------------------------------------------------------------------------------- | ------------ | -| mpv | Required. The player SubMiner draws over. | All | -| fuse2 | Required to run the AppImage. | Linux | -| ffmpeg | Recommended. Audio clips and screenshots on cards. Without it those fields stay empty. | All | -| MeCab + mecab-ipadic | Recommended. More accurate N+1, JLPT, and frequency highlighting. | All | -| yt-dlp | YouTube playback. | All | -| xz | [TsukiHime](/tsukihime-integration) subtitle downloads. Most Linux distros already have it. | All | -| guessit | Better title, season, and episode detection for [AniSkip](/aniskip-integration). | All | -| alass or ffsubsync | Subtitle syncing. You need at least one to use it. | All | -| fzf, rofi | The file pickers in the `subminer` command (rofi is Linux only). | Linux, macOS | -| chafa, ffmpegthumbnailer | Thumbnail previews in the pickers. | Linux, macOS | +| Dependency | Needed for | Platforms | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------ | +| mpv | Required. The player SubMiner draws over. | All | +| fuse2 | Required to run the AppImage. | Linux | +| ffmpeg | Recommended. Audio clips and screenshots on cards. Without it those fields stay empty. | All | +| MeCab + mecab-ipadic | Recommended. More accurate N+1, JLPT, and frequency highlighting. | All | +| yt-dlp | YouTube playback. | All | +| xz | [TsukiHime](/tsukihime-integration) subtitle downloads. Most Linux distros already have it. | All | +| guessit | Better title, season, and episode detection for [AniSkip](/aniskip-integration) and [AniList](/anilist-integration). | All | +| alass or ffsubsync | Subtitle syncing. You need at least one to use it. | All | +| fzf, rofi | The file pickers in the `subminer` command (rofi is Linux only). | Linux, macOS | +| chafa, ffmpegthumbnailer | Thumbnail previews in the pickers. | Linux, macOS | To generate Japanese subtitles from audio, you also need whisper.cpp. See [Subtitle generation](/subtitle-generation). @@ -42,8 +42,8 @@ SubMiner needs to track the mpv window, and how it does that depends on your des ```bash sudo pacman -S --needed mpv ffmpeg -# Recommended -sudo pacman -S --needed mecab mecab-ipadic +# Recommended (MeCab is only in the AUR) +paru -S --needed mecab-git mecab-ipadic # Optional sudo pacman -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer # Optional: subtitle sync (install at least one)