sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-03-20 12:11:28 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: update stats dashboard docs, config, and releasing checklist

Browse Source 
- Update dashboard tab descriptions to include Anime tab and richer session timelines
- Add autoOpenBrowser config option to stats section
- Add subminer stats cleanup command to changelog fragment
- Expand releasing checklist with doc verification, changelog lint, and build gates
This commit is contained in:
Kyle Yasuda
2026-03-14 23:09:00 -07:00
parent c4bea1f9ca
commit e68defbedf
9 changed files with 41 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@@ -27,7 +27,7 @@ SubMiner is an Electron overlay that sits on top of mpv. It turns your video pla
- **Look up words as you watch** — Yomitan dictionary popups on hover or keyboard-driven token-by-token navigation
- **One-key Anki mining** — Creates cards with sentence, audio, screenshot, and translation; optional local AnkiConnect proxy auto-enriches Yomitan cards instantly
- **Reading annotations** — N+1 targeting, frequency-dictionary highlighting, JLPT underlining, and character name dictionary for anime/manga proper nouns
- **Immersion stats** — Optional dashboard for watch time, sessions, trends, vocabulary, and mining throughput
- **Immersion stats** — Optional local dashboard and overlay for watch time, anime progress, session drill-down, vocabulary growth, and mining throughput
- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync
- **Jellyfin & AniList integration** — Remote playback, cast device mode, and automatic episode progress tracking
- **Texthooker & API** — Built-in texthooker page and annotated websocket feed for external clients
@@ -102,6 +102,7 @@ The mpv plugin step is optional. Yomitan must report at least one installed dict
```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

2
changes/stats-command.md
View File

@@ -2,3 +2,5 @@ type: added
area: launcher
- Added `subminer stats` to launch the local stats dashboard, force-start the stats server on demand, and open the dashboard in your browser.
- Added `subminer stats cleanup` to backfill vocabulary metadata and prune stale or excluded immersion rows on demand.
- Added `stats.autoOpenBrowser` so browser launch after `subminer stats` can be enabled or disabled explicitly.

6
changes/stats-dashboard.md
View File

@@ -1,5 +1,7 @@
type: added
area: immersion
- Added a local stats dashboard for immersion tracking with overview, trends, sessions, and vocabulary views.
- Added an in-app stats overlay toggle, a localhost browser page, and documented `stats.toggleKey`, `stats.serverPort`, and `stats.autoStartServer`.
- Added a local stats dashboard for immersion tracking with Overview, Anime, Trends, Vocabulary, and Sessions views.
- Added anime progress, episode completion, Anki card links, and occurrence drill-down across the stats dashboard.
- Added richer session timelines with new-word activity, cumulative totals, and pause/seek/card event markers.
- Added completed-episodes and completed-anime totals to the Overview tracking snapshot.

3
config.example.jsonc
View File

@@ -471,6 +471,7 @@
"stats": {
"toggleKey": "Backquote", // Key code to toggle the stats overlay.
"serverPort": 5175, // Port for the stats HTTP server.
"autoStartServer": true // Automatically start the stats server on launch. Values: true | false
"autoStartServer": true, // Automatically start the stats server on launch. Values: true | false
"autoOpenBrowser": true // Automatically open the stats dashboard in a browser when the server starts. Values: true | false
} // Local immersion stats dashboard served on localhost and available as an in-app overlay.
}

6
docs-site/configuration.md
View File

@@ -1202,7 +1202,8 @@ Configure the local stats UI served from SubMiner and the in-app stats overlay t
"stats": {
"toggleKey": "Backquote",
"serverPort": 5175,
"autoStartServer": true
"autoStartServer": true,
"autoOpenBrowser": true
}
}
```
@@ -1212,13 +1213,14 @@ Configure the local stats UI served from SubMiner and the in-app stats overlay t
| `toggleKey` | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`. |
| `serverPort` | integer | Localhost port for the browser stats UI. Default `5175`. |
| `autoStartServer` | `true`, `false` | Start the local stats HTTP server automatically once immersion tracking is active. Default `true`. |
| `autoOpenBrowser` | `true`, `false` | When `subminer stats` starts the server on demand, also open the dashboard in your default browser. Default `true`. |
Usage notes:
- The browser UI is served at `http://127.0.0.1:<serverPort>`.
- The overlay toggle is local to the focused visible overlay window; it is not registered as a global OS shortcut.
- The dashboard reads from the same immersion-tracking database, so keep `immersionTracking.enabled` on if you want data to appear.
- The UI includes Overview, Trends, Sessions, and Vocabulary tabs.
- The UI includes Overview, Anime, Trends, Vocabulary, and Sessions tabs.
### YouTube Subtitle Generation

