docs: update immersion and Jellyfin docs/backlog notes

2026-02-28 06:22:45 -08:00 · 2026-02-17 18:58:38 -08:00
parent e7a522a485
commit a6a28f52f3
16 changed files with 963 additions and 52 deletions
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -72,7 +72,9 @@ export default {
        text: "Reference",
        items: [
          { text: "Configuration", link: "/configuration" },
+          { text: "Immersion Tracking", link: "/immersion-tracking" },
          { text: "Anki Integration", link: "/anki-integration" },
+          { text: "Jellyfin Integration", link: "/jellyfin-integration" },
          { text: "MPV Plugin", link: "/mpv-plugin" },
          { text: "Troubleshooting", link: "/troubleshooting" },
        ],
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,13 +15,15 @@ make docs-preview # Preview built site at http://localhost:4173
 ### Getting Started

 - [Installation](/installation) — Requirements, Linux/macOS/Windows install, mpv plugin setup
- [Usage](/usage) — `subminer` wrapper, mpv plugin, keybindings, YouTube playback
+- [Usage](/usage) — `subminer` wrapper + subcommands (`jellyfin`, `yt`, `doctor`, `config`, `mpv`, `texthooker`), mpv plugin, keybindings
 - [Mining Workflow](/mining-workflow) — End-to-end sentence mining guide, overlay layers, card creation

 ### Reference

 - [Configuration](/configuration) — Full config file reference and option details
+- [Immersion Tracking](/immersion-tracking) — SQLite schema, retention/rollup policies, query templates, and extension points
 - [Anki Integration](/anki-integration) — AnkiConnect setup, field mapping, media generation, field grouping
+- [Jellyfin Integration](/jellyfin-integration) — Optional Jellyfin auth, cast discovery, remote control, and playback launch
 - [MPV Plugin](/mpv-plugin) — Chord keybindings, subminer.conf options, script messages
 - [Troubleshooting](/troubleshooting) — Common issues and solutions by category

--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -53,6 +53,7 @@ The configuration file includes several main sections:
 - [**Invisible Overlay**](#invisible-overlay) - Startup visibility behavior for the invisible mining layer
 - [**Jimaku**](#jimaku) - Jimaku API configuration and defaults
 - [**AniList**](#anilist) - Optional post-watch progress updates
+- [**Jellyfin**](#jellyfin) - Optional Jellyfin auth, library listing, and playback launch
 - [**Keybindings**](#keybindings) - MPV command shortcuts
 - [**Runtime Option Palette**](#runtime-option-palette) - Live, session-only option toggles
 - [**Secondary Subtitles**](#secondary-subtitles) - Dual subtitle track support
@@ -442,6 +443,69 @@ AniList IPC channels:
 - `anilist:get-queue-status`: return retry queue state snapshot.
 - `anilist:retry-now`: process one ready retry queue item immediately.

+### Jellyfin
+
+Jellyfin integration is optional and disabled by default. When enabled, SubMiner can authenticate, list libraries/items, and resolve direct/transcoded playback URLs for mpv launch.
+
+```json
+{
+  "jellyfin": {
+    "enabled": true,
+    "serverUrl": "http://127.0.0.1:8096",
+    "username": "",
+    "accessToken": "",
+    "userId": "",
+    "remoteControlEnabled": true,
+    "remoteControlAutoConnect": true,
+    "autoAnnounce": false,
+    "remoteControlDeviceName": "SubMiner",
+    "defaultLibraryId": "",
+    "directPlayPreferred": true,
+    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
+    "transcodeVideoCodec": "h264"
+  }
+}
+```
+
+| Option | Values | Description |
+| ------ | ------ | ----------- |
+| `enabled` | `true`, `false` | Enable Jellyfin integration and CLI commands (default: `false`) |
+| `serverUrl` | string (URL) | Jellyfin server base URL |
+| `username` | string | Default username used by `--jellyfin-login` |
+| `accessToken` | string | Stored Jellyfin access token (treat as secret) |
+| `userId` | string | Jellyfin user id bound to token/session |
+| `deviceId` | string | Client device id sent in auth headers (default: `subminer`) |
+| `clientName` | string | Client name sent in auth headers (default: `SubMiner`) |
+| `clientVersion` | string | Client version sent in auth headers (default: `0.1.0`) |
+| `defaultLibraryId` | string | Default library id for `--jellyfin-items` when CLI value is omitted |
+| `remoteControlEnabled` | `true`, `false` | Enable Jellyfin cast/remote-control session support |
+| `remoteControlAutoConnect` | `true`, `false` | Auto-connect Jellyfin remote session on app startup |
+| `autoAnnounce` | `true`, `false` | Auto-run cast-target visibility announce check on connect (default: `false`) |
+| `remoteControlDeviceName` | string | Device name shown in Jellyfin cast/device lists |
+| `pullPictures` | `true`, `false` | Enable poster/icon fetching for launcher Jellyfin pickers |
+| `iconCacheDir` | string | Cache directory for launcher-fetched Jellyfin poster icons |
+| `directPlayPreferred` | `true`, `false` | Prefer direct stream URLs before transcoding |
+| `directPlayContainers` | string[] | Container allowlist for direct play decisions |
+| `transcodeVideoCodec` | string | Preferred transcode video codec fallback (default: `h264`) |
+
+Jellyfin direct app CLI commands (`SubMiner.AppImage ...`):
+
+- `--jellyfin`: open the in-app Jellyfin setup window (server/user/password form).
+- `--jellyfin-login` with `--jellyfin-server`, `--jellyfin-username`, `--jellyfin-password`: authenticate and store token/session data.
+- `--jellyfin-logout`: clear stored Jellyfin token/session data.
+- `--jellyfin-libraries`: list available Jellyfin libraries.
+- `--jellyfin-items`: list playable items (`--jellyfin-library-id`, optional `--jellyfin-search`, `--jellyfin-limit`).
+- `--jellyfin-play`: resolve playback URL and launch (`--jellyfin-item-id`, optional audio/subtitle stream index overrides; requires connected mpv IPC).
+- `--jellyfin-remote-announce`: force capability announce + visibility check in Jellyfin sessions (debug helper).
+- `--jellyfin-server`: optional server URL override for Jellyfin commands.
+
+Launcher subcommand equivalents:
+
+- `subminer jellyfin` (or `subminer jf`) opens setup.
+- `subminer jellyfin -l --server ... --username ... --password ...` logs in.
+- `subminer jellyfin -p` opens play picker.
+- `subminer jellyfin -d` starts cast discovery mode.
+
 ### Keybindings

 Add a `keybindings` array to configure keyboard shortcuts that send commands to mpv:
@@ -717,15 +781,37 @@ Enable or disable local immersion analytics stored in SQLite for mined subtitles
 {
  "immersionTracking": {
    "enabled": true,
-    "dbPath": ""
+    "dbPath": "",
+    "batchSize": 25,
+    "flushIntervalMs": 500,
+    "queueCap": 1000,
+    "payloadCapBytes": 256,
+    "maintenanceIntervalMs": 86400000,
+    "retention": {
+      "eventsDays": 7,
+      "telemetryDays": 30,
+      "dailyRollupsDays": 365,
+      "monthlyRollupsDays": 1825,
+      "vacuumIntervalDays": 7
+    }
  }
 }
 ```

-| Option     | Values                     | Description |
-| ---------- | -------------------------- | ----------- |
-| `enabled`  | `true`, `false`            | Enable immersion tracking. Defaults to `true`. |
-| `dbPath`   | string                     | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
+| Option | Values | Description |
+| --- | --- | --- |
+| `enabled` | `true`, `false` | Enable immersion tracking. Defaults to `true`. |
+| `dbPath` | string | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
+| `batchSize` | integer (`1`-`10000`) | Buffered writes per transaction. Default `25`. |
+| `flushIntervalMs` | integer (`50`-`60000`) | Maximum queue delay before flush. Default `500ms`. |
+| `queueCap` | integer (`100`-`100000`) | In-memory queue cap. Overflow drops oldest writes. Default `1000`. |
+| `payloadCapBytes` | integer (`64`-`8192`) | Event payload byte cap before truncation marker. Default `256`. |
+| `maintenanceIntervalMs` | integer (`60000`-`604800000`) | Prune + rollup maintenance cadence. Default `86400000` (24h). |
+| `retention.eventsDays` | integer (`1`-`3650`) | Raw event retention window. Default `7` days. |
+| `retention.telemetryDays` | integer (`1`-`3650`) | Telemetry retention window. Default `30` days. |
+| `retention.dailyRollupsDays` | integer (`1`-`36500`) | Daily rollup retention window. Default `365` days. |
+| `retention.monthlyRollupsDays` | integer (`1`-`36500`) | Monthly rollup retention window. Default `1825` days (~5 years). |
+| `retention.vacuumIntervalDays` | integer (`1`-`3650`) | Minimum spacing between `VACUUM` passes. Default `7` days. |

 When `dbPath` is blank or omitted, SubMiner writes telemetry and session summaries to the default app-data location:

@@ -735,6 +821,8 @@ When `dbPath` is blank or omitted, SubMiner writes telemetry and session summari

 Set `dbPath` only if you want to relocate the database (for backup, syncing, or inspection workflows). The database is created when tracking starts for the first time.

+See [Immersion Tracking Storage](/immersion-tracking) for schema details, query templates, retention/rollup behavior, and backend portability notes.
+
 ### YouTube Subtitle Generation

 Set defaults used by the `subminer` launcher for YouTube subtitle extraction/transcription:
--- a/docs/immersion-tracking.md
+++ b/docs/immersion-tracking.md
@@ -0,0 +1,156 @@
+# Immersion Tracking Storage
+
+SubMiner stores immersion analytics in local SQLite (`immersion.sqlite`) by default.
+
+## Runtime Model
+
+- Write path is asynchronous and queue-backed.
+- Hot paths (subtitle parsing/render/token flows) enqueue telemetry/events and never await SQLite writes.
+- Queue overflow policy is deterministic: drop oldest queued writes, keep newest.
+- Flush policy defaults to `25` writes or `500ms` max delay.
+- SQLite pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=2500`.
+
+## Schema (v1)
+
+Schema versioning table:
+
+- `imm_schema_version(schema_version PK, applied_at_ms)`
+
+Core entities:
+
+- `imm_videos`: video key/title/source metadata + optional media metadata fields
+- `imm_sessions`: session UUID, video reference, timing/status fields
+- `imm_session_telemetry`: high-frequency session aggregates over time
+- `imm_session_events`: event stream with compact numeric event types
+
+Rollups:
+
+- `imm_daily_rollups`
+- `imm_monthly_rollups`
+
+Primary index coverage:
+
+- session-by-video/time: `idx_sessions_video_started`
+- session-by-status/time: `idx_sessions_status_started`
+- timeline reads: `idx_telemetry_session_sample`
+- event timeline/type reads: `idx_events_session_ts`, `idx_events_type_ts`
+- rollup reads: `idx_rollups_day_video`, `idx_rollups_month_video`
+
+Reference implementation lives in `src/core/services/immersion-tracker-service.ts` (`ensureSchema`).
+
+## Retention and Maintenance Defaults
+
+- Raw events: `7d`
+- Telemetry: `30d`
+- Daily rollups: `365d`
+- Monthly rollups: `5y`
+- Maintenance cadence: startup + every `24h`
+- Vacuum cadence: idle weekly (`7d` minimum spacing)
+
+Retention cleanup, rollup refresh, and vacuum scheduling are implemented in `runMaintenance` / `runRollupMaintenance`.
+
+## Configurable Policy Knobs
+
+All knobs are under `immersionTracking` in config:
+
+- `batchSize`
+- `flushIntervalMs`
+- `queueCap`
+- `payloadCapBytes`
+- `maintenanceIntervalMs`
+- `retention.eventsDays`
+- `retention.telemetryDays`
+- `retention.dailyRollupsDays`
+- `retention.monthlyRollupsDays`
+- `retention.vacuumIntervalDays`
+
+These map directly to runtime tracker policy and allow tuning without code changes.
+
+## Query Templates
+
+Timeline for one session:
+
+```sql
+SELECT
+  sample_ms,
+  total_watched_ms,
+  active_watched_ms,
+  lines_seen,
+  words_seen,
+  tokens_seen,
+  cards_mined
+FROM imm_session_telemetry
+WHERE session_id = ?
+ORDER BY sample_ms DESC
+LIMIT ?;
+```
+
+Session throughput summary:
+
+```sql
+SELECT
+  s.session_id,
+  s.video_id,
+  s.started_at_ms,
+  s.ended_at_ms,
+  COALESCE(SUM(t.active_watched_ms), 0) AS active_watched_ms,
+  COALESCE(SUM(t.words_seen), 0) AS words_seen,
+  COALESCE(SUM(t.cards_mined), 0) AS cards_mined,
+  CASE
+    WHEN COALESCE(SUM(t.active_watched_ms), 0) > 0
+      THEN COALESCE(SUM(t.words_seen), 0) / (COALESCE(SUM(t.active_watched_ms), 0) / 60000.0)
+    ELSE NULL
+  END AS words_per_min,
+  CASE
+    WHEN COALESCE(SUM(t.active_watched_ms), 0) > 0
+      THEN (COALESCE(SUM(t.cards_mined), 0) * 60.0) / (COALESCE(SUM(t.active_watched_ms), 0) / 60000.0)
+    ELSE NULL
+  END AS cards_per_hour
+FROM imm_sessions s
+LEFT JOIN imm_session_telemetry t ON t.session_id = s.session_id
+GROUP BY s.session_id
+ORDER BY s.started_at_ms DESC
+LIMIT ?;
+```
+
+Daily rollups:
+
+```sql
+SELECT
+  rollup_day,
+  video_id,
+  total_sessions,
+  total_active_min,
+  total_lines_seen,
+  total_words_seen,
+  total_tokens_seen,
+  total_cards,
+  cards_per_hour,
+  words_per_min,
+  lookup_hit_rate
+FROM imm_daily_rollups
+ORDER BY rollup_day DESC, video_id DESC
+LIMIT ?;
+```
+
+Monthly rollups:
+
+```sql
+SELECT
+  rollup_month,
+  video_id,
+  total_sessions,
+  total_active_min,
+  total_lines_seen,
+  total_words_seen,
+  total_tokens_seen,
+  total_cards
+FROM imm_monthly_rollups
+ORDER BY rollup_month DESC, video_id DESC
+LIMIT ?;
+```
+
+## Extension Points
+
+- Adapter boundary for non-SQLite backends is tracked in `TASK-32`.
+- Keep analytics/query callers bound to tracker service methods (not raw table assumptions) so persistence adapters can swap in later.
--- a/docs/index.md
+++ b/docs/index.md
@@ -176,6 +176,22 @@ features:

 <div class="demo-section">

+## CLI Quick Reference
+
+```bash
+subminer                    # Default picker + playback workflow
+subminer jellyfin -d        # Jellyfin cast discovery mode (foreground)
+subminer jellyfin -p        # Jellyfin play picker
+subminer yt -o ~/subs URL   # YouTube subcommand with output dir shortcut
+subminer doctor             # Dependency/config/socket health checks
+subminer config path        # Active config file path
+subminer config show        # Print active config
+subminer mpv status         # MPV socket readiness
+subminer texthooker         # Texthooker-only mode
+```
+
+See [Usage](/usage) for full command and option coverage.
+
 ## See It in Action

 <video controls playsinline preload="metadata" poster="/assets/demo-poster.jpg">
--- a/docs/jellyfin-integration.md
+++ b/docs/jellyfin-integration.md
@@ -0,0 +1,157 @@
+# Jellyfin Integration
+
+SubMiner includes an optional Jellyfin CLI integration for:
+
+- authenticating against a server
+- listing libraries and media items
+- launching item playback in the connected mpv instance
+- receiving Jellyfin remote cast-to-device playback events in-app
+- opening an in-app setup window for server/user/password input
+
+## Requirements
+
+- Jellyfin server URL and user credentials
+- For `--jellyfin-play`: connected mpv IPC socket (`--start` or existing mpv plugin workflow)
+
+## Setup
+
+1. Set base config values (`config.jsonc`):
+
+```jsonc
+{
+  "jellyfin": {
+    "enabled": true,
+    "serverUrl": "http://127.0.0.1:8096",
+    "username": "your-user",
+    "remoteControlEnabled": true,
+    "remoteControlAutoConnect": true,
+    "autoAnnounce": false,
+    "remoteControlDeviceName": "SubMiner",
+    "defaultLibraryId": "",
+    "pullPictures": false,
+    "iconCacheDir": "/tmp/subminer-jellyfin-icons",
+    "directPlayPreferred": true,
+    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
+    "transcodeVideoCodec": "h264"
+  }
+}
+```
+
+2. Authenticate:
+
+```bash
+subminer jellyfin
+subminer jellyfin -l \
+  --server http://127.0.0.1:8096 \
+  --username your-user \
+  --password 'your-password'
+```
+
+3. List libraries:
+
+```bash
+SubMiner.AppImage --jellyfin-libraries
+```
+
+Launcher wrapper equivalent for interactive playback flow:
+
+```bash
+subminer jellyfin -p
+```
+
+Launcher wrapper for Jellyfin cast discovery mode (foreground app process):
+
+```bash
+subminer jellyfin -d
+```
+
+`subminer jf ...` is an alias for `subminer jellyfin ...`.
+
+To clear saved session credentials:
+
+```bash
+subminer jellyfin --logout
+```
+
+4. List items in a library:
+
+```bash
+SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search term
+```
+
+5. Start playback:
+
+```bash
+SubMiner.AppImage --start
+SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID
+```
+
+Optional stream overrides:
+
+- `--jellyfin-audio-stream-index N`
+- `--jellyfin-subtitle-stream-index N`
+
+## Playback Behavior
+
+- Direct play is attempted first when:
+  - `jellyfin.directPlayPreferred=true`
+  - media source supports direct stream
+  - source container matches `jellyfin.directPlayContainers`
+- If direct play is not selected/available, SubMiner requests a Jellyfin transcoded stream (`master.m3u8`) using `jellyfin.transcodeVideoCodec`.
+- Resume position (`PlaybackPositionTicks`) is applied via mpv seek.
+- Media title is set in mpv as `[Jellyfin/<mode>] <title>`.
+
+## Cast To Device Mode (jellyfin-mpv-shim style)
+
+When SubMiner is running with a valid Jellyfin session, it can appear as a
+remote playback target in Jellyfin's cast-to-device menu.
+
+### Requirements
+
+- `jellyfin.enabled=true`
+- valid `jellyfin.serverUrl`, `jellyfin.accessToken`, and `jellyfin.userId`
+- `jellyfin.remoteControlEnabled=true` (default)
+- `jellyfin.remoteControlAutoConnect=true` (default)
+- `jellyfin.autoAnnounce=false` by default (`true` enables auto announce/visibility check logs on connect)
+
+### Behavior
+
+- SubMiner connects to Jellyfin remote websocket and posts playback capabilities.
+- `Play` events open media in mpv with the same defaults used by `--jellyfin-play`.
+- If mpv IPC is not connected at cast time, SubMiner auto-launches mpv in idle mode with SubMiner defaults and retries playback.
+- `Playstate` events map to mpv pause/resume/seek/stop controls.
+- Stream selection commands (`SetAudioStreamIndex`, `SetSubtitleStreamIndex`) are mapped to mpv track selection.
+- SubMiner reports start/progress/stop timeline updates back to Jellyfin so now-playing and resume state stay synchronized.
+- `--jellyfin-remote-announce` forces an immediate capability re-broadcast and logs whether server sessions can see the device.
+
+### Troubleshooting
+
+- Device not visible in Jellyfin cast menu:
+  - ensure SubMiner is running
+  - ensure session token is valid (`--jellyfin-login` again if needed)
+  - ensure `remoteControlEnabled` and `remoteControlAutoConnect` are true
+- Cast command received but playback does not start:
+  - verify mpv IPC can connect (`--start` flow)
+  - verify item is playable from normal `--jellyfin-play --jellyfin-item-id ...`
+- Frequent reconnects:
+  - check Jellyfin server/network stability and token expiration
+
+## Failure Handling
+
+User-visible errors are shown through CLI logs and mpv OSD for:
+
+- invalid credentials
+- expired/invalid token
+- server/network errors
+- missing library/item identifiers
+- no playable source
+- mpv not connected for playback
+
+## Security Notes and Limitations
+
+- Jellyfin access token is persisted in `config.jsonc`.
+- Treat config files as secrets and avoid committing them.
+- Password is used only for login and is not stored.
+- Optional setup UI is available via `--jellyfin`; all actions are also available via CLI flags.
+- `subminer` wrapper uses Jellyfin subcommands (`subminer jellyfin ...`, alias `subminer jf ...`). Use `SubMiner.AppImage` for direct `--jellyfin-libraries` and `--jellyfin-items`.
+- For direct app CLI usage (`SubMiner.AppImage ...`), `--jellyfin-server` can override server URL for login/play flows without editing config.
--- a/docs/public/config.example.jsonc
+++ b/docs/public/config.example.jsonc
@@ -51,7 +51,19 @@
  // ==========================================
  "immersionTracking": {
    "enabled": true,
-    "dbPath": ""
+    "dbPath": "",
+    "batchSize": 25,
+    "flushIntervalMs": 500,
+    "queueCap": 1000,
+    "payloadCapBytes": 256,
+    "maintenanceIntervalMs": 86400000,
+    "retention": {
+      "eventsDays": 7,
+      "telemetryDays": 30,
+      "dailyRollupsDays": 365,
+      "monthlyRollupsDays": 1825,
+      "vacuumIntervalDays": 7
+    }
  },

  // ==========================================
@@ -268,5 +280,39 @@
  "anilist": {
    "enabled": false,
    "accessToken": ""
+  },
+
+  // ==========================================
+  // Jellyfin
+  // Optional Jellyfin integration for auth, browsing, and playback launch.
+  // Access token is stored in config and should be treated as a secret.
+  // ==========================================
+  "jellyfin": {
+    "enabled": false,
+    "serverUrl": "",
+    "username": "",
+    "accessToken": "",
+    "userId": "",
+    "deviceId": "subminer",
+    "clientName": "SubMiner",
+    "clientVersion": "0.1.0",
+    "defaultLibraryId": "",
+    "remoteControlEnabled": true,
+    "remoteControlAutoConnect": true,
+    "autoAnnounce": false,
+    "remoteControlDeviceName": "SubMiner",
+    "pullPictures": false,
+    "iconCacheDir": "/tmp/subminer-jellyfin-icons",
+    "directPlayPreferred": true,
+    "directPlayContainers": [
+      "mkv",
+      "mp4",
+      "webm",
+      "mov",
+      "flac",
+      "mp3",
+      "aac"
+    ],
+    "transcodeVideoCodec": "h264"
  }
 }
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -30,7 +30,20 @@ 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 --yt-subgen-mode preprocess --whisper-bin /path/to/whisper-cli --whisper-model /path/to/model.bin https://youtu.be/...  # Pre-generate subtitle tracks before playback
+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
+subminer jellyfin -p              # Interactive Jellyfin library/item picker + playback
+subminer jellyfin -d              # Jellyfin cast-discovery mode (foreground app)
+subminer doctor                   # Dependency + config + socket diagnostics
+subminer config path              # Print active config path
+subminer config show              # Print active config contents
+subminer mpv socket               # Print active mpv socket path
+subminer mpv status               # Exit 0 if socket is ready, else exit 1
+subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
+subminer texthooker               # Launch texthooker-only mode
+subminer yt -o ~/subs https://youtu.be/...  # YouTube subcommand: output directory shortcut
+subminer yt --mode preprocess --whisper-bin /path/to/whisper-cli --whisper-model /path/to/model.bin https://youtu.be/...  # Pre-generate subtitle tracks before playback

 # Direct AppImage control
 SubMiner.AppImage --start --texthooker   # Start overlay with texthooker
@@ -46,6 +59,13 @@ SubMiner.AppImage --start --dev                         # Enable app/dev mode on
 SubMiner.AppImage --start --debug                       # Alias for --dev
 SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
 SubMiner.AppImage --settings              # Open Yomitan settings
+SubMiner.AppImage --jellyfin              # Open Jellyfin setup window
+SubMiner.AppImage --jellyfin-login --jellyfin-server http://127.0.0.1:8096 --jellyfin-username me --jellyfin-password 'secret'
+SubMiner.AppImage --jellyfin-logout       # Clear stored Jellyfin token/session data
+SubMiner.AppImage --jellyfin-libraries
+SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search anime --jellyfin-limit 20
+SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2  # Requires connected mpv IPC (--start or plugin workflow)
+SubMiner.AppImage --jellyfin-remote-announce  # Force cast-target capability announce + visibility check
 SubMiner.AppImage --help                  # Show all options
 ```

@@ -55,12 +75,26 @@ SubMiner.AppImage --help                  # Show all options
 - `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
 - Use both when needed, for example `SubMiner.AppImage --start --dev --log-level debug`.

+### Launcher Subcommands
+
+- `subminer jellyfin` / `subminer jf`: Jellyfin-focused workflow aliases.
+- `subminer yt` / `subminer youtube`: YouTube-focused shorthand flags (`-o`, `-m`).
+- `subminer doctor`: health checks for core dependencies and runtime paths.
+- `subminer config`: config helpers (`path`, `show`).
+- `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
+- `subminer texthooker`: texthooker-only shortcut (same behavior as `--texthooker`).
+- Subcommand help pages are available (for example `subminer jellyfin -h`, `subminer yt -h`).
+
+Use subcommands for Jellyfin/YouTube command families (`subminer jellyfin ...`, `subminer yt ...`).
+Top-level launcher flags like `--jellyfin-*` and `--yt-subgen-*` are intentionally rejected.
+
 ### MPV Profile Example (mpv.conf)

 `subminer` passes the following MPV options directly on launch by default:

 - `--input-ipc-server=/tmp/subminer-socket` (or your configured socket path)
- `--slang=ja,jpn,en,eng`
+- `--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
+- `--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
 - `--sub-auto=fuzzy`
 - `--sub-file-paths=.;subs;subtitles`
 - `--sid=auto`
@@ -74,8 +108,9 @@ You can define a matching profile in `~/.config/mpv/mpv.conf` for consistency wh
 # IPC socket (must match SubMiner config)
 input-ipc-server=/tmp/subminer-socket

-# Prefer JP subs, then EN
-slang=ja,jpn,en,eng
+# Prefer JP/EN audio + subtitle language variants
+alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us

 # Auto-load external subtitles
 sub-auto=fuzzy
@@ -116,6 +151,8 @@ Notes:
 | `Alt+Shift+I` | Toggle invisible overlay  |
 | `Alt+Shift+Y` | Open Yomitan settings     |

+`Alt+Shift+Y` is a fixed global shortcut; it is not part of `shortcuts` config.
+
 ### Overlay Controls (Configurable)

 | Input                | Action                                             |