From 7a0d7a488bf2f277288c5df34021f4f48bbad57d Mon Sep 17 00:00:00 2001 From: sudacode Date: Wed, 18 Mar 2026 23:35:17 -0700 Subject: [PATCH] docs: redesign README for cleaner layout and scannability - Condense features into bold-label paragraphs instead of H3 subsections - Collapse install instructions into
sections - Remove redundant screenshots (annotations-key, stats-vocabulary) - Add AUR version badge - Merge first-launch and setup steps into a single paragraph - Add horizontal rule dividers between major sections --- README.md | 155 +++++++++++++++++++++--------------------------------- 1 file changed, 61 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 98d9628..59455e5 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@
- SubMiner logo -

SubMiner

- Look up words, mine to Anki, and enrich cards with context — without leaving mpv. -

+ SubMiner logo -[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) -[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)]() -[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe) + # SubMiner + + **Sentence-mine from mpv — look up words, one-key Anki export, immersion tracking.** + + [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) + [![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)]() + [![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe) + [![AUR](https://img.shields.io/aur/version/subminer-bin)](https://aur.archlinux.org/packages/subminer-bin)
-
+--- + +SubMiner is an Electron overlay for [mpv](https://mpv.io) that turns video into a sentence-mining workstation. Look up any word with [Yomitan](https://github.com/yomidevs/yomitan), mine it to Anki with one key, and track your immersion over time.
@@ -18,66 +22,42 @@
-
- -## What it does - -SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation — look up any word with Yomitan, mine it to Anki with one key, and track your immersion progress over time. - ## Features -### Dictionary Lookups While You Watch +**Dictionary lookups** — Yomitan runs inside the overlay. Hover or navigate to any word for full dictionary popups without leaving mpv. -Yomitan runs directly inside the overlay. Hover over any word in the subtitles or navigate with keyboard/controller to get full dictionary popups without pausing or switching windows. - -### One-Key Anki Mining - -Press a single key to send a word to Anki. SubMiner auto-fills the card with the sentence, audio clip, screenshot, and machine translation — all captured from the exact moment you looked it up. +**One-key Anki mining** — Press one key to create a card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment.
- One-key Anki card creation — Yomitan popup with dictionary entry and mine button over annotated subtitles + Yomitan popup with dictionary entry and mine button over annotated subtitles in mpv
-### Reading Annotations - -Subtitles are annotated in real time with N+1 targeting, frequency-dictionary highlighting, JLPT level tags, and a character name dictionary for anime and manga proper nouns. +**Reading annotations** — Real-time subtitle annotations with N+1 targeting, frequency highlighting, JLPT tags, and a character name dictionary. Grammar-only tokens render as plain text.
- Subtitle annotations with frequency highlighting, JLPT underlines, known words, N+1 targets, and character names -
- Subtitle annotations with frequency highlighting, JLPT underlines, known words, N+1 targets, and character names + Annotated subtitles with frequency highlighting, JLPT underlines, known words, and N+1 targets
-### Immersion Dashboard - -A local stats dashboard tracks your watch time, anime progress, vocabulary growth, mining throughput, and session history. Drill down into individual sessions or browse your full library. +**Immersion dashboard** — Local stats dashboard with watch time, anime progress, vocabulary growth, mining throughput, and session history.
- Stats dashboard — overview with watch time, cards mined, streaks, and tracking snapshot -

- Vocabulary tab — unique words, known words, top repeated words, and unmined word list -

- + Stats dashboard with watch time, cards mined, streaks, and tracking snapshot
-### External Integrations - -- **AniList** — Automatic episode progress tracking -- **Jellyfin** — Remote playback, cast device mode -- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync -- **Texthooker & API** — Custom texthooker page and annotated websocket feed for external clients +**Integrations** — AniList episode tracking, Jellyfin remote playback, Jimaku subtitle downloads, alass/ffsubsync, and an annotated websocket feed for external clients.
- Texthooker page with annotated subtitle lines — known words, N+1 targets, character names, and frequency highlighting + Texthooker page with annotated subtitle lines and frequency highlighting
-## Quick start +--- -### 1. Install +## Quick Start -**Arch Linux (AUR):** +### Install -Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. It installs the packaged AppImage plus the `subminer` wrapper: +
+Arch Linux (AUR) ```bash paru -S subminer-bin @@ -86,84 +66,71 @@ paru -S subminer-bin Or manually: ```bash -git clone https://aur.archlinux.org/subminer-bin.git -cd subminer-bin -makepkg -si +git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si ``` -**Linux (AppImage):** +
+ +
+Linux (AppImage) ```bash wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \ && chmod +x ~/.local/bin/SubMiner.AppImage wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \ && chmod +x ~/.local/bin/subminer - ``` > [!NOTE] > The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`. -**macOS (DMG/ZIP):** download the latest packaged build from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`. +
-**Windows (Installer/ZIP):** download the latest `SubMiner-.exe` installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Keep `mpv` installed and available on `PATH`. +
+macOS / Windows / From source -**From source** — see [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source). +**macOS** — Download the latest DMG/ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`. -### 2. Launch the app once +**Windows** — Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Keep `mpv` on `PATH`. + +**From source** — See [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source). + +
+ +### First Launch + +Run `SubMiner.AppImage` (Linux), `SubMiner.app` (macOS), or `SubMiner.exe` (Windows). On first launch, SubMiner starts in the tray, creates a default config, and opens a setup popup where you can install the mpv plugin and configure Yomitan dictionaries. + +### Mine ```bash -# Linux -SubMiner.AppImage +subminer video.mkv # auto-starts overlay + resumes playback +subminer --start video.mkv # explicit overlay start (if plugin auto_start=no) +subminer stats # open the immersion dashboard ``` -On macOS, launch `SubMiner.app`. On Windows, launch `SubMiner.exe` from the Start menu or install directory. - -On first launch, SubMiner: - -- starts in the tray/background -- creates the default config directory and `config.jsonc` -- opens a compact setup popup -- can install the mpv plugin to the default mpv scripts location for you -- links directly to Yomitan settings so you can install dictionaries before finishing setup - -### 3. Finish setup - -- click `Install mpv plugin` if you want the default plugin auto-start flow -- click `Open Yomitan Settings` and install at least one dictionary -- click `Refresh status` -- click `Finish setup` - -The mpv plugin step is optional. Yomitan must report at least one installed dictionary before setup can be completed. - -### 4. Mine - -```bash -subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready -subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no -subminer stats # open the local stats dashboard in your browser -``` +--- ## Requirements -| Required | Optional | -| ------------------------------------------ | -------------------------------------------------- | -| `bun` (source builds, Linux `subminer`) | | -| `mpv` with IPC socket | `yt-dlp` | -| `ffmpeg` | `guessit` (better AniSkip title/episode detection) | -| `mecab` + `mecab-ipadic` | `fzf` / `rofi` | -| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer` | -| macOS: Accessibility permission | | +| Required | Optional | +|---|---| +| [`mpv`](https://mpv.io) with IPC socket | `yt-dlp` | +| `ffmpeg` | `guessit` (AniSkip detection) | +| `mecab` + `mecab-ipadic` | `fzf` / `rofi` | +| [`bun`](https://bun.sh) (source builds, Linux wrapper) | `chafa`, `ffmpegthumbnailer` | +| Linux: `hyprctl` or `xdotool` + `xwininfo` | | +| macOS: Accessibility permission | | -Windows builds use native window tracking and do not require the Linux compositor helper tools. +Windows uses native window tracking and does not need the Linux compositor tools. ## Documentation -For full guides on configuration, Anki, Jellyfin, immersion tracking/stats, and more, see [docs.subminer.moe](https://docs.subminer.moe). The VitePress source for that site lives in [`docs-site/`](./docs-site/). +Full guides on configuration, Anki, Jellyfin, immersion tracking, and more at **[docs.subminer.moe](https://docs.subminer.moe)**. ## Acknowledgments -Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles powered by [Jimaku.cc](https://jimaku.cc). Dictionary lookups via [Yomitan](https://github.com/yomidevs/yomitan), and JLPT tags from [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab). +Built on [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles from [Jimaku.cc](https://jimaku.cc). Lookups via [Yomitan](https://github.com/yomidevs/yomitan). JLPT tags from [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab). ## License