13
docs-site/immersion-tracking.md
View File

@@ -29,10 +29,11 @@ The same immersion data powers the stats dashboard.
Dashboard tabs:
- Overview: recent sessions, quick totals, short-term watch-time chart
- Trends: watch time, cards mined, cards/hour, lookup hit rate over time
- Sessions: per-session breakdown with timeline and event drill-down
- Vocabulary: top words, kanji frequency, recent vocabulary growth, and click-through occurrence drilldown in a right-side drawer
- Overview: recent sessions, streak calendar, watch-time history, and a tracking snapshot with completed episodes/anime totals
- Anime: cover-art library, per-series progress, episode drill-down, and direct links into mined cards
- Trends: watch time, sessions, words seen, and per-anime progress/pattern charts
- Sessions: expandable session history with new-word activity, cumulative totals, and pause/seek/card markers
- Vocabulary: top repeated words, new-word timeline, kanji breakdown, and click-through occurrence drilldown in a right-side drawer
Stats server config lives under `stats`:
@@ -41,7 +42,8 @@ Stats server config lives under `stats`:
"stats": {
"toggleKey": "Backquote",
"serverPort": 5175,
"autoStartServer": true
"autoStartServer": true,
"autoOpenBrowser": true
}
}
```
@@ -49,6 +51,7 @@ Stats server config lives under `stats`:
- `toggleKey` is overlay-local, not a system-wide shortcut.
- `serverPort` controls the localhost dashboard URL.
- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active.
- `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
- `subminer stats` forces the dashboard server to start even when `autoStartServer` is `false`.
- `subminer stats` fails with an error when `immersionTracking.enabled` is `false`.
- `subminer stats cleanup` defaults to vocabulary cleanup, repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still fail vocab filtering.

2
docs-site/mining-workflow.md
View File

@@ -206,7 +206,7 @@ Enable it in your config:
}
```
Open the dashboard in the overlay with `stats.toggleKey` (default: `` ` ``), launch it in a browser with `subminer stats`, or visit `http://127.0.0.1:5175` directly if the local stats server is already running.
Open the dashboard in the overlay with `stats.toggleKey` (default: `` ` ``), launch it in a browser with `subminer stats`, or visit `http://127.0.0.1:5175` directly if the local stats server is already running. The dashboard covers overview totals, anime progress, session detail, and vocabulary drill-down from the same local immersion database.
See [Immersion Tracking](/immersion-tracking) for dashboard details, schema, and retention settings.

3
docs-site/public/config.example.jsonc
View File

@@ -471,6 +471,7 @@
"stats": {
"toggleKey": "Backquote", // Key code to toggle the stats overlay.
"serverPort": 5175, // Port for the stats HTTP server.
"autoStartServer": true // Automatically start the stats server on launch. Values: true | false
"autoStartServer": true, // Automatically start the stats server on launch. Values: true | false
"autoOpenBrowser": true // Automatically open the stats dashboard in a browser when the server starts. Values: true | false
} // Local immersion stats dashboard served on localhost and available as an in-app overlay.
}

24
docs/RELEASING.md
View File

@@ -3,22 +3,30 @@
# Releasing
1. Confirm `main` is green: `gh run list --workflow CI --limit 5`.
2. Bump `package.json` to the release version.
3. Build release metadata before tagging:
2. Confirm release-facing docs are current: `README.md`, `changes/*.md`, and any touched `docs-site/` pages/config examples.
3. Run `bun run changelog:lint`.
4. Bump `package.json` to the release version.
5. Build release metadata before tagging:
`bun run changelog:build --version <version>`
4. Review `CHANGELOG.md`.
5. Run release gate locally:
6. Review `CHANGELOG.md` and `release/release-notes.md`.
7. Run release gate locally:
`bun run changelog:check --version <version>`
`bun run verify:config-example`
`bun run test:fast`
`bun run typecheck`
6. Commit release prep.
7. Tag the commit: `git tag v<version>`.
8. Push commit + tag.
`bun run test:fast`
`bun run test:env`
`bun run build`
8. If `docs-site/` changed, also run:
`bun run docs:test`
`bun run docs:build`
9. Commit release prep.
10. Tag the commit: `git tag v<version>`.
11. Push commit + tag.
Notes:
- `changelog:check` now rejects tag/package version mismatches.
- `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` and removes the released `changes/*.md` fragments.
- Do not tag while `changes/*.md` fragments still exist.
- Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
- Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.