chore(release): prepare 0.18.0-beta.1

- Drop changes/kiku-field-grouping-modal-wiring.md (landed in #138)
- Drop changes/known-word-partial-reading-highlight.md (landed in #142)
- Remove assets/minecard.mkv demo video

.github/workflows/ci.yml

@@ -55,9 +55,6 @@ jobs:
       - name: Verify generated config examples
         run: bun run verify:config-example
 
-      - name: Internal docs knowledge-base checks
-        run: bun run test:docs:kb
-
       - name: Test suite (source)
         run: bun run test:fast
 
@@ -71,6 +68,9 @@ jobs:
           path: coverage/test-src/lcov.info
           if-no-files-found: error
 
+      - name: Stats UI tests
+        run: bun run test:stats
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.github/workflows/prerelease.yml

@@ -70,6 +70,9 @@ jobs:
           path: coverage/test-src/lcov.info
           if-no-files-found: error
 
+      - name: Stats UI tests
+        run: bun run test:stats
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.github/workflows/release.yml

@@ -61,6 +61,9 @@ jobs:
           path: coverage/test-src/lcov.info
           if-no-files-found: error
 
+      - name: Stats UI tests
+        run: bun run test:stats
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules/
+/package-lock.json
 
 # Superpowers brainstorming
 .superpowers/
@@ -16,6 +17,8 @@ coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
+/main-entry.js
+/main-entry.js.map
 
 # Logs
 *.log

AGENTS.md

@@ -42,7 +42,10 @@ Start here, then leave this file.
 - Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
+- Stats dashboard UI (`stats/`): `bun run test:stats`
+- Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Docs-only: `bun run docs:test`, then `bun run docs:build`
+- Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
 
 ## Docs Upkeep
 

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.17.2 (2026-06-28)
+
+### Fixed
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+### Added
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+### Fixed
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
 ## v0.17.0 (2026-06-15)
 
 ### Changed

README.md

@@ -213,6 +213,7 @@ On **Windows**, just run `SubMiner.exe` and the setup will open automatically on
 subminer video.mkv          # launch mpv 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 local watch history (replay / next episode / browse)
 ```
 
 On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it.

changes/audio-normalization.md

@@ -0,0 +1,4 @@
+type: fixed
+area: mining
+
+- Normalized generated card audio by default during media extraction, with `ankiConnect.media.normalizeAudio` available to keep raw source loudness when needed.

changes/background-app-stats-server.md

@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- `subminer app` background launches now start the stats server automatically when `stats.autoStartServer` is enabled, and skip startup when a background stats server is already running.

changes/character-name-split-and-scan-recovery.md

@@ -0,0 +1,6 @@
+type: fixed
+area: overlay
+
+- Fixed character-dictionary surname/given-name splitting for unspaced AniList native names where romanized reading length misled the boundary guess (東紫乃 split as 東紫+乃, 渡辺真奈美 as 渡辺真+奈美), so surnames like 東 and 渡辺 were never highlighted with character portraits and unmatched leading kanji (渡) lost hover lookup entirely. Name parts are now resolved with MeCab person-name POS tags and reading validation when MeCab is available; without MeCab, terms are generated for both plausible boundaries so the real surname still matches. Existing snapshots regenerate automatically (format version bump), and snapshots built without MeCab are upgraded to exact MeCab splits once MeCab is detected.
+- Fixed subtitle tokenization dropping a character entirely when Yomitan's greedy scan consumed trailing punctuation/whitespace past the term (e.g. 平 in 「（東）平　（平）え？」 matched across the paren with no exact-source headword). The scanner now retries shorter windows so the prefix term still tokenizes with its name match and portrait.
+- Fixed character-name highlights being stripped when MeCab's context-dependent POS tag put the token in the annotation noise filter (e.g. 平 tagged as prefix 接頭詞 in 「あっ 平 これ…」 lost its highlight and portrait even though hover lookup showed the character). Confirmed name matches now survive the POS exclusion filter, and name matching alone keeps the annotation stage active when all other annotations are disabled.

changes/history-rofi-cover-art.md

@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Show cover art icons in the rofi watch-history picker, reusing AniList covers already stored in the stats database (extracted to `~/.cache/subminer/covers`).

changes/kiku-field-grouping-cancel-double-toast.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Fixed cancelling the Kiku field grouping dialog showing two "Field grouping cancelled" notifications when grouping was started via the trigger shortcut: the manual workflow already notifies about its outcome (cancelled, UI unavailable, failed), and the trigger path re-notified on top of it. The workflow now owns all outcome notifications, and a previously silent failure (the original card no longer loadable) gets its own message.

changes/kiku-field-grouping-modal-recovery.md

@@ -0,0 +1,6 @@
+type: fixed
+area: overlay
+
+- Fixed Kiku manual field grouping freezing the overlay after adding a duplicate card: the field grouping modal now reliably appears above fullscreen mpv on Hyprland/Wayland by re-asserting window placement until the compositor maps the modal window, instead of a single post-show attempt that raced the async map and left the dialog invisible.
+- Fixed manual field grouping staying broken after the first attempt: the request resolver is now always cleared once a choice is made or the request is abandoned, so later grouping attempts no longer short-circuit to an instant "Field grouping cancelled".
+- Fixed a timed-out or failed field grouping request leaving an orphaned, invisible modal window covering mpv: abandoned requests now tear down the modal window and close the dialog so the overlay recovers immediately.

changes/known-word-reading-aware-matching.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed words being highlighted green as known when a same-spelled Anki card taught a different reading (e.g. とこ parsed as 床 "bed" matching a known 床/ゆか "floor" card). The known-word cache now stores each card's word together with its reading and only matches when the token's reading agrees; cards without a reading field keep matching in any reading as before.

changes/launcher-history-command.md

@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Added `subminer -H` / `--history` to browse local watch history, replay the last watched episode, continue to the next episode, or browse episodes with fzf/rofi.

changes/pixel-art-app-icon.md

@@ -0,0 +1,4 @@
+type: changed
+area: branding
+
+- Replaced the SubMiner app icon with new pixel-art submarine artwork contributed by an anonymous community member, used across the app icon, tray, notifications, README, docs site, and stats page.

changes/secondary-sub-karaoke-collapse.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed secondary subtitles stacking dozens of one-syllable lines down the screen during karaoke-typeset openings/endings, which made the hover-pause band cover the whole video: karaoke-like event spam is now collapsed into a single deduped line, and the secondary subtitle area is height-capped so it always stays a strip at the top.

changes/stats-trend-title-limits.md

@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Show all trend chart titles by default, persist hidden-title choices, and add a per-chart top-title limit selector.

changes/test-lane-overhaul.md

@@ -0,0 +1,7 @@
+type: internal
+area: testing
+
+- Test lanes are now defined once in `scripts/test-lanes.ts` and discovered by directory instead of hand-maintained file lists in `package.json`; the unused `test:core:*`/`test:config:dist`/`test:full` scripts were removed.
+- `scripts/run-test-lane.mjs` runs each test file in an isolated `bun test` process with a wall timeout, so a hanging test or leaked global can no longer cascade failures across the lane.
+- Previously orphaned suites now run in CI: the stats dashboard tests (`bun run test:stats`), the `scripts/**` tests (`bun run test:scripts`, including the change-verification skill tests), the `test-plugin-process-start-retries.lua` plugin test, and the runtime-compat dist slice (now part of `bun run test:fast`).
+- The change-verification skill gained a `stats` lane for `stats/` edits.

changes/unparsed-token-hover-lookup.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed subtitle text that Yomitan's parser cannot match (e.g. the truncated volitional in とこ戻ろ…) being rendered as plain, non-interactive text: it was invisible to hover/lookup and excluded from the n+1 word count, which could wrongly mark a sentence as n+1. Unparsed runs are now kept as hoverable tokens matching Yomitan's own segmentation; bracketed SFX/speaker captions and punctuation-only runs are still skipped.

changes/youtube-stream-edl-options.md

@@ -0,0 +1,4 @@
+type: fixed
+area: youtube
+
+- Fixed direct YouTube stream media extraction by parsing mpv EDL stream URLs with their byte-length guards, preventing trailing EDL segment options from corrupting signed googlevideo URLs and causing ffmpeg 403 errors.

config.example.jsonc

@@ -559,6 +559,7 @@
       "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
       "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
@@ -568,7 +569,7 @@
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
       "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
     }, // Known words setting.
     "behavior": {
       "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -618,7 +619,11 @@
     "primarySubLanguages": [
       "ja",
       "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "mediaCache": {
+      "mode": "direct", // How YouTube card audio/images are extracted. Values: direct | background
+      "maxHeight": 720 // Maximum video height downloaded for the YouTube background media cache. Set to 0 for unlimited.
+    } // Media cache setting.
   }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================

docs-site/anki-integration.md

@@ -161,13 +161,14 @@ Audio is extracted from the video file using the subtitle's start and end timest
 "ankiConnect": {
   "media": {
     "generateAudio": true,
+    "normalizeAudio": true,      // normalize generated clip loudness
     "audioPadding": 0,           // optional seconds before and after subtitle timing
     "maxMediaDuration": 30       // cap total duration in seconds
   }
 }
 ```
 
-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream.
+Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness.
 
 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
 
@@ -347,6 +348,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
       "imageType": "static",
       "imageFormat": "jpg",
       "imageQuality": 92,
+      "normalizeAudio": true,
       "audioPadding": 0,
       "maxMediaDuration": 30,
     },

docs-site/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.17.2 (2026-06-28)
+
+**Fixed**
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+**Added**
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+**Fixed**
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
 ## v0.17.0 (2026-06-15)
 
 **Changed**

docs-site/character-dictionary.md

@@ -56,6 +56,8 @@ A single character produces many searchable terms so that names are recognized r
 - Family name alone: 須々木
 - Given name alone: 心一
 
+Unspaced native names (AniList often stores 渡辺真奈美 without a separator) are split into family/given parts with MeCab when it is available: person-name POS tags (姓/名) decide the boundary, validated against AniList's romanized first/last name readings. Without MeCab, a length heuristic based on the romanized readings guesses the boundary — and because that guess can be ambiguous (東紫乃 could be 東+紫乃 or 東紫+乃), terms are generated for the top two candidate boundaries so the real surname still matches. Snapshots built without MeCab are regenerated automatically once MeCab becomes available, upgrading them to the exact splits.
+
 **Middle-dot removal** (common in katakana foreign names):
 
 - ア・リ・ス → アリス (combined), plus individual segments

docs-site/configuration.md

@@ -188,6 +188,9 @@ Control the minimum log level for runtime output:
 | `files.launcher` | boolean                                  | Write launcher command logs (default: `true`)                        |
 | `files.mpv`      | boolean                                  | Write mpv player logs. Enable temporarily for mpv/plugin debugging.  |
 
+Log filenames use the local calendar date, for example `app-YYYY-MM-DD.log`, `launcher-YYYY-MM-DD.log`, and `mpv-YYYY-MM-DD.log`.
+Log export creates a sanitized copy of those files; it does not rewrite the original log files on disk.
+
 ### Updates
 
 Configure automatic update checks and update notifications:
@@ -948,6 +951,7 @@ Enable automatic Anki card creation and updates with media generation:
       "animatedMaxWidth": 640,
       "animatedMaxHeight": 0,
       "animatedCrf": 35,
+      "normalizeAudio": true,
       "audioPadding": 0,
       "fallbackDuration": 3,
       "maxMediaDuration": 30
@@ -998,6 +1002,7 @@ This example is intentionally compact. The option table below documents availabl
 | `ankiConnect.ai.model`                            | string                                      | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                                               |
 | `ankiConnect.ai.systemPrompt`                     | string                                      | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                                       |
 | `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
+| `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness.                                                                                              |
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
@@ -1520,14 +1525,24 @@ Set defaults used by managed subtitle auto-selection and the `subminer` launcher
 ```json
 {
   "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
+    "primarySubLanguages": ["ja", "jpn"],
+    "mediaCache": {
+      "mode": "direct",
+      "maxHeight": 720
+    }
   }
 }
 ```
 
-| Option                | Values   | Description                                                                                      |
-| --------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `primarySubLanguages` | string[] | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
+| Option                 | Values                   | Description                                                                                      |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `primarySubLanguages`  | string[]                 | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
+| `mediaCache.mode`      | `direct` \| `background` | YouTube card audio/image extraction mode (default `direct`)                                      |
+| `mediaCache.maxHeight` | number                   | Maximum background cache download height. Set `0` for unlimited (default `720`)                  |
+
+`mediaCache.mode: "direct"` extracts card media from the active YouTube stream URL. `mediaCache.mode: "background"` starts a separate yt-dlp media download after YouTube playback has loaded, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. Playback and subtitle loading do not wait for that download. Use background mode if direct card media generation hits YouTube `403` errors from expiring stream URLs.
+
+Background cache downloads are capped by `mediaCache.maxHeight`, which defaults to 720p; set it to `0` to let yt-dlp choose the best available height. Downloads use IPv4 and yt-dlp retry flags to reduce YouTube throttling failures. SubMiner announces when the background cache download starts and when the cache is ready, using the configured notification surface; overlay and OSD messages queue until the overlay or mpv is ready. If you mine cards before the cache is ready, SubMiner creates the text fields immediately, queues the audio/image work for those note IDs, shows a status notification, and fills the media fields once the cached file is ready. If the cache download fails, SubMiner shows a failure notification, shows queued-card failure notifications, and clears the pending updates.
 
 Current launcher behavior:
 

docs-site/development.md

@@ -80,18 +80,24 @@ Default lanes:
 
 ```bash
 bun run test           # alias for test:fast
-bun run test:fast      # default fast lane
-bun run test:full      # maintained source + launcher-unit + runtime compat surface
+bun run test:fast      # full source lanes: src + launcher-unit + scripts + runtime compat
 bun run test:runtime:compat # compiled/runtime compatibility slice only
 bun run test:env       # launcher/plugin + env-sensitive verification
+bun run test:stats     # stats dashboard UI suite
 bun run test:immersion:sqlite # SQLite persistence lane
 bun run test:subtitle  # maintained alass/ffsubsync subtitle surface
 ```
 
-- `bun run test` and `bun run test:fast` cover config/core suites plus representative entry/runtime, Anki integration, release-workflow coverage, typecheck, and runtime-registry checks.
-- `bun run test:full` is the maintained full surface: Bun-compatible `src/**` discovery, Bun-compatible launcher unit discovery, and the compiled/runtime compatibility lane for suites routed through `dist/**`.
+Test lane membership is defined once in `scripts/test-lanes.ts` and discovered by
+directory, so new test files join their lane automatically. `scripts/run-test-lane.mjs`
+runs each test file in its own `bun test` process (per-file isolation) so a hanging
+test or leaked global in one file cannot cascade into the rest of the lane; pass
+`--jobs N` to parallelize or `--single-process` for one shared process.
+
+- `bun run test` and `bun run test:fast` cover the full discovered `src/**` suite, launcher unit tests, `scripts/**` tests, and the compiled/runtime compatibility lane.
 - `bun run test:runtime:compat` covers the compiled/runtime slice directly: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry`.
 - `bun run test:env` covers environment-sensitive checks: launcher smoke/plugin verification plus the Bun source SQLite lane.
+- `bun run test:stats` runs the stats dashboard suite under `stats/src/**`.
 - `bun run test:immersion:sqlite` is the reproducible persistence lane when you need real DB-backed SQLite coverage under Bun.
 
 The Bun-managed discovery lanes intentionally exclude a small compiled/runtime-focused set: `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, `src/core/services/overlay-manager.test.ts`, `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:runtime:compat` keeps them in the standard workflow via `dist/**`.
@@ -126,11 +132,11 @@ Focused commands:
 ```bash
 bun run test:config       # Source-level config schema/validation tests
 bun run test:launcher     # Launcher regression tests (config discovery + command routing)
-bun run test:core         # Source-level core regression tests (default lane)
 bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
 bun run test:launcher:env:src # Launcher smoke + Lua plugin gate
 bun run test:src          # Bun-managed maintained src/** discovery lane
 bun run test:launcher:unit:src # Bun-managed maintained launcher unit lane
+bun run test:scripts      # Bun-managed scripts/** test lane
 bun run test:immersion:sqlite:src # Bun source lane
 ```
 
@@ -144,8 +150,6 @@ Smoke and optional deep dist commands:
 bun run build                 # compile dist artifacts
 bun run test:immersion:sqlite # compile + run SQLite-backed immersion tests under Bun
 bun run test:smoke:dist       # explicit smoke scope for compiled runtime
-bun run test:config:dist      # optional full dist config suite
-bun run test:core:dist        # optional full dist core suite
 ```
 
 Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.

docs-site/immersion-tracking.md

@@ -95,7 +95,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, or reuses the dedicated background stats server when one is already running.
+- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running. Background app launches (`subminer app`) start the stats server immediately, registering it so later launches reuse it instead of starting another one.
 - `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 -b` starts or reuses the dedicated background stats daemon and exits after startup acknowledgement.

docs-site/launcher-script.md

@@ -61,6 +61,23 @@ Override with the `SUBMINER_ROFI_THEME` environment variable:
 SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
 ```
 
+## Watch History
+
+`subminer -H` (or `--history`) browses your local watch history, sourced from the immersion tracker database. It works with both pickers: fzf by default, rofi with `-R -H`.
+
+```bash
+subminer -H                            # fzf history browser
+subminer -R -H                         # rofi history browser
+```
+
+The first menu lists every locally watched series, most recently watched first, using the parsed media title (e.g. the anime title) when available and the directory name otherwise. Selecting a series opens an action menu:
+
+- **Replay last watched** — replays the most recently watched episode
+- **Next episode** — plays the episode after the last watched one (continues into the next season directory when the season ends)
+- **Browse episodes** — lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu is shown first
+
+Series whose directories are not currently accessible (e.g. an unmounted network share) are hidden from the list. Watch history requires the immersion tracker database (`immersionTracking.dbPath`, default `<config dir>/immersion.sqlite`), which SubMiner populates during playback.
+
 ## Common Commands
 
 ```bash
@@ -83,7 +100,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows                  |
 | `subminer doctor`                          | Dependency + config + socket diagnostics                           |
 | `subminer settings`                        | Open the SubMiner settings window                                  |
-| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                      |
+| `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path           |
 | `subminer config path`                     | Print active config file path                                      |
 | `subminer config show`                     | Print active config contents                                       |
 | `subminer mpv status`                      | Check mpv socket readiness                                         |
@@ -105,6 +122,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `-d, --directory`     | Video search directory (default: cwd)                                |
 | `-r, --recursive`     | Search directories recursively                                       |
 | `-R, --rofi`          | Use rofi instead of fzf                                              |
+| `-H, --history`       | Browse local watch history (see [Watch History](#watch-history))     |
 | `--setup`             | Open first-run setup popup manually                                  |
 | `-v, --version`       | Print installed SubMiner version                                     |
 | `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible |

docs-site/public/config.example.jsonc

@@ -559,6 +559,7 @@
       "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
       "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
@@ -568,7 +569,7 @@
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
       "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
     }, // Known words setting.
     "behavior": {
       "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -618,7 +619,11 @@
     "primarySubLanguages": [
       "ja",
       "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "mediaCache": {
+      "mode": "direct", // How YouTube card audio/images are extracted. Values: direct | background
+      "maxHeight": 720 // Maximum video height downloaded for the YouTube background media cache. Set to 0 for unlimited.
+    } // Media cache setting.
   }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================

docs-site/usage.md

@@ -148,7 +148,7 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin corre
 SubMiner.AppImage --help                  # Show all options
 ```
 
-The tray menu includes `Export Logs`, which creates the same sanitized log ZIP as `subminer logs -e` and shows the archive path when complete.
+The tray menu includes `Export Logs`, which creates the same sanitized local-date log ZIP as `subminer logs -e` and shows the archive path when complete. Export sanitization masks common PII and secrets, including home-directory usernames, IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL query strings. The exported copy is sanitized; source log files remain unredacted on disk.
 
 Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.
 
@@ -191,7 +191,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 - `subminer jellyfin` / `subminer jf`: Jellyfin-focused workflow aliases.
 - `subminer doctor`: health checks for core dependencies and runtime paths.
 - `subminer settings`: open the SubMiner settings window (also `subminer --settings`).
-- `subminer logs -e`: export a sanitized ZIP of today's logs, or the most recent logs when no current-day log exists.
+- `subminer logs -e`: export a sanitized ZIP of today's local-date logs, or the most recent logs when no current-day log exists. The exported copy masks common PII and secrets; on-disk logs are unchanged.
 - `subminer config`: config file helpers (`path`, `show`).
 - `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
 - `subminer dictionary <path>`: generates a Yomitan-importable character dictionary ZIP from a file/directory target.

docs-site/youtube-integration.md

@@ -74,20 +74,30 @@ Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay
 - Select different primary and secondary tracks
 - Retry track loading if the auto-load failed or picked the wrong track
 
+SubMiner shows an "Opening YouTube subtitle picker..." status through your configured notification
+surface while it probes tracks and prepares the modal, then updates the subtitle download progress
+card to a success notification after the selected tracks load.
+
 The picker displays each track with its language, kind (manual/auto), and title when available.
 
 ## Subtitle Format Handling
 
 SubMiner handles several YouTube subtitle formats transparently:
 
-| Format | Handling |
-| ------ | -------- |
-| `srt`, `vtt` | Used directly (preferred for manual tracks) |
+| Format                 | Handling                                                 |
+| ---------------------- | -------------------------------------------------------- |
+| `srt`, `vtt`           | Used directly (preferred for manual tracks)              |
 | `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
-| Auto-generated VTT | Normalized to remove rolling-caption text duplication |
+| Auto-generated VTT     | Normalized to remove rolling-caption text duplication    |
 
 For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.
 
+## Card Media Cache
+
+By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.
+
+Background cache downloads use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.
+
 ## Configuration Reference
 
 ### Primary Subtitle Languages
@@ -95,13 +105,13 @@ For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (Ti
 ```jsonc
 {
   "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
-  }
+    "primarySubLanguages": ["ja", "jpn"],
+  },
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
+| Option                | Type       | Description                                                                           |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------- |
 | `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |
 
 ### Secondary Subtitle Languages
@@ -113,16 +123,16 @@ Secondary track selection uses the shared `secondarySub` config:
   "secondarySub": {
     "secondarySubLanguages": [],
     "autoLoadSecondarySub": false,
-    "defaultMode": "hover"
-  }
+    "defaultMode": "hover",
+  },
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `secondarySubLanguages` | `string[]` | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
-| `autoLoadSecondarySub` | `boolean` | Auto-detect and load a matching secondary track (default: `false`) |
-| `defaultMode` | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`) |
+| Option                  | Type                                 | Description                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
+| `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary track (default: `false`)                                                                                                                                  |
+| `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                                                   |
 
 Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
 
@@ -131,6 +141,7 @@ Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
 - **No subtitles found**: The video may not have Japanese subtitles. Open the picker with `Ctrl+Alt+C` to see all available tracks.
 - **yt-dlp not found**: Install `yt-dlp` and ensure it is on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
 - **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
+- **Card media `403` errors**: Switch `youtube.mediaCache.mode` from `"direct"` to `"background"` so card media is generated from a local `yt-dlp` cache instead of ffmpeg reading an expiring YouTube stream URL.
 - **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
 - **`ytsearch:` targets**: `subminer ytsearch:"keyword"` plays the first search result. Subtitle availability depends on the matched video.
 - **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.

docs/workflow/verification.md

@@ -3,10 +3,22 @@
 # Verification
 
 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-07-06  
 Owner: Kyle Yasuda  
 Read when: selecting the right verification lane for a change
 
+## Lane Infrastructure
+
+- Lane membership is defined once in `scripts/test-lanes.ts` and discovered by
+  directory — new test files join their lane automatically; never hand-list test
+  files in `package.json`.
+- `scripts/run-test-lane.mjs` runs each test file in its own `bun test` process
+  (per-file isolation with a wall timeout) so a hanging test or leaked global in
+  one file cannot cascade into the rest of the lane. `--jobs N` parallelizes;
+  `--single-process` restores the shared-process mode for debugging.
+- `bun run test:fast` is the full source gate: discovered `src/**`, launcher
+  unit, `scripts/**`, and the compiled runtime-compat slice.
+
 ## Default Handoff Gate
 
 ```bash
@@ -31,6 +43,8 @@ bun run docs:build
 - Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / compiled behavior: `bun run test:runtime:compat`
+- Stats dashboard UI: `bun run test:stats`
+- Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Coverage for the maintained source lane: `bun run test:coverage:src`
 - Deep/local full gate: default handoff gate above
 

launcher/bun-sqlite.d.ts

@@ -0,0 +1,30 @@
+// Minimal ambient typing for bun:sqlite. The launcher always runs under bun
+// (see the build banner in package.json), but the repo typechecks with plain
+// tsc which has no bun type definitions.
+declare module 'bun:sqlite' {
+  export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+  }
+
+  export interface Statement<ReturnType = unknown, ParamsType extends unknown[] = unknown[]> {
+    all(...params: ParamsType): ReturnType[];
+    get(...params: ParamsType): ReturnType | undefined;
+    run(...params: ParamsType): RunResult;
+  }
+
+  export class Database {
+    constructor(
+      filename: string,
+      options?: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+    );
+    query<ReturnType = unknown, ParamsType extends unknown[] = unknown[]>(
+      sql: string,
+    ): Statement<ReturnType, ParamsType>;
+    prepare<ReturnType = unknown, ParamsType extends unknown[] = unknown[]>(
+      sql: string,
+    ): Statement<ReturnType, ParamsType>;
+    run(sql: string, ...params: unknown[]): RunResult;
+    close(throwOnError?: boolean): void;
+  }
+}

launcher/commands/history-command.ts

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fail, log } from '../log.js';
+import { commandExists } from '../util.js';
+import {
+  collectVideos,
+  findRofiTheme,
+  formatPickerLaunchError,
+  showFzfMenu,
+  showRofiMenu,
+} from '../picker.js';
+import {
+  findNextEpisode,
+  groupHistoryBySeries,
+  listSeasonDirs,
+  materializeCoverArt,
+  queryLocalWatchHistory,
+  resolveImmersionDbPath,
+  sortVideosByEpisode,
+  type HistorySeriesEntry,
+} from '../history.js';
+import type { Args } from '../types.js';
+import type { LauncherCommandContext } from './context.js';
+
+function checkPickerDependencies(args: Args): void {
+  if (args.useRofi) {
+    if (!commandExists('rofi')) fail('Missing dependency: rofi');
+    return;
+  }
+  if (!commandExists('fzf')) fail('Missing dependency: fzf');
+}
+
+function showRofiIndexMenu(
+  labels: string[],
+  prompt: string,
+  themePath: string | null,
+  icons: Array<string | null> = [],
+): number {
+  const rofiArgs = ['-dmenu', '-i', '-matching', 'fuzzy', '-format', 'i', '-p', prompt];
+  const hasIcons = icons.some(Boolean);
+  if (hasIcons) rofiArgs.push('-show-icons');
+  if (themePath) {
+    rofiArgs.push('-theme', themePath);
+  } else {
+    rofiArgs.push('-theme-str', 'configuration { font: "Noto Sans CJK JP Regular 8";}');
+  }
+  if (hasIcons) {
+    rofiArgs.push('-theme-str', 'configuration { show-icons: true; }');
+    rofiArgs.push('-theme-str', 'element-icon { enabled: true; size: 3em; }');
+  }
+  const lines = labels.map((label, index) =>
+    icons[index] ? `${label}\u0000icon\u001f${icons[index]}` : label,
+  );
+  const result = spawnSync('rofi', rofiArgs, {
+    input: `${lines.join('\n')}\n`,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'ignore'],
+  });
+  if (result.error) {
+    fail(formatPickerLaunchError('rofi', result.error as NodeJS.ErrnoException));
+  }
+  const out = (result.stdout || '').trim();
+  if (!out) return -1;
+  const idx = Number.parseInt(out, 10);
+  return Number.isInteger(idx) && idx >= 0 && idx < labels.length ? idx : -1;
+}
+
+function showFzfIndexMenu(labels: string[], prompt: string): number {
+  const lines = labels.map((label, index) => `${index}\t${label}`);
+  const result = spawnSync(
+    'fzf',
+    [
+      '--ansi',
+      '--reverse',
+      '--ignore-case',
+      `--prompt=${prompt}: `,
+      '--delimiter=\t',
+      '--with-nth=2..',
+    ],
+    {
+      input: `${lines.join('\n')}\n`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'inherit'],
+    },
+  );
+  if (result.error) {
+    fail(formatPickerLaunchError('fzf', result.error as NodeJS.ErrnoException));
+  }
+  const picked = (result.stdout || '').trim();
+  const tab = picked.indexOf('\t');
+  if (tab === -1) return -1;
+  const idx = Number.parseInt(picked.slice(0, tab), 10);
+  return Number.isInteger(idx) && idx >= 0 && idx < labels.length ? idx : -1;
+}
+
+function pickIndex(
+  labels: string[],
+  prompt: string,
+  useRofi: boolean,
+  themePath: string | null,
+  icons: Array<string | null> = [],
+): number {
+  if (labels.length === 0) return -1;
+  return useRofi
+    ? showRofiIndexMenu(labels, prompt, themePath, icons)
+    : showFzfIndexMenu(labels, prompt);
+}
+
+function formatEpisodeLabel(entry: HistorySeriesEntry): string {
+  const { parsedSeason, parsedEpisode } = entry.lastWatched;
+  if (parsedEpisode === null) return '';
+  return parsedSeason !== null ? `S${parsedSeason}E${parsedEpisode}` : `E${parsedEpisode}`;
+}
+
+function formatSeriesLabel(entry: HistorySeriesEntry): string {
+  const episodeLabel = formatEpisodeLabel(entry);
+  return episodeLabel ? `${entry.displayName}  [last: ${episodeLabel}]` : entry.displayName;
+}
+
+function pickEpisodeFromDir(dir: string, context: LauncherCommandContext): string | null {
+  const { args, scriptPath } = context;
+  const videos = sortVideosByEpisode(collectVideos(dir, false));
+  if (videos.length === 0) {
+    fail(`No video files found in: ${dir}`);
+  }
+  const selected = args.useRofi
+    ? showRofiMenu(videos, dir, false, scriptPath, args.logLevel)
+    : showFzfMenu(videos);
+  return selected || null;
+}
+
+function browseEpisodes(
+  entry: HistorySeriesEntry,
+  context: LauncherCommandContext,
+  themePath: string | null,
+): string | null {
+  const { args } = context;
+  const seasons = listSeasonDirs(entry.seriesRoot);
+  let dir = entry.seriesRoot;
+
+  if (seasons.length > 1) {
+    const idx = pickIndex(
+      seasons.map((season) => season.name),
+      `${entry.displayName} — Season`,
+      args.useRofi,
+      themePath,
+    );
+    if (idx < 0) return null;
+    dir = seasons[idx]!.path;
+  } else if (seasons.length === 1 && collectVideos(dir, false).length === 0) {
+    dir = seasons[0]!.path;
+  }
+
+  return pickEpisodeFromDir(dir, context);
+}
+
+export async function runHistoryCommand(context: LauncherCommandContext): Promise<string | null> {
+  const { args, scriptPath } = context;
+
+  checkPickerDependencies(args);
+  const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;
+
+  const dbPath = resolveImmersionDbPath();
+  if (!fs.existsSync(dbPath)) {
+    fail(`Watch history database not found: ${dbPath}`);
+  }
+
+  const rows = queryLocalWatchHistory(dbPath);
+  const series = groupHistoryBySeries(rows);
+  if (series.length === 0) {
+    fail('No local watch history found (or watched directories are not accessible).');
+  }
+
+  log('info', args.logLevel, `Watch history: ${series.length} series found in ${dbPath}`);
+
+  const coverPaths = args.useRofi
+    ? materializeCoverArt(
+        dbPath,
+        series.map((seriesEntry) => seriesEntry.coverBlobHash),
+      )
+    : new Map<string, string>();
+  const seriesIcons = series.map((seriesEntry) =>
+    seriesEntry.coverBlobHash ? (coverPaths.get(seriesEntry.coverBlobHash) ?? null) : null,
+  );
+
+  const seriesIdx = pickIndex(
+    series.map(formatSeriesLabel),
+    'Watch History',
+    args.useRofi,
+    themePath,
+    seriesIcons,
+  );
+  if (seriesIdx < 0) return null;
+  const entry = series[seriesIdx]!;
+
+  const lastPath = path.resolve(entry.lastWatched.sourcePath);
+  const lastExists = fs.existsSync(lastPath);
+  const nextEpisode = findNextEpisode(lastPath);
+
+  const actions: Array<{ kind: 'replay' | 'next' | 'browse'; label: string }> = [];
+  if (lastExists) {
+    actions.push({ kind: 'replay', label: `Replay last watched — ${path.basename(lastPath)}` });
+  }
+  if (nextEpisode) {
+    actions.push({ kind: 'next', label: `Next episode — ${path.basename(nextEpisode)}` });
+  }
+  actions.push({ kind: 'browse', label: 'Browse episodes' });
+
+  const entryIcon = seriesIcons[seriesIdx] ?? null;
+  const actionIdx = pickIndex(
+    actions.map((action) => action.label),
+    entry.displayName,
+    args.useRofi,
+    themePath,
+    actions.map(() => entryIcon),
+  );
+  if (actionIdx < 0) return null;
+
+  switch (actions[actionIdx]!.kind) {
+    case 'replay':
+      return lastPath;
+    case 'next':
+      return nextEpisode;
+    case 'browse':
+      return browseEpisodes(entry, context, themePath);
+  }
+}

launcher/commands/playback-command.test.ts

@@ -35,6 +35,7 @@ function createContext(): LauncherCommandContext {
       texthookerOnly: false,
       texthookerOpenBrowser: false,
       useRofi: false,
+      history: false,
       logLevel: 'info',
       logRotation: 7,
       passwordStore: '',

launcher/config/args-normalizer.ts

@@ -198,6 +198,7 @@ export function createDefaultArgs(
     texthookerOnly: false,
     texthookerOpenBrowser: false,
     useRofi: false,
+    history: false,
     logLevel: loggingConfig.level ?? 'warn',
     logRotation: loggingConfig.rotation ?? 7,
     passwordStore: '',
@@ -231,6 +232,7 @@ export function applyRootOptionsToArgs(
   if (typeof options.logLevel === 'string') parsed.logLevel = parseLogLevel(options.logLevel);
   if (typeof options.passwordStore === 'string') parsed.passwordStore = options.passwordStore;
   if (options.rofi === true) parsed.useRofi = true;
+  if (options.history === true) parsed.history = true;
   if (options.update === true) parsed.update = true;
   if (options.version === true) parsed.version = true;
   if (options.settings === true) parsed.settings = true;

launcher/config/cli-parser-builder.ts

@@ -64,6 +64,7 @@ function applyRootOptions(program: Command): void {
     .option('--settings', 'Open settings window')
     .option('-u, --update', 'Check for updates')
     .option('-R, --rofi', 'Use rofi picker')
+    .option('-H, --history', 'Browse local watch history')
     .option('-S, --start-overlay', 'Auto-start overlay')
     .option('-T, --no-texthooker', 'Disable texthooker-ui server');
 }

launcher/history-art.ts

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+import { withReadonlyWalRetry } from './history-db.js';
+
+const COVER_EXTENSIONS = ['.jpg', '.png', '.webp', '.gif'] as const;
+const SAFE_COVER_HASH_PATTERN = /^[a-z0-9_-]+$/i;
+
+export function getDefaultCoverCacheDir(): string {
+  return path.join(os.homedir(), '.cache', 'subminer', 'covers');
+}
+
+export function detectImageExtension(blob: Buffer): string {
+  if (blob.length >= 8 && blob.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+    return '.png';
+  }
+  if (blob.length >= 3 && blob[0] === 0xff && blob[1] === 0xd8 && blob[2] === 0xff) {
+    return '.jpg';
+  }
+  if (
+    blob.length >= 12 &&
+    blob.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    blob.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return '.webp';
+  }
+  if (blob.length >= 4 && blob.subarray(0, 3).toString('ascii') === 'GIF') {
+    return '.gif';
+  }
+  return '.jpg';
+}
+
+function findCachedCover(cacheDir: string, hash: string): string | null {
+  for (const ext of COVER_EXTENSIONS) {
+    const candidate = path.join(cacheDir, `${hash}${ext}`);
+    try {
+      if (fs.statSync(candidate).size > 0) return candidate;
+    } catch {
+      // not cached with this extension
+    }
+  }
+  return null;
+}
+
+function queryCoverBlobs(
+  dbPath: string,
+  hashes: string[],
+  options: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+): Map<string, Buffer> {
+  const blobs = new Map<string, Buffer>();
+  const db = new Database(dbPath, options);
+  try {
+    const hasBlobTable = db
+      .query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'imm_cover_art_blobs'`)
+      .get();
+    if (!hasBlobTable) return blobs;
+
+    const stmt = db.query<{ cover_blob: Uint8Array | null }>(
+      'SELECT cover_blob FROM imm_cover_art_blobs WHERE blob_hash = ?',
+    );
+    for (const hash of hashes) {
+      const row = stmt.get(hash);
+      if (row?.cover_blob && row.cover_blob.length > 0) {
+        blobs.set(hash, Buffer.from(row.cover_blob));
+      }
+    }
+    return blobs;
+  } finally {
+    db.close();
+  }
+}
+
+function isSafeCoverHash(hash: string | null | undefined): hash is string {
+  return typeof hash === 'string' && SAFE_COVER_HASH_PATTERN.test(hash);
+}
+
+/**
+ * Ensures cover art blobs referenced by hash exist as image files in the cache
+ * directory, extracting missing ones from the stats database. Returns a map of
+ * blob hash to on-disk image path for every cover that could be materialized.
+ */
+export function materializeCoverArt(
+  dbPath: string,
+  hashes: Array<string | null | undefined>,
+  cacheDir: string = getDefaultCoverCacheDir(),
+): Map<string, string> {
+  const wanted = Array.from(new Set(hashes.filter(isSafeCoverHash)));
+  const resolved = new Map<string, string>();
+  if (wanted.length === 0) return resolved;
+
+  const missing: string[] = [];
+  for (const hash of wanted) {
+    const cached = findCachedCover(cacheDir, hash);
+    if (cached) {
+      resolved.set(hash, cached);
+    } else {
+      missing.push(hash);
+    }
+  }
+  if (missing.length === 0) return resolved;
+
+  let blobs: Map<string, Buffer>;
+  try {
+    blobs = withReadonlyWalRetry(dbPath, (options) => queryCoverBlobs(dbPath, missing, options));
+  } catch {
+    return resolved;
+  }
+  if (blobs.size === 0) return resolved;
+
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  } catch {
+    return resolved;
+  }
+  for (const [hash, blob] of blobs) {
+    const target = path.join(cacheDir, `${hash}${detectImageExtension(blob)}`);
+    try {
+      fs.writeFileSync(target, blob);
+      resolved.set(hash, target);
+    } catch {
+      // cache write failure just means no icon for this entry
+    }
+  }
+  return resolved;
+}

launcher/history-db.ts

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+import { resolveConfigDir } from '../src/config/path-resolution.js';
+import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
+import type { HistoryVideoRow } from './history-types.js';
+import { resolvePathMaybe } from './util.js';
+
+export function resolveImmersionDbPath(): string {
+  const root = readLauncherMainConfigObject();
+  const tracking =
+    root?.immersionTracking &&
+    typeof root.immersionTracking === 'object' &&
+    !Array.isArray(root.immersionTracking)
+      ? (root.immersionTracking as Record<string, unknown>)
+      : null;
+  const configured = typeof tracking?.dbPath === 'string' ? tracking.dbPath.trim() : '';
+  if (configured) return resolvePathMaybe(configured);
+
+  const configDir = resolveConfigDir({
+    platform: process.platform,
+    appDataDir: process.env.APPDATA,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    homeDir: os.homedir(),
+    existsSync: fs.existsSync,
+  });
+  return path.join(configDir, 'immersion.sqlite');
+}
+
+interface RawHistoryRow {
+  video_id: number;
+  source_path: string | null;
+  parsed_title: string | null;
+  parsed_season: number | null;
+  parsed_episode: number | null;
+  anime_title: string | null;
+  last_watched_ms: number | bigint | null;
+  cover_blob_hash: string | null;
+}
+
+export function queryLocalWatchHistory(dbPath: string): HistoryVideoRow[] {
+  return withReadonlyWalRetry(dbPath, (options) => readHistoryRows(dbPath, options));
+}
+
+export function withReadonlyWalRetry<T>(
+  dbPath: string,
+  query: (options: { readonly?: boolean; readwrite?: boolean; create?: boolean }) => T,
+): T {
+  try {
+    return query({ readonly: true });
+  } catch (error) {
+    if (!isReadonlyWalRetryError(error, dbPath)) throw error;
+    return query({ readwrite: true, create: false });
+  }
+}
+
+export function isReadonlyWalRetryError(error: unknown, dbPath: string): boolean {
+  if (!isWalModeSqliteDatabase(dbPath)) return false;
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? String((error as { code?: unknown }).code ?? '')
+      : '';
+  const message = error instanceof Error ? error.message : String(error);
+  const text = `${code} ${message}`.toLowerCase();
+  return (
+    text.includes('readonly') ||
+    text.includes('read-only') ||
+    text.includes('attempt to write a readonly database') ||
+    text.includes('sqlite_cantopen') ||
+    text.includes('unable to open database file')
+  );
+}
+
+function isWalModeSqliteDatabase(dbPath: string): boolean {
+  const header = Buffer.alloc(20);
+  let fd: number | null = null;
+  try {
+    fd = fs.openSync(dbPath, 'r');
+    if (fs.readSync(fd, header, 0, header.length, 0) < header.length) return false;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+  }
+  return header.subarray(0, 16).toString('ascii') === 'SQLite format 3\0' && header[18] === 2;
+}
+
+function tableExists(db: Database, tableName: string): boolean {
+  return Boolean(
+    db.query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`).get(tableName),
+  );
+}
+
+function readHistoryRows(
+  dbPath: string,
+  options: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+): HistoryVideoRow[] {
+  const db = new Database(dbPath, options);
+  try {
+    const hasMediaArt = tableExists(db, 'imm_media_art');
+    const coverSelect = hasMediaArt
+      ? `COALESCE(
+          ma.cover_blob_hash,
+          (SELECT ma2.cover_blob_hash
+           FROM imm_media_art ma2
+           JOIN imm_videos v2 ON v2.video_id = ma2.video_id
+           WHERE v2.anime_id = v.anime_id AND ma2.cover_blob_hash IS NOT NULL
+           LIMIT 1)
+        ) AS cover_blob_hash`
+      : 'NULL AS cover_blob_hash';
+    const coverJoin = hasMediaArt ? 'LEFT JOIN imm_media_art ma ON ma.video_id = v.video_id' : '';
+    const rows = db
+      .query<RawHistoryRow>(
+        `
+        SELECT
+          v.video_id,
+          v.source_path,
+          v.parsed_title,
+          v.parsed_season,
+          v.parsed_episode,
+          COALESCE(a.title_romaji, a.canonical_title) AS anime_title,
+          MAX(CAST(s.started_at_ms AS INTEGER)) AS last_watched_ms,
+          ${coverSelect}
+        FROM imm_sessions s
+        JOIN imm_videos v ON v.video_id = s.video_id
+        LEFT JOIN imm_anime a ON a.anime_id = v.anime_id
+        ${coverJoin}
+        WHERE v.source_type = 1 AND v.source_path IS NOT NULL AND v.source_path != ''
+        GROUP BY v.video_id
+        ORDER BY last_watched_ms DESC
+        `,
+      )
+      .all();
+
+    return rows
+      .filter((row) => typeof row.source_path === 'string' && row.source_path.length > 0)
+      .map((row) => ({
+        videoId: row.video_id,
+        sourcePath: row.source_path!,
+        parsedTitle: row.parsed_title,
+        parsedSeason: row.parsed_season,
+        parsedEpisode: row.parsed_episode,
+        animeTitle: row.anime_title,
+        lastWatchedMs: Number(row.last_watched_ms ?? 0),
+        coverBlobHash: row.cover_blob_hash,
+      }));
+  } finally {
+    db.close();
+  }
+}

launcher/history-navigation.ts

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseMediaInfo } from '../src/jimaku/utils.js';
+import { collectVideos } from './picker.js';
+import type { HistorySeriesEntry, HistoryVideoRow, SeasonDirEntry } from './history-types.js';
+
+const SEASON_DIR_PATTERN = /^(?:season|s)[\s._-]*(\d{1,3})\b/i;
+
+export function seasonNumberFromDirName(name: string): number | null {
+  const match = name.trim().match(SEASON_DIR_PATTERN);
+  if (!match) return null;
+  const parsed = Number.parseInt(match[1]!, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function resolveSeriesRoot(filePath: string): string {
+  const parent = path.dirname(filePath);
+  if (seasonNumberFromDirName(path.basename(parent)) !== null) {
+    return path.dirname(parent);
+  }
+  return parent;
+}
+
+export function groupHistoryBySeries(
+  rows: HistoryVideoRow[],
+  existsFn: (candidate: string) => boolean = fs.existsSync,
+): HistorySeriesEntry[] {
+  const byRoot = new Map<string, HistorySeriesEntry>();
+  const sorted = [...rows].sort((a, b) => b.lastWatchedMs - a.lastWatchedMs);
+
+  for (const row of sorted) {
+    const seriesRoot = resolveSeriesRoot(row.sourcePath);
+    const existing = byRoot.get(seriesRoot);
+    if (existing) {
+      if (existing.coverBlobHash === null && row.coverBlobHash !== null) {
+        existing.coverBlobHash = row.coverBlobHash;
+      }
+      continue;
+    }
+    if (!existsFn(seriesRoot)) continue;
+    const displayName =
+      row.parsedTitle?.trim() || row.animeTitle?.trim() || path.basename(seriesRoot);
+    byRoot.set(seriesRoot, {
+      seriesRoot,
+      displayName,
+      lastWatched: row,
+      coverBlobHash: row.coverBlobHash,
+    });
+  }
+
+  return Array.from(byRoot.values());
+}
+
+function compareNatural(a: string, b: string): number {
+  return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+}
+
+export function sortVideosByEpisode(videos: string[]): string[] {
+  const parsed = videos.map((video) => ({ video, info: parseMediaInfo(video) }));
+  parsed.sort((a, b) => {
+    if (a.info.episode !== null && b.info.episode !== null) {
+      const seasonA = a.info.season ?? 0;
+      const seasonB = b.info.season ?? 0;
+      if (seasonA !== seasonB) return seasonA - seasonB;
+      if (a.info.episode !== b.info.episode) return a.info.episode - b.info.episode;
+    }
+    return compareNatural(a.video, b.video);
+  });
+  return parsed.map((entry) => entry.video);
+}
+
+function dirContainsVideo(dir: string): boolean {
+  return collectVideos(dir, true).length > 0;
+}
+
+export function listSeasonDirs(seriesRoot: string): SeasonDirEntry[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(seriesRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const dirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      name: entry.name,
+      path: path.join(seriesRoot, entry.name),
+      season: seasonNumberFromDirName(entry.name),
+    }))
+    .filter((entry) => dirContainsVideo(entry.path));
+
+  dirs.sort((a, b) => {
+    if (a.season !== null && b.season !== null && a.season !== b.season) {
+      return a.season - b.season;
+    }
+    return compareNatural(a.name, b.name);
+  });
+  return dirs;
+}
+
+function findFirstEpisodeInNextSeason(resolvedLast: string, dir: string): string | null {
+  const seriesRoot = resolveSeriesRoot(resolvedLast);
+  if (seriesRoot === dir) return null;
+  const seasons = listSeasonDirs(seriesRoot);
+  const currentIdx = seasons.findIndex((season) => path.resolve(season.path) === dir);
+  if (currentIdx < 0 || currentIdx + 1 >= seasons.length) return null;
+  const nextSeason = sortVideosByEpisode(collectVideos(seasons[currentIdx + 1]!.path, false));
+  return nextSeason[0] ?? null;
+}
+
+export function findNextEpisode(lastPath: string): string | null {
+  const resolvedLast = path.resolve(lastPath);
+  const dir = path.dirname(resolvedLast);
+  const episodes = sortVideosByEpisode(collectVideos(dir, false));
+  const idx = episodes.indexOf(resolvedLast);
+
+  if (idx >= 0) {
+    if (idx + 1 < episodes.length) return episodes[idx + 1]!;
+  } else {
+    const lastInfo = parseMediaInfo(resolvedLast);
+    if (lastInfo.episode !== null) {
+      const candidate = episodes.find((episode) => {
+        const info = parseMediaInfo(episode);
+        return info.episode !== null && info.episode > lastInfo.episode!;
+      });
+      if (candidate) return candidate;
+    }
+  }
+
+  return findFirstEpisodeInNextSeason(resolvedLast, dir);
+}

launcher/history-types.ts

@@ -0,0 +1,23 @@
+export interface HistoryVideoRow {
+  videoId: number;
+  sourcePath: string;
+  parsedTitle: string | null;
+  parsedSeason: number | null;
+  parsedEpisode: number | null;
+  animeTitle: string | null;
+  lastWatchedMs: number;
+  coverBlobHash: string | null;
+}
+
+export interface HistorySeriesEntry {
+  seriesRoot: string;
+  displayName: string;
+  lastWatched: HistoryVideoRow;
+  coverBlobHash: string | null;
+}
+
+export interface SeasonDirEntry {
+  name: string;
+  path: string;
+  season: number | null;
+}

launcher/history.test.ts

@@ -0,0 +1,441 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+import {
+  detectImageExtension,
+  findNextEpisode,
+  groupHistoryBySeries,
+  isReadonlyWalRetryError,
+  listSeasonDirs,
+  materializeCoverArt,
+  queryLocalWatchHistory,
+  resolveSeriesRoot,
+  seasonNumberFromDirName,
+  sortVideosByEpisode,
+  type HistoryVideoRow,
+} from './history.js';
+
+function makeRow(overrides: Partial<HistoryVideoRow> = {}): HistoryVideoRow {
+  return {
+    videoId: 1,
+    sourcePath: '/media/anime/Show/Season-1/Show - S01E01.mkv',
+    parsedTitle: 'Show',
+    parsedSeason: 1,
+    parsedEpisode: 1,
+    animeTitle: null,
+    lastWatchedMs: 1000,
+    coverBlobHash: null,
+    ...overrides,
+  };
+}
+
+test('seasonNumberFromDirName detects common season directory names', () => {
+  assert.equal(seasonNumberFromDirName('Season-1'), 1);
+  assert.equal(seasonNumberFromDirName('Season 2'), 2);
+  assert.equal(seasonNumberFromDirName('S03'), 3);
+  assert.equal(seasonNumberFromDirName('season_04'), 4);
+  assert.equal(seasonNumberFromDirName('Specials'), null);
+  assert.equal(seasonNumberFromDirName('Show Name'), null);
+});
+
+test('resolveSeriesRoot skips season directories', () => {
+  assert.equal(
+    resolveSeriesRoot('/media/anime/Show/Season-1/Show - S01E01.mkv'),
+    '/media/anime/Show',
+  );
+  assert.equal(resolveSeriesRoot('/media/anime/Show/Show - 01.mkv'), '/media/anime/Show');
+});
+
+test('groupHistoryBySeries keeps most recent entry per series root', () => {
+  const rows = [
+    makeRow({ videoId: 1, parsedEpisode: 1, lastWatchedMs: 1000 }),
+    makeRow({
+      videoId: 2,
+      sourcePath: '/media/anime/Show/Season-1/Show - S01E02.mkv',
+      parsedEpisode: 2,
+      lastWatchedMs: 3000,
+    }),
+    makeRow({
+      videoId: 3,
+      sourcePath: '/media/anime/Other/Other - 05.mkv',
+      parsedTitle: 'Other',
+      parsedSeason: null,
+      parsedEpisode: 5,
+      lastWatchedMs: 2000,
+    }),
+  ];
+
+  const series = groupHistoryBySeries(rows, () => true);
+
+  assert.equal(series.length, 2);
+  assert.equal(series[0]?.displayName, 'Show');
+  assert.equal(series[0]?.seriesRoot, '/media/anime/Show');
+  assert.equal(series[0]?.lastWatched.parsedEpisode, 2);
+  assert.equal(series[1]?.displayName, 'Other');
+});
+
+test('groupHistoryBySeries filters series roots that no longer exist', () => {
+  const rows = [
+    makeRow({ videoId: 1 }),
+    makeRow({
+      videoId: 2,
+      sourcePath: '/gone/anime/Missing/Season-1/Missing - S01E01.mkv',
+      parsedTitle: 'Missing',
+      lastWatchedMs: 5000,
+    }),
+  ];
+
+  const series = groupHistoryBySeries(rows, (candidate) => !candidate.startsWith('/gone/'));
+
+  assert.equal(series.length, 1);
+  assert.equal(series[0]?.displayName, 'Show');
+});
+
+test('groupHistoryBySeries falls back to directory name for display', () => {
+  const rows = [
+    makeRow({
+      sourcePath: '/media/anime/Some Show Dir/video.mkv',
+      parsedTitle: null,
+      animeTitle: null,
+    }),
+  ];
+
+  const series = groupHistoryBySeries(rows, () => true);
+
+  assert.equal(series[0]?.displayName, 'Some Show Dir');
+});
+
+test('sortVideosByEpisode orders by parsed episode with natural fallback', () => {
+  const videos = [
+    '/media/Show/Show - S01E10 - Ten.mkv',
+    '/media/Show/Show - S01E02 - Two.mkv',
+    '/media/Show/Show - S01E01 - One.mkv',
+  ];
+
+  assert.deepEqual(sortVideosByEpisode(videos), [
+    '/media/Show/Show - S01E01 - One.mkv',
+    '/media/Show/Show - S01E02 - Two.mkv',
+    '/media/Show/Show - S01E10 - Ten.mkv',
+  ]);
+});
+
+function createSeriesTree(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-'));
+  const seriesRoot = path.join(root, 'Show');
+  const season1 = path.join(seriesRoot, 'Season-1');
+  const season2 = path.join(seriesRoot, 'Season-2');
+  fs.mkdirSync(season1, { recursive: true });
+  fs.mkdirSync(season2, { recursive: true });
+  fs.mkdirSync(path.join(seriesRoot, 'extras-empty'), { recursive: true });
+  for (const name of ['Show - S01E01.mkv', 'Show - S01E02.mkv', 'Show - S01E03.mkv']) {
+    fs.writeFileSync(path.join(season1, name), '');
+  }
+  fs.writeFileSync(path.join(season2, 'Show - S02E01.mkv'), '');
+  fs.writeFileSync(path.join(season1, 'notes.txt'), '');
+  return seriesRoot;
+}
+
+test('listSeasonDirs returns only video-bearing directories in season order', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const seasons = listSeasonDirs(seriesRoot);
+    assert.deepEqual(
+      seasons.map((entry) => entry.name),
+      ['Season-1', 'Season-2'],
+    );
+    assert.deepEqual(
+      seasons.map((entry) => entry.season),
+      [1, 2],
+    );
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+test('findNextEpisode advances within a season and across seasons', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const season2 = path.join(seriesRoot, 'Season-2');
+
+    assert.equal(
+      findNextEpisode(path.join(season1, 'Show - S01E02.mkv')),
+      path.join(season1, 'Show - S01E03.mkv'),
+    );
+    assert.equal(
+      findNextEpisode(path.join(season1, 'Show - S01E03.mkv')),
+      path.join(season2, 'Show - S02E01.mkv'),
+    );
+    assert.equal(findNextEpisode(path.join(season2, 'Show - S02E01.mkv')), null);
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+test('findNextEpisode falls back to episode numbers when file was removed', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const missing = path.join(season1, 'Show - S01E02 - Deleted Cut.mkv');
+    assert.equal(findNextEpisode(missing), path.join(season1, 'Show - S01E03.mkv'));
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+test('findNextEpisode advances seasons when a deleted file was the last episode', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const season2 = path.join(seriesRoot, 'Season-2');
+    const missing = path.join(season1, 'Show - S01E03 - Deleted Cut.mkv');
+    assert.equal(findNextEpisode(missing), path.join(season2, 'Show - S02E01.mkv'));
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+const PNG_MAGIC = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+
+function createHistoryDb(
+  dbPath: string,
+  options: { wal?: boolean; coverArt?: boolean } = {},
+): void {
+  const db = new Database(dbPath);
+  try {
+    if (options.wal) db.run('PRAGMA journal_mode = WAL;');
+    db.run(`
+      CREATE TABLE imm_anime(
+        anime_id INTEGER PRIMARY KEY,
+        canonical_title TEXT,
+        title_romaji TEXT
+      );
+    `);
+    db.run(`
+      CREATE TABLE imm_videos(
+        video_id INTEGER PRIMARY KEY,
+        anime_id INTEGER,
+        source_type INTEGER,
+        source_path TEXT,
+        parsed_title TEXT,
+        parsed_season INTEGER,
+        parsed_episode INTEGER
+      );
+    `);
+    db.run(`
+      CREATE TABLE imm_sessions(
+        session_id INTEGER PRIMARY KEY,
+        video_id INTEGER,
+        started_at_ms TEXT
+      );
+    `);
+    db.run(`INSERT INTO imm_anime VALUES (1, 'Show Season 1', 'Show Romaji');`);
+    db.run(`
+      INSERT INTO imm_videos VALUES
+        (1, 1, 1, '/media/Show/Season-1/Show - S01E01.mkv', 'Show', 1, 1),
+        (2, 1, 1, '/media/Show/Season-1/Show - S01E02.mkv', 'Show', 1, 2),
+        (3, NULL, 2, NULL, 'Remote Show', NULL, NULL),
+        (4, NULL, 1, '', 'Empty Path', NULL, NULL);
+    `);
+    db.run(`
+      INSERT INTO imm_sessions VALUES
+        (1, 1, '1000'),
+        (2, 1, '5000'),
+        (3, 2, '3000'),
+        (4, 3, '9000');
+    `);
+    if (options.coverArt) {
+      db.run(`
+        CREATE TABLE imm_media_art(
+          video_id INTEGER PRIMARY KEY,
+          cover_blob_hash TEXT
+        );
+      `);
+      db.run(`
+        CREATE TABLE imm_cover_art_blobs(
+          blob_hash TEXT PRIMARY KEY,
+          cover_blob BLOB NOT NULL
+        );
+      `);
+      // Art only on video 1; video 2 resolves it through the shared anime_id.
+      db.run(`INSERT INTO imm_media_art VALUES (1, 'hash-1');`);
+      db.query('INSERT INTO imm_cover_art_blobs VALUES (?, ?)').run('hash-1', PNG_MAGIC);
+    }
+    if (options.wal) db.run('PRAGMA wal_checkpoint(TRUNCATE);');
+  } finally {
+    db.close();
+  }
+}
+
+function assertHistoryRows(dbPath: string): void {
+  const rows = queryLocalWatchHistory(dbPath);
+
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0]?.videoId, 1);
+  assert.equal(rows[0]?.lastWatchedMs, 5000);
+  assert.equal(rows[0]?.animeTitle, 'Show Romaji');
+  assert.equal(rows[1]?.videoId, 2);
+  assert.equal(rows[1]?.lastWatchedMs, 3000);
+}
+
+test('queryLocalWatchHistory returns local files ordered by most recent session', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-db-'));
+  const dbPath = path.join(dir, 'immersion.sqlite');
+  try {
+    createHistoryDb(dbPath);
+    assertHistoryRows(dbPath);
+    const rows = queryLocalWatchHistory(dbPath);
+    assert.equal(rows[0]?.coverBlobHash, null);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('queryLocalWatchHistory resolves cover hashes directly and via shared anime', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-art-'));
+  const dbPath = path.join(dir, 'immersion.sqlite');
+  try {
+    createHistoryDb(dbPath, { coverArt: true });
+    const rows = queryLocalWatchHistory(dbPath);
+    assert.equal(rows[0]?.videoId, 1);
+    assert.equal(rows[0]?.coverBlobHash, 'hash-1');
+    assert.equal(rows[1]?.videoId, 2);
+    assert.equal(rows[1]?.coverBlobHash, 'hash-1');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('materializeCoverArt extracts blobs to the cache dir and reuses cached files', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-covers-'));
+  const dbPath = path.join(dir, 'immersion.sqlite');
+  const cacheDir = path.join(dir, 'covers');
+  try {
+    createHistoryDb(dbPath, { coverArt: true });
+
+    const covers = materializeCoverArt(
+      dbPath,
+      ['hash-1', 'hash-1', null, 'hash-missing'],
+      cacheDir,
+    );
+    const coverPath = covers.get('hash-1');
+    assert.ok(coverPath);
+    assert.equal(path.extname(coverPath!), '.png');
+    assert.ok(fs.statSync(coverPath!).size > 0);
+    assert.equal(covers.has('hash-missing'), false);
+
+    // Cached file is reused even when the database has disappeared.
+    fs.rmSync(dbPath);
+    const cachedCovers = materializeCoverArt(dbPath, ['hash-1'], cacheDir);
+    assert.equal(cachedCovers.get('hash-1'), coverPath);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('materializeCoverArt rejects cover hashes that escape the cache dir', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-cover-safety-'));
+  const dbPath = path.join(dir, 'immersion.sqlite');
+  const cacheDir = path.join(dir, 'covers');
+  const unsafeHash = '../escape';
+  try {
+    createHistoryDb(dbPath, { coverArt: true });
+    const db = new Database(dbPath);
+    try {
+      db.query('INSERT INTO imm_cover_art_blobs VALUES (?, ?)').run(unsafeHash, PNG_MAGIC);
+    } finally {
+      db.close();
+    }
+
+    const covers = materializeCoverArt(dbPath, [unsafeHash], cacheDir);
+
+    assert.equal(covers.has(unsafeHash), false);
+    assert.equal(fs.existsSync(path.join(dir, 'escape.png')), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('detectImageExtension identifies common cover formats', () => {
+  assert.equal(detectImageExtension(PNG_MAGIC), '.png');
+  assert.equal(detectImageExtension(Buffer.from([0xff, 0xd8, 0xff, 0xe0])), '.jpg');
+  assert.equal(detectImageExtension(Buffer.from('RIFF0000WEBPVP8 ', 'ascii')), '.webp');
+  assert.equal(detectImageExtension(Buffer.from('GIF89a', 'ascii')), '.gif');
+  assert.equal(detectImageExtension(Buffer.from('unknown', 'ascii')), '.jpg');
+});
+
+test('groupHistoryBySeries backfills cover hash from older rows of the same series', () => {
+  const rows = [
+    makeRow({ videoId: 2, parsedEpisode: 2, lastWatchedMs: 3000, coverBlobHash: null }),
+    makeRow({ videoId: 1, parsedEpisode: 1, lastWatchedMs: 1000, coverBlobHash: 'hash-1' }),
+  ];
+
+  const series = groupHistoryBySeries(rows, () => true);
+
+  assert.equal(series.length, 1);
+  assert.equal(series[0]?.lastWatched.videoId, 2);
+  assert.equal(series[0]?.coverBlobHash, 'hash-1');
+});
+
+test('queryLocalWatchHistory reads a cleanly-closed WAL database', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-wal-'));
+  const dbPath = path.join(dir, 'immersion.sqlite');
+  try {
+    createHistoryDb(dbPath, { wal: true });
+    // Reproduce the state after the app shuts down cleanly: WAL journal mode
+    // with no -wal/-shm sidecar files on disk. A read-only connection then
+    // fails at query time because it cannot recreate them.
+    fs.rmSync(`${dbPath}-wal`, { force: true });
+    fs.rmSync(`${dbPath}-shm`, { force: true });
+    assertHistoryRows(dbPath);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('isReadonlyWalRetryError only accepts readonly errors from WAL-mode databases', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-history-retry-'));
+  const walDbPath = path.join(dir, 'wal.sqlite');
+  const rollbackDbPath = path.join(dir, 'rollback.sqlite');
+  try {
+    createHistoryDb(walDbPath, { wal: true });
+    createHistoryDb(rollbackDbPath);
+
+    assert.equal(
+      isReadonlyWalRetryError(
+        Object.assign(new Error('attempt to write a readonly database'), {
+          code: 'SQLITE_READONLY',
+        }),
+        walDbPath,
+      ),
+      true,
+    );
+    assert.equal(
+      isReadonlyWalRetryError(
+        Object.assign(new Error('unable to open database file'), {
+          code: 'SQLITE_CANTOPEN',
+        }),
+        walDbPath,
+      ),
+      true,
+    );
+    assert.equal(
+      isReadonlyWalRetryError(new Error('no such table: imm_sessions'), walDbPath),
+      false,
+    );
+    assert.equal(
+      isReadonlyWalRetryError(
+        Object.assign(new Error('attempt to write a readonly database'), {
+          code: 'SQLITE_READONLY',
+        }),
+        rollbackDbPath,
+      ),
+      false,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

launcher/history.ts

@@ -0,0 +1,4 @@
+export * from './history-art.js';
+export * from './history-db.js';
+export * from './history-navigation.js';
+export type { HistorySeriesEntry, HistoryVideoRow, SeasonDirEntry } from './history-types.js';

launcher/jellyfin.test.ts

@@ -29,6 +29,7 @@ function createArgs(): Args {
     texthookerOnly: false,
     texthookerOpenBrowser: false,
     useRofi: false,
+    history: false,
     logLevel: 'info',
     logRotation: 7,
     passwordStore: '',

launcher/log.test.ts

@@ -2,9 +2,10 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import { getDefaultLauncherLogFile, getDefaultMpvLogFile } from './types.js';
+import { localDateKey } from '../src/shared/log-files.js';
 
 test('getDefaultMpvLogFile uses APPDATA on windows', () => {
-  const today = new Date().toISOString().slice(0, 10);
+  const today = localDateKey(new Date());
   const resolved = getDefaultMpvLogFile({
     platform: 'win32',
     homeDir: 'C:\\Users\\tester',
@@ -20,7 +21,7 @@ test('getDefaultMpvLogFile uses APPDATA on windows', () => {
 });
 
 test('getDefaultLauncherLogFile uses launcher prefix', () => {
-  const today = new Date().toISOString().slice(0, 10);
+  const today = localDateKey(new Date());
   const resolved = getDefaultLauncherLogFile({
     platform: 'linux',
     homeDir: '/home/tester',

launcher/main.test.ts

@@ -65,11 +65,36 @@ function makeTestEnv(homeDir: string, xdgConfigHome: string): NodeJS.ProcessEnv
     APPDATA: xdgConfigHome,
     LOCALAPPDATA: path.join(homeDir, 'AppData', 'Local'),
     XDG_CONFIG_HOME: xdgConfigHome,
+    // Pin the data dir under the temp home so the Linux runtime-plugin preflight
+    // resolves managed asset paths deterministically (not the CI runner's).
+    XDG_DATA_HOME: path.join(homeDir, '.local', 'share'),
     PATH: pathValue,
     Path: pathValue,
   };
 }
 
+// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which —
+// when the runtime plugin/theme are missing — spawns the app with
+// `--ensure-linux-runtime-plugin-assets` and polls up to 30s
+// (RESPONSE_TIMEOUT_MS) for an install response. A fake app that just exits
+// never writes that response, so the launcher hangs and the test times out on
+// Linux CI (the preflight is a no-op on macOS/Windows). This shell prelude makes
+// the fake app install the managed plugin/theme and write the response, matching
+// launcher/smoke.e2e.test.ts. Prepend it to each fake app that reaches playback.
+const RUNTIME_PLUGIN_PREFLIGHT_SH = `if [ "$1" = "--ensure-linux-runtime-plugin-assets" ]; then
+  data="\${XDG_DATA_HOME:-$HOME/.local/share}/SubMiner"
+  mkdir -p "$data/plugin/subminer" "$data/themes"
+  printf -- '-- test plugin\\n' > "$data/plugin/subminer/main.lua"
+  printf 'test=true\\n' > "$data/plugin/subminer.conf"
+  printf '/* test theme */\\n' > "$data/themes/subminer.rasi"
+  if [ "$2" = "--ensure-linux-runtime-plugin-assets-response-path" ] && [ -n "$3" ]; then
+    mkdir -p "$(dirname "$3")"
+    printf '{"ok":true,"status":"installed","path":"%s"}' "$data/plugin/subminer/main.lua" > "$3"
+  fi
+  exit 0
+fi
+`;
+
 test('config path uses XDG_CONFIG_HOME override', () => {
   withTempDir((root) => {
     const xdgConfigHome = path.join(root, 'xdg');
@@ -237,7 +262,7 @@ test('doctor refresh-known-words forwards app refresh command without requiring
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -264,7 +289,7 @@ test('launcher settings option forwards app settings window command', () => {
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -288,7 +313,7 @@ test('launcher settings command forwards app settings window command', () => {
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -369,7 +394,7 @@ test('launcher forwards --args to mpv as parsed tokens', { timeout: 15000 }, ()
         },
       }),
     );
-    fs.writeFileSync(appPath, '#!/bin/sh\nexit 0\n');
+    fs.writeFileSync(appPath, `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}exit 0\n`);
     fs.chmodSync(appPath, 0o755);
 
     fs.writeFileSync(
@@ -460,7 +485,7 @@ test('launcher forwards non-info log level into mpv logging args', { timeout: 15
         },
       }),
     );
-    fs.writeFileSync(appPath, '#!/bin/sh\nexit 0\n');
+    fs.writeFileSync(appPath, `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}exit 0\n`);
     fs.chmodSync(appPath, 0o755);
 
     fs.writeFileSync(
@@ -539,7 +564,7 @@ test('launcher routes youtube urls through regular playback startup', { timeout:
     );
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -566,17 +591,22 @@ ${bunBinary} -e "const net=require('node:net'); const fs=require('node:fs'); con
     fs.chmodSync(path.join(binDir, 'yt-dlp'), 0o755);
     fs.chmodSync(path.join(binDir, 'ffmpeg'), 0o755);
 
+    // Note: no SUBMINER_TEST_CAPTURE here. When set, the launcher intercepts
+    // *every* app command — including the Linux runtime-plugin preflight's
+    // `--ensure-linux-runtime-plugin-assets` install — and returns without
+    // running the fake app, so the preflight would poll 30s for a response that
+    // never arrives and time out. This test asserts on the mpv args, not on
+    // captured app args, so capture isn't needed.
     const env = {
       ...makeTestEnv(homeDir, xdgConfigHome),
       PATH: `${binDir}${path.delimiter}${process.env.Path || process.env.PATH || ''}`,
       Path: `${binDir}${path.delimiter}${process.env.Path || process.env.PATH || ''}`,
-      DISPLAY: ':99',
-      XDG_SESSION_TYPE: 'x11',
       SUBMINER_APPIMAGE_PATH: appPath,
       SUBMINER_TEST_MPV_ARGS: mpvArgsPath,
-      SUBMINER_TEST_CAPTURE: path.join(root, 'captured-args.txt'),
     };
-    const result = runLauncher(['https://www.youtube.com/watch?v=abc123'], env);
+    // Pass an explicit backend so overlay startup doesn't probe for a display
+    // (headless CI has none), matching launcher/smoke.e2e.test.ts.
+    const result = runLauncher(['--backend', 'x11', 'https://www.youtube.com/watch?v=abc123'], env);
 
     assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
     const forwardedArgs = fs
@@ -597,7 +627,7 @@ test('dictionary command forwards --dictionary and --dictionary-target to app co
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -626,7 +656,7 @@ test('dictionary command forwards manual AniList selection modes to app command
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -763,7 +793,7 @@ test('jellyfin discovery routes to app --background and remote announce with log
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -790,7 +820,7 @@ test('jellyfin discovery via jf alias forwards remote announce for cast visibili
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -817,7 +847,7 @@ test('jellyfin login routes credentials to app command', () => {
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 
@@ -856,7 +886,7 @@ test('jellyfin setup forwards password-store to app command', () => {
     const capturePath = path.join(root, 'captured-args.txt');
     fs.writeFileSync(
       appPath,
-      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+      `#!/bin/sh\n${RUNTIME_PLUGIN_PREFLIGHT_SH}if [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n`,
     );
     fs.chmodSync(appPath, 0o755);
 

launcher/main.ts

@@ -21,6 +21,7 @@ import { runDictionaryCommand } from './commands/dictionary-command.js';
 import { runLogsCommand } from './commands/logs-command.js';
 import { runStatsCommand } from './commands/stats-command.js';
 import { runJellyfinCommand } from './commands/jellyfin-command.js';
+import { runHistoryCommand } from './commands/history-command.js';
 import { runPlaybackCommand } from './commands/playback-command.js';
 import { runUpdateCommand } from './commands/update-command.js';
 
@@ -142,6 +143,16 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (appContext.args.history) {
+    const selected = await runHistoryCommand(appContext);
+    if (!selected) {
+      log('info', args.logLevel, 'No watch history selection made, exiting');
+      return;
+    }
+    appContext.args.target = selected;
+    appContext.args.targetKind = 'file';
+  }
+
   await runPlaybackCommand(appContext);
 }
 

launcher/mpv.test.ts

@@ -570,6 +570,7 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     texthookerOnly: false,
     texthookerOpenBrowser: false,
     useRofi: false,
+    history: false,
     logLevel: 'error',
     logRotation: 7,
     passwordStore: '',

launcher/parse-args.test.ts

@@ -42,6 +42,19 @@ test('parseArgs maps root settings window option', () => {
   assert.equal(parsed.settings, true);
 });
 
+test('parseArgs maps root watch history flags', () => {
+  const shortParsed = parseArgs(['-H'], 'subminer', {});
+  const longParsed = parseArgs(['--history'], 'subminer', {});
+  const rofiParsed = parseArgs(['-R', '-H'], 'subminer', {});
+  const defaultParsed = parseArgs([], 'subminer', {});
+
+  assert.equal(shortParsed.history, true);
+  assert.equal(longParsed.history, true);
+  assert.equal(rofiParsed.history, true);
+  assert.equal(rofiParsed.useRofi, true);
+  assert.equal(defaultParsed.history, false);
+});
+
 test('parseArgs maps root update flags without conflicting with jellyfin username', () => {
   const shortParsed = parseArgs(['-u'], 'subminer', {});
   const longParsed = parseArgs(['--update'], 'subminer', {});

launcher/types.ts

@@ -112,6 +112,7 @@ export interface Args {
   texthookerOnly: boolean;
   texthookerOpenBrowser: boolean;
   useRofi: boolean;
+  history: boolean;
   logLevel: LogLevel;
   logRotation: LogRotation;
   passwordStore: string;

main-entry.js

@@ -1,233 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_os_1 = __importDefault(require("node:os"));
-const node_child_process_1 = require("node:child_process");
-const electron_1 = require("electron");
-const help_1 = require("./cli/help");
-const main_entry_runtime_1 = require("./main-entry-runtime");
-const early_single_instance_1 = require("./main/early-single-instance");
-const main_entry_launch_config_1 = require("./main-entry-launch-config");
-const app_control_client_1 = require("./shared/app-control-client");
-const first_run_setup_plugin_1 = require("./main/runtime/first-run-setup-plugin");
-const windows_mpv_launch_1 = require("./main/runtime/windows-mpv-launch");
-const stats_daemon_entry_1 = require("./stats-daemon-entry");
-const fatal_error_1 = require("./main/fatal-error");
-const mpv_logging_args_1 = require("./shared/mpv-logging-args");
-const log_files_1 = require("./shared/log-files");
-const DEFAULT_TEXTHOOKER_PORT = 5174;
-function appendWindowsMpvLaunchLog(message, logRotation) {
-    if (!(0, log_files_1.isLogFileEnabled)('app')) {
-        return;
-    }
-    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
-    (0, log_files_1.appendLogLine)(process.env.SUBMINER_APP_LOG?.trim() || (0, log_files_1.resolveDefaultLogFilePath)('app'), `[subminer] - ${timestamp} - INFO - [main:windows-mpv-launch] ${message}`, { rotation: logRotation });
-}
-function applySanitizedEnv(sanitizedEnv) {
-    if (sanitizedEnv.NODE_NO_WARNINGS) {
-        process.env.NODE_NO_WARNINGS = sanitizedEnv.NODE_NO_WARNINGS;
-    }
-    if (sanitizedEnv.VK_INSTANCE_LAYERS) {
-        process.env.VK_INSTANCE_LAYERS = sanitizedEnv.VK_INSTANCE_LAYERS;
-    }
-    else {
-        delete process.env.VK_INSTANCE_LAYERS;
-    }
-}
-function resolveBundledWindowsMpvPluginEntrypoint() {
-    return ((0, first_run_setup_plugin_1.resolvePackagedRuntimePluginPath)({
-        dirname: __dirname,
-        appPath: electron_1.app.getAppPath(),
-        resourcesPath: process.resourcesPath,
-    }) ?? undefined);
-}
-function buildInstalledWindowsMpvPluginMessage(pathValue, version) {
-    return [
-        'SubMiner detected an installed mpv plugin at:',
-        pathValue,
-        '',
-        "This mpv session will use the installed plugin. Remove it to use SubMiner's bundled runtime plugin automatically.",
-        `Detected plugin version: ${version ?? 'unknown or legacy'}`,
-    ].join('\n');
-}
-async function promptForWindowsLegacyMpvPluginRemoval(mpvPath, detection) {
-    const response = await electron_1.dialog.showMessageBox({
-        type: 'warning',
-        title: 'SubMiner mpv plugin detected',
-        message: buildInstalledWindowsMpvPluginMessage(detection.path ?? 'unknown path', detection.version),
-        detail: 'Remove the legacy SubMiner mpv plugin files from mpv before launching this video? This moves the files to the OS trash. SubMiner-managed playback will then use the bundled runtime plugin.',
-        buttons: ['Remove legacy plugin', 'Continue with installed plugin', 'Cancel'],
-        defaultId: 0,
-        cancelId: 2,
-    });
-    if (response.response === 2) {
-        return 'cancel';
-    }
-    if (response.response === 1) {
-        return 'continue';
-    }
-    const candidates = (0, first_run_setup_plugin_1.detectInstalledFirstRunPluginCandidates)({
-        platform: 'win32',
-        homeDir: node_os_1.default.homedir(),
-        appDataDir: electron_1.app.getPath('appData'),
-        mpvExecutablePath: mpvPath,
-    });
-    const result = await (0, first_run_setup_plugin_1.removeLegacyMpvPluginCandidates)({
-        candidates,
-        trashItem: (candidatePath) => electron_1.shell.trashItem(candidatePath),
-    });
-    if (result.ok) {
-        await electron_1.dialog.showMessageBox({
-            type: 'info',
-            title: 'Legacy mpv plugin removed',
-            message: 'Legacy mpv plugin removed. SubMiner-managed playback will use the bundled runtime plugin.',
-        });
-        return 'removed';
-    }
-    await electron_1.dialog.showMessageBox({
-        type: 'error',
-        title: 'Could not remove legacy mpv plugin',
-        message: 'Some legacy SubMiner mpv plugin files could not be moved to the trash.',
-        detail: result.failedPaths.map((failure) => `${failure.path}: ${failure.message}`).join('\n'),
-    });
-    return 'cancel';
-}
-function createWindowsRuntimePluginPolicy() {
-    return {
-        detectInstalledMpvPlugin: (mpvPath) => (0, first_run_setup_plugin_1.detectInstalledMpvPlugin)({
-            platform: 'win32',
-            homeDir: node_os_1.default.homedir(),
-            appDataDir: electron_1.app.getPath('appData'),
-            mpvExecutablePath: mpvPath,
-        }),
-        notifyInstalledPluginDetected: (detection) => {
-            if (!detection.installed || !detection.path)
-                return;
-            electron_1.dialog.showMessageBoxSync({
-                type: 'warning',
-                title: 'SubMiner mpv plugin detected',
-                message: buildInstalledWindowsMpvPluginMessage(detection.path, detection.version),
-            });
-        },
-        resolveInstalledPluginBeforeLaunch: (detection, mpvPath) => promptForWindowsLegacyMpvPluginRemoval(mpvPath, detection),
-    };
-}
-process.argv = (0, main_entry_runtime_1.normalizeStartupArgv)(process.argv, process.env);
-(0, main_entry_runtime_1.applyEarlyLinuxCommandLineSwitches)(electron_1.app.commandLine, process.argv);
-applySanitizedEnv((0, main_entry_runtime_1.sanitizeStartupEnv)(process.env));
-const userDataPath = (0, main_entry_runtime_1.configureEarlyAppPaths)(electron_1.app);
-const reportFatalError = (0, fatal_error_1.createFatalErrorReporter)({
-    showErrorBox: (title, details) => electron_1.dialog.showErrorBox(title, details),
-    consoleError: (message, error) => console.error(message, error),
-});
-(0, fatal_error_1.registerFatalErrorHandlers)({
-    reportFatalError,
-    exit: (code) => electron_1.app.exit(code),
-});
-function startMainProcess() {
-    const gotSingleInstanceLock = (0, early_single_instance_1.requestSingleInstanceLockEarly)(electron_1.app);
-    if (!gotSingleInstanceLock) {
-        electron_1.app.exit(0);
-        return;
-    }
-    try {
-        require('./main.js');
-    }
-    catch (error) {
-        reportFatalError(error, {
-            title: 'SubMiner startup failed',
-            context: 'SubMiner failed while loading the main process.',
-        });
-        electron_1.app.exit(1);
-    }
-}
-async function forwardStartupArgvViaAppControlIfAvailable() {
-    if (!(0, main_entry_runtime_1.shouldForwardStartupArgvViaAppControl)(process.argv, process.env)) {
-        return false;
-    }
-    const result = await (0, app_control_client_1.sendAppControlCommand)(process.argv, {
-        configDir: userDataPath,
-        timeoutMs: 500,
-    });
-    if (result.ok) {
-        electron_1.app.exit(0);
-        return true;
-    }
-    if (!result.unavailable) {
-        console.error(`SubMiner app-control handoff failed: ${result.error ?? 'unknown error'}`);
-        electron_1.app.exit(1);
-        return true;
-    }
-    return false;
-}
-async function runEntryProcess() {
-    if ((0, main_entry_runtime_1.shouldHandleHelpOnlyAtEntry)(process.argv, process.env)) {
-        const sanitizedEnv = (0, main_entry_runtime_1.sanitizeHelpEnv)(process.env);
-        process.env.NODE_NO_WARNINGS = sanitizedEnv.NODE_NO_WARNINGS;
-        if (!sanitizedEnv.VK_INSTANCE_LAYERS) {
-            delete process.env.VK_INSTANCE_LAYERS;
-        }
-        (0, help_1.printHelp)(DEFAULT_TEXTHOOKER_PORT);
-        process.exit(0);
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldHandleLaunchMpvAtEntry)(process.argv, process.env)) {
-        const sanitizedEnv = (0, main_entry_runtime_1.sanitizeLaunchMpvEnv)(process.env);
-        applySanitizedEnv(sanitizedEnv);
-        await electron_1.app.whenReady();
-        const configuredMpvLaunch = (0, main_entry_launch_config_1.readConfiguredWindowsMpvLaunch)(userDataPath);
-        const extraArgs = (0, main_entry_runtime_1.normalizeLaunchMpvExtraArgs)(process.argv);
-        (0, log_files_1.applyLogFileTogglesToEnv)(configuredMpvLaunch.logFiles);
-        const mpvLogPath = (0, log_files_1.isLogFileEnabled)('mpv')
-            ? process.env.SUBMINER_MPV_LOG?.trim() || (0, log_files_1.resolveDefaultLogFilePath)('mpv')
-            : '';
-        if (mpvLogPath) {
-            (0, log_files_1.pruneLogDirectoryForPath)(mpvLogPath, configuredMpvLaunch.logRotation);
-        }
-        const result = await (0, windows_mpv_launch_1.launchWindowsMpv)((0, main_entry_runtime_1.normalizeLaunchMpvTargets)(process.argv), (0, windows_mpv_launch_1.createWindowsMpvLaunchDeps)({
-            getEnv: (name) => process.env[name],
-            isAppControlServerAvailable: () => (0, app_control_client_1.isAppControlServerAvailable)({
-                configDir: userDataPath,
-                timeoutMs: 350,
-            }),
-            sendAppControlCommand: (argv) => (0, app_control_client_1.sendAppControlCommand)(argv, {
-                configDir: userDataPath,
-                timeoutMs: 1000,
-            }),
-            showError: (title, content) => {
-                electron_1.dialog.showErrorBox(title, content);
-            },
-            logInfo: (message) => appendWindowsMpvLaunchLog(message, configuredMpvLaunch.logRotation),
-        }), [...extraArgs, ...(0, mpv_logging_args_1.buildMpvLoggingArgs)(configuredMpvLaunch.logLevel, mpvLogPath, extraArgs)], process.execPath, resolveBundledWindowsMpvPluginEntrypoint(), configuredMpvLaunch.executablePath, configuredMpvLaunch.launchMode, createWindowsRuntimePluginPolicy(), configuredMpvLaunch.pluginRuntimeConfig);
-        electron_1.app.exit(result.ok ? 0 : 1);
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldHandleStatsDaemonCommandAtEntry)(process.argv, process.env)) {
-        await electron_1.app.whenReady();
-        const exitCode = await (0, stats_daemon_entry_1.runStatsDaemonControlFromProcess)(electron_1.app.getPath('userData'));
-        electron_1.app.exit(exitCode);
-        return;
-    }
-    if (await forwardStartupArgvViaAppControlIfAvailable()) {
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldDetachBackgroundLaunch)(process.argv, process.env)) {
-        const childArgs = (0, main_entry_runtime_1.hasTransportedStartupArgs)(process.env) ? [] : process.argv.slice(1);
-        const child = (0, node_child_process_1.spawn)(process.execPath, childArgs, {
-            detached: true,
-            stdio: 'ignore',
-            env: (0, main_entry_runtime_1.sanitizeBackgroundEnv)(process.env),
-        });
-        child.unref();
-        process.exit(0);
-        return;
-    }
-    startMainProcess();
-}
-void runEntryProcess().catch((error) => {
-    console.error('SubMiner app-control handoff failed:', error);
-    startMainProcess();
-});
-//# sourceMappingURL=main-entry.js.map

plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md

@@ -105,6 +105,8 @@ bash plugins/subminer-workflow/skills/subminer-change-verification/scripts/verif
   - For `docs-site/`, `docs/`, and doc-only edits.
 - `config`
   - For `src/config/` and config-template-sensitive edits.
+- `stats`
+  - For `stats/` dashboard UI edits.
 - `core`
   - For general source changes where `typecheck` + `test:fast` is the best cheap signal.
 - `launcher-plugin`

plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh

@@ -108,6 +108,14 @@ for path in "${PATHS[@]}"; do
       ;;
   esac
 
+  case "$path" in
+    stats/*)
+      add_lane "stats"
+      add_reason "$path -> stats"
+      specialized=1
+      ;;
+  esac
+
   case "$path" in
     launcher/*|plugin/subminer/*|plugin/subminer.conf|scripts/test-plugin-*|scripts/get-mpv-window-*|scripts/configure-plugin-binary-path.mjs)
       add_lane "launcher-plugin"

plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh

@@ -255,8 +255,18 @@ write_summary_files() {
   local lane_lines
   lane_lines=$(printf '%s\n' "${SELECTED_LANES[@]}")
   printf '%s\n' "$lane_lines" >"$ARTIFACT_DIR/lanes.txt"
-  printf '%s\n' "${BLOCKERS[@]}" >"$ARTIFACT_DIR/blockers.txt"
-  printf '%s\n' "${PATH_ARGS[@]}" >"$ARTIFACT_DIR/requested-paths.txt"
+  # bash 3.2 raises "unbound variable" under set -u when expanding an empty
+  # array, so guard on length (matching the idiom used elsewhere here).
+  if [[ ${#BLOCKERS[@]} -gt 0 ]]; then
+    printf '%s\n' "${BLOCKERS[@]}" >"$ARTIFACT_DIR/blockers.txt"
+  else
+    : >"$ARTIFACT_DIR/blockers.txt"
+  fi
+  if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
+    printf '%s\n' "${PATH_ARGS[@]}" >"$ARTIFACT_DIR/requested-paths.txt"
+  else
+    : >"$ARTIFACT_DIR/requested-paths.txt"
+  fi
 
   ARTIFACT_DIR_ENV="$ARTIFACT_DIR" \
   SESSION_ID_ENV="$SESSION_ID" \
@@ -482,6 +492,9 @@ for lane in "${SELECTED_LANES[@]}"; do
     config)
       run_step "$lane" "config" "bun run test:config" || break
       ;;
+    stats)
+      run_step "$lane" "stats" "bun run test:stats" || break
+      ;;
     core)
       run_step "$lane" "typecheck" "bun run typecheck" || break
       run_step "$lane" "fast-tests" "bun run test:fast" || break

release/prerelease-notes.md

@@ -1,60 +1,55 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
-<!-- prerelease-base-version: 0.17.0 -->
+<!-- prerelease-base-version: 0.18.0 -->
 
 ## Highlights
+### Added
+- **Watch History Browser**
+  - New `subminer -H` / `--history` command to browse your local watch history, replay the last episode, jump to the next one, or pick an episode via fzf/rofi.
+  - The rofi picker now shows AniList cover art for each show, making it easier to spot the right title at a glance.
+
 ### Changed
-
-- **Subtitle Delay Shortcuts:** Overlay subtitle delay controls now match mpv's native defaults.
-  - `z`, `Z`, and `x` adjust `sub-delay`; `Ctrl+Shift+Left/Right` run native `sub-step` and show the current delay on the OSD.
-  - The previous SubMiner-only adjacent-cue delay action has been removed.
-
-- **Update Notifications:** New installs now default to overlay-only update notifications instead of overlay plus system notifications.
+- **New App Icon**
+  - SubMiner now ships pixel-art submarine artwork, contributed by an anonymous community member.
+  - Applied across the app icon, tray icon, notifications, README, docs site, and stats page.
 
 ### Fixed
-
-- **Anki Card Enrichment:** Fixed two issues where card fields were not populated correctly after mining.
-  - Highlight Word now bolds the mined word in Kiku sentence and sentence-furigana fields even when the source Yomitan sentence has no existing bold markup.
-  - Lapis and Kiku word cards enriched through SubMiner now include the word-and-sentence marker, restoring sentence context on the card front.
-
-- **Windows Overlay:** Fixed shaky hover and click behavior on the subtitle bar when a video attaches to an already-running SubMiner instance.
-
-- **Windows Anki & Media:** Fixed two issues affecting Windows users running SubMiner in background-launch mode.
-  - Known-word cache refreshes no longer fail when no deck is configured.
-  - Audio and image clipping now works correctly by recreating missing FFmpeg temp directories before processing.
-
-- **Windows Character Dictionary:** The character dictionary auto-sync now correctly falls back to mpv's current video path on Windows when app media state is not yet ready.
-
-- **Linux Support Assets:** Linux updates now create and refresh both managed support assets: the launcher runtime plugin copy and the rofi theme.
-  - First playback on a fresh Linux install auto-installs those bundled assets before mpv starts if either one is missing.
-  - Asset refreshes leave unrelated SubMiner data directories untouched and stage plugin copies before replacing the live runtime plugin.
-
-- **Linux Visible Overlay Startup:** Auto-paused visible overlay startup stays fully interactive during the first measurement gap.
-  - Startup subtitle cache misses paint raw text before tokenization finishes, and temporarily empty mpv subtitle reads refresh parsed cues before warm readiness resumes playback.
-
-- **Playlist Transitions:** The visible overlay stays active while mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
-
-- **macOS Yomitan Popup Focus:** Yomitan popup focus is restored after card mining or popup reload.
-  - Clicking transparent overlay space now closes the popup and returns passthrough to mpv without a hide/reappear cycle.
-
-- **Stats AniList Search:** Manual AniList linking from the stats page now strips generated `Season N` suffixes before searching, so the base anime title is used.
-
-- **Desktop Notifications:** System notifications now show the SubMiner app icon when no custom notification image is provided.
-
-- **Release Notes:** GitHub release `What's Changed` and `New Contributors` attribution sections are preserved when CI regenerates release notes from committed changelog output.
-
-### Docs
-
-- **Linux Update Flow:** Documented that Linux update flows manage the launcher runtime plugin copy and rofi theme from `subminer-assets.tar.gz`, and that normal playback auto-installs those managed support assets if either one is missing.
+- **Character Name Highlighting in Subtitles**
+  - Fixed unspaced Japanese names (e.g. 東紫乃, 渡辺真奈美) being split at the wrong point, which left surnames like 東 and 渡辺 without their character portrait or hover lookup.
+  - Fixed names getting cut off or losing their highlight when caught by the subtitle scanner's punctuation handling or by conflicting grammar tagging.
+  - No action needed — existing data upgrades automatically the next time a matching name is seen.
+- **Known-Word Highlighting**
+  - Words are no longer marked "known" (green) just because they share spelling with a known Anki card that actually teaches a different reading (e.g. 床 read as とこ no longer falsely matches a known 床/ゆか card).
+- **Unparsed Subtitle Text**
+  - Subtitle text the dictionary can't recognize (like a truncated verb form) is now still hoverable for lookup and correctly counted toward a sentence's difficulty, instead of showing as dead, non-interactive text.
+- **Kiku Manual Field Grouping**
+  - Fixed the field-grouping dialog getting stuck invisible behind fullscreen video on Hyprland/Wayland, and failing silently on repeated attempts after the first use.
+  - Fixed a duplicate "Field grouping cancelled" notification appearing when grouping was cancelled via the trigger shortcut.
+- **Secondary Subtitles**
+  - Karaoke-style secondary subtitles (common in opening/ending songs) no longer spam dozens of lines down the screen; repeated lines are now collapsed and the subtitle area is capped to a strip at the top.
+- **Card Audio Normalization**
+  - Audio extracted for Anki cards is now volume-normalized by default for more consistent playback loudness.
+  - If you prefer the original source volume, disable it via the new `ankiConnect.media.normalizeAudio` setting.
+- **YouTube Extraction**
+  - Fixed direct YouTube stream extraction occasionally corrupting the stream URL and causing failed audio/video capture.
+- **Background Stats Server**
+  - Launching SubMiner in the background now correctly auto-starts the stats server when enabled, and won't start a duplicate if one's already running.
+- **Stats Trend Charts**
+  - All trend chart titles now show by default, with the ability to hide specific titles (remembered across sessions) and cap how many top titles a chart displays.
 
 ## What's Changed
 
-- Replace subtitle delay actions with native mpv keybindings by @ksyasuda in #120
-- fix(stats): strip Season N suffix from AniList title searches by @ksyasuda in #121
-- fix(overlay): preserve visible state across playlist item transitions by @ksyasuda in #124
-- fix(overlay): restore macOS Yomitan popup focus without breaking click-away by @ksyasuda in #125
-- fix(linux): auto-install managed plugin copy; include in asset updates by @ksyasuda in #127
-- Fix Windows Anki startup and overlay regressions by @ksyasuda in #128
+- fix(youtube): parse mpv EDL stream URLs with byte-length guards by @ksyasuda in #134
+- Normalize generated Anki audio by default by @ksyasuda in #135
+- feat(launcher): add -H/--history command to browse local watch history by @ksyasuda in #136
+- fix(overlay): prevent field grouping modal from freezing overlay on Hyprland by @ksyasuda in #138
+- fix(overlay): collapse karaoke syllable spam in secondary subtitles by @ksyasuda in #139
+- feat(stats): Trends dashboard overhaul — title visibility, ranking modes, calendar-accurate windows, tooltips by @ksyasuda in #140
+- feat(branding): replace app icon with contributed pixel-art set by @ksyasuda in #141
+- feat(anki): reading-aware known-word matching (cache v3) by @ksyasuda in #142
+- fix(stats): start stats server on background app launch by @ksyasuda in #144
+- fix(tokenizer): keep unparsed Yomitan tokens hoverable by @ksyasuda in #145
+- fix(overlay): resolve unspaced Japanese name splits and scan recovery by @ksyasuda in #146
 
 ## Installation
 

release/release-notes.md

@@ -1,68 +0,0 @@
-## Highlights
-### Changed
-
-- **Subtitle Delay Keybindings:** Overlay subtitle delay controls now match mpv's native bindings.
-  - `z`, `Z`, and `x` adjust subtitle delay; `Ctrl+Shift+Left/Right` step to the adjacent subtitle and show the current delay on the OSD.
-  - Removes the old SubMiner-specific adjacent-cue delay action in favor of mpv's built-in `sub-step`.
-
-- **Update Notifications:** New installs now default to overlay-only update notifications instead of also sending a system notification.
-
-### Fixed
-
-- **Anki — Highlight Word:** The mined word is now correctly bolded in Kiku sentence and sentence-furigana fields even when the source Yomitan sentence did not already contain bold markup.
-
-- **Anki — Lapis/Kiku Word Cards:** Word cards enriched through SubMiner now correctly include the word-and-sentence marker, restoring sentence context on the card front.
-
-- **Anki — Windows:** Fixed two issues that surfaced after background app launches on Windows.
-  - Audio clip and image generation now works correctly by recreating missing FFmpeg temp directories before export.
-  - Known-word cache refreshes no longer fail when no deck is configured.
-
-- **Desktop Notifications:** Restored the SubMiner app icon on system notifications that do not supply their own image.
-
-- **Dictionary — Windows:** The character dictionary auto-sync on `SubMiner mpv` shortcut launches can now fall back to mpv's current video path when app media state is not yet ready.
-
-- **Overlay — macOS Yomitan Popup:** Fixed focus and dismiss behavior for the Yomitan popup on macOS.
-  - Popup focus is correctly restored after mining a card or reloading the popup.
-  - Clicking on transparent overlay space now properly closes the popup and passes the click through to mpv, with no hide/reappear cycle.
-
-- **Overlay — Linux Startup:** Fixed several edge cases that could leave the overlay unresponsive or drop subtitles at startup when auto-pause was active.
-  - The overlay stays interactive during the initial render measurement gap.
-  - Subtitles paint as plain text immediately on cache misses, before tokenization finishes.
-  - Temporarily empty subtitle state is now re-parsed correctly before warm readiness resumes playback.
-
-- **Overlay — Playlist Advance:** The visible overlay now stays interactive when mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
-
-- **Overlay — Windows:** Fixed shaky subtitle-bar hover and click behavior when a video connects to an already-running background SubMiner instance.
-
-- **Stats — AniList Search:** Manual AniList linking from the stats anime page now searches only the anime title, dropping any generated "Season N" suffix that was causing failed lookups.
-
-- **Updates — Linux:** Improved Linux update reliability for managed support assets.
-  - Updates now correctly install and refresh both the launcher runtime plugin copy and the rofi theme alongside AppImage and launcher updates.
-  - Support-asset refreshes no longer touch unrelated SubMiner data directories, and plugin copies are staged safely before replacing the live runtime plugin.
-  - Fresh installs now auto-install the managed runtime plugin and rofi theme from the bundled app on first launcher playback if either asset is missing.
-
-### Docs
-
-- **Linux Updates:** Documented how Linux update flows manage the launcher runtime plugin and rofi theme, and that the first launcher playback auto-installs any missing managed support assets from the bundled app.
-
-## What's Changed
-
-- Replace subtitle delay actions with native mpv keybindings by @ksyasuda in #120
-- fix(stats): strip Season N suffix from AniList title searches by @ksyasuda in #121
-- fix(overlay): preserve visible state across playlist item transitions by @ksyasuda in #124
-- fix(overlay): restore macOS Yomitan popup focus without breaking click-away by @ksyasuda in #125
-- fix(linux): auto-install managed plugin copy; include in asset updates by @ksyasuda in #127
-- Fix Windows Anki startup and overlay regressions by @ksyasuda in #128
-
-## Installation
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
-- Linux: `SubMiner.AppImage`
-- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
-- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
-- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
-
-Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.

scripts/build-changelog.ts

@@ -108,15 +108,11 @@ function renderPrereleaseBaseVersionMarker(version: string): string {
 }
 
 function extractPrereleaseBaseVersionMarker(notes: string): string | null {
-  return (
-    /<!--\s*prerelease-base-version:\s*(\d+\.\d+\.\d+)\s*-->/u.exec(notes)?.[1] ?? null
-  );
+  return /<!--\s*prerelease-base-version:\s*(\d+\.\d+\.\d+)\s*-->/u.exec(notes)?.[1] ?? null;
 }
 
 function stripPrereleaseMetadata(notes: string): string {
-  return notes
-    .replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '')
-    .trim();
+  return notes.replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '').trim();
 }
 
 function resolveReusablePrereleaseNotes(notes: string, version: string): string | undefined {

scripts/run-coverage-lane.ts

@@ -1,12 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { isAbsolute, join, relative, resolve } from 'node:path';
-
-type LaneConfig = {
-  roots: string[];
-  include: string[];
-  exclude: Set<string>;
-};
+import { collectLaneFiles } from './test-lanes';
 
 type LcovRecord = {
   sourceFile: string;
@@ -18,64 +13,6 @@ type LcovRecord = {
 
 const repoRoot = resolve(__dirname, '..');
 
-const lanes: Record<string, LaneConfig> = {
-  'bun-src-full': {
-    roots: ['src'],
-    include: ['.test.ts', '.type-test.ts'],
-    exclude: new Set([
-      'src/core/services/anki-jimaku-ipc.test.ts',
-      'src/core/services/ipc.test.ts',
-      'src/core/services/overlay-manager.test.ts',
-      'src/main/config-validation.test.ts',
-      'src/main/runtime/registry.test.ts',
-      'src/main/runtime/startup-config.test.ts',
-    ]),
-  },
-  'bun-launcher-unit': {
-    roots: ['launcher'],
-    include: ['.test.ts'],
-    exclude: new Set(['launcher/smoke.e2e.test.ts']),
-  },
-};
-
-function collectFiles(
-  rootDir: string,
-  includeSuffixes: string[],
-  excludeSet: Set<string>,
-): string[] {
-  const out: string[] = [];
-  const visit = (currentDir: string) => {
-    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
-      const fullPath = resolve(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        visit(fullPath);
-        continue;
-      }
-      const relPath = relative(repoRoot, fullPath).replaceAll('\\', '/');
-      if (excludeSet.has(relPath)) continue;
-      if (includeSuffixes.some((suffix) => relPath.endsWith(suffix))) {
-        out.push(relPath);
-      }
-    }
-  };
-
-  visit(resolve(repoRoot, rootDir));
-  out.sort();
-  return out;
-}
-
-function getLaneFiles(laneName: string): string[] {
-  const lane = lanes[laneName];
-  if (!lane) {
-    throw new Error(`Unknown coverage lane: ${laneName}`);
-  }
-  const files = lane.roots.flatMap((rootDir) => collectFiles(rootDir, lane.include, lane.exclude));
-  if (files.length === 0) {
-    throw new Error(`No test files found for coverage lane: ${laneName}`);
-  }
-  return files;
-}
-
 function parseCoverageDirArg(argv: string[]): string {
   for (let index = 0; index < argv.length; index += 1) {
     if (argv[index] === '--coverage-dir') {
@@ -277,7 +214,13 @@ function runCoverageLane(): number {
   rmSync(shardRoot, { recursive: true, force: true });
   mkdirSync(shardRoot, { recursive: true });
 
-  const files = getLaneFiles(laneName);
+  let files: string[];
+  try {
+    files = collectLaneFiles(repoRoot, laneName);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+    return 1;
+  }
   const reports: string[] = [];
 
   try {

scripts/run-test-lane.mjs

@@ -1,73 +1,153 @@
-import { readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { relative, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { collectLaneFiles } from './test-lanes.ts';
+
+// Runs a test lane with per-file process isolation: one `bun test` process per
+// test file so a hanging test or leaked global in one file cannot poison the
+// rest of the lane. Use --single-process for the old all-in-one-process mode.
+//
+// Usage: bun scripts/run-test-lane.mjs <lane> [--jobs N] [--timeout-secs N] [--single-process]
 
 const repoRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
 
-const lanes = {
-  'bun-src-full': {
-    roots: ['src'],
-    include: ['.test.ts', '.type-test.ts'],
-    exclude: new Set([
-      'src/core/services/anki-jimaku-ipc.test.ts',
-      'src/core/services/ipc.test.ts',
-      'src/core/services/overlay-manager.test.ts',
-      'src/main/config-validation.test.ts',
-      'src/main/runtime/registry.test.ts',
-      'src/main/runtime/startup-config.test.ts',
-    ]),
-  },
-  'bun-launcher-unit': {
-    roots: ['launcher'],
-    include: ['.test.ts'],
-    exclude: new Set(['launcher/smoke.e2e.test.ts']),
-  },
-};
+// Cap per-file buffered output so a long or noisy test cannot grow the string
+// without bound and exhaust memory.
+const MAX_OUTPUT_BYTES = 1024 * 1024;
 
-function collectFiles(rootDir, includeSuffixes, excludeSet) {
-  const out = [];
-  const visit = (currentDir) => {
-    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
-      const fullPath = resolve(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        visit(fullPath);
-        continue;
+// Track spawned `bun test` children so we can kill them if the runner is
+// interrupted, avoiding orphaned in-flight test processes.
+const activeChildren = new Set();
+
+function terminateChildren() {
+  for (const child of activeChildren) {
+    child.kill('SIGKILL');
+  }
+  activeChildren.clear();
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    terminateChildren();
+    process.exit(130);
+  });
+}
+
+function parseArgs(argv) {
+  const options = { lane: undefined, jobs: 1, timeoutSecs: 300, singleProcess: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--jobs') {
+      options.jobs = Math.max(1, Number(argv[(index += 1)]) || 1);
+    } else if (arg === '--timeout-secs') {
+      options.timeoutSecs = Math.max(1, Number(argv[(index += 1)]) || 300);
+    } else if (arg === '--single-process') {
+      options.singleProcess = true;
+    } else if (!arg.startsWith('--') && options.lane === undefined) {
+      options.lane = arg;
+    } else {
+      process.stderr.write(`Unknown argument: ${arg}\n`);
+      process.exit(1);
+    }
+  }
+  return options;
+}
+
+function runFile(file, timeoutSecs) {
+  return new Promise((resolvePromise) => {
+    const child = spawn('bun', ['test', `./${file}`], { cwd: repoRoot });
+    activeChildren.add(child);
+    let output = '';
+    let truncated = false;
+    let timedOut = false;
+    const append = (chunk) => {
+      if (truncated) return;
+      output += chunk;
+      if (output.length > MAX_OUTPUT_BYTES) {
+        output = `${output.slice(0, MAX_OUTPUT_BYTES)}\n[output truncated at ${MAX_OUTPUT_BYTES} bytes]\n`;
+        truncated = true;
       }
-      const relPath = relative(repoRoot, fullPath).replaceAll('\\', '/');
-      if (excludeSet.has(relPath)) continue;
-      if (includeSuffixes.some((suffix) => relPath.endsWith(suffix))) {
-        out.push(relPath);
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutSecs * 1000);
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      activeChildren.delete(child);
+      resolvePromise({ file, code: timedOut ? 124 : (code ?? 1), output, timedOut });
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      activeChildren.delete(child);
+      resolvePromise({ file, code: 1, output: String(error), timedOut: false });
+    });
+  });
+}
+
+async function runIsolated(files, options) {
+  const failures = [];
+  let nextIndex = 0;
+  let completed = 0;
+
+  async function worker() {
+    while (nextIndex < files.length) {
+      const file = files[nextIndex];
+      nextIndex += 1;
+      const result = await runFile(file, options.timeoutSecs);
+      completed += 1;
+      if (result.code !== 0) {
+        failures.push(result);
+        const reason = result.timedOut ? `timed out after ${options.timeoutSecs}s` : 'failed';
+        process.stderr.write(`\n[${completed}/${files.length}] ${file} ${reason}\n`);
+        process.stderr.write(result.output);
       }
     }
-  };
+  }
 
-  visit(resolve(repoRoot, rootDir));
-  out.sort();
-  return out;
+  await Promise.all(Array.from({ length: Math.min(options.jobs, files.length) }, worker));
+
+  if (failures.length > 0) {
+    process.stderr.write(`\n${failures.length} of ${files.length} test files failed:\n`);
+    for (const failure of failures) {
+      process.stderr.write(`  ${failure.file}${failure.timedOut ? ' (timeout)' : ''}\n`);
+    }
+    return 1;
+  }
+  process.stdout.write(`All ${files.length} test files passed.\n`);
+  return 0;
 }
 
-const lane = lanes[process.argv[2]];
+function runSingleProcess(files) {
+  const result = spawnSync('bun', ['test', ...files.map((file) => `./${file}`)], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result.status ?? 1;
+}
 
-if (!lane) {
-  process.stderr.write(`Unknown test lane: ${process.argv[2] ?? '(missing)'}\n`);
+const options = parseArgs(process.argv.slice(2));
+
+if (!options.lane) {
+  process.stderr.write('Missing test lane name\n');
   process.exit(1);
 }
 
-const files = lane.roots.flatMap((rootDir) => collectFiles(rootDir, lane.include, lane.exclude));
-
-if (files.length === 0) {
-  process.stderr.write(`No test files found for lane: ${process.argv[2]}\n`);
+let files;
+try {
+  files = collectLaneFiles(repoRoot, options.lane);
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
   process.exit(1);
 }
 
-const result = spawnSync('bun', ['test', ...files.map((file) => `./${file}`)], {
-  cwd: repoRoot,
-  stdio: 'inherit',
-});
-
-if (result.error) {
-  throw result.error;
+if (options.singleProcess) {
+  process.exit(runSingleProcess(files));
 }
 
-process.exit(result.status ?? 1);
+process.exit(await runIsolated(files, options));

scripts/test-lanes.ts

@@ -0,0 +1,97 @@
+import { readdirSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
+export type TestLane = {
+  roots: string[];
+  include: string[];
+  exclude?: string[];
+  extraFiles?: string[];
+};
+
+// Single source of truth for test-lane membership. Consumed by
+// scripts/run-test-lane.mjs (plain runs) and scripts/run-coverage-lane.ts
+// (per-file coverage shards). Lanes discover files by directory so new test
+// files join their lane automatically.
+export const testLanes: Record<string, TestLane> = {
+  'bun-src-full': {
+    roots: ['src'],
+    include: ['.test.ts', '.type-test.ts'],
+    // Node-compat suites; their dist builds run via test:runtime:compat.
+    exclude: [
+      'src/core/services/anki-jimaku-ipc.test.ts',
+      'src/core/services/ipc.test.ts',
+      'src/core/services/overlay-manager.test.ts',
+      'src/main/config-validation.test.ts',
+      'src/main/runtime/registry.test.ts',
+      'src/main/runtime/startup-config.test.ts',
+    ],
+  },
+  config: {
+    roots: ['src/config'],
+    include: ['.test.ts'],
+    extraFiles: ['src/generate-config-example.test.ts', 'src/verify-config-example.test.ts'],
+  },
+  launcher: {
+    roots: ['launcher'],
+    include: ['.test.ts'],
+  },
+  'bun-launcher-unit': {
+    roots: ['launcher'],
+    include: ['.test.ts'],
+    exclude: ['launcher/smoke.e2e.test.ts'],
+  },
+  scripts: {
+    roots: ['scripts'],
+    include: ['.test.ts'],
+  },
+  stats: {
+    roots: ['stats/src'],
+    include: ['.test.ts', '.test.tsx'],
+  },
+};
+
+function collectFiles(
+  repoRoot: string,
+  rootDir: string,
+  includeSuffixes: string[],
+  excludeSet: Set<string>,
+): string[] {
+  const out: string[] = [];
+  const visit = (currentDir: string): void => {
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+      const fullPath = resolve(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+        continue;
+      }
+      const relPath = relative(repoRoot, fullPath).replaceAll('\\', '/');
+      if (excludeSet.has(relPath)) continue;
+      if (includeSuffixes.some((suffix) => relPath.endsWith(suffix))) {
+        out.push(relPath);
+      }
+    }
+  };
+
+  visit(resolve(repoRoot, rootDir));
+  out.sort();
+  return out;
+}
+
+export function collectLaneFiles(repoRoot: string, laneName: string): string[] {
+  const lane = testLanes[laneName];
+  if (!lane) {
+    throw new Error(`Unknown test lane: ${laneName}`);
+  }
+  const excludeSet = new Set(lane.exclude ?? []);
+  const files = lane.roots.flatMap((rootDir) =>
+    collectFiles(repoRoot, rootDir, lane.include, excludeSet),
+  );
+  for (const extra of lane.extraFiles ?? []) {
+    if (!files.includes(extra)) files.push(extra);
+  }
+  files.sort();
+  if (files.length === 0) {
+    throw new Error(`No test files found for lane: ${laneName}`);
+  }
+  return files;
+}

src/anki-integration.test.ts

@@ -5,6 +5,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { AnkiIntegration } from './anki-integration';
 import { FieldGroupingMergeCollaborator } from './anki-integration/field-grouping-merge';
+import type { MediaInput } from './media-input';
 import { AnkiConnectConfig } from './types';
 
 type TestOverlayNotificationPayload = {
@@ -24,6 +25,13 @@ interface IntegrationTestContext {
   stateDir: string;
 }
 
+function describeMediaInputForTest(input: MediaInput): string {
+  if (typeof input === 'string') {
+    return input;
+  }
+  return `${input.path}:${input.source ?? 'raw'}`;
+}
+
 function createIntegrationTestContext(
   options: {
     highlightEnabled?: boolean;
@@ -527,6 +535,460 @@ test('AnkiIntegration marks partial update notifications as failures in OSD mode
   assert.deepEqual(osdMessages, ['x Updated card: taberu (image failed)']);
 });
 
+test('AnkiIntegration applies ready YouTube cache media to every queued note id', async () => {
+  const osdMessages: string[] = [];
+  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const storedMedia: string[] = [];
+  const mediaInputs: string[] = [];
+
+  const integration = new AnkiIntegration(
+    {
+      fields: {
+        image: 'Picture',
+      },
+      media: {
+        imageFormat: 'jpg',
+      },
+      behavior: {
+        notificationType: 'osd',
+      },
+    },
+    {} as never,
+    {} as never,
+    (text) => {
+      osdMessages.push(text);
+    },
+  );
+
+  const internals = integration as unknown as {
+    client: {
+      notesInfo: (noteIds: number[]) => Promise<unknown[]>;
+      updateNoteFields: (noteId: number, fields: Record<string, string>) => Promise<void>;
+      storeMediaFile: (filename: string, data: Buffer) => Promise<void>;
+    };
+    mediaGenerator: {
+      generateAudio: (
+        path: MediaInput,
+        startTime: number,
+        endTime: number,
+        audioPadding?: number,
+        audioStreamIndex?: number,
+      ) => Promise<Buffer>;
+      generateScreenshot: (path: MediaInput) => Promise<Buffer>;
+    };
+    queuePendingYoutubeMediaUpdate: (job: {
+      sourceUrl: string;
+      noteId: number;
+      startTime: number;
+      endTime: number;
+      label: string | number;
+      audioStreamIndex?: number;
+      audioFieldName?: string;
+      imageFieldName?: string;
+      generateAudio: boolean;
+      generateImage: boolean;
+    }) => void;
+  };
+  internals.client = {
+    notesInfo: async (noteIds) =>
+      noteIds.map((noteId) => ({
+        noteId,
+        fields: {
+          SentenceAudio: { value: '' },
+          Picture: { value: '' },
+        },
+      })),
+    updateNoteFields: async (noteId, fields) => {
+      updatedNotes.push({ noteId, fields });
+    },
+    storeMediaFile: async (filename) => {
+      storedMedia.push(filename);
+    },
+  };
+  internals.mediaGenerator = {
+    generateAudio: async (mediaPath, _startTime, _endTime, _audioPadding, audioStreamIndex) => {
+      mediaInputs.push(
+        `audio:${describeMediaInputForTest(mediaPath)}:${audioStreamIndex ?? 'auto'}`,
+      );
+      return Buffer.from('audio');
+    },
+    generateScreenshot: async (mediaPath) => {
+      mediaInputs.push(`image:${describeMediaInputForTest(mediaPath)}`);
+      return Buffer.from('image');
+    },
+  };
+  internals.queuePendingYoutubeMediaUpdate({
+    sourceUrl: 'https://www.youtube.com/watch?v=abc123',
+    noteId: 101,
+    startTime: 10,
+    endTime: 12,
+    label: 'first',
+    audioStreamIndex: 22,
+    audioFieldName: 'SentenceAudio',
+    imageFieldName: 'Picture',
+    generateAudio: true,
+    generateImage: true,
+  });
+  internals.queuePendingYoutubeMediaUpdate({
+    sourceUrl: 'https://youtu.be/abc123',
+    noteId: 202,
+    startTime: 20,
+    endTime: 22,
+    label: 'second',
+    audioStreamIndex: 23,
+    audioFieldName: 'SentenceAudio',
+    imageFieldName: 'Picture',
+    generateAudio: true,
+    generateImage: true,
+  });
+
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.deepEqual(mediaInputs, [
+    'audio:/tmp/media.mkv:youtube-cache:auto',
+    'image:/tmp/media.mkv:youtube-cache',
+    'audio:/tmp/media.mkv:youtube-cache:auto',
+    'image:/tmp/media.mkv:youtube-cache',
+  ]);
+  assert.deepEqual(
+    updatedNotes.map((update) => update.noteId),
+    [101, 202],
+  );
+  const firstUpdate = updatedNotes[0];
+  const secondUpdate = updatedNotes[1];
+  assert.ok(firstUpdate);
+  assert.ok(secondUpdate);
+  assert.match(firstUpdate.fields.SentenceAudio ?? '', /^\[sound:audio_/);
+  assert.match(firstUpdate.fields.Picture ?? '', /^<img src="image_/);
+  assert.match(secondUpdate.fields.SentenceAudio ?? '', /^\[sound:audio_/);
+  assert.match(secondUpdate.fields.Picture ?? '', /^<img src="image_/);
+  assert.equal(storedMedia.length, 4);
+  assert.equal(
+    osdMessages.some((message) =>
+      message.includes('YouTube media cache ready. Adding media to 2 queued cards.'),
+    ),
+    true,
+  );
+});
+
+test('AnkiIntegration reports partial queued YouTube media updates separately from failures', async () => {
+  const osdMessages: string[] = [];
+  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const notifications: Array<{ noteId: number; label: string | number; suffix?: string }> = [];
+
+  const integration = new AnkiIntegration(
+    {
+      fields: {
+        image: 'Picture',
+      },
+      media: {
+        imageFormat: 'jpg',
+      },
+      behavior: {
+        notificationType: 'osd',
+      },
+    },
+    {} as never,
+    {} as never,
+    (text) => {
+      osdMessages.push(text);
+    },
+  );
+
+  const internals = integration as unknown as {
+    client: {
+      notesInfo: (noteIds: number[]) => Promise<unknown[]>;
+      updateNoteFields: (noteId: number, fields: Record<string, string>) => Promise<void>;
+      storeMediaFile: () => Promise<void>;
+    };
+    mediaGenerator: {
+      generateAudio: () => Promise<Buffer>;
+      generateScreenshot: () => Promise<Buffer>;
+    };
+    queuePendingYoutubeMediaUpdate: (job: {
+      sourceUrl: string;
+      noteId: number;
+      startTime: number;
+      endTime: number;
+      label: string | number;
+      audioFieldName?: string;
+      imageFieldName?: string;
+      generateAudio: boolean;
+      generateImage: boolean;
+    }) => void;
+    showNotification: (noteId: number, label: string | number, suffix?: string) => Promise<void>;
+  };
+  internals.client = {
+    notesInfo: async (noteIds) =>
+      noteIds.map((noteId) => ({
+        noteId,
+        fields: {
+          SentenceAudio: { value: '' },
+          Picture: { value: '' },
+        },
+      })),
+    updateNoteFields: async (noteId, fields) => {
+      updatedNotes.push({ noteId, fields });
+    },
+    storeMediaFile: async () => undefined,
+  };
+  internals.mediaGenerator = {
+    generateAudio: async () => {
+      throw new Error('audio stream not found');
+    },
+    generateScreenshot: async () => Buffer.from('image'),
+  };
+  internals.showNotification = async (noteId, label, suffix) => {
+    notifications.push({ noteId, label, suffix });
+  };
+
+  internals.queuePendingYoutubeMediaUpdate({
+    sourceUrl: 'https://www.youtube.com/watch?v=partial',
+    noteId: 303,
+    startTime: 10,
+    endTime: 12,
+    label: 'partial',
+    audioFieldName: 'SentenceAudio',
+    imageFieldName: 'Picture',
+    generateAudio: true,
+    generateImage: true,
+  });
+
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/partial', '/tmp/media.mkv');
+
+  assert.equal(updatedNotes.length, 1);
+  assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
+  assert.equal(updatedNotes[0]?.fields.SentenceAudio, undefined);
+  assert.deepEqual(notifications, [{ noteId: 303, label: 'partial', suffix: 'audio failed' }]);
+  assert.equal(
+    osdMessages.some((message) =>
+      message.includes('Queued YouTube media finished with 0 updated, 1 partial, and 0 failed.'),
+    ),
+    true,
+  );
+});
+
+test('AnkiIntegration queues YouTube media updates against recovered source URLs', async () => {
+  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const storedMedia: string[] = [];
+
+  const integration = new AnkiIntegration(
+    {
+      fields: {
+        image: 'Picture',
+      },
+      media: {
+        imageFormat: 'jpg',
+      },
+    },
+    {} as never,
+    {
+      currentVideoPath: 'https://rr1---sn.example.googlevideo.com/videoplayback?expire=1777777777',
+      currentSubStart: 10,
+      currentSubEnd: 12,
+      currentTimePos: 11,
+    } as never,
+    () => undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    undefined,
+    async () => null,
+    () => true,
+    () => 'https://www.youtube.com/watch?v=abc123',
+  );
+
+  const internals = integration as unknown as {
+    client: {
+      notesInfo: (noteIds: number[]) => Promise<unknown[]>;
+      updateNoteFields: (noteId: number, fields: Record<string, string>) => Promise<void>;
+      storeMediaFile: (filename: string) => Promise<void>;
+    };
+    mediaGenerator: {
+      generateAudio: () => Promise<Buffer>;
+      generateScreenshot: () => Promise<Buffer>;
+    };
+    queuePendingYoutubeMediaUpdateForNote: (job: {
+      noteId: number;
+      noteInfo: { noteId: number; fields: Record<string, { value: string }> };
+      label: string | number;
+    }) => Promise<boolean>;
+    showNotification: () => Promise<void>;
+  };
+  internals.client = {
+    notesInfo: async (noteIds) =>
+      noteIds.map((noteId) => ({
+        noteId,
+        fields: {
+          SentenceAudio: { value: '' },
+          Picture: { value: '' },
+        },
+      })),
+    updateNoteFields: async (noteId, fields) => {
+      updatedNotes.push({ noteId, fields });
+    },
+    storeMediaFile: async (filename) => {
+      storedMedia.push(filename);
+    },
+  };
+  internals.mediaGenerator = {
+    generateAudio: async () => Buffer.from('audio'),
+    generateScreenshot: async () => Buffer.from('image'),
+  };
+  internals.showNotification = async () => undefined;
+
+  const queued = await internals.queuePendingYoutubeMediaUpdateForNote({
+    noteId: 404,
+    noteInfo: {
+      noteId: 404,
+      fields: {
+        SentenceAudio: { value: '' },
+        Picture: { value: '' },
+      },
+    },
+    label: 'resolved source',
+  });
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.equal(queued, true);
+  assert.equal(updatedNotes.length, 1);
+  assert.equal(updatedNotes[0]?.noteId, 404);
+  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio_/);
+  assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
+  assert.equal(storedMedia.length, 2);
+});
+
+test('AnkiIntegration passes audio normalization config for ready cached YouTube audio', async () => {
+  const audioCalls: Array<{
+    path: string;
+    audioStreamIndex?: number;
+    normalizeAudio?: boolean;
+  }> = [];
+
+  const integration = new AnkiIntegration(
+    {
+      media: {
+        audioPadding: 0,
+        normalizeAudio: false,
+      },
+    },
+    {} as never,
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      currentAudioStreamIndex: 0,
+      currentSubStart: 10,
+      currentSubEnd: 12,
+      currentTimePos: 11,
+    } as never,
+    () => undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    undefined,
+    async () => '/tmp/subminer-youtube-media-cache/media.mkv',
+    () => true,
+  );
+
+  const internals = integration as unknown as {
+    mediaGenerator: {
+      generateAudio: (
+        path: { path: string },
+        startTime: number,
+        endTime: number,
+        audioPadding?: number,
+        audioStreamIndex?: number,
+        normalizeAudio?: boolean,
+      ) => Promise<Buffer>;
+    };
+    generateAudio: () => Promise<Buffer | null>;
+  };
+  internals.mediaGenerator = {
+    generateAudio: async (
+      path,
+      _startTime,
+      _endTime,
+      _audioPadding,
+      audioStreamIndex,
+      normalizeAudio,
+    ) => {
+      audioCalls.push({ path: path.path, audioStreamIndex, normalizeAudio });
+      return Buffer.from('audio');
+    },
+  };
+
+  await internals.generateAudio();
+
+  assert.deepEqual(audioCalls, [
+    {
+      path: '/tmp/subminer-youtube-media-cache/media.mkv',
+      audioStreamIndex: undefined,
+      normalizeAudio: false,
+    },
+  ]);
+});
+
+test('AnkiIntegration announces ready YouTube cache when no queued notes exist', async () => {
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+
+  const integration = new AnkiIntegration(
+    {
+      behavior: {
+        notificationType: 'overlay',
+      },
+    },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload as TestOverlayNotificationPayload);
+    },
+  );
+
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.equal(overlayNotifications.length, 1);
+  assert.equal(overlayNotifications[0]?.title, 'SubMiner');
+  assert.equal(overlayNotifications[0]?.body, 'YouTube media cache ready.');
+});
+
+test('AnkiIntegration can let caller own no-queued YouTube cache ready notification', async () => {
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+
+  const integration = new AnkiIntegration(
+    {
+      behavior: {
+        notificationType: 'overlay',
+      },
+    },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload as TestOverlayNotificationPayload);
+    },
+  );
+
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv', {
+    notifyNoQueued: false,
+  });
+
+  assert.deepEqual(overlayNotifications, []);
+});
+
 test('AnkiIntegration embeds generated notification image on overlay mined-card notifications', async () => {
   const desktopNotifications: Array<{ title: string; body?: string; icon?: string }> = [];
   const overlayNotifications: TestOverlayNotificationPayload[] = [];

src/anki-integration.ts

@@ -61,7 +61,18 @@ import { NoteUpdateWorkflow } from './anki-integration/note-update-workflow';
 import { FieldGroupingWorkflow } from './anki-integration/field-grouping-workflow';
 import { resolveAnimatedImageLeadInSeconds } from './anki-integration/animated-image-sync';
 import { AnkiIntegrationRuntime, normalizeAnkiIntegrationConfig } from './anki-integration/runtime';
-import { resolveMediaGenerationInputPath } from './anki-integration/media-source';
+import {
+  resolveAudioStreamIndexForMediaGeneration,
+  resolveMediaGenerationInput,
+  resolveMediaGenerationInputPath,
+  type MediaGenerationInputResolverOptions,
+} from './anki-integration/media-source';
+import type { PendingYoutubeMediaUpdate } from './anki-integration/pending-youtube-media';
+import { PendingYoutubeMediaQueue } from './anki-integration/pending-youtube-media-queue';
+import type {
+  PendingYoutubeMediaQueueFailedOptions,
+  PendingYoutubeMediaQueueReadyOptions,
+} from './anki-integration/pending-youtube-media-queue';
 
 const log = createLogger('anki').child('integration');
 
@@ -225,6 +236,13 @@ export class AnkiIntegration {
   private consumeSubtitleMiningContextCallback: (() => SubtitleMiningContext | null) | null = null;
   private noteIdRedirects = new Map<number, number>();
   private trackedDuplicateNoteIds = new Map<number, number[]>();
+  private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
+    null;
+  private shouldRequireRemoteMediaCache: (() => boolean) | null = null;
+  private getYoutubeMediaSourceUrl:
+    | (() => Promise<string | null | undefined> | string | null | undefined)
+    | null = null;
+  private pendingYoutubeMediaQueue: PendingYoutubeMediaQueue;
 
   constructor(
     config: AnkiConnectConfig,
@@ -240,6 +258,9 @@ export class AnkiIntegration {
     aiConfig: AiConfig = {},
     recordCardsMined?: (count: number, noteIds?: number[]) => void,
     overlayNotificationCallback?: (payload: OverlayNotificationPayload) => void,
+    getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'],
+    shouldRequireRemoteMediaCache?: () => boolean,
+    getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined,
   ) {
     this.config = normalizeAnkiIntegrationConfig(config);
     this.aiConfig = { ...aiConfig };
@@ -252,6 +273,10 @@ export class AnkiIntegration {
     this.overlayNotificationCallback = overlayNotificationCallback || null;
     this.fieldGroupingCallback = fieldGroupingCallback || null;
     this.recordCardsMinedCallback = recordCardsMined ?? null;
+    this.getCachedMediaPath = getCachedMediaPath ?? null;
+    this.shouldRequireRemoteMediaCache = shouldRequireRemoteMediaCache ?? null;
+    this.getYoutubeMediaSourceUrl = getYoutubeMediaSourceUrl ?? null;
+    this.pendingYoutubeMediaQueue = this.createPendingYoutubeMediaQueue();
     this.knownWordCache = this.createKnownWordCache(knownWordCacheStatePath);
     this.pollingRunner = this.createPollingRunner();
     this.cardCreationService = this.createCardCreationService();
@@ -295,6 +320,82 @@ export class AnkiIntegration {
     }
   }
 
+  private getMediaResolverOptions(): MediaGenerationInputResolverOptions {
+    const options: MediaGenerationInputResolverOptions = {
+      logDebug: (message) => log.debug(message),
+    };
+    if (this.getCachedMediaPath) {
+      options.getCachedMediaPath = this.getCachedMediaPath;
+    }
+    if (this.shouldRequireRemoteMediaCache?.()) {
+      options.remoteCacheMode = 'required';
+    }
+    return options;
+  }
+
+  private createPendingYoutubeMediaQueue(): PendingYoutubeMediaQueue {
+    return new PendingYoutubeMediaQueue({
+      client: {
+        notesInfo: async (noteIds) => (await this.client.notesInfo(noteIds)) as unknown,
+        updateNoteFields: (noteId, fields) => this.client.updateNoteFields(noteId, fields),
+        storeMediaFile: (filename, data) => this.client.storeMediaFile(filename, data),
+      },
+      mediaGenerator: {
+        generateAudio: (videoPath, startTime, endTime, audioPadding, audioStreamIndex) =>
+          this.mediaGenerator.generateAudio(
+            videoPath,
+            startTime,
+            endTime,
+            audioPadding,
+            audioStreamIndex,
+            this.config.media?.normalizeAudio !== false,
+          ),
+        generateScreenshot: (videoPath, timestamp, options) =>
+          this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
+        generateAnimatedImage: (videoPath, startTime, endTime, audioPadding, options) =>
+          this.mediaGenerator.generateAnimatedImage(
+            videoPath,
+            startTime,
+            endTime,
+            audioPadding,
+            options,
+          ),
+      },
+      getConfig: () => this.config,
+      getCurrentVideoPath: () => this.getCurrentYoutubeMediaSourceUrl(),
+      getCachedMediaPath: this.getCachedMediaPath,
+      shouldRequireRemoteMediaCache: () => this.shouldRequireRemoteMediaCache?.() === true,
+      getSubtitleMediaRange: (context) => this.getSubtitleMediaRange(context),
+      getResolvedSentenceAudioFieldName: (noteInfo) =>
+        this.getResolvedSentenceAudioFieldName(noteInfo),
+      resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
+        this.resolveConfiguredFieldName(noteInfo, ...preferredNames),
+      mergeFieldValue: (existing, newValue, overwrite) =>
+        this.mergeFieldValue(existing, newValue, overwrite),
+      getAnimatedImageLeadInSeconds: (noteInfo) => this.getAnimatedImageLeadInSeconds(noteInfo),
+      generateAudioFilename: () => this.generateAudioFilename(),
+      generateImageFilename: () => this.generateImageFilename(),
+      formatMiscInfoPatternForMediaPath: (
+        fallbackFilename,
+        startTimeSeconds,
+        mediaPath,
+        mediaTitle,
+      ) =>
+        this.formatMiscInfoPatternForMediaPath(
+          fallbackFilename,
+          startTimeSeconds,
+          mediaPath,
+          mediaTitle,
+        ),
+      showStatusNotification: (message) => this.showStatusNotification(message),
+      showNotification: (noteId, label, errorSuffix) =>
+        this.showNotification(noteId, label, errorSuffix),
+      logInfo: (...args) => log.info(args[0] as string, ...args.slice(1)),
+      logWarn: (...args) => log.warn(args[0] as string, ...args.slice(1)),
+      logError: (...args) => log.error(args[0] as string, ...args.slice(1)),
+    });
+  }
+
   private createKnownWordCache(knownWordCacheStatePath?: string): KnownWordCacheManager {
     return new KnownWordCacheManager({
       client: {
@@ -377,6 +478,10 @@ export class AnkiIntegration {
       getAiConfig: () => this.aiConfig,
       getTimingTracker: () => this.timingTracker,
       getMpvClient: () => this.mpvClient,
+      ...(this.getCachedMediaPath ? { getCachedMediaPath: this.getCachedMediaPath } : {}),
+      shouldRequireRemoteMediaCache: () => this.shouldRequireRemoteMediaCache?.() === true,
+      getYoutubeMediaSourceUrl: () => this.getCurrentYoutubeMediaSourceUrl(),
+      queuePendingYoutubeMediaUpdate: (job) => this.queuePendingYoutubeMediaUpdate(job),
       getDeck: () => this.config.deck,
       client: {
         addNote: (deck, modelName, fields, tags) =>
@@ -398,6 +503,7 @@ export class AnkiIntegration {
             endTime,
             audioPadding,
             audioStreamIndex,
+            this.config.media?.normalizeAudio !== false,
           ),
         generateScreenshot: (videoPath, timestamp, options) =>
           this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
@@ -540,6 +646,7 @@ export class AnkiIntegration {
       formatMiscInfoPattern: (fallbackFilename, startTimeSeconds) =>
         this.formatMiscInfoPattern(fallbackFilename, startTimeSeconds),
       consumeSubtitleMiningContext: () => this.consumeSubtitleMiningContext(),
+      queuePendingYoutubeMediaUpdate: (job) => this.queuePendingYoutubeMediaUpdateForNote(job),
       addConfiguredTagsToNote: (noteId) => this.addConfiguredTagsToNote(noteId),
       showNotification: (noteId, label) => this.showNotification(noteId, label),
       showOsdNotification: (message) => this.showStatusNotification(message),
@@ -596,8 +703,8 @@ export class AnkiIntegration {
     });
   }
 
-  isKnownWord(text: string): boolean {
-    return this.knownWordCache.isKnownWord(text);
+  isKnownWord(text: string, reading?: string): boolean {
+    return this.knownWordCache.isKnownWord(text, reading);
   }
 
   getKnownWordMatchMode(): NPlusOneMatchMode {
@@ -833,13 +940,53 @@ export class AnkiIntegration {
     };
   }
 
+  private queuePendingYoutubeMediaUpdate(job: PendingYoutubeMediaUpdate): void {
+    this.pendingYoutubeMediaQueue.enqueue(job);
+  }
+
+  private async queuePendingYoutubeMediaUpdateForNote(job: {
+    noteId: number;
+    noteInfo: NoteInfo;
+    context?: SubtitleMiningContext;
+    label: string | number;
+  }): Promise<boolean> {
+    return this.pendingYoutubeMediaQueue.queueFromNote(job);
+  }
+
+  private async getCurrentYoutubeMediaSourceUrl(): Promise<string> {
+    return (
+      trimToNonEmptyString(await this.getYoutubeMediaSourceUrl?.()) ??
+      trimToNonEmptyString(this.mpvClient.currentVideoPath) ??
+      ''
+    );
+  }
+
+  async handleYoutubeMediaCacheReady(
+    sourceUrl: string,
+    cachedPath: string,
+    options?: PendingYoutubeMediaQueueReadyOptions,
+  ): Promise<void> {
+    await this.pendingYoutubeMediaQueue.handleReady(sourceUrl, cachedPath, options);
+  }
+
+  async handleYoutubeMediaCacheFailed(
+    sourceUrl: string,
+    options?: PendingYoutubeMediaQueueFailedOptions,
+  ): Promise<void> {
+    await this.pendingYoutubeMediaQueue.handleFailed(sourceUrl, options);
+  }
+
   private async generateAudio(context?: SubtitleMiningContext): Promise<Buffer | null> {
     const mpvClient = this.mpvClient;
     if (!mpvClient || !mpvClient.currentVideoPath) {
       return null;
     }
 
-    const videoPath = await resolveMediaGenerationInputPath(mpvClient, 'audio');
+    const videoPath = await resolveMediaGenerationInput(
+      mpvClient,
+      'audio',
+      this.getMediaResolverOptions(),
+    );
     if (!videoPath) {
       return null;
     }
@@ -850,7 +997,8 @@ export class AnkiIntegration {
       startTime,
       endTime,
       this.config.media?.audioPadding,
-      this.mpvClient.currentAudioStreamIndex,
+      resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
+      this.config.media?.normalizeAudio !== false,
     );
   }
 
@@ -862,7 +1010,11 @@ export class AnkiIntegration {
       return null;
     }
 
-    const videoPath = await resolveMediaGenerationInputPath(this.mpvClient, 'video');
+    const videoPath = await resolveMediaGenerationInput(
+      this.mpvClient,
+      'video',
+      this.getMediaResolverOptions(),
+    );
     if (!videoPath) {
       return null;
     }
@@ -896,17 +1048,30 @@ export class AnkiIntegration {
   }
 
   private formatMiscInfoPattern(fallbackFilename: string, startTimeSeconds?: number): string {
+    return this.formatMiscInfoPatternForMediaPath(
+      fallbackFilename,
+      startTimeSeconds,
+      this.mpvClient.currentVideoPath || '',
+      this.mpvClient.currentMediaTitle ?? undefined,
+    );
+  }
+
+  private formatMiscInfoPatternForMediaPath(
+    fallbackFilename: string,
+    startTimeSeconds: number | undefined,
+    mediaPath: string,
+    mediaTitle?: string,
+  ): string {
     if (!this.config.metadata?.pattern) {
       return '';
     }
 
-    const currentVideoPath = this.mpvClient.currentVideoPath || '';
-    const videoFilename = extractFilenameFromMediaPath(currentVideoPath);
-    const mediaTitle = trimToNonEmptyString(this.mpvClient.currentMediaTitle);
+    const videoFilename = extractFilenameFromMediaPath(mediaPath);
+    const resolvedMediaTitle = trimToNonEmptyString(mediaTitle);
     const filenameWithExt =
-      (shouldPreferMediaTitleForMiscInfo(currentVideoPath, videoFilename)
-        ? mediaTitle || videoFilename
-        : videoFilename || mediaTitle) || fallbackFilename;
+      (shouldPreferMediaTitleForMiscInfo(mediaPath, videoFilename)
+        ? resolvedMediaTitle || videoFilename
+        : videoFilename || resolvedMediaTitle) || fallbackFilename;
     const filenameWithoutExt = filenameWithExt.replace(/\.[^.]+$/, '');
 
     const currentTimePos =
@@ -1457,7 +1622,7 @@ export class AnkiIntegration {
       miscInfoValue?: string;
     } = {};
 
-    if (this.config.media?.generateAudio && this.mpvClient?.currentVideoPath) {
+    if (this.config.media?.generateAudio !== false && this.mpvClient?.currentVideoPath) {
       try {
         const audioFilename = this.generateAudioFilename();
         const audioBuffer = await this.generateAudio();
@@ -1477,7 +1642,7 @@ export class AnkiIntegration {
       }
     }
 
-    if (this.config.media?.generateImage && this.mpvClient?.currentVideoPath) {
+    if (this.config.media?.generateImage !== false && this.mpvClient?.currentVideoPath) {
       try {
         const animatedLeadInSeconds = noteInfo
           ? await this.getAnimatedImageLeadInSeconds(noteInfo)

src/anki-integration/card-creation-manual-update.test.ts

@@ -2,6 +2,8 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import { CardCreationService } from './card-creation';
+import { toMpvEdlValue } from './mpv-edl-test-utils';
+import type { MediaInput } from '../media-generator';
 import type { AnkiConnectConfig } from '../types/anki';
 
 type CardCreationDeps = ConstructorParameters<typeof CardCreationService>[0];
@@ -266,9 +268,13 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
 test('manual clipboard subtitle update uses resolved mpv stream URLs for remote media', async () => {
   const audioPaths: string[] = [];
   const imagePaths: string[] = [];
+  const recordMediaPath = (mediaInput: MediaInput): string =>
+    typeof mediaInput === 'string' ? mediaInput : mediaInput.path;
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
   const edlSource = [
-    'edl://!new_stream;!no_clip;!no_chapters;%70%https://audio.example/videoplayback?mime=audio%2Fwebm',
-    '!new_stream;!no_clip;!no_chapters;%69%https://video.example/videoplayback?mime=video%2Fmp4',
+    `edl://!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(audioUrl)}`,
+    `!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(videoUrl)}`,
     '!global_tags,title=test',
   ].join(';');
 
@@ -338,11 +344,11 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
     },
     mediaGenerator: {
       generateAudio: async (path) => {
-        audioPaths.push(path);
+        audioPaths.push(recordMediaPath(path));
         return Buffer.from('audio');
       },
       generateScreenshot: async (path) => {
-        imagePaths.push(path);
+        imagePaths.push(recordMediaPath(path));
         return Buffer.from('image');
       },
       generateAnimatedImage: async () => null,
@@ -351,8 +357,8 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
 
   await service.updateLastAddedFromClipboard('一行目\n\n二行目');
 
-  assert.deepEqual(audioPaths, ['https://audio.example/videoplayback?mime=audio%2Fwebm']);
-  assert.deepEqual(imagePaths, ['https://video.example/videoplayback?mime=video%2Fmp4']);
+  assert.deepEqual(audioPaths, [audioUrl]);
+  assert.deepEqual(imagePaths, [videoUrl]);
   assert.equal(storedMedia.length, 2);
   assert.equal(updatedFields.length, 1);
   assert.equal(updatedFields[0]?.Sentence, '一行目 二行目');

src/anki-integration/card-creation.test.ts

@@ -2,6 +2,8 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import { CardCreationService } from './card-creation';
+import { toMpvEdlValue } from './mpv-edl-test-utils';
+import type { MediaInput } from '../media-generator';
 import type { AnkiConnectConfig } from '../types/anki';
 
 test('CardCreationService counts locally created sentence cards', async () => {
@@ -287,9 +289,13 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
 test('CardCreationService uses stream-open-filename for remote media generation', async () => {
   const audioPaths: string[] = [];
   const imagePaths: string[] = [];
+  const recordMediaPath = (mediaInput: MediaInput): string =>
+    typeof mediaInput === 'string' ? mediaInput : mediaInput.path;
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
   const edlSource = [
-    'edl://!new_stream;!no_clip;!no_chapters;%70%https://audio.example/videoplayback?mime=audio%2Fwebm',
-    '!new_stream;!no_clip;!no_chapters;%69%https://video.example/videoplayback?mime=video%2Fmp4',
+    `edl://!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(audioUrl)}`,
+    `!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(videoUrl)}`,
     '!global_tags,title=test',
   ].join(';');
 
@@ -345,11 +351,11 @@ test('CardCreationService uses stream-open-filename for remote media generation'
     },
     mediaGenerator: {
       generateAudio: async (path) => {
-        audioPaths.push(path);
+        audioPaths.push(recordMediaPath(path));
         return Buffer.from('audio');
       },
       generateScreenshot: async (path) => {
-        imagePaths.push(path);
+        imagePaths.push(recordMediaPath(path));
         return Buffer.from('image');
       },
       generateAnimatedImage: async () => null,
@@ -394,8 +400,261 @@ test('CardCreationService uses stream-open-filename for remote media generation'
   const created = await service.createSentenceCard('テスト', 0, 1);
 
   assert.equal(created, true);
-  assert.deepEqual(audioPaths, ['https://audio.example/videoplayback?mime=audio%2Fwebm']);
-  assert.deepEqual(imagePaths, ['https://video.example/videoplayback?mime=video%2Fmp4']);
+  assert.deepEqual(audioPaths, [audioUrl]);
+  assert.deepEqual(imagePaths, [videoUrl]);
+});
+
+test('CardCreationService does not use mpv stream indexes for ready cached YouTube media', async () => {
+  const audioCalls: Array<{ path: string; audioStreamIndex?: number }> = [];
+
+  const service = new CardCreationService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          sentence: 'Sentence',
+          audio: 'SentenceAudio',
+          image: 'Picture',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          imageFormat: 'jpg',
+        },
+        behavior: {},
+        ai: false,
+      }) as AnkiConnectConfig,
+    getAiConfig: () => ({}),
+    getTimingTracker: () => ({}) as never,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+        currentSubText: '字幕',
+        currentSubStart: 10,
+        currentSubEnd: 12,
+        currentTimePos: 11,
+        currentAudioStreamIndex: 0,
+      }) as never,
+    getCachedMediaPath: async () => '/tmp/subminer-youtube-media-cache/media.mkv',
+    shouldRequireRemoteMediaCache: () => true,
+    client: {
+      addNote: async () => 42,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Picture: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async () => undefined,
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [],
+      retrieveMediaFile: async () => '',
+    },
+    mediaGenerator: {
+      generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
+        audioCalls.push({ path: typeof path === 'string' ? path : path.path, audioStreamIndex });
+        return Buffer.from('audio');
+      },
+      generateScreenshot: async () => null,
+      generateAnimatedImage: async () => null,
+    },
+    showOsdNotification: () => undefined,
+    showUpdateResult: () => undefined,
+    showStatusNotification: () => undefined,
+    showNotification: async () => undefined,
+    beginUpdateProgress: () => undefined,
+    endUpdateProgress: () => undefined,
+    withUpdateProgress: async (_message, action) => action(),
+    resolveConfiguredFieldName: (noteInfo, preferredName) => {
+      if (!preferredName) return null;
+      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
+    },
+    resolveNoteFieldName: (noteInfo, preferredName) => {
+      if (!preferredName) return null;
+      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
+    },
+    getAnimatedImageLeadInSeconds: async () => 0,
+    extractFields: () => ({}),
+    processSentence: (sentence) => sentence,
+    setCardTypeFields: () => undefined,
+    mergeFieldValue: (_existing, newValue) => newValue,
+    formatMiscInfoPattern: () => '',
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: false,
+      kikuEnabled: false,
+      kikuFieldGrouping: 'disabled',
+      kikuDeleteDuplicateInAuto: false,
+    }),
+    getFallbackDurationSeconds: () => 10,
+    appendKnownWordsFromNoteInfo: () => undefined,
+    isUpdateInProgress: () => false,
+    setUpdateInProgress: () => undefined,
+    trackLastAddedNoteId: () => undefined,
+  });
+
+  const created = await service.createSentenceCard('テスト', 10, 12);
+
+  assert.equal(created, true);
+  assert.deepEqual(audioCalls, [
+    {
+      path: '/tmp/subminer-youtube-media-cache/media.mkv',
+      audioStreamIndex: undefined,
+    },
+  ]);
+});
+
+test('CardCreationService queues YouTube media when required cache is not ready', async () => {
+  const mediaCalls: string[] = [];
+  const updates: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const queuedUpdates: Array<{
+    sourceUrl: string;
+    noteId: number;
+    startTime: number;
+    endTime: number;
+    label: string | number;
+    audioFieldName?: string;
+    imageFieldName?: string;
+    miscInfoFieldName?: string;
+    generateAudio: boolean;
+    generateImage: boolean;
+  }> = [];
+  let streamRequests = 0;
+
+  const service = new CardCreationService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          sentence: 'Sentence',
+          audio: 'SentenceAudio',
+          image: 'Picture',
+          miscInfo: 'MiscInfo',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: true,
+          imageFormat: 'jpg',
+        },
+        behavior: {},
+        ai: false,
+      }) as AnkiConnectConfig,
+    getAiConfig: () => ({}),
+    getTimingTracker: () => ({}) as never,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+        currentSubText: '字幕',
+        currentSubStart: 10,
+        currentSubEnd: 12,
+        currentTimePos: 11,
+        currentAudioStreamIndex: 2,
+        requestProperty: async () => {
+          streamRequests += 1;
+          return 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123';
+        },
+      }) as never,
+    getCachedMediaPath: async () => null,
+    shouldRequireRemoteMediaCache: () => true,
+    queuePendingYoutubeMediaUpdate: (job) => {
+      queuedUpdates.push(job);
+    },
+    client: {
+      addNote: async () => 42,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Picture: { value: '' },
+            MiscInfo: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async (noteId, fields) => {
+        updates.push({ noteId, fields });
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [],
+      retrieveMediaFile: async () => '',
+    },
+    mediaGenerator: {
+      generateAudio: async () => {
+        mediaCalls.push('audio');
+        return Buffer.from('audio');
+      },
+      generateScreenshot: async () => {
+        mediaCalls.push('image');
+        return Buffer.from('image');
+      },
+      generateAnimatedImage: async () => null,
+    },
+    showOsdNotification: () => undefined,
+    showUpdateResult: () => undefined,
+    showStatusNotification: () => undefined,
+    showNotification: async () => undefined,
+    beginUpdateProgress: () => undefined,
+    endUpdateProgress: () => undefined,
+    withUpdateProgress: async (_message, action) => action(),
+    resolveConfiguredFieldName: (noteInfo, preferredName) => {
+      if (!preferredName) return null;
+      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
+    },
+    resolveNoteFieldName: (noteInfo, preferredName) => {
+      if (!preferredName) return null;
+      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
+    },
+    getAnimatedImageLeadInSeconds: async () => 0,
+    extractFields: () => ({}),
+    processSentence: (sentence) => sentence,
+    setCardTypeFields: () => undefined,
+    mergeFieldValue: (_existing, newValue) => newValue,
+    formatMiscInfoPattern: () => '',
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: false,
+      kikuEnabled: false,
+      kikuFieldGrouping: 'disabled',
+      kikuDeleteDuplicateInAuto: false,
+    }),
+    getFallbackDurationSeconds: () => 10,
+    appendKnownWordsFromNoteInfo: () => undefined,
+    isUpdateInProgress: () => false,
+    setUpdateInProgress: () => undefined,
+    trackLastAddedNoteId: () => undefined,
+  });
+
+  const created = await service.createSentenceCard('テスト', 10, 12);
+
+  assert.equal(created, true);
+  assert.equal(streamRequests, 0);
+  assert.deepEqual(mediaCalls, []);
+  assert.deepEqual(queuedUpdates, [
+    {
+      sourceUrl: 'https://www.youtube.com/watch?v=abc123',
+      noteId: 42,
+      startTime: 10,
+      endTime: 12,
+      label: 'テスト',
+      audioFieldName: 'SentenceAudio',
+      imageFieldName: 'Picture',
+      miscInfoFieldName: 'MiscInfo',
+      generateAudio: true,
+      generateImage: true,
+    },
+  ]);
+  assert.deepEqual(updates, []);
 });
 
 test('CardCreationService tracks pre-add duplicate note ids for kiku sentence cards', async () => {

src/anki-integration/card-creation.ts

@@ -5,15 +5,37 @@ import {
 } from '../anki-field-config';
 import { AnkiConnectConfig } from '../types/anki';
 import { createLogger } from '../logger';
+import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
 import { AiConfig } from '../types/integrations';
 import { MpvClient } from '../types/runtime';
 import { resolveSentenceBackText } from './ai';
-import { resolveMediaGenerationInputPath } from './media-source';
+import {
+  resolveMediaGenerationInput,
+  resolveAudioStreamIndexForMediaGeneration,
+  type MediaGenerationInputResolverOptions,
+} from './media-source';
 import { shouldMarkWordAndSentenceCard } from './note-field-utils';
+import type { PendingYoutubeMediaUpdate } from './pending-youtube-media';
 
 const log = createLogger('anki').child('integration.card-creation');
 
+function shouldGenerateAudio(config: AnkiConnectConfig): boolean {
+  return config.media?.generateAudio !== false;
+}
+
+function shouldGenerateImage(config: AnkiConnectConfig): boolean {
+  return config.media?.generateImage !== false;
+}
+
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 export interface CardCreationNoteInfo {
   noteId: number;
   fields: Record<string, { value: string }>;
@@ -38,14 +60,15 @@ interface CardCreationClient {
 
 interface CardCreationMediaGenerator {
   generateAudio(
-    path: string,
+    path: MediaInput,
     startTime: number,
     endTime: number,
     audioPadding?: number,
     audioStreamIndex?: number,
+    normalizeAudio?: boolean,
   ): Promise<Buffer | null>;
   generateScreenshot(
-    path: string,
+    path: MediaInput,
     timestamp: number,
     options: {
       format: 'jpg' | 'png' | 'webp';
@@ -55,7 +78,7 @@ interface CardCreationMediaGenerator {
     },
   ): Promise<Buffer | null>;
   generateAnimatedImage(
-    path: string,
+    path: MediaInput,
     startTime: number,
     endTime: number,
     audioPadding?: number,
@@ -74,6 +97,10 @@ interface CardCreationDeps {
   getAiConfig: () => AiConfig;
   getTimingTracker: () => SubtitleTimingTracker;
   getMpvClient: () => MpvClient;
+  getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'];
+  shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
+  queuePendingYoutubeMediaUpdate?: (job: PendingYoutubeMediaUpdate) => void;
   getDeck?: () => string | undefined;
   client: CardCreationClient;
   mediaGenerator: CardCreationMediaGenerator;
@@ -121,6 +148,19 @@ interface CardCreationDeps {
 export class CardCreationService {
   constructor(private readonly deps: CardCreationDeps) {}
 
+  private getMediaResolverOptions(): MediaGenerationInputResolverOptions {
+    const options: MediaGenerationInputResolverOptions = {
+      logDebug: (message) => log.debug(message),
+    };
+    if (this.deps.getCachedMediaPath) {
+      options.getCachedMediaPath = this.deps.getCachedMediaPath;
+    }
+    if (this.deps.shouldRequireRemoteMediaCache?.()) {
+      options.remoteCacheMode = 'required';
+    }
+    return options;
+  }
+
   private getConfiguredAnkiTags(): string[] {
     const tags = this.deps.getConfig().tags;
     if (!Array.isArray(tags)) {
@@ -246,14 +286,18 @@ export class CardCreationService {
           `Clipboard update: timing range ${rangeStart.toFixed(2)}s - ${rangeEnd.toFixed(2)}s`,
         );
 
-        const audioSourcePath = this.deps.getConfig().media?.generateAudio
-          ? await resolveMediaGenerationInputPath(mpvClient, 'audio')
+        const config = this.deps.getConfig();
+        const generateAudio = shouldGenerateAudio(config);
+        const generateImage = shouldGenerateImage(config);
+        const mediaResolverOptions = this.getMediaResolverOptions();
+        const audioSourcePath = generateAudio
+          ? await resolveMediaGenerationInput(mpvClient, 'audio', mediaResolverOptions)
           : null;
-        const videoPath = this.deps.getConfig().media?.generateImage
-          ? await resolveMediaGenerationInputPath(mpvClient, 'video')
+        const videoPath = generateImage
+          ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
           : null;
 
-        if (this.deps.getConfig().media?.generateAudio) {
+        if (generateAudio) {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
@@ -281,7 +325,7 @@ export class CardCreationService {
           }
         }
 
-        if (this.deps.getConfig().media?.generateImage) {
+        if (generateImage) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -441,7 +485,7 @@ export class CardCreationService {
           errors.push('audio');
         }
 
-        if (this.deps.getConfig().media?.generateImage) {
+        if (shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -522,9 +566,23 @@ export class CardCreationService {
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
-        const videoPath = await resolveMediaGenerationInputPath(mpvClient, 'video');
-        const audioSourcePath = await resolveMediaGenerationInputPath(mpvClient, 'audio');
-        if (!videoPath) {
+        const config = this.deps.getConfig();
+        const generateAudio = shouldGenerateAudio(config);
+        const generateImage = shouldGenerateImage(config);
+        const mediaResolverOptions = this.getMediaResolverOptions();
+        const videoPath = generateImage
+          ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
+          : null;
+        const audioSourcePath = generateAudio
+          ? await resolveMediaGenerationInput(mpvClient, 'audio', mediaResolverOptions)
+          : null;
+        const missingRequestedMediaInput =
+          (generateImage && !videoPath) || (generateAudio && !audioSourcePath);
+        const shouldQueuePendingYoutubeMedia =
+          missingRequestedMediaInput &&
+          this.deps.shouldRequireRemoteMediaCache?.() === true &&
+          typeof this.deps.queuePendingYoutubeMediaUpdate === 'function';
+        if (missingRequestedMediaInput && !shouldQueuePendingYoutubeMedia) {
           this.deps.showOsdNotification('No video loaded');
           return false;
         }
@@ -534,13 +592,13 @@ export class CardCreationService {
 
         const sentenceField = sentenceCardConfig.sentenceField;
         const audioFieldName = sentenceCardConfig.audioField || 'SentenceAudio';
-        const translationField = this.deps.getConfig().fields?.translation || 'SelectionText';
+        const translationField = config.fields?.translation || 'SelectionText';
         let resolvedMiscInfoField: string | null = null;
         let resolvedSentenceAudioField: string = audioFieldName;
 
         fields[sentenceField] = sentence;
 
-        const ankiAiConfig = this.deps.getConfig().ai;
+        const ankiAiConfig = config.ai;
         const ankiAiEnabled =
           typeof ankiAiConfig === 'object' && ankiAiConfig !== null
             ? ankiAiConfig.enabled === true
@@ -563,7 +621,7 @@ export class CardCreationService {
 
         if (sentenceCardConfig.lapisEnabled || sentenceCardConfig.kikuEnabled) {
           fields.IsSentenceCard = 'x';
-          fields[getConfiguredWordFieldName(this.deps.getConfig())] = sentence;
+          fields[getConfiguredWordFieldName(config)] = sentence;
         }
 
         const pendingNoteInfo = this.createPendingNoteInfo(fields);
@@ -572,7 +630,7 @@ export class CardCreationService {
         );
         const pendingExpressionText = getPreferredWordValueFromExtractedFields(
           pendingNoteFields,
-          this.deps.getConfig(),
+          config,
         ).trim();
         let duplicateNoteIds: number[] = [];
         if (
@@ -590,7 +648,7 @@ export class CardCreationService {
           }
         }
 
-        const deck = this.deps.getConfig().deck || 'Default';
+        const deck = config.deck || 'Default';
         let noteId: number;
         try {
           noteId = await this.deps.client.addNote(
@@ -636,7 +694,7 @@ export class CardCreationService {
               this.deps.resolveNoteFieldName(createdNoteInfo, audioFieldName) || audioFieldName;
             resolvedMiscInfoField = this.deps.resolveConfiguredFieldName(
               createdNoteInfo,
-              this.deps.getConfig().fields?.miscInfo,
+              config.fields?.miscInfo,
             );
 
             const cardTypeFields: Record<string, string> = {};
@@ -654,41 +712,69 @@ export class CardCreationService {
           errors.push('card type fields');
         }
 
+        const label = sentence.length > 30 ? sentence.substring(0, 30) + '...' : sentence;
+        if (shouldQueuePendingYoutubeMedia) {
+          this.deps.queuePendingYoutubeMediaUpdate?.({
+            sourceUrl:
+              trimToNonEmptyString(await this.deps.getYoutubeMediaSourceUrl?.()) ??
+              mpvClient.currentVideoPath,
+            noteId,
+            startTime,
+            endTime,
+            label,
+            audioFieldName: resolvedSentenceAudioField,
+            imageFieldName: config.fields?.image,
+            miscInfoFieldName: resolvedMiscInfoField ?? undefined,
+            generateAudio,
+            generateImage,
+          });
+          await this.deps.showNotification(noteId, label, 'media queued');
+          return true;
+        }
+
+        if (missingRequestedMediaInput) {
+          return false;
+        }
+
         const mediaFields: Record<string, string> = {};
 
-        try {
-          const audioFilename = this.generateAudioFilename();
-          const audioBuffer = audioSourcePath
-            ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
-            : null;
+        if (generateAudio) {
+          try {
+            const audioFilename = this.generateAudioFilename();
+            const audioBuffer = audioSourcePath
+              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
+              : null;
 
-          if (audioBuffer) {
-            await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-            const audioValue = `[sound:${audioFilename}]`;
-            mediaFields[resolvedSentenceAudioField] = audioValue;
-            miscInfoFilename = audioFilename;
+            if (audioBuffer) {
+              await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
+              const audioValue = `[sound:${audioFilename}]`;
+              mediaFields[resolvedSentenceAudioField] = audioValue;
+              miscInfoFilename = audioFilename;
+            }
+          } catch (error) {
+            log.error('Failed to generate sentence audio:', (error as Error).message);
+            errors.push('audio');
           }
-        } catch (error) {
-          log.error('Failed to generate sentence audio:', (error as Error).message);
-          errors.push('audio');
         }
 
-        try {
-          const imageFilename = this.generateImageFilename();
-          const imageBuffer = await this.generateImageBuffer(videoPath, startTime, endTime);
+        if (generateImage) {
+          try {
+            const imageFilename = this.generateImageFilename();
+            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
 
-          const imageField = this.deps.getConfig().fields?.image;
-          if (imageBuffer && imageField) {
-            await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
-            mediaFields[imageField] = `<img src="${imageFilename}">`;
-            miscInfoFilename = imageFilename;
+            const imageField = config.fields?.image;
+            if (imageBuffer && imageField) {
+              await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
+              mediaFields[imageField] = `<img src="${imageFilename}">`;
+              miscInfoFilename = imageFilename;
+            }
+          } catch (error) {
+            log.error('Failed to generate sentence image:', (error as Error).message);
+            errors.push('image');
           }
-        } catch (error) {
-          log.error('Failed to generate sentence image:', (error as Error).message);
-          errors.push('image');
         }
 
-        if (this.deps.getConfig().fields?.miscInfo) {
+        if (config.fields?.miscInfo) {
           const miscInfo = this.deps.formatMiscInfoPattern(miscInfoFilename || '', startTime);
           if (miscInfo && resolvedMiscInfoField) {
             mediaFields[resolvedMiscInfoField] = miscInfo;
@@ -704,7 +790,6 @@ export class CardCreationService {
           }
         }
 
-        const label = sentence.length > 30 ? sentence.substring(0, 30) + '...' : sentence;
         const errorSuffix = errors.length > 0 ? `${errors.join(', ')} failed` : undefined;
         await this.deps.showNotification(noteId, label, errorSuffix);
         return true;
@@ -740,7 +825,7 @@ export class CardCreationService {
   }
 
   private async mediaGenerateAudio(
-    videoPath: string,
+    videoPath: MediaInput,
     startTime: number,
     endTime: number,
   ): Promise<Buffer | null> {
@@ -754,12 +839,16 @@ export class CardCreationService {
       startTime,
       endTime,
       this.deps.getConfig().media?.audioPadding,
-      mpvClient.currentAudioStreamIndex ?? undefined,
+      resolveAudioStreamIndexForMediaGeneration(
+        videoPath,
+        mpvClient.currentAudioStreamIndex ?? undefined,
+      ),
+      this.deps.getConfig().media?.normalizeAudio !== false,
     );
   }
 
   private async generateImageBuffer(
-    videoPath: string,
+    videoPath: MediaInput,
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,

src/anki-integration/field-grouping-workflow.test.ts

@@ -26,6 +26,7 @@ function createWorkflowHarness() {
   const deleted: number[][] = [];
   const addedTags: Array<{ noteIds: number[]; tags: string[] }> = [];
   const statuses: string[] = [];
+  const osdMessages: string[] = [];
   const rememberedMerges: Array<{ deletedNoteId: number; keptNoteId: number }> = [];
   const mergeCalls: Array<{
     keepNoteId: number;
@@ -112,7 +113,9 @@ function createWorkflowHarness() {
       statuses.push(message);
     },
     showNotification: async () => undefined,
-    showOsdNotification: () => undefined,
+    showOsdNotification: (message: string) => {
+      osdMessages.push(message);
+    },
     logError: () => undefined,
     logInfo: () => undefined,
     truncateSentence: (value: string) => value,
@@ -125,6 +128,7 @@ function createWorkflowHarness() {
     addedTags,
     rememberedMerges,
     statuses,
+    osdMessages,
     mergeCalls,
     setManualChoice: (choice: typeof manualChoice) => {
       manualChoice = choice;
@@ -191,6 +195,50 @@ test('FieldGroupingWorkflow manual mode returns false when callback unavailable'
   assert.equal(harness.updates.length, 0);
 });
 
+test('FieldGroupingWorkflow manual cancel notifies exactly once', async () => {
+  const harness = createWorkflowHarness();
+  harness.setManualChoice({
+    keepNoteId: 0,
+    deleteNoteId: 0,
+    deleteDuplicate: true,
+    cancelled: true,
+  });
+
+  const handled = await harness.workflow.handleManual(1, 2, {
+    noteId: 2,
+    fields: {
+      Expression: { value: 'word-2' },
+      Sentence: { value: 'line-2' },
+    },
+  });
+
+  assert.equal(handled, false);
+  assert.deepEqual(harness.osdMessages, ['Field grouping cancelled']);
+  assert.equal(harness.updates.length, 0);
+});
+
+test('FieldGroupingWorkflow manual mode notifies when the original card cannot be loaded', async () => {
+  const harness = createWorkflowHarness();
+  harness.setManualChoice({
+    keepNoteId: 1,
+    deleteNoteId: 2,
+    deleteDuplicate: true,
+    cancelled: false,
+  });
+  harness.deps.client.notesInfo = async () => [];
+
+  const handled = await harness.workflow.handleManual(1, 2, {
+    noteId: 2,
+    fields: {
+      Expression: { value: 'word-2' },
+      Sentence: { value: 'line-2' },
+    },
+  });
+
+  assert.equal(handled, false);
+  assert.deepEqual(harness.osdMessages, ['Field grouping failed: original card not found']);
+});
+
 test('FieldGroupingWorkflow manual keep-new uses new note as merge target and old note as source', async () => {
   const harness = createWorkflowHarness();
   harness.setManualChoice({

src/anki-integration/field-grouping-workflow.ts

@@ -98,6 +98,8 @@ export class FieldGroupingWorkflow {
       const originalNotesInfoResult = await this.deps.client.notesInfo([originalNoteId]);
       const originalNotesInfo = originalNotesInfoResult as FieldGroupingWorkflowNoteInfo[];
       if (!originalNotesInfo || originalNotesInfo.length === 0) {
+        // handleManual owns all user-facing notifications; callers must not re-notify on false.
+        this.deps.showOsdNotification('Field grouping failed: original card not found');
         return false;
       }
 

src/anki-integration/field-grouping.test.ts

@@ -302,7 +302,7 @@ test('triggerFieldGroupingForLastAddedCard refreshes the card when configured fi
   assert.deepEqual(harness.manualCalls, []);
 });
 
-test('triggerFieldGroupingForLastAddedCard shows a cancellation message when manual grouping is declined', async () => {
+test('triggerFieldGroupingForLastAddedCard does not re-notify when manual grouping is declined', async () => {
   const harness = createHarness({
     kikuFieldGrouping: 'manual',
     noteIds: [9],
@@ -339,7 +339,9 @@ test('triggerFieldGroupingForLastAddedCard shows a cancellation message when man
       expression: 'word-9',
     },
   ]);
-  assert.equal(harness.calls.at(-1), 'osd:Field grouping cancelled');
+  // The manual workflow already notifies about its outcome (cancelled/unavailable/failed);
+  // the trigger wrapper re-notifying produced two "Field grouping cancelled" toasts.
+  assert.equal(harness.calls.filter((call) => call === 'osd:Field grouping cancelled').length, 0);
 });
 
 test('buildFieldGroupingPreview returns merged compact and full previews', async () => {

src/anki-integration/field-grouping.ts

@@ -156,15 +156,14 @@ export class FieldGroupingService {
           );
           return;
         }
-        const handled = await this.deps.handleFieldGroupingManual(
+        // The manual workflow owns all user-facing notifications for its outcomes (cancelled,
+        // unavailable, failed) — re-notifying on a false return here duplicated them.
+        await this.deps.handleFieldGroupingManual(
           duplicateNoteId,
           noteId,
           noteInfo,
           expressionText,
         );
-        if (!handled) {
-          this.deps.showOsdNotification('Field grouping cancelled');
-        }
       });
     } catch (error) {
       log.error('Error triggering field grouping:', (error as Error).message);

src/anki-integration/known-word-cache.test.ts

@@ -108,6 +108,55 @@ test('KnownWordCacheManager startLifecycle keeps fresh persisted cache without i
     assert.equal(manager.isKnownWord('猫'), true);
     assert.equal(calls.findNotes, 0);
     assert.equal(calls.notesInfo, 0);
+    // v2 states carry no readings, so they load usable but stale to trigger a
+    // prompt upgrade refresh.
+    assert.equal(
+      (
+        manager as unknown as {
+          getMsUntilNextRefresh: () => number;
+        }
+      ).getMsUntilNextRefresh(),
+      0,
+    );
+  } finally {
+    Date.now = originalDateNow;
+    manager.stopLifecycle();
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager startLifecycle keeps fresh v3 persisted cache without immediate refresh', async () => {
+  const config: AnkiConnectConfig = {
+    knownWords: {
+      highlightEnabled: true,
+      refreshMinutes: 60,
+    },
+  };
+  const { manager, calls, statePath, cleanup } = createKnownWordCacheHarness(config);
+  const originalDateNow = Date.now;
+
+  try {
+    Date.now = () => 120_000;
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({
+        version: 3,
+        refreshedAtMs: 120_000,
+        scope: '{"refreshMinutes":60,"scope":"all","fieldsWord":""}',
+        notes: {
+          '1': [{ word: '猫', reading: 'ねこ' }],
+        },
+      }),
+      'utf-8',
+    );
+
+    manager.startLifecycle();
+
+    assert.equal(manager.isKnownWord('猫'), true);
+    assert.equal(manager.isKnownWord('猫', 'ねこ'), true);
+    assert.equal(manager.isKnownWord('猫', 'びょう'), false);
+    assert.equal(calls.findNotes, 0);
+    assert.equal(calls.notesInfo, 0);
     assert.equal(
       (
         manager as unknown as {
@@ -263,13 +312,11 @@ test('KnownWordCacheManager refresh incrementally reconciles deleted and edited
 
     const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
       version: number;
-      words: string[];
-      notes?: Record<string, string[]>;
+      notes?: Record<string, Array<{ word: string; reading: string | null }>>;
     };
-    assert.equal(persisted.version, 2);
-    assert.deepEqual(persisted.words.sort(), ['鳥']);
+    assert.equal(persisted.version, 3);
     assert.deepEqual(persisted.notes, {
-      '1': ['鳥'],
+      '1': [{ word: '鳥', reading: null }],
     });
   } finally {
     cleanup();
@@ -392,10 +439,10 @@ test('KnownWordCacheManager preserves cache state key captured before refresh wo
 
     const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
       scope: string;
-      words: string[];
+      notes: Record<string, Array<{ word: string; reading: string | null }>>;
     };
     assert.equal(persisted.scope, '{"refreshMinutes":1,"scope":"all","fieldsWord":"Word"}');
-    assert.deepEqual(persisted.words, ['猫']);
+    assert.deepEqual(persisted.notes, { '1': [{ word: '猫', reading: null }] });
   } finally {
     fs.rmSync(stateDir, { recursive: true, force: true });
   }
@@ -648,3 +695,200 @@ test('KnownWordCacheManager skips immediate append when addMinedWordsImmediately
     cleanup();
   }
 });
+
+test('KnownWordCacheManager disambiguates known words by note reading', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Word: { value: '床' },
+          'Word Reading': { value: 'ゆか' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('床'), true);
+    assert.equal(manager.isKnownWord('床', 'ゆか'), true);
+    assert.equal(manager.isKnownWord('床', 'ユカ'), true);
+    // Same spelling, different word (床/とこ "bed") must not match.
+    assert.equal(manager.isKnownWord('床', 'とこ'), false);
+    // Note readings stay matchable as kana words.
+    assert.equal(manager.isKnownWord('ゆか'), true);
+    assert.equal(manager.isKnownWord('とこ'), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager probes reading fields even with per-deck word fields configured', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Expression',
+    },
+    knownWords: {
+      highlightEnabled: true,
+      decks: {
+        'Kaishi 1.5k': ['Word'],
+      },
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesByQuery.set('deck:"Kaishi 1.5k"', [1]);
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Word: { value: '床' },
+          'Word Reading': { value: 'ゆか' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('床', 'ゆか'), true);
+    assert.equal(manager.isKnownWord('床', 'とこ'), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager matches words without readings in any reading', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Word: { value: '床' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('床'), true);
+    assert.equal(manager.isKnownWord('床', 'とこ'), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager extracts word and reading from furigana word fields', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Word: { value: 'お 決[き]まり' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('お決まり'), true);
+    assert.equal(manager.isKnownWord('お決まり', 'おきまり'), true);
+    assert.equal(manager.isKnownWord('お決まり', 'おさだまり'), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager treats non-kana reading fields as words', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Reading: { value: '漢字' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('漢字'), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test('KnownWordCacheManager keeps kana-only reading notes matchable', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Reading: { value: 'たべる' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('たべる'), true);
+    assert.equal(manager.isKnownWord('タベル'), true);
+  } finally {
+    cleanup();
+  }
+});

src/anki-integration/known-word-cache.ts

@@ -5,6 +5,16 @@ import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getConfiguredWordFieldName } from '../anki-field-config';
 import { AnkiConnectConfig } from '../types/anki';
 import { createLogger } from '../logger';
+import {
+  DEFAULT_KNOWN_WORD_READING_FIELDS,
+  KnownWordEntry,
+  convertKatakanaToHiragana,
+  isReadingFieldName,
+  knownWordEntryListsEqual,
+  normalizeKnownReadingForLookup,
+  normalizeKnownWordEntryList,
+  parseFuriganaAnnotatedText,
+} from './known-word-entries';
 
 const log = createLogger('anki').child('integration.known-word-cache');
 
@@ -79,7 +89,16 @@ interface KnownWordCacheStateV2 {
   readonly notes: Record<string, string[]>;
 }
 
-type KnownWordCacheState = KnownWordCacheStateV1 | KnownWordCacheStateV2;
+interface KnownWordCacheStateV3 {
+  readonly version: 3;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly notes: Record<string, KnownWordEntry[]>;
+}
+
+type KnownWordCacheState = KnownWordCacheStateV1 | KnownWordCacheStateV2 | KnownWordCacheStateV3;
+
+const NO_READING_KEY = '';
 
 interface KnownWordCacheClient {
   findNotes: (
@@ -106,9 +125,12 @@ type KnownWordQueryScope = {
 export class KnownWordCacheManager {
   private knownWordsLastRefreshedAtMs = 0;
   private knownWordsStateKey = '';
-  private knownWords: Set<string> = new Set();
-  private wordReferenceCounts = new Map<string, number>();
-  private noteWordsById = new Map<number, string[]>();
+  // word → (hiragana reading | NO_READING_KEY → note count). NO_READING_KEY
+  // entries fail open: the word matches regardless of the token's reading.
+  private wordReadingCounts = new Map<string, Map<string, number>>();
+  // hiragana reading → note count, so kana tokens still match by reading alone.
+  private readingCounts = new Map<string, number>();
+  private noteEntriesById = new Map<number, KnownWordEntry[]>();
   private knownWordsRefreshTimer: ReturnType<typeof setInterval> | null = null;
   private knownWordsRefreshTimeout: ReturnType<typeof setTimeout> | null = null;
   private isRefreshingKnownWords = false;
@@ -120,13 +142,28 @@ export class KnownWordCacheManager {
     );
   }
 
-  isKnownWord(text: string): boolean {
+  isKnownWord(text: string, reading?: string): boolean {
     if (!this.isKnownWordCacheEnabled()) {
       return false;
     }
 
     const normalized = this.normalizeKnownWordForLookup(text);
-    return normalized.length > 0 ? this.knownWords.has(normalized) : false;
+    if (normalized.length === 0) {
+      return false;
+    }
+
+    const knownReadings = this.wordReadingCounts.get(normalized);
+    if (knownReadings && knownReadings.size > 0) {
+      const normalizedReading =
+        typeof reading === 'string' ? normalizeKnownReadingForLookup(reading) : '';
+      return (
+        normalizedReading.length === 0 ||
+        knownReadings.has(NO_READING_KEY) ||
+        knownReadings.has(normalizedReading)
+      );
+    }
+
+    return this.readingCounts.has(convertKatakanaToHiragana(normalized));
   }
 
   refresh(force = false): Promise<void> {
@@ -173,7 +210,7 @@ export class KnownWordCacheManager {
     let didMutateCache = false;
     const currentStateKey = this.getKnownWordCacheStateKey();
     if (this.knownWordsStateKey && this.knownWordsStateKey !== currentStateKey) {
-      didMutateCache = this.knownWords.size > 0 || this.noteWordsById.size > 0;
+      didMutateCache = this.wordReadingCounts.size > 0 || this.noteEntriesById.size > 0;
       this.clearKnownWordCacheState();
     }
     if (!this.knownWordsStateKey) {
@@ -185,8 +222,8 @@ export class KnownWordCacheManager {
       return didMutateCache;
     }
 
-    const nextWords = this.extractNormalizedKnownWordsFromNoteInfo(noteInfo, preferredFields);
-    const changed = this.replaceNoteSnapshot(noteInfo.noteId, nextWords);
+    const nextEntries = this.extractKnownWordEntriesFromNoteInfo(noteInfo, preferredFields);
+    const changed = this.replaceNoteSnapshot(noteInfo.noteId, nextEntries);
     if (!changed) {
       return didMutateCache;
     }
@@ -198,7 +235,7 @@ export class KnownWordCacheManager {
     log.info(
       'Known-word cache updated in-session',
       `noteId=${noteInfo.noteId}`,
-      `wordCount=${nextWords.length}`,
+      `wordCount=${nextEntries.length}`,
       `scope=${getKnownWordCacheScopeForConfig(this.deps.getConfig())}`,
     );
     return true;
@@ -236,11 +273,11 @@ export class KnownWordCacheManager {
       const noteFieldsById = await this.fetchKnownWordNoteFieldsById();
       const currentNoteIds = Array.from(noteFieldsById.keys()).sort((a, b) => a - b);
 
-      if (this.noteWordsById.size === 0) {
+      if (this.noteEntriesById.size === 0) {
         await this.rebuildFromCurrentNotes(currentNoteIds, noteFieldsById);
       } else {
         const currentNoteIdSet = new Set(currentNoteIds);
-        for (const noteId of Array.from(this.noteWordsById.keys())) {
+        for (const noteId of Array.from(this.noteEntriesById.keys())) {
           if (!currentNoteIdSet.has(noteId)) {
             this.removeNoteSnapshot(noteId);
           }
@@ -251,7 +288,7 @@ export class KnownWordCacheManager {
           for (const noteInfo of noteInfos) {
             this.replaceNoteSnapshot(
               noteInfo.noteId,
-              this.extractNormalizedKnownWordsFromNoteInfo(
+              this.extractKnownWordEntriesFromNoteInfo(
                 noteInfo,
                 noteFieldsById.get(noteInfo.noteId),
               ),
@@ -266,7 +303,7 @@ export class KnownWordCacheManager {
       log.info(
         'Known-word cache refreshed',
         `noteCount=${currentNoteIds.length}`,
-        `wordCount=${this.knownWords.size}`,
+        `wordCount=${this.wordReadingCounts.size}`,
       );
     } catch (error) {
       log.warn('Failed to refresh known-word cache:', (error as Error).message);
@@ -291,7 +328,13 @@ export class KnownWordCacheManager {
 
   private getDefaultKnownWordFields(): string[] {
     const configuredWordField = getConfiguredWordFieldName(this.deps.getConfig());
-    return [...new Set([configuredWordField, 'Word', 'Reading', 'Word Reading'])];
+    return this.withDefaultReadingFields([configuredWordField, 'Word']);
+  }
+
+  // Reading fields are always probed (even when a deck configures explicit
+  // word fields) so entries can carry the reading their note teaches.
+  private withDefaultReadingFields(fields: string[]): string[] {
+    return [...new Set([...fields, ...DEFAULT_KNOWN_WORD_READING_FIELDS])];
   }
 
   private getKnownWordDecks(): string[] {
@@ -337,7 +380,9 @@ export class KnownWordCacheManager {
               .filter((field) => field.length > 0),
           ),
         ];
-        return normalizedFields.length > 0 ? normalizedFields : this.getDefaultKnownWordFields();
+        return normalizedFields.length > 0
+          ? this.withDefaultReadingFields(normalizedFields)
+          : this.getDefaultKnownWordFields();
       }
 
       const deckFields = selectedDeckEntry[1];
@@ -351,7 +396,7 @@ export class KnownWordCacheManager {
           ),
         ];
         if (normalizedFields.length > 0) {
-          return normalizedFields;
+          return this.withDefaultReadingFields(normalizedFields);
         }
       }
 
@@ -382,7 +427,10 @@ export class KnownWordCacheManager {
           : [];
         scopes.push({
           query: `deck:"${escapeAnkiSearchValue(trimmedDeckName)}"`,
-          fields: normalizedFields.length > 0 ? normalizedFields : this.getDefaultKnownWordFields(),
+          fields:
+            normalizedFields.length > 0
+              ? this.withDefaultReadingFields(normalizedFields)
+              : this.getDefaultKnownWordFields(),
         });
       }
       if (scopes.length > 0) {
@@ -490,7 +538,7 @@ export class KnownWordCacheManager {
     for (const noteInfo of noteInfos) {
       this.replaceNoteSnapshot(
         noteInfo.noteId,
-        this.extractNormalizedKnownWordsFromNoteInfo(noteInfo, noteFieldsById.get(noteInfo.noteId)),
+        this.extractKnownWordEntriesFromNoteInfo(noteInfo, noteFieldsById.get(noteInfo.noteId)),
       );
     }
   }
@@ -519,56 +567,77 @@ export class KnownWordCacheManager {
     return noteInfos;
   }
 
-  private replaceNoteSnapshot(noteId: number, nextWords: string[]): boolean {
-    const normalizedWords = normalizeKnownWordList(nextWords);
-    const previousWords = this.noteWordsById.get(noteId) ?? [];
-    if (knownWordListsEqual(previousWords, normalizedWords)) {
+  private replaceNoteSnapshot(noteId: number, nextEntries: KnownWordEntry[]): boolean {
+    const normalizedEntries = normalizeKnownWordEntryList(nextEntries);
+    const previousEntries = this.noteEntriesById.get(noteId) ?? [];
+    if (knownWordEntryListsEqual(previousEntries, normalizedEntries)) {
       return false;
     }
 
-    this.removeWordsFromCounts(previousWords);
-    if (normalizedWords.length > 0) {
-      this.noteWordsById.set(noteId, normalizedWords);
-      this.addWordsToCounts(normalizedWords);
+    this.removeEntriesFromCounts(previousEntries);
+    if (normalizedEntries.length > 0) {
+      this.noteEntriesById.set(noteId, normalizedEntries);
+      this.addEntriesToCounts(normalizedEntries);
     } else {
-      this.noteWordsById.delete(noteId);
+      this.noteEntriesById.delete(noteId);
     }
     return true;
   }
 
   private removeNoteSnapshot(noteId: number): void {
-    const previousWords = this.noteWordsById.get(noteId);
-    if (!previousWords) {
+    const previousEntries = this.noteEntriesById.get(noteId);
+    if (!previousEntries) {
       return;
     }
-    this.noteWordsById.delete(noteId);
-    this.removeWordsFromCounts(previousWords);
+    this.noteEntriesById.delete(noteId);
+    this.removeEntriesFromCounts(previousEntries);
   }
 
-  private addWordsToCounts(words: string[]): void {
-    for (const word of words) {
-      const nextCount = (this.wordReferenceCounts.get(word) ?? 0) + 1;
-      this.wordReferenceCounts.set(word, nextCount);
-      this.knownWords.add(word);
+  private addEntriesToCounts(entries: KnownWordEntry[]): void {
+    for (const entry of entries) {
+      const readingKey = entry.reading ?? NO_READING_KEY;
+      let readings = this.wordReadingCounts.get(entry.word);
+      if (!readings) {
+        readings = new Map();
+        this.wordReadingCounts.set(entry.word, readings);
+      }
+      readings.set(readingKey, (readings.get(readingKey) ?? 0) + 1);
+      if (entry.reading) {
+        this.readingCounts.set(entry.reading, (this.readingCounts.get(entry.reading) ?? 0) + 1);
+      }
     }
   }
 
-  private removeWordsFromCounts(words: string[]): void {
-    for (const word of words) {
-      const nextCount = (this.wordReferenceCounts.get(word) ?? 0) - 1;
-      if (nextCount > 0) {
-        this.wordReferenceCounts.set(word, nextCount);
-      } else {
-        this.wordReferenceCounts.delete(word);
-        this.knownWords.delete(word);
+  private removeEntriesFromCounts(entries: KnownWordEntry[]): void {
+    for (const entry of entries) {
+      const readingKey = entry.reading ?? NO_READING_KEY;
+      const readings = this.wordReadingCounts.get(entry.word);
+      if (readings) {
+        const nextCount = (readings.get(readingKey) ?? 0) - 1;
+        if (nextCount > 0) {
+          readings.set(readingKey, nextCount);
+        } else {
+          readings.delete(readingKey);
+          if (readings.size === 0) {
+            this.wordReadingCounts.delete(entry.word);
+          }
+        }
+      }
+      if (entry.reading) {
+        const nextReadingCount = (this.readingCounts.get(entry.reading) ?? 0) - 1;
+        if (nextReadingCount > 0) {
+          this.readingCounts.set(entry.reading, nextReadingCount);
+        } else {
+          this.readingCounts.delete(entry.reading);
+        }
       }
     }
   }
 
   private clearInMemoryState(): void {
-    this.knownWords = new Set();
-    this.wordReferenceCounts = new Map();
-    this.noteWordsById = new Map();
+    this.wordReadingCounts = new Map();
+    this.readingCounts = new Map();
+    this.noteEntriesById = new Map();
     this.knownWordsLastRefreshedAtMs = 0;
   }
 
@@ -601,32 +670,48 @@ export class KnownWordCacheManager {
       }
 
       this.clearInMemoryState();
+      if (parsed.version === 3) {
+        for (const [noteIdKey, entries] of Object.entries(parsed.notes)) {
+          const noteId = Number.parseInt(noteIdKey, 10);
+          if (!Number.isInteger(noteId) || noteId <= 0) {
+            continue;
+          }
+          const normalizedEntries = normalizeKnownWordEntryList(entries);
+          if (normalizedEntries.length === 0) {
+            continue;
+          }
+          this.noteEntriesById.set(noteId, normalizedEntries);
+          this.addEntriesToCounts(normalizedEntries);
+        }
+        this.knownWordsLastRefreshedAtMs = parsed.refreshedAtMs;
+        this.knownWordsStateKey = parsed.scope;
+        return;
+      }
+
       if (parsed.version === 2) {
+        // Older states have no readings; load them reading-less (fail-open,
+        // matching the old behavior) but leave the cache marked stale so the
+        // next refresh upgrades entries with readings from Anki.
         for (const [noteIdKey, words] of Object.entries(parsed.notes)) {
           const noteId = Number.parseInt(noteIdKey, 10);
           if (!Number.isInteger(noteId) || noteId <= 0) {
             continue;
           }
-          const normalizedWords = normalizeKnownWordList(words);
-          if (normalizedWords.length === 0) {
+          const normalizedEntries = normalizeKnownWordEntryList(
+            words.map((word) => ({ word: this.normalizeKnownWordForLookup(word), reading: null })),
+          );
+          if (normalizedEntries.length === 0) {
             continue;
           }
-          this.noteWordsById.set(noteId, normalizedWords);
-          this.addWordsToCounts(normalizedWords);
-        }
-      } else {
-        for (const value of parsed.words) {
-          const normalized = this.normalizeKnownWordForLookup(value);
-          if (!normalized) {
-            continue;
-          }
-          this.knownWords.add(normalized);
-          this.wordReferenceCounts.set(normalized, 1);
+          this.noteEntriesById.set(noteId, normalizedEntries);
+          this.addEntriesToCounts(normalizedEntries);
         }
+        this.knownWordsStateKey = parsed.scope;
+        return;
       }
 
-      this.knownWordsLastRefreshedAtMs = parsed.refreshedAtMs;
-      this.knownWordsStateKey = parsed.scope;
+      // v1 has no per-note snapshots to convert; refetch from Anki.
+      this.knownWordsStateKey = this.getKnownWordCacheStateKey();
     } catch (error) {
       log.warn('Failed to load known-word cache state:', (error as Error).message);
       this.clearInMemoryState();
@@ -636,18 +721,17 @@ export class KnownWordCacheManager {
 
   private persistKnownWordCacheState(): void {
     try {
-      const notes: Record<string, string[]> = {};
-      for (const [noteId, words] of this.noteWordsById.entries()) {
-        if (words.length > 0) {
-          notes[String(noteId)] = words;
+      const notes: Record<string, KnownWordEntry[]> = {};
+      for (const [noteId, entries] of this.noteEntriesById.entries()) {
+        if (entries.length > 0) {
+          notes[String(noteId)] = entries;
         }
       }
 
-      const state: KnownWordCacheStateV2 = {
-        version: 2,
+      const state: KnownWordCacheStateV3 = {
+        version: 3,
         refreshedAtMs: this.knownWordsLastRefreshedAtMs,
         scope: this.knownWordsStateKey,
-        words: Array.from(this.knownWords),
         notes,
       };
       fs.writeFileSync(this.statePath, JSON.stringify(state), 'utf-8');
@@ -659,14 +743,18 @@ export class KnownWordCacheManager {
   private isKnownWordCacheStateValid(value: unknown): value is KnownWordCacheState {
     if (typeof value !== 'object' || value === null) return false;
     const candidate = value as Record<string, unknown>;
-    if (candidate.version !== 1 && candidate.version !== 2) return false;
-    if (typeof candidate.refreshedAtMs !== 'number') return false;
-    if (typeof candidate.scope !== 'string') return false;
-    if (!Array.isArray(candidate.words)) return false;
-    if (!candidate.words.every((entry: unknown) => typeof entry === 'string')) {
+    if (candidate.version !== 1 && candidate.version !== 2 && candidate.version !== 3) {
       return false;
     }
-    if (candidate.version === 2) {
+    if (typeof candidate.refreshedAtMs !== 'number') return false;
+    if (typeof candidate.scope !== 'string') return false;
+    if (candidate.version !== 3) {
+      if (!Array.isArray(candidate.words)) return false;
+      if (!candidate.words.every((entry: unknown) => typeof entry === 'string')) {
+        return false;
+      }
+    }
+    if (candidate.version === 2 || candidate.version === 3) {
       if (
         typeof candidate.notes !== 'object' ||
         candidate.notes === null ||
@@ -674,10 +762,18 @@ export class KnownWordCacheManager {
       ) {
         return false;
       }
+      const isValidNoteEntry =
+        candidate.version === 2
+          ? (entry: unknown): boolean => typeof entry === 'string'
+          : (entry: unknown): boolean =>
+              typeof entry === 'object' &&
+              entry !== null &&
+              typeof (entry as KnownWordEntry).word === 'string' &&
+              ((entry as KnownWordEntry).reading === null ||
+                typeof (entry as KnownWordEntry).reading === 'string');
       if (
         !Object.values(candidate.notes as Record<string, unknown>).every(
-          (entry) =>
-            Array.isArray(entry) && entry.every((word: unknown) => typeof word === 'string'),
+          (noteEntries) => Array.isArray(noteEntries) && noteEntries.every(isValidNoteEntry),
         )
       ) {
         return false;
@@ -686,11 +782,12 @@ export class KnownWordCacheManager {
     return true;
   }
 
-  private extractNormalizedKnownWordsFromNoteInfo(
+  private extractKnownWordEntriesFromNoteInfo(
     noteInfo: KnownWordCacheNoteInfo,
     preferredFields = this.getConfiguredFields(),
-  ): string[] {
-    const words: string[] = [];
+  ): KnownWordEntry[] {
+    const wordValues: string[] = [];
+    let noteReading: string | null = null;
     for (const preferredField of preferredFields) {
       const fieldName = resolveFieldName(Object.keys(noteInfo.fields), preferredField);
       if (!fieldName) continue;
@@ -698,12 +795,36 @@ export class KnownWordCacheManager {
       const raw = noteInfo.fields[fieldName]?.value;
       if (!raw) continue;
 
-      const normalized = this.normalizeKnownWordForLookup(raw);
-      if (normalized) {
-        words.push(normalized);
+      const cleaned = this.normalizeRawKnownWordValue(raw);
+      if (!cleaned) continue;
+
+      if (isReadingFieldName(preferredField)) {
+        const normalizedReading = normalizeKnownReadingForLookup(cleaned);
+        if (normalizedReading) {
+          noteReading ??= normalizedReading;
+          continue;
+        }
+        // Non-kana content in a reading field: treat it as a word so decks
+        // with repurposed reading fields keep matching (fail-open).
       }
+      wordValues.push(cleaned);
     }
-    return normalizeKnownWordList(words);
+
+    const entries: KnownWordEntry[] = [];
+    for (const value of wordValues) {
+      const parsed = parseFuriganaAnnotatedText(value);
+      const word = parsed.text.trim().toLowerCase();
+      if (!word) continue;
+      const inlineReading = parsed.reading ? normalizeKnownReadingForLookup(parsed.reading) : '';
+      entries.push({ word, reading: inlineReading || noteReading });
+    }
+
+    // Kana-only notes (reading field but no word field) stay matchable.
+    if (entries.length === 0 && noteReading) {
+      entries.push({ word: noteReading, reading: noteReading });
+    }
+
+    return normalizeKnownWordEntryList(entries);
   }
 
   private normalizeRawKnownWordValue(value: string): string {
@@ -718,22 +839,6 @@ export class KnownWordCacheManager {
   }
 }
 
-function normalizeKnownWordList(words: string[]): string[] {
-  return [...new Set(words.map((word) => word.trim()).filter((word) => word.length > 0))].sort();
-}
-
-function knownWordListsEqual(left: string[], right: string[]): boolean {
-  if (left.length !== right.length) {
-    return false;
-  }
-  for (let index = 0; index < left.length; index += 1) {
-    if (left[index] !== right[index]) {
-      return false;
-    }
-  }
-  return true;
-}
-
 function resolveFieldName(availableFieldNames: string[], preferredName: string): string | null {
   const exact = availableFieldNames.find((name) => name === preferredName);
   if (exact) return exact;

src/anki-integration/known-word-entries.ts

@@ -0,0 +1,113 @@
+// Known-word cache entries pair a word with the reading its Anki note teaches,
+// so spelling collisions across readings (e.g. 床/ゆか vs 床/とこ) don't mark
+// unrelated words as known. reading === null means the note carries no usable
+// reading and the word matches in any reading (fail-open).
+export interface KnownWordEntry {
+  word: string;
+  reading: string | null;
+}
+
+const KATAKANA_TO_HIRAGANA_OFFSET = 0x60;
+const KATAKANA_CODEPOINT_START = 0x30a1;
+const KATAKANA_CODEPOINT_END = 0x30f6;
+const FURIGANA_SEGMENT_PATTERN = /([^\s　\[\]]*)\[([^\]]*)\]/g;
+const FURIGANA_BRACKET_PATTERN = /\[[^\]]*\]/g;
+const WHITESPACE_PATTERN = /[\s　]+/g;
+
+// Reading-bearing field names probed on every known-word note, in addition to
+// any configured word fields (covers Kaishi's "Word Reading" and Lapis's
+// "ExpressionReading" note types).
+export const DEFAULT_KNOWN_WORD_READING_FIELDS = [
+  'Reading',
+  'Word Reading',
+  'ExpressionReading',
+  'Expression Reading',
+];
+
+export function isReadingFieldName(fieldName: string): boolean {
+  return /reading/i.test(fieldName);
+}
+
+export function convertKatakanaToHiragana(text: string): string {
+  let converted = '';
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code !== undefined && code >= KATAKANA_CODEPOINT_START && code <= KATAKANA_CODEPOINT_END) {
+      converted += String.fromCodePoint(code - KATAKANA_TO_HIRAGANA_OFFSET);
+      continue;
+    }
+    converted += char;
+  }
+  return converted;
+}
+
+function isHiraganaReadingChar(char: string): boolean {
+  const code = char.codePointAt(0);
+  if (code === undefined) {
+    return false;
+  }
+  return (code >= 0x3041 && code <= 0x309f) || code === 0x30fc;
+}
+
+// Splits Anki furigana syntax (`床[とこ]`, `お 決[き]まり`) into base text and
+// reading. Values without brackets pass through with reading null.
+export function parseFuriganaAnnotatedText(value: string): {
+  text: string;
+  reading: string | null;
+} {
+  if (!value.includes('[')) {
+    return { text: value, reading: null };
+  }
+  const text = value.replace(FURIGANA_BRACKET_PATTERN, '').replace(WHITESPACE_PATTERN, '');
+  const reading = value.replace(FURIGANA_SEGMENT_PATTERN, '$2').replace(WHITESPACE_PATTERN, '');
+  return { text, reading: reading.length > 0 ? reading : null };
+}
+
+// Returns the hiragana-normalized reading, or '' when the value is not a
+// plausible kana reading (callers fall back to text-only matching then).
+export function normalizeKnownReadingForLookup(value: string): string {
+  const parsed = parseFuriganaAnnotatedText(value.trim());
+  const candidate = (parsed.reading ?? parsed.text).trim();
+  if (!candidate) {
+    return '';
+  }
+  const hiragana = convertKatakanaToHiragana(candidate);
+  for (const char of hiragana) {
+    if (!isHiraganaReadingChar(char)) {
+      return '';
+    }
+  }
+  return hiragana;
+}
+
+export function makeKnownWordEntryKey(entry: KnownWordEntry): string {
+  return `${entry.word}\u0000${entry.reading ?? ''}`;
+}
+
+export function normalizeKnownWordEntryList(entries: KnownWordEntry[]): KnownWordEntry[] {
+  const byKey = new Map<string, KnownWordEntry>();
+  for (const entry of entries) {
+    const word = entry.word.trim();
+    if (!word) {
+      continue;
+    }
+    const reading = entry.reading?.trim() || null;
+    const normalized: KnownWordEntry = { word, reading };
+    byKey.set(makeKnownWordEntryKey(normalized), normalized);
+  }
+  return [...byKey.values()].sort((left, right) =>
+    makeKnownWordEntryKey(left).localeCompare(makeKnownWordEntryKey(right)),
+  );
+}
+
+export function knownWordEntryListsEqual(left: KnownWordEntry[], right: KnownWordEntry[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (makeKnownWordEntryKey(left[index]!) !== makeKnownWordEntryKey(right[index]!)) {
+      return false;
+    }
+  }
+  return true;
+}

src/anki-integration/media-source.test.ts

@@ -1,7 +1,34 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
-import { resolveMediaGenerationInputPath } from './media-source';
+import * as mediaSource from './media-source';
+import { toMpvEdlValue } from './mpv-edl-test-utils';
+
+const { resolveMediaGenerationInputPath } = mediaSource;
+
+type StructuredMediaInput = {
+  path: string;
+  source: string;
+  singleResolvedStream: boolean;
+  inputOptions?: {
+    reconnect?: boolean;
+    userAgent?: string;
+    headers?: Record<string, string>;
+  };
+};
+
+type StructuredMediaResolver = (
+  mpvClient: Parameters<typeof resolveMediaGenerationInputPath>[0],
+  kind?: Parameters<typeof resolveMediaGenerationInputPath>[1],
+  options?: {
+    getCachedMediaPath?: (
+      currentVideoPath: string,
+      kind: Parameters<typeof resolveMediaGenerationInputPath>[1],
+    ) => Promise<string | null>;
+    remoteCacheMode?: 'optional' | 'required';
+    logDebug?: (message: string) => void;
+  },
+) => Promise<StructuredMediaInput | null>;
 
 test('resolveMediaGenerationInputPath keeps local file paths', async () => {
   const result = await resolveMediaGenerationInputPath({
@@ -27,9 +54,11 @@ test('resolveMediaGenerationInputPath prefers stream-open-filename for remote me
 });
 
 test('resolveMediaGenerationInputPath unwraps mpv edl source for audio and video', async () => {
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
   const edlSource = [
-    'edl://!new_stream;!no_clip;!no_chapters;%70%https://audio.example/videoplayback?mime=audio%2Fwebm',
-    '!new_stream;!no_clip;!no_chapters;%69%https://video.example/videoplayback?mime=video%2Fmp4',
+    `edl://!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(audioUrl)}`,
+    `!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(videoUrl)}`,
     '!global_tags,title=test',
   ].join(';');
 
@@ -48,8 +77,52 @@ test('resolveMediaGenerationInputPath unwraps mpv edl source for audio and video
     'video',
   );
 
-  assert.equal(audioResult, 'https://audio.example/videoplayback?mime=audio%2Fwebm');
-  assert.equal(videoResult, 'https://video.example/videoplayback?mime=video%2Fmp4');
+  assert.equal(audioResult, audioUrl);
+  assert.equal(videoResult, videoUrl);
+});
+
+test('resolveMediaGenerationInputPath strips mpv edl segment options from unwrapped streams', async () => {
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const signedVideoUrl =
+    'https://rr1---sn.example.googlevideo.com/videoplayback?mime=video%2Fmp4&mn=sn-a,sn-b&lsig=abc%3D';
+  const edlSource = [
+    `edl://!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(audioUrl)}`,
+    `!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(signedVideoUrl)},title=clip,length=73,timestamps=chapters`,
+    '!global_tags,title=test',
+  ].join(';');
+
+  const result = await resolveMediaGenerationInputPath(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async () => edlSource,
+    },
+    'video',
+  );
+
+  assert.equal(result, signedVideoUrl);
+});
+
+test('resolveMediaGenerationInputPath ignores length-guarded URLs in mpv edl headers', async () => {
+  const initUrl = 'https://init.example/init.mp4';
+  const audioUrl = 'https://audio.example/stream';
+  const videoUrl = 'https://video.example/stream';
+  const edlSource = [
+    `edl://!mp4_dash,init=${toMpvEdlValue(initUrl)}`,
+    '!new_stream',
+    toMpvEdlValue(audioUrl),
+    '!new_stream',
+    toMpvEdlValue(videoUrl),
+  ].join(';');
+
+  const audioResult = await resolveMediaGenerationInputPath(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async () => edlSource,
+    },
+    'audio',
+  );
+
+  assert.equal(audioResult, audioUrl);
 });
 
 test('resolveMediaGenerationInputPath falls back to currentVideoPath when stream-open-filename fails', async () => {
@@ -62,3 +135,213 @@ test('resolveMediaGenerationInputPath falls back to currentVideoPath when stream
 
   assert.equal(result, 'https://www.youtube.com/watch?v=abc123');
 });
+
+test('resolveMediaGenerationInput returns single-stream metadata for mpv EDL URLs', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
+  const edlSource = [
+    `edl://!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(audioUrl)}`,
+    `!new_stream;!no_clip;!no_chapters;${toMpvEdlValue(videoUrl)}`,
+  ].join(';');
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async (name: string) => {
+        if (name === 'stream-open-filename') return edlSource;
+        if (name === 'user-agent') return 'Mozilla/5.0';
+        if (name === 'http-header-fields') {
+          return ['Cookie: SID=secret', 'Referer: https://www.youtube.com/', 'X-Test: ok'];
+        }
+        return null;
+      },
+    },
+    'audio',
+  );
+
+  assert.equal(result?.path, audioUrl);
+  assert.equal(result?.singleResolvedStream, true);
+  assert.equal(result?.inputOptions?.reconnect, true);
+  assert.equal(result?.inputOptions?.userAgent, 'Mozilla/5.0');
+  assert.deepEqual(result?.inputOptions?.headers, {
+    Referer: 'https://www.youtube.com/',
+    'X-Test': 'ok',
+  });
+});
+
+test('resolveMediaGenerationInput reads file-local mpv request options', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async (name: string) => {
+        if (name === 'stream-open-filename') {
+          return 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123';
+        }
+        if (name === 'file-local-options/user-agent') return 'SubMiner Test Agent';
+        if (name === 'options/http-header-fields') return ['X-Shared: ok'];
+        if (name === 'file-local-options/http-header-fields') {
+          return ['Cookie: SID=secret', 'Referer: https://m.youtube.com/', 'X-Local: yes'];
+        }
+        return null;
+      },
+    },
+    'video',
+  );
+
+  assert.equal(result?.path, 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123');
+  assert.equal(result?.singleResolvedStream, true);
+  assert.equal(result?.inputOptions?.userAgent, 'SubMiner Test Agent');
+  assert.deepEqual(result?.inputOptions?.headers, {
+    'X-Shared': 'ok',
+    Referer: 'https://m.youtube.com/',
+    'X-Local': 'yes',
+    Origin: 'https://www.youtube.com',
+  });
+});
+
+test('resolveMediaGenerationInput prefers a ready cached media file for YouTube extraction', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async () => 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123',
+    },
+    'video',
+    {
+      getCachedMediaPath: async () => '/tmp/subminer-youtube-media-cache/abc123/media.mkv',
+    },
+  );
+
+  assert.equal(result?.path, '/tmp/subminer-youtube-media-cache/abc123/media.mkv');
+  assert.equal(result?.source, 'youtube-cache');
+  assert.equal(result?.singleResolvedStream, false);
+  assert.equal(result?.inputOptions, undefined);
+});
+
+test('resolveMediaGenerationInput debug-logs sanitized YouTube cache hits', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+  const logs: string[] = [];
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123&signature=secret',
+      requestProperty: async () => 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123',
+    },
+    'video',
+    {
+      getCachedMediaPath: async () => '/tmp/subminer-youtube-media-cache/abc123/media.mkv',
+      logDebug: (message) => logs.push(message),
+    },
+  );
+
+  assert.equal(result?.source, 'youtube-cache');
+  assert.match(logs.join('\n'), /kind=video source=youtube-cache/);
+  assert.match(
+    logs.join('\n'),
+    /input=local:\/tmp\/subminer-youtube-media-cache\/abc123\/media\.mkv/,
+  );
+  assert.match(logs.join('\n'), /current=remote:www\.youtube\.com/);
+  assert.doesNotMatch(logs.join('\n'), /signature=secret|videoplayback/);
+});
+
+test('resolveMediaGenerationInput does not fall back to direct remote streams when cache is required', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async () => 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123',
+    },
+    'video',
+    {
+      getCachedMediaPath: async () => null,
+      remoteCacheMode: 'required',
+    },
+  );
+
+  assert.equal(result, null);
+});
+
+test('resolveMediaGenerationInput falls back when optional cache lookup fails', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+      requestProperty: async () => 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123',
+    },
+    'video',
+    {
+      getCachedMediaPath: async () => {
+        throw new Error('cache unavailable');
+      },
+    },
+  );
+
+  assert.equal(result?.path, 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123');
+  assert.equal(result?.source, 'stream-open-filename');
+});
+
+test('resolveMediaGenerationInput debug-logs sanitized required-cache misses', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+  const logs: string[] = [];
+
+  const result = await resolver!(
+    {
+      currentVideoPath: 'https://www.youtube.com/watch?v=abc123&signature=secret',
+      requestProperty: async () => 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123',
+    },
+    'video',
+    {
+      getCachedMediaPath: async () => null,
+      remoteCacheMode: 'required',
+      logDebug: (message) => logs.push(message),
+    },
+  );
+
+  assert.equal(result, null);
+  assert.match(logs.join('\n'), /kind=video source=cache-miss/);
+  assert.match(logs.join('\n'), /mode=required/);
+  assert.match(logs.join('\n'), /current=remote:www\.youtube\.com/);
+  assert.doesNotMatch(logs.join('\n'), /signature=secret|videoplayback|googlevideo/);
+});

src/anki-integration/media-source.ts

@@ -1,7 +1,58 @@
 import { isRemoteMediaPath } from '../jimaku/utils';
+import type { MediaInput, MediaInputOptions } from '../media-input';
 import type { MpvClient } from '../types/runtime';
+import { extractFileUrlsFromMpvEdlSource } from './mpv-edl';
 
 export type MediaGenerationKind = 'audio' | 'video';
+export type MediaGenerationInputSource =
+  | 'current-path'
+  | 'stream-open-filename'
+  | 'edl-stream'
+  | 'youtube-cache';
+
+export interface ResolvedMediaGenerationInput {
+  path: string;
+  kind: MediaGenerationKind;
+  source: MediaGenerationInputSource;
+  singleResolvedStream: boolean;
+  inputOptions?: MediaInputOptions;
+}
+
+export interface MediaGenerationInputResolverOptions {
+  getCachedMediaPath?: (
+    currentVideoPath: string,
+    kind: MediaGenerationKind,
+  ) => Promise<string | null>;
+  remoteCacheMode?: 'optional' | 'required';
+  logDebug?: (message: string) => void;
+}
+
+export function resolveAudioStreamIndexForMediaGeneration(
+  input: MediaInput,
+  audioStreamIndex: number | null | undefined,
+): number | undefined {
+  if (typeof input === 'object' && 'source' in input && input.source === 'youtube-cache') {
+    return undefined;
+  }
+  return audioStreamIndex ?? undefined;
+}
+
+const BLOCKED_HTTP_HEADER_NAMES = new Set(['authorization', 'cookie', 'proxy-authorization']);
+const HTTP_HEADER_FIELD_PROPERTY_NAMES = [
+  'http-header-fields',
+  'options/http-header-fields',
+  'file-local-options/http-header-fields',
+] as const;
+const USER_AGENT_PROPERTY_NAMES = [
+  'file-local-options/user-agent',
+  'options/user-agent',
+  'user-agent',
+] as const;
+const REFERRER_PROPERTY_NAMES = [
+  'file-local-options/referrer',
+  'options/referrer',
+  'referrer',
+] as const;
 
 function trimToNonEmptyString(value: unknown): string | null {
   if (typeof value !== 'string') {
@@ -11,10 +62,20 @@ function trimToNonEmptyString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function normalizeHeaderName(value: string): string | null {
+  const trimmed = value.trim();
+  if (!/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(trimmed)) {
+    return null;
+  }
+  if (BLOCKED_HTTP_HEADER_NAMES.has(trimmed.toLowerCase())) {
+    return null;
+  }
+  return trimmed;
+}
+
 function extractUrlsFromMpvEdlSource(source: string): string[] {
-  const matches = source.matchAll(/%\d+%(https?:\/\/.*?)(?=;!new_stream|;!global_tags|$)/gms);
-  return [...matches]
-    .map((match) => trimToNonEmptyString(match[1]))
+  return extractFileUrlsFromMpvEdlSource(source)
+    .map((value) => trimToNonEmptyString(value))
     .filter((value): value is string => value !== null);
 }
 
@@ -53,6 +114,317 @@ function resolvePreferredUrlFromMpvEdlSource(
   return kind === 'audio' ? (urls[0] ?? null) : (urls[urls.length - 1] ?? null);
 }
 
+function getHostname(value: string): string | null {
+  try {
+    return new URL(value).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function matchesHost(hostname: string, expectedHost: string): boolean {
+  return hostname === expectedHost || hostname.endsWith(`.${expectedHost}`);
+}
+
+function isGoogleVideoMediaPath(value: string): boolean {
+  const host = getHostname(value);
+  return Boolean(host && matchesHost(host, 'googlevideo.com'));
+}
+
+function describeMediaPathForDebugLog(value: string): string {
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'http:' || url.protocol === 'https:') {
+      return `remote:${url.hostname.toLowerCase() || 'unknown'}`;
+    }
+    return `${url.protocol.replace(/:$/, '')}:`;
+  } catch {
+    // Not a URL; treat as a local file path below.
+  }
+
+  if (value.startsWith('edl://')) {
+    return 'edl:';
+  }
+
+  return `local:${value}`;
+}
+
+function logMediaResolutionDebug(
+  options: MediaGenerationInputResolverOptions,
+  message: string,
+): void {
+  if (!options.logDebug) {
+    return;
+  }
+  try {
+    options.logDebug(`[media-source] ${message}`);
+  } catch {
+    // Debug logging should not affect media generation.
+  }
+}
+
+function logResolvedMediaGenerationInput(
+  options: MediaGenerationInputResolverOptions,
+  currentVideoPath: string,
+  result: ResolvedMediaGenerationInput,
+): void {
+  logMediaResolutionDebug(
+    options,
+    [
+      `kind=${result.kind}`,
+      `source=${result.source}`,
+      `input=${describeMediaPathForDebugLog(result.path)}`,
+      `current=${describeMediaPathForDebugLog(currentVideoPath)}`,
+      `singleResolvedStream=${result.singleResolvedStream}`,
+    ].join(' '),
+  );
+}
+
+function logMediaGenerationInputMiss(
+  options: MediaGenerationInputResolverOptions,
+  kind: MediaGenerationKind,
+  currentVideoPath: string,
+  reason: string,
+): void {
+  logMediaResolutionDebug(
+    options,
+    [
+      `kind=${kind}`,
+      'source=cache-miss',
+      `reason=${reason}`,
+      `mode=${options.remoteCacheMode ?? 'optional'}`,
+      `current=${describeMediaPathForDebugLog(currentVideoPath)}`,
+    ].join(' '),
+  );
+}
+
+function setHeaderIfMissing(headers: Record<string, string>, name: string, value: string): void {
+  const lowerName = name.toLowerCase();
+  if (!Object.keys(headers).some((existing) => existing.toLowerCase() === lowerName)) {
+    headers[name] = value;
+  }
+}
+
+function parseMpvHeaderField(value: string): [string, string] | null {
+  const separatorIndex = value.indexOf(':');
+  if (separatorIndex <= 0) {
+    return null;
+  }
+
+  const name = normalizeHeaderName(value.slice(0, separatorIndex));
+  const headerValue = trimToNonEmptyString(value.slice(separatorIndex + 1));
+  if (!name || !headerValue) {
+    return null;
+  }
+  return [name, headerValue.replace(/[\r\n]+/g, ' ')];
+}
+
+function toHeaderFields(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === 'string');
+  }
+  if (typeof value === 'string') {
+    return value
+      .split(/\r?\n/)
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0);
+  }
+  return [];
+}
+
+async function requestOptionalMpvProperty(
+  mpvClient: Pick<MpvClient, 'requestProperty'>,
+  name: string,
+): Promise<unknown> {
+  if (!mpvClient.requestProperty) {
+    return null;
+  }
+
+  try {
+    return await mpvClient.requestProperty(name);
+  } catch {
+    return null;
+  }
+}
+
+async function requestFirstNonEmptyStringProperty(
+  mpvClient: Pick<MpvClient, 'requestProperty'>,
+  names: readonly string[],
+): Promise<string | null> {
+  for (const name of names) {
+    const value = trimToNonEmptyString(await requestOptionalMpvProperty(mpvClient, name));
+    if (value) {
+      return value;
+    }
+  }
+  return null;
+}
+
+async function resolveRemoteInputOptions(
+  mpvClient: Pick<MpvClient, 'requestProperty'>,
+  resolvedPath: string,
+): Promise<MediaInputOptions | undefined> {
+  if (!isRemoteMediaPath(resolvedPath) || !mpvClient.requestProperty) {
+    return undefined;
+  }
+
+  const headers: Record<string, string> = {};
+  for (const propertyName of HTTP_HEADER_FIELD_PROPERTY_NAMES) {
+    const mpvHeaderFields = toHeaderFields(
+      await requestOptionalMpvProperty(mpvClient, propertyName),
+    );
+    for (const field of mpvHeaderFields) {
+      const parsed = parseMpvHeaderField(field);
+      if (parsed) {
+        headers[parsed[0]] = parsed[1];
+      }
+    }
+  }
+
+  const userAgent = await requestFirstNonEmptyStringProperty(mpvClient, USER_AGENT_PROPERTY_NAMES);
+  const referrer = await requestFirstNonEmptyStringProperty(mpvClient, REFERRER_PROPERTY_NAMES);
+  if (referrer) {
+    setHeaderIfMissing(headers, 'Referer', referrer);
+  }
+  if (isGoogleVideoMediaPath(resolvedPath)) {
+    setHeaderIfMissing(headers, 'Referer', 'https://www.youtube.com/');
+    setHeaderIfMissing(headers, 'Origin', 'https://www.youtube.com');
+  }
+
+  return {
+    reconnect: true,
+    ...(userAgent ? { userAgent } : {}),
+    ...(Object.keys(headers).length > 0 ? { headers } : {}),
+  };
+}
+
+async function toResolvedMediaGenerationInput(
+  mpvClient: Pick<MpvClient, 'requestProperty'>,
+  path: string,
+  kind: MediaGenerationKind,
+  source: MediaGenerationInputSource,
+  singleResolvedStream: boolean,
+): Promise<ResolvedMediaGenerationInput> {
+  const inputOptions = await resolveRemoteInputOptions(mpvClient, path);
+  return {
+    path,
+    kind,
+    source,
+    singleResolvedStream,
+    ...(inputOptions ? { inputOptions } : {}),
+  };
+}
+
+export async function resolveMediaGenerationInput(
+  mpvClient: Pick<MpvClient, 'currentVideoPath' | 'requestProperty'> | null | undefined,
+  kind: MediaGenerationKind = 'video',
+  options: MediaGenerationInputResolverOptions = {},
+): Promise<ResolvedMediaGenerationInput | null> {
+  const currentVideoPath = trimToNonEmptyString(mpvClient?.currentVideoPath);
+  if (!currentVideoPath) {
+    logMediaResolutionDebug(options, `kind=${kind} source=none reason=no-current-video`);
+    return null;
+  }
+
+  if (!isRemoteMediaPath(currentVideoPath)) {
+    const result: ResolvedMediaGenerationInput = {
+      path: currentVideoPath,
+      kind,
+      source: 'current-path',
+      singleResolvedStream: false,
+    };
+    logResolvedMediaGenerationInput(options, currentVideoPath, result);
+    return result;
+  }
+
+  let cachedPath: string | null = null;
+  if (options.getCachedMediaPath) {
+    try {
+      cachedPath = trimToNonEmptyString(await options.getCachedMediaPath(currentVideoPath, kind));
+    } catch {
+      cachedPath = null;
+    }
+  }
+  if (cachedPath) {
+    const result: ResolvedMediaGenerationInput = {
+      path: cachedPath,
+      kind,
+      source: 'youtube-cache',
+      singleResolvedStream: false,
+    };
+    logResolvedMediaGenerationInput(options, currentVideoPath, result);
+    return result;
+  }
+
+  if (options.remoteCacheMode === 'required') {
+    logMediaGenerationInputMiss(options, kind, currentVideoPath, 'required-cache-unavailable');
+    return null;
+  }
+
+  if (!mpvClient?.requestProperty) {
+    const result: ResolvedMediaGenerationInput = {
+      path: currentVideoPath,
+      kind,
+      source: 'current-path',
+      singleResolvedStream: false,
+    };
+    logResolvedMediaGenerationInput(options, currentVideoPath, result);
+    return result;
+  }
+
+  try {
+    const streamOpenFilename = trimToNonEmptyString(
+      await mpvClient.requestProperty('stream-open-filename'),
+    );
+    if (streamOpenFilename?.startsWith('edl://')) {
+      const preferredUrl = resolvePreferredUrlFromMpvEdlSource(streamOpenFilename, kind);
+      if (preferredUrl) {
+        const result = await toResolvedMediaGenerationInput(
+          mpvClient,
+          preferredUrl,
+          kind,
+          'edl-stream',
+          true,
+        );
+        logResolvedMediaGenerationInput(options, currentVideoPath, result);
+        return result;
+      }
+      const result = await toResolvedMediaGenerationInput(
+        mpvClient,
+        streamOpenFilename,
+        kind,
+        'stream-open-filename',
+        false,
+      );
+      logResolvedMediaGenerationInput(options, currentVideoPath, result);
+      return result;
+    }
+    if (streamOpenFilename) {
+      const result = await toResolvedMediaGenerationInput(
+        mpvClient,
+        streamOpenFilename,
+        kind,
+        'stream-open-filename',
+        isRemoteMediaPath(streamOpenFilename),
+      );
+      logResolvedMediaGenerationInput(options, currentVideoPath, result);
+      return result;
+    }
+  } catch {
+    // Fall back to the current path when mpv does not expose a resolved stream URL.
+  }
+
+  const result = await toResolvedMediaGenerationInput(
+    mpvClient,
+    currentVideoPath,
+    kind,
+    'current-path',
+    false,
+  );
+  logResolvedMediaGenerationInput(options, currentVideoPath, result);
+  return result;
+}
+
 export async function resolveMediaGenerationInputPath(
   mpvClient: Pick<MpvClient, 'currentVideoPath' | 'requestProperty'> | null | undefined,
   kind: MediaGenerationKind = 'video',

src/anki-integration/mpv-edl-test-utils.ts

@@ -0,0 +1,3 @@
+export function toMpvEdlValue(value: string): string {
+  return `%${Buffer.byteLength(value, 'utf8')}%${value}`;
+}

src/anki-integration/mpv-edl.test.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { extractFileUrlsFromMpvEdlSource } from './mpv-edl';
+import { toMpvEdlValue } from './mpv-edl-test-utils';
+
+test('extractFileUrlsFromMpvEdlSource honors length-guarded file values', () => {
+  const url =
+    'https://rr1---sn.example.googlevideo.com/videoplayback?mime=video%2Fmp4&mn=sn-a,sn-b&lsig=abc%3D';
+  const source = `edl://!new_stream;${toMpvEdlValue(url)},title=clip,length=73`;
+
+  assert.deepEqual(extractFileUrlsFromMpvEdlSource(source), [url]);
+});
+
+test('extractFileUrlsFromMpvEdlSource reads file parameters', () => {
+  const initUrl = 'https://init.example/init.mp4';
+  const fileUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
+  const source = `edl://!mp4_dash,init=${toMpvEdlValue(initUrl)};file=${toMpvEdlValue(
+    fileUrl,
+  )},length=42`;
+
+  assert.deepEqual(extractFileUrlsFromMpvEdlSource(source), [fileUrl]);
+});
+
+test('extractFileUrlsFromMpvEdlSource aggregates file URLs across entries', () => {
+  const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
+  const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
+  const source = [
+    'edl://!new_stream',
+    toMpvEdlValue(audioUrl),
+    '!new_stream',
+    `file=${toMpvEdlValue(videoUrl)},length=50`,
+    '!global_tags,title=test',
+  ].join(';');
+
+  assert.deepEqual(extractFileUrlsFromMpvEdlSource(source), [audioUrl, videoUrl]);
+});

src/anki-integration/mpv-edl.ts

@@ -0,0 +1,195 @@
+const EDL_URI_PREFIX = 'edl://';
+
+const BYTE_COMMA = ','.charCodeAt(0);
+const BYTE_CR = '\r'.charCodeAt(0);
+const BYTE_EQUALS = '='.charCodeAt(0);
+const BYTE_EXCLAMATION = '!'.charCodeAt(0);
+const BYTE_LF = '\n'.charCodeAt(0);
+const BYTE_PERCENT = '%'.charCodeAt(0);
+const BYTE_SEMICOLON = ';'.charCodeAt(0);
+
+function isDigitByte(value: number | undefined): value is number {
+  return value !== undefined && value >= 48 && value <= 57;
+}
+
+function isEntrySeparator(value: number | undefined): boolean {
+  return value === BYTE_SEMICOLON || value === BYTE_LF || value === BYTE_CR;
+}
+
+function isParamSeparator(value: number | undefined): boolean {
+  return value === BYTE_COMMA || isEntrySeparator(value);
+}
+
+function decodeBytes(buffer: Buffer, start: number, end: number): string {
+  return buffer.subarray(start, end).toString('utf8');
+}
+
+function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function toEdlDataBuffer(source: string): Buffer {
+  const data = source.startsWith(EDL_URI_PREFIX) ? source.slice(EDL_URI_PREFIX.length) : source;
+  return Buffer.from(data, 'utf8');
+}
+
+function parseLengthGuardedValue(
+  buffer: Buffer,
+  position: number,
+): { value: string; end: number } | null {
+  if (buffer[position] !== BYTE_PERCENT) {
+    return null;
+  }
+
+  let cursor = position + 1;
+  if (!isDigitByte(buffer[cursor])) {
+    return null;
+  }
+
+  let byteLength = 0;
+  while (true) {
+    const digit = buffer[cursor];
+    if (!isDigitByte(digit)) {
+      break;
+    }
+    byteLength = byteLength * 10 + (digit - 48);
+    cursor += 1;
+  }
+
+  if (buffer[cursor] !== BYTE_PERCENT) {
+    return null;
+  }
+
+  const valueStart = cursor + 1;
+  const valueEnd = valueStart + byteLength;
+  if (valueEnd > buffer.length) {
+    return null;
+  }
+
+  return {
+    value: decodeBytes(buffer, valueStart, valueEnd),
+    end: valueEnd,
+  };
+}
+
+function skipEntrySeparators(buffer: Buffer, position: number): number {
+  let cursor = position;
+  while (cursor < buffer.length && isEntrySeparator(buffer[cursor])) {
+    cursor += 1;
+  }
+  return cursor;
+}
+
+function skipEntry(buffer: Buffer, position: number): number {
+  let cursor = position;
+  while (cursor < buffer.length) {
+    const guardedValue = parseLengthGuardedValue(buffer, cursor);
+    if (guardedValue) {
+      cursor = guardedValue.end;
+      continue;
+    }
+    if (isEntrySeparator(buffer[cursor])) {
+      break;
+    }
+    cursor += 1;
+  }
+  return cursor;
+}
+
+function parseRawValue(buffer: Buffer, position: number): { value: string; end: number } {
+  let cursor = position;
+  while (
+    cursor < buffer.length &&
+    !isParamSeparator(buffer[cursor]) &&
+    buffer[cursor] !== BYTE_EXCLAMATION
+  ) {
+    cursor += 1;
+  }
+  return {
+    value: decodeBytes(buffer, position, cursor),
+    end: cursor,
+  };
+}
+
+function parseParamValue(buffer: Buffer, position: number): { value: string; end: number } {
+  return parseLengthGuardedValue(buffer, position) ?? parseRawValue(buffer, position);
+}
+
+function parseOptionalParamName(
+  buffer: Buffer,
+  position: number,
+): { name: string | null; valueStart: number } {
+  let cursor = position;
+  while (
+    cursor < buffer.length &&
+    !isParamSeparator(buffer[cursor]) &&
+    buffer[cursor] !== BYTE_PERCENT &&
+    buffer[cursor] !== BYTE_EXCLAMATION
+  ) {
+    if (buffer[cursor] === BYTE_EQUALS) {
+      return {
+        name: decodeBytes(buffer, position, cursor),
+        valueStart: cursor + 1,
+      };
+    }
+    cursor += 1;
+  }
+
+  return { name: null, valueStart: position };
+}
+
+function parseSegmentEntry(buffer: Buffer, position: number): { urls: string[]; end: number } {
+  const urls: string[] = [];
+  let cursor = position;
+  let unnamedParamIndex = 0;
+
+  while (cursor < buffer.length && !isEntrySeparator(buffer[cursor])) {
+    const { name, valueStart } = parseOptionalParamName(buffer, cursor);
+    const value = parseParamValue(buffer, valueStart);
+    const lowerName = name?.toLowerCase() ?? null;
+    const isFileParam = lowerName === 'file' || (lowerName === null && unnamedParamIndex === 0);
+
+    if (isFileParam && isHttpUrl(value.value)) {
+      urls.push(value.value);
+    }
+
+    if (lowerName === null) {
+      unnamedParamIndex += 1;
+    }
+
+    cursor = value.end;
+    if (buffer[cursor] === BYTE_COMMA) {
+      cursor += 1;
+      continue;
+    }
+    if (!isEntrySeparator(buffer[cursor])) {
+      cursor = skipEntry(buffer, cursor);
+    }
+  }
+
+  return { urls, end: cursor };
+}
+
+export function extractFileUrlsFromMpvEdlSource(source: string): string[] {
+  const buffer = toEdlDataBuffer(source);
+  const urls: string[] = [];
+  let cursor = 0;
+
+  while (cursor < buffer.length) {
+    cursor = skipEntrySeparators(buffer, cursor);
+    if (cursor >= buffer.length) {
+      break;
+    }
+
+    if (buffer[cursor] === BYTE_EXCLAMATION) {
+      cursor = skipEntry(buffer, cursor);
+      continue;
+    }
+
+    const segment = parseSegmentEntry(buffer, cursor);
+    urls.push(...segment.urls);
+    cursor = segment.end;
+  }
+
+  return urls;
+}

src/anki-integration/note-field-utils.ts

@@ -2,7 +2,10 @@ export interface NoteFieldValueInfo {
   fields: Record<string, { value: string }>;
 }
 
-export function getNoteFieldValue(noteInfo: NoteFieldValueInfo, preferredName: string): string | null {
+export function getNoteFieldValue(
+  noteInfo: NoteFieldValueInfo,
+  preferredName: string,
+): string | null {
   const resolvedFieldName = Object.keys(noteInfo.fields).find(
     (fieldName) => fieldName.toLowerCase() === preferredName.toLowerCase(),
   );

src/anki-integration/note-update-workflow.test.ts

@@ -409,3 +409,59 @@ test('NoteUpdateWorkflow uses subtitle sidebar context for sentence media timing
   assert.deepEqual(imageContext, sidebarContext);
   assert.equal(miscInfoStartTime, 10);
 });
+
+test('NoteUpdateWorkflow queues media updates when YouTube cache is pending', async () => {
+  const harness = createWorkflowHarness();
+  const queuedUpdates: Array<{
+    noteId: number;
+    noteInfo: NoteUpdateWorkflowNoteInfo;
+    context?: SubtitleMiningContext;
+    label: string | number;
+  }> = [];
+  const mediaCalls: string[] = [];
+
+  harness.deps.client.notesInfo = async () =>
+    [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: 'taberu' },
+          Sentence: { value: '' },
+          SentenceAudio: { value: '' },
+          Picture: { value: '' },
+        },
+      },
+    ] satisfies NoteUpdateWorkflowNoteInfo[];
+  harness.deps.getConfig = () => ({
+    fields: {
+      sentence: 'Sentence',
+      image: 'Picture',
+    },
+    media: {
+      generateAudio: true,
+      generateImage: true,
+    },
+    behavior: {},
+  });
+  harness.deps.generateAudio = async () => {
+    mediaCalls.push('audio');
+    return Buffer.from('audio');
+  };
+  harness.deps.generateImage = async () => {
+    mediaCalls.push('image');
+    return Buffer.from('image');
+  };
+  harness.deps.queuePendingYoutubeMediaUpdate = async (job) => {
+    queuedUpdates.push(job);
+    return true;
+  };
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(mediaCalls, []);
+  assert.equal(queuedUpdates.length, 1);
+  assert.equal(queuedUpdates[0]?.noteId, 42);
+  assert.equal(queuedUpdates[0]?.label, 'taberu');
+  assert.equal(queuedUpdates[0]?.context, undefined);
+  assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
+});

src/anki-integration/note-update-workflow.ts

@@ -85,6 +85,12 @@ export interface NoteUpdateWorkflowDeps {
   ) => Promise<Buffer | null>;
   formatMiscInfoPattern: (fallbackFilename: string, startTimeSeconds?: number) => string;
   consumeSubtitleMiningContext?: () => SubtitleMiningContext | null;
+  queuePendingYoutubeMediaUpdate?: (job: {
+    noteId: number;
+    noteInfo: NoteUpdateWorkflowNoteInfo;
+    context?: SubtitleMiningContext;
+    label: string | number;
+  }) => Promise<boolean>;
   addConfiguredTagsToNote: (noteId: number) => Promise<void>;
   showNotification: (noteId: number, label: string | number) => Promise<void>;
   showOsdNotification: (message: string) => void;
@@ -195,6 +201,7 @@ export class NoteUpdateWorkflow {
         sentenceField,
         config.fields?.sentence,
       );
+      const noteLabel = hasExpressionText ? expressionText : noteId;
 
       const currentSubtitleText = subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
       if (sentenceField && currentSubtitleText) {
@@ -227,7 +234,19 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      if (config.media?.generateAudio) {
+      const generateAudio = config.media?.generateAudio !== false;
+      const generateImage = config.media?.generateImage !== false;
+      const mediaCacheQueued =
+        (generateAudio || generateImage) && this.deps.queuePendingYoutubeMediaUpdate
+          ? await this.deps.queuePendingYoutubeMediaUpdate({
+              noteId,
+              noteInfo,
+              context: subtitleMiningContext ?? undefined,
+              label: noteLabel,
+            })
+          : false;
+
+      if (!mediaCacheQueued && generateAudio) {
         try {
           const audioFilename = this.deps.generateAudioFilename();
           const audioBuffer = await this.deps.generateAudio(subtitleMiningContext ?? undefined);
@@ -252,7 +271,7 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      if (config.media?.generateImage) {
+      if (!mediaCacheQueued && generateImage) {
         try {
           const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
           const imageFilename = this.deps.generateImageFilename();
@@ -287,7 +306,7 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      if (config.fields?.miscInfo) {
+      if (!mediaCacheQueued && config.fields?.miscInfo) {
         const miscInfo = this.deps.formatMiscInfoPattern(
           miscInfoFilename || '',
           subtitleMiningContext?.startTime ?? this.deps.getCurrentSubtitleStart(),
@@ -305,8 +324,8 @@ export class NoteUpdateWorkflow {
       if (updatePerformed) {
         await this.deps.client.updateNoteFields(noteId, updatedFields);
         await this.deps.addConfiguredTagsToNote(noteId);
-        this.deps.logInfo('Updated card fields for:', hasExpressionText ? expressionText : noteId);
-        await this.deps.showNotification(noteId, hasExpressionText ? expressionText : noteId);
+        this.deps.logInfo('Updated card fields for:', noteLabel);
+        await this.deps.showNotification(noteId, noteLabel);
       }
 
       if (shouldRunFieldGrouping && hasExpressionText && duplicateNoteId !== null) {

src/anki-integration/pending-youtube-media-queue.test.ts

@@ -0,0 +1,193 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { AnkiConnectConfig } from '../types/anki';
+import {
+  PendingYoutubeMediaQueue,
+  type PendingYoutubeMediaQueueDeps,
+} from './pending-youtube-media-queue';
+
+function createDeps(
+  overrides: Partial<PendingYoutubeMediaQueueDeps> = {},
+): PendingYoutubeMediaQueueDeps {
+  const warnings: unknown[][] = [];
+  const deps: PendingYoutubeMediaQueueDeps & { warnings: unknown[][] } = {
+    client: {
+      notesInfo: async () => [],
+      updateNoteFields: async () => {},
+      storeMediaFile: async () => {},
+    },
+    mediaGenerator: {
+      generateAudio: async () => Buffer.from('audio'),
+      generateScreenshot: async () => Buffer.from('image'),
+      generateAnimatedImage: async () => Buffer.from('image'),
+    },
+    getConfig: () =>
+      ({
+        media: { generateAudio: true, generateImage: true },
+        fields: {},
+      }) as AnkiConnectConfig,
+    getCurrentVideoPath: () => 'https://www.youtube.com/watch?v=abc123',
+    getCachedMediaPath: async () => null,
+    shouldRequireRemoteMediaCache: () => true,
+    getSubtitleMediaRange: () => ({ startTime: 1, endTime: 2 }),
+    getResolvedSentenceAudioFieldName: () => 'SentenceAudio',
+    resolveConfiguredFieldName: () => 'Picture',
+    mergeFieldValue: (_existing, newValue) => newValue,
+    getAnimatedImageLeadInSeconds: async () => 0,
+    generateAudioFilename: () => 'audio.mp3',
+    generateImageFilename: () => 'image.webp',
+    formatMiscInfoPatternForMediaPath: () => '',
+    showStatusNotification: () => {},
+    showNotification: async () => {},
+    logInfo: () => {},
+    logWarn: (...args) => {
+      warnings.push(args);
+    },
+    logError: () => {},
+    warnings,
+    ...overrides,
+  };
+  return deps;
+}
+
+test('PendingYoutubeMediaQueue treats cache lookup failures as an immediate generation fallback', async () => {
+  const deps = createDeps({
+    getCachedMediaPath: async () => {
+      throw new Error('cache unavailable');
+    },
+  });
+  const queue = new PendingYoutubeMediaQueue(deps);
+
+  const queued = await queue.queueFromNote({
+    noteId: 42,
+    noteInfo: { noteId: 42, fields: {} },
+    label: 'demo',
+  });
+
+  assert.equal(queued, false);
+  assert.deepEqual((deps as typeof deps & { warnings: unknown[][] }).warnings, [
+    [
+      'Failed to read YouTube cache state; falling back to immediate media generation:',
+      'cache unavailable',
+    ],
+  ]);
+});
+
+test('PendingYoutubeMediaQueue drains matching queued jobs when the cache download fails', async () => {
+  const statusMessages: string[] = [];
+  const notifications: Array<{ noteId: number; label: string | number; suffix?: string }> = [];
+  const updatedNotes: number[] = [];
+  const deps = createDeps({
+    client: {
+      notesInfo: async (noteIds) =>
+        noteIds.map((noteId) => ({
+          noteId,
+          fields: {
+            SentenceAudio: { value: '' },
+            Picture: { value: '' },
+          },
+        })),
+      updateNoteFields: async (noteId) => {
+        updatedNotes.push(noteId);
+      },
+      storeMediaFile: async () => {},
+    },
+    showStatusNotification: (message) => {
+      statusMessages.push(message);
+    },
+    showNotification: async (noteId, label, suffix) => {
+      notifications.push({ noteId, label, suffix });
+    },
+  });
+  const queue = new PendingYoutubeMediaQueue(deps);
+
+  queue.enqueue({
+    sourceUrl: 'https://www.youtube.com/watch?v=abc123',
+    noteId: 42,
+    startTime: 1,
+    endTime: 2,
+    label: 'queued',
+    generateAudio: true,
+    generateImage: true,
+  });
+
+  await queue.handleFailed('https://youtu.be/abc123');
+  await queue.handleReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.deepEqual(updatedNotes, []);
+  assert.deepEqual(notifications, [{ noteId: 42, label: 'queued', suffix: 'media cache failed' }]);
+  assert.equal(
+    statusMessages.includes('YouTube media cache failed. Media was not added to 1 queued card.'),
+    true,
+  );
+});
+
+test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queuing from notes', async () => {
+  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const storedMedia: string[] = [];
+  const deps = createDeps({
+    client: {
+      notesInfo: async (noteIds) =>
+        noteIds.map((noteId) => ({
+          noteId,
+          fields: {
+            SentenceAudio: { value: '' },
+            Picture: { value: '' },
+          },
+        })),
+      updateNoteFields: async (noteId, fields) => {
+        updatedNotes.push({ noteId, fields });
+      },
+      storeMediaFile: async (filename) => {
+        storedMedia.push(filename);
+      },
+    },
+    getConfig: () => ({ media: {}, fields: { image: 'Picture' } }) as AnkiConnectConfig,
+  });
+  const queue = new PendingYoutubeMediaQueue(deps);
+
+  const queued = await queue.queueFromNote({
+    noteId: 42,
+    noteInfo: { noteId: 42, fields: {} },
+    label: 'demo',
+  });
+  await queue.handleReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.equal(queued, true);
+  assert.equal(updatedNotes.length, 1);
+  assert.equal(storedMedia.length, 2);
+  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio\.mp3\]$/);
+  assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image\.webp">$/);
+});
+
+test('PendingYoutubeMediaQueue only announces a download once per source while jobs collect', () => {
+  const statusMessages: string[] = [];
+  const deps = createDeps({
+    showStatusNotification: (message) => {
+      statusMessages.push(message);
+    },
+  });
+  const queue = new PendingYoutubeMediaQueue(deps);
+
+  queue.enqueue({
+    sourceUrl: 'https://youtu.be/abc123',
+    noteId: 1,
+    startTime: 1,
+    endTime: 2,
+    label: 'first',
+    generateAudio: true,
+    generateImage: false,
+  });
+  queue.enqueue({
+    sourceUrl: 'https://www.youtube.com/watch?v=abc123',
+    noteId: 2,
+    startTime: 3,
+    endTime: 4,
+    label: 'second',
+    generateAudio: false,
+    generateImage: true,
+  });
+
+  assert.equal(statusMessages.length, 1);
+});

src/anki-integration/pending-youtube-media-queue.ts

@@ -0,0 +1,392 @@
+import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
+import type { MediaInput } from '../media-input';
+import type { MediaGenerator } from '../media-generator';
+import type { AnkiConnectConfig } from '../types/anki';
+import type { SubtitleMiningContext } from '../types/subtitle';
+import { youtubeMediaUrlsMatch, type PendingYoutubeMediaUpdate } from './pending-youtube-media';
+import type { MediaGenerationInputResolverOptions } from './media-source';
+
+type PendingYoutubeMediaUpdateResult = 'updated' | 'partial' | 'failed';
+
+export interface PendingYoutubeMediaQueueReadyOptions {
+  notifyNoQueued?: boolean;
+}
+
+export interface PendingYoutubeMediaQueueFailedOptions {
+  notifyStatus?: boolean;
+}
+
+export interface PendingYoutubeMediaNoteInfo {
+  noteId: number;
+  fields: Record<string, { value: string }>;
+}
+
+export interface PendingYoutubeMediaQueueDeps {
+  client: {
+    notesInfo(noteIds: number[]): Promise<unknown>;
+    updateNoteFields(noteId: number, fields: Record<string, string>): Promise<void>;
+    storeMediaFile(filename: string, data: Buffer): Promise<void>;
+  };
+  mediaGenerator: Pick<
+    MediaGenerator,
+    'generateAudio' | 'generateScreenshot' | 'generateAnimatedImage'
+  >;
+  getConfig: () => AnkiConnectConfig;
+  getCurrentVideoPath: () => Promise<string | undefined> | string | undefined;
+  getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null;
+  shouldRequireRemoteMediaCache: () => boolean;
+  getSubtitleMediaRange: (context?: SubtitleMiningContext) => {
+    startTime: number;
+    endTime: number;
+  };
+  getResolvedSentenceAudioFieldName: (noteInfo: PendingYoutubeMediaNoteInfo) => string | null;
+  resolveConfiguredFieldName: (
+    noteInfo: PendingYoutubeMediaNoteInfo,
+    ...preferredNames: (string | undefined)[]
+  ) => string | null;
+  mergeFieldValue: (existing: string, newValue: string, overwrite: boolean) => string;
+  getAnimatedImageLeadInSeconds: (noteInfo: PendingYoutubeMediaNoteInfo) => Promise<number>;
+  generateAudioFilename: () => string;
+  generateImageFilename: () => string;
+  formatMiscInfoPatternForMediaPath: (
+    fallbackFilename: string,
+    startTimeSeconds: number | undefined,
+    mediaPath: string,
+    mediaTitle?: string,
+  ) => string;
+  showStatusNotification: (message: string) => void;
+  showNotification: (noteId: number, label: string | number, errorSuffix?: string) => Promise<void>;
+  logInfo: (message: string, ...args: unknown[]) => void;
+  logWarn: (message: string, ...args: unknown[]) => void;
+  logError: (message: string, ...args: unknown[]) => void;
+}
+
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function shouldGenerateAudio(config: AnkiConnectConfig): boolean {
+  return config.media?.generateAudio !== false;
+}
+
+function shouldGenerateImage(config: AnkiConnectConfig): boolean {
+  return config.media?.generateImage !== false;
+}
+
+export class PendingYoutubeMediaQueue {
+  private updates: PendingYoutubeMediaUpdate[] = [];
+
+  constructor(private readonly deps: PendingYoutubeMediaQueueDeps) {}
+
+  enqueue(job: PendingYoutubeMediaUpdate): void {
+    if (!job.generateAudio && !job.generateImage) {
+      return;
+    }
+    const isFirstQueuedForSource = !this.updates.some((existing) =>
+      youtubeMediaUrlsMatch(existing.sourceUrl, job.sourceUrl),
+    );
+    this.updates.push(job);
+    this.deps.logInfo('Queued YouTube media update for note:', job.noteId);
+    if (isFirstQueuedForSource) {
+      this.deps.showStatusNotification(
+        'YouTube media cache is still downloading. Card media will be added when the cache is ready.',
+      );
+    }
+  }
+
+  async queueFromNote(job: {
+    noteId: number;
+    noteInfo: PendingYoutubeMediaNoteInfo;
+    context?: SubtitleMiningContext;
+    label: string | number;
+  }): Promise<boolean> {
+    const sourceUrl = trimToNonEmptyString(await this.deps.getCurrentVideoPath());
+    const getCachedMediaPath = this.deps.getCachedMediaPath;
+    if (!sourceUrl || this.deps.shouldRequireRemoteMediaCache() !== true || !getCachedMediaPath) {
+      return false;
+    }
+
+    let cachedPath: string | null = null;
+    try {
+      cachedPath = await getCachedMediaPath(sourceUrl, 'video');
+    } catch (error) {
+      this.deps.logWarn(
+        'Failed to read YouTube cache state; falling back to immediate media generation:',
+        error instanceof Error ? error.message : String(error),
+      );
+      return false;
+    }
+    if (cachedPath) {
+      return false;
+    }
+
+    const config = this.deps.getConfig();
+    const mediaRange = this.deps.getSubtitleMediaRange(job.context);
+    this.enqueue({
+      sourceUrl,
+      noteId: job.noteId,
+      startTime: mediaRange.startTime,
+      endTime: mediaRange.endTime,
+      label: job.label,
+      audioFieldName: this.deps.getResolvedSentenceAudioFieldName(job.noteInfo) ?? undefined,
+      imageFieldName:
+        this.deps.resolveConfiguredFieldName(
+          job.noteInfo,
+          config.fields?.image,
+          DEFAULT_ANKI_CONNECT_CONFIG.fields.image,
+        ) ?? undefined,
+      miscInfoFieldName:
+        this.deps.resolveConfiguredFieldName(job.noteInfo, config.fields?.miscInfo) ?? undefined,
+      generateAudio: shouldGenerateAudio(config),
+      generateImage: shouldGenerateImage(config),
+    });
+    return true;
+  }
+
+  async handleReady(
+    sourceUrl: string,
+    cachedPath: string,
+    options: PendingYoutubeMediaQueueReadyOptions = {},
+  ): Promise<void> {
+    const jobs = this.takeMatchingUpdates(sourceUrl);
+    if (jobs.length === 0) {
+      if (options.notifyNoQueued !== false) {
+        this.deps.showStatusNotification('YouTube media cache ready.');
+      }
+      return;
+    }
+
+    this.deps.showStatusNotification(
+      `YouTube media cache ready. Adding media to ${jobs.length} queued card${
+        jobs.length === 1 ? '' : 's'
+      }.`,
+    );
+
+    let updatedCount = 0;
+    let partialCount = 0;
+    let failedCount = 0;
+    for (const job of jobs) {
+      try {
+        const result = await this.applyUpdate(job, cachedPath);
+        if (result === 'updated') {
+          updatedCount += 1;
+        } else if (result === 'partial') {
+          partialCount += 1;
+        } else {
+          failedCount += 1;
+        }
+      } catch (error) {
+        failedCount += 1;
+        this.deps.logError(
+          'Failed to apply queued YouTube media update:',
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+
+    if (partialCount > 0 || failedCount > 0) {
+      this.deps.showStatusNotification(
+        `Queued YouTube media finished with ${updatedCount} updated, ${partialCount} partial, and ${failedCount} failed.`,
+      );
+    }
+  }
+
+  async handleFailed(
+    sourceUrl: string,
+    options: PendingYoutubeMediaQueueFailedOptions = {},
+  ): Promise<void> {
+    const jobs = this.takeMatchingUpdates(sourceUrl);
+    if (jobs.length === 0) {
+      if (options.notifyStatus !== false) {
+        this.deps.showStatusNotification('YouTube media cache failed.');
+      }
+      return;
+    }
+
+    if (options.notifyStatus !== false) {
+      this.deps.showStatusNotification(
+        `YouTube media cache failed. Media was not added to ${jobs.length} queued card${
+          jobs.length === 1 ? '' : 's'
+        }.`,
+      );
+    }
+    this.deps.logWarn('Discarding queued YouTube media updates after cache failure:', jobs.length);
+
+    for (const job of jobs) {
+      try {
+        await this.deps.showNotification(job.noteId, job.label, 'media cache failed');
+      } catch (error) {
+        this.deps.logWarn(
+          'Failed to show queued YouTube media failure notification:',
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+  }
+
+  private takeMatchingUpdates(sourceUrl: string): PendingYoutubeMediaUpdate[] {
+    const matched: PendingYoutubeMediaUpdate[] = [];
+    const remaining: PendingYoutubeMediaUpdate[] = [];
+    for (const job of this.updates) {
+      if (youtubeMediaUrlsMatch(job.sourceUrl, sourceUrl)) {
+        matched.push(job);
+      } else {
+        remaining.push(job);
+      }
+    }
+    this.updates = remaining;
+    return matched;
+  }
+
+  private async applyUpdate(
+    job: PendingYoutubeMediaUpdate,
+    cachedPath: string,
+  ): Promise<PendingYoutubeMediaUpdateResult> {
+    const notesInfoResult = await this.deps.client.notesInfo([job.noteId]);
+    const notesInfo = notesInfoResult as unknown as PendingYoutubeMediaNoteInfo[];
+    const noteInfo = notesInfo[0];
+    if (!noteInfo) {
+      this.deps.logWarn('Queued YouTube media target note not found:', job.noteId);
+      return 'failed';
+    }
+
+    const config = this.deps.getConfig();
+    const mediaFields: Record<string, string> = {};
+    const errors: string[] = [];
+    let miscInfoFilename: string | null = null;
+    const cachedMediaInput: MediaInput = {
+      path: cachedPath,
+      source: 'youtube-cache',
+    };
+
+    if (job.generateAudio) {
+      try {
+        const audioFilename = this.deps.generateAudioFilename();
+        const audioBuffer = await this.deps.mediaGenerator.generateAudio(
+          cachedMediaInput,
+          job.startTime,
+          job.endTime,
+          config.media?.audioPadding,
+          undefined,
+          config.media?.normalizeAudio !== false,
+        );
+        if (audioBuffer) {
+          await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
+          const audioField =
+            job.audioFieldName || this.deps.getResolvedSentenceAudioFieldName(noteInfo) || null;
+          if (audioField) {
+            const existingAudio = noteInfo.fields[audioField]?.value || '';
+            mediaFields[audioField] = this.deps.mergeFieldValue(
+              existingAudio,
+              `[sound:${audioFilename}]`,
+              config.behavior?.overwriteAudio !== false,
+            );
+          }
+          miscInfoFilename = audioFilename;
+        }
+      } catch (error) {
+        errors.push('audio');
+        this.deps.logError('Failed to generate queued YouTube audio:', (error as Error).message);
+      }
+    }
+
+    if (job.generateImage) {
+      try {
+        const imageFilename = this.deps.generateImageFilename();
+        const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
+        const imageBuffer = await this.generateImageFromInput(
+          cachedMediaInput,
+          job.startTime,
+          job.endTime,
+          animatedLeadInSeconds,
+        );
+        if (imageBuffer) {
+          await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
+          const imageField =
+            job.imageFieldName ||
+            this.deps.resolveConfiguredFieldName(
+              noteInfo,
+              config.fields?.image,
+              DEFAULT_ANKI_CONNECT_CONFIG.fields.image,
+            );
+          if (imageField) {
+            const existingImage = noteInfo.fields[imageField]?.value || '';
+            mediaFields[imageField] = this.deps.mergeFieldValue(
+              existingImage,
+              `<img src="${imageFilename}">`,
+              config.behavior?.overwriteImage !== false,
+            );
+          } else {
+            this.deps.logWarn(
+              'Image field not found on queued YouTube media note, skipping image update',
+            );
+          }
+          miscInfoFilename = imageFilename;
+        }
+      } catch (error) {
+        errors.push('image');
+        this.deps.logError('Failed to generate queued YouTube image:', (error as Error).message);
+      }
+    }
+
+    if (config.fields?.miscInfo && miscInfoFilename) {
+      const miscInfoField =
+        job.miscInfoFieldName ||
+        this.deps.resolveConfiguredFieldName(noteInfo, config.fields.miscInfo);
+      const miscInfo = this.deps.formatMiscInfoPatternForMediaPath(
+        miscInfoFilename,
+        job.startTime,
+        job.sourceUrl,
+      );
+      if (miscInfoField && miscInfo) {
+        mediaFields[miscInfoField] = miscInfo;
+      }
+    }
+
+    if (Object.keys(mediaFields).length === 0) {
+      return 'failed';
+    }
+
+    await this.deps.client.updateNoteFields(job.noteId, mediaFields);
+    const errorSuffix = errors.length > 0 ? `${errors.join(', ')} failed` : undefined;
+    await this.deps.showNotification(job.noteId, job.label, errorSuffix);
+    this.deps.logInfo('Applied queued YouTube media update for note:', job.noteId);
+    return errors.length === 0 ? 'updated' : 'partial';
+  }
+
+  private async generateImageFromInput(
+    videoPath: MediaInput,
+    startTime: number,
+    endTime: number,
+    animatedLeadInSeconds = 0,
+  ): Promise<Buffer | null> {
+    const config = this.deps.getConfig();
+    if (config.media?.imageType === 'avif') {
+      return this.deps.mediaGenerator.generateAnimatedImage(
+        videoPath,
+        startTime,
+        endTime,
+        config.media?.audioPadding,
+        {
+          fps: config.media?.animatedFps,
+          maxWidth: config.media?.animatedMaxWidth,
+          maxHeight: config.media?.animatedMaxHeight,
+          crf: config.media?.animatedCrf,
+          leadingStillDuration: animatedLeadInSeconds,
+        },
+      );
+    }
+
+    const timestamp = startTime + (endTime - startTime) / 2;
+    return this.deps.mediaGenerator.generateScreenshot(videoPath, timestamp, {
+      format: config.media?.imageFormat as 'jpg' | 'png' | 'webp',
+      quality: config.media?.imageQuality,
+      maxWidth: config.media?.imageMaxWidth,
+      maxHeight: config.media?.imageMaxHeight,
+    });
+  }
+}

src/anki-integration/pending-youtube-media.ts

@@ -0,0 +1,53 @@
+export interface PendingYoutubeMediaUpdate {
+  sourceUrl: string;
+  noteId: number;
+  startTime: number;
+  endTime: number;
+  label: string | number;
+  audioFieldName?: string;
+  imageFieldName?: string;
+  miscInfoFieldName?: string;
+  generateAudio: boolean;
+  generateImage: boolean;
+}
+
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function getYoutubeVideoId(rawUrl: string): string | null {
+  try {
+    const parsed = new URL(rawUrl);
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'youtu.be' || host.endsWith('.youtu.be')) {
+      return trimToNonEmptyString(parsed.pathname.replace(/^\/+/, '').split('/')[0]);
+    }
+    if (host === 'youtube.com' || host.endsWith('.youtube.com')) {
+      const watchId = trimToNonEmptyString(parsed.searchParams.get('v'));
+      if (watchId) {
+        return watchId;
+      }
+      const parts = parsed.pathname.split('/').filter(Boolean);
+      if (parts[0] === 'shorts' || parts[0] === 'embed' || parts[0] === 'live') {
+        return trimToNonEmptyString(parts[1]);
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function youtubeMediaUrlsMatch(a: string, b: string): boolean {
+  if (a.trim() === b.trim()) {
+    return true;
+  }
+
+  const aVideoId = getYoutubeVideoId(a);
+  const bVideoId = getYoutubeVideoId(b);
+  return Boolean(aVideoId && bVideoId && aVideoId === bVideoId);
+}

src/config/config.test.ts

@@ -80,6 +80,8 @@ test('loads defaults when config is missing', () => {
   assert.equal('remoteControlDeviceName' in config.jellyfin, false);
   assert.equal('deviceId' in config.jellyfin, false);
   assert.equal('clientVersion' in config.jellyfin, false);
+  assert.equal(config.youtube.mediaCache.mode, 'direct');
+  assert.equal(config.youtube.mediaCache.maxHeight, 720);
   assert.equal(config.ai.enabled, false);
   assert.equal(config.ai.apiKeyCommand, '');
   assert.equal(config.texthooker.openBrowser, false);
@@ -90,6 +92,7 @@ test('loads defaults when config is missing', () => {
     model: '',
     systemPrompt: '',
   });
+  assert.equal(config.ankiConnect.media.normalizeAudio, true);
   assert.equal(config.startupWarmups.lowPowerMode, false);
   assert.equal(config.startupWarmups.mecab, true);
   assert.equal(config.startupWarmups.yomitanExtension, true);
@@ -1750,6 +1753,56 @@ test('parses global shortcuts and startup settings', () => {
   assert.equal(config.youtubeSubgen.fixWithAi, true);
 });
 
+test('parses YouTube media cache config and warns on invalid values', () => {
+  const validDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(validDir, 'config.jsonc'),
+    `{
+      "youtube": {
+        "mediaCache": {
+          "mode": "background",
+          "maxHeight": 480
+        }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const validService = new ConfigService(validDir);
+  assert.equal(validService.getConfig().youtube.mediaCache.mode, 'background');
+  assert.equal(validService.getConfig().youtube.mediaCache.maxHeight, 480);
+
+  const invalidDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(invalidDir, 'config.jsonc'),
+    `{
+      "youtube": {
+        "mediaCache": {
+          "mode": "always",
+          "maxHeight": -1
+        }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const invalidService = new ConfigService(invalidDir);
+  assert.equal(
+    invalidService.getConfig().youtube.mediaCache.mode,
+    DEFAULT_CONFIG.youtube.mediaCache.mode,
+  );
+  assert.equal(
+    invalidService.getConfig().youtube.mediaCache.maxHeight,
+    DEFAULT_CONFIG.youtube.mediaCache.maxHeight,
+  );
+  assert.ok(
+    invalidService.getWarnings().some((warning) => warning.path === 'youtube.mediaCache.mode'),
+  );
+  assert.ok(
+    invalidService.getWarnings().some((warning) => warning.path === 'youtube.mediaCache.maxHeight'),
+  );
+});
+
 test('parses controller settings with logical bindings and tuning knobs', () => {
   const dir = makeTempDir();
   fs.writeFileSync(

src/config/definitions/defaults-core.ts

@@ -111,6 +111,10 @@ export const CORE_DEFAULT_CONFIG: Pick<
   },
   youtube: {
     primarySubLanguages: ['ja', 'jpn'],
+    mediaCache: {
+      mode: 'direct',
+      maxHeight: 720,
+    },
   },
   subsync: {
     alass_path: '',

src/config/definitions/defaults-integrations.ts

@@ -51,6 +51,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       animatedMaxHeight: 0,
       animatedCrf: 35,
       syncAnimatedImageToWordAudio: true,
+      normalizeAudio: true,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,