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 documentation site for stats dashboard and immersion tracking

Browse Source
This commit is contained in:
Kyle Yasuda
2026-03-14 22:15:14 -07:00
parent 0f44107beb
commit 2d87dae6cc
13 changed files with 112 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,8 +1,8 @@
# Immersion Tracking
SubMiner can log your watching and mining activity to a local SQLite database. This is optional and disabled by default.
SubMiner can log your watching and mining activity to a local SQLite database, then surface it in the built-in stats dashboard. Tracking is enabled by default and can be turned off if you do not want local analytics.
When enabled, SubMiner records per-session statistics (watch time, subtitle lines seen, words encountered, cards mined) and maintains daily and monthly rollups. You can query the database directly with any SQLite tool to track your progress over time.
When enabled, SubMiner records per-session statistics (watch time, subtitle lines seen, words encountered, cards mined) and maintains daily and monthly rollups. You can view that data in SubMiner's stats UI or query the database directly with any SQLite tool.
## Enabling
@@ -18,6 +18,41 @@ When enabled, SubMiner records per-session statistics (watch time, subtitle line
- Leave `dbPath` empty to use the default location (`immersion.sqlite` in SubMiner's app-data directory).
- Set an explicit path to move the database (useful for backups, cloud syncing, or external tools).
## Stats Dashboard
The same immersion data powers the stats dashboard.
- In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
- Launcher command: run `subminer stats` to start the local stats server on demand and open the dashboard in your browser.
- Maintenance command: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand.
- Browser page: open `http://127.0.0.1:5175` directly if the local stats server is already running.
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
Stats server config lives under `stats`:
```jsonc
{
"stats": {
"toggleKey": "Backquote",
"serverPort": 5175,
"autoStartServer": true
}
}
```
- `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.
- `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.
## Retention Defaults
Data is kept for the following durations before automatic cleanup: