chore(release): prepare v0.19.6

- Reapply hidden visibility after secondary track changes
- Relinquish suppression only after successful restoration

CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## v0.19.6 (2026-09-04)
+
+### Added
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+### Changed
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+### Fixed
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **Jellyfin Subtitle Sync**: Jellyfin subtitle files now load with zero mpv delay instead of inferring and saving an offset from Japanese and English cue timelines.
+- **Secondary Subtitle Visibility**: Native mpv secondary subtitles stay hidden when switching secondary subtitle tracks during playback.
+
+## v0.19.5 (2026-08-30)
+
+### Fixed
+
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - Long speech is paged instead of covering the video with a wall of text.
+  - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
+
 ## v0.19.4 (2026-08-25)
 
 ### Added
@@ -10,9 +56,22 @@
 - **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
 
 ### Fixed
-- **Subtitle & Karaoke Duplication**: Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, or repeated animation events. Lines are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved. Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly. Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container. Secondary subtitles now go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines. Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
-- **Character Dictionary Reliability**: Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries. Snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path. Dictionaries are reused instead of regenerated when MeCab finds no name splits, and cached portraits now restore correctly after the portrait index finishes loading post-tokenization. Desktop progress notifications on Linux AppImage installs now update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
-- **Overlay Startup & Modals**: Fixed several causes of the overlay getting stuck on "Overlay loading": the macOS window-tracking helper now targets macOS 12.0+ instead of requiring the build machine's exact macOS version (previously crashed on older systems like Ventura), and mpv IPC connection attempts now time out and retry, showing an actionable error if content still isn't ready after 30 seconds. Dedicated overlay modals are also prewarmed on macOS and Windows so shortcuts open them promptly, and on macOS reused modals and the stats window now open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
 - **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
 - **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
 - **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.

bun.lock

@@ -38,7 +38,7 @@
     "app-builder-lib": "26.15.3",
     "brace-expansion": "5.0.9",
     "electron-builder-squirrel-windows": "26.15.3",
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.6",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
     "js-yaml": "4.3.1",
@@ -406,7 +406,7 @@
 
     "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
 
-    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],
+    "fast-uri": ["fast-uri@3.1.6", "", {}, "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 

changes/README.md

@@ -42,7 +42,7 @@ How fragments turn into a release:
 
 - At release time, `bun run changelog:build` (and `bun run changelog:prerelease-notes`) pipes every pending fragment through `claude -p` to merge related items, drop noise, and rewrite into a clean user-facing release body. Write fragments as raw, informative notes — don't worry about polished prose, deduping across PRs, or line-by-line phrasing. The polish step handles all of that.
 - The polish step treats pending fragments as the final release outcome, not prerelease history. If a feature is added and then renamed or fixed before the stable cut, ship the final feature bullet instead of separate prerelease-only breaking/fix entries.
-- GitHub release notes and prerelease notes use short top-level items with nested bullets for the change, user benefit, and any useful action note. The stable `CHANGELOG.md` can stay in compact single-line bullets.
+- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use short top-level items with one nested bullet per distinct change, instead of packing a release's worth of detail into a single paragraph bullet. An item with only one thing to say stays inline on the top-level bullet. Release notes and prerelease notes additionally cover user benefit and any useful action note in their nested bullets.
 - `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
 - The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.
 

config.example.jsonc

@@ -523,7 +523,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -569,6 +569,7 @@
       "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. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. 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.
@@ -606,6 +607,11 @@
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
     "lapisKiku": {
       "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
     } // Lapis kiku setting.

docs-site/anki-integration.md

@@ -136,6 +136,8 @@ SubMiner maps its data to your Anki note fields. Configure these under `ankiConn
 
 Field names are matched against your Anki note type case-insensitively (an exact match wins, then a lowercase comparison). If a configured field does not exist on the note type, SubMiner skips it without error.
 
+These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
+
 Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).
 
 ### Minimal Config
@@ -156,6 +158,8 @@ If you only want sentence and audio on your cards:
 
 SubMiner uses FFmpeg to generate audio and image media from the video. FFmpeg must be installed and on `PATH`.
 
+For remote streams such as Jellyfin playback, SubMiner downloads the clip's time window once into a temporary Matroska file (a stream copy, no re-encoding) and reads the timing review waveform, audio preview, audio, and image from that file instead of fetching the stream again for each step. The window covers the clip plus padding, plus the visible timeline in timing review, and grows when you reveal more of the timeline. It is deleted when a different window replaces it, after ten minutes without use, or when SubMiner exits. If the download fails, media generation reads the remote stream directly as before.
+
 ### Audio
 
 Audio is extracted from the video file using the subtitle's start and end timestamps. Padding is opt-in; keep it at `0` when you want sentence audio to start exactly at the mined sentence.
@@ -166,6 +170,7 @@ Audio is extracted from the video file using the subtitle's start and end timest
     "generateAudio": true,
     "normalizeAudio": true,      // normalize generated clip loudness
     "mirrorMpvVolume": true,     // apply the current mpv volume level
+    "reviewTiming": false,       // review and adjust timing before media generation
     "audioPadding": 0,           // optional seconds before and after subtitle timing
     "maxMediaDuration": 30       // cap total duration in seconds
   }
@@ -178,6 +183,12 @@ Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMine
 
 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
 
+Set `media.reviewTiming` to `true` to pause playback and review each word, sentence, or audio card before its media is generated. The review opens with the subtitle range plus configured audio padding. Subtitles usually linger past the dialogue, so once the waveform loads an untouched clip end moves back to just after the line's last speech (plus the configured padding); the Line end rail keeps marking the subtitle timing, Reset restores it, and a line whose speech runs through its end is left alone. Drag either edge of the clip to trim it, drag the middle to slide it without changing its length, or press anywhere else on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys, by 100 ms alone or 500 ms with Shift, and the 100 ms buttons do the same. Space previews the selection with a playhead that sweeps the clip; the preview ends when the hidden player has actually played the last sample, so output latency such as Bluetooth headphones does not cut the clip short. Enter confirms, and Escape cancels. The Earlier and Later buttons reveal another two seconds of available timeline without moving the selected clip. A speech-weighted waveform shows the mined subtitle as a tinted band with labeled line-start and line-end rails, making adjacent dialogue easier to distinguish. SubMiner uses a center channel when one carries dialogue, then falls back to a mono mix, keeps only the 250 to 3500 Hz speech band, and draws each slice's loudness relative to the clip's own noise floor, so steady background music or ambience reads as a flat line while dialogue stands out. Waveform analysis failure leaves the timing controls available. The confirmed range is exact: SubMiner does not apply audio padding a second time. Static screenshots use its midpoint, and animated AVIF clips use the full confirmed range.
+
+The review can also pull adjacent subtitle lines onto the card. Press `P` or `N` (or use the Prev and Next steppers above the sentence preview) to add the previous or next line, as many times as lines are available; Shift+`P` and Shift+`N` remove them again. The sentence preview lists every included line with the mined line highlighted, so the card's sentence field is always visible before you confirm, and the clip start or end, along with the line-start and line-end rails on the waveform, follows the outermost added line, keeping the review's audio padding. Confirming writes the combined lines to the sentence field; the Reset button drops the added lines along with any timing changes. Adjacent lines come from the parsed subtitle track when one is loaded; otherwise only lines that already played are offered, and a clip capped by `media.maxMediaDuration` keeps the full combined sentence even when the audio cannot cover every added line.
+
+Canceling the review lets you keep editing, finish with the original timing, keep or create the card without audio or an image, or discard the card. Discard deletes an existing Yomitan or audio card and skips creation for a direct sentence card. Clipboard updates and stats-dashboard mining do not open timing review. Audio preview failure does not block confirmation or card creation. The option is disabled by default and hot-reloads. You can also toggle **Review Media Timing** for the current session from the runtime options palette (`Ctrl/Cmd+Shift+O`).
+
 ### Screenshots (Static)
 
 A single frame is captured at the current playback position.
@@ -233,7 +244,7 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)
 
 When media is available, mined-card overlay and system notifications include the same current-frame thumbnail.
 
-`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio, while leaving the word audio field unchanged.
+`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio in `ankiConnect.fields.audio`, even when `overwriteAudio` is disabled.
 
 ## AI Translation
 
@@ -287,6 +298,8 @@ Sentence card creation and audio card marking require a non-empty `ankiConnect.i
 
 Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is created directly via AnkiConnect with the sentence, audio, and image filled in.
 
+The dedicated sentence-card and audio-card shortcuts use the Lapis/Kiku-compatible `Sentence` and `SentenceAudio` fields. This does not affect the configured fields used to enrich normal word cards.
+
 To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.
 
 ## Word Card Type (Kiku/Lapis)
@@ -304,9 +317,9 @@ Word cards get a card-type flag when SubMiner fills their sentence, whether that
 
 `click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.
 
-## Field Grouping (Kiku)
+## Field Grouping (Kiku/Senren)
 
-When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types like [Kiku](https://github.com/youyoumu/kiku) that support grouped sentence/audio/image fields.
+When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types that support grouped fields: [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls the feature scene switching).
 
 ```jsonc
 "ankiConnect": {
@@ -318,6 +331,18 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
 }
 ```
 
+For Senren note types, enable `isSenren` instead. Kiku and Senren write incompatible markup into the same fields, so only one can be enabled at a time; if both are enabled, Kiku wins and a config warning is emitted.
+
+```jsonc
+"ankiConnect": {
+  "isSenren": {
+    "enabled": true,
+    "fieldGrouping": "auto",           // "auto" (default), "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+  }
+}
+```
+
 ### Modes
 
 **Disabled** (`"disabled"`): No duplicate detection. Each card is independent.
@@ -329,13 +354,16 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
 ### What Gets Merged
 
 | Field    | Merge behavior                                  |
-| -------- | --------------------------------------------- |
+| -------- | ----------------------------------------------- |
 | Sentence | Both cards' sentences kept as grouped entries   |
 | Audio    | Both cards' `[sound:...]` entries kept          |
 | Image    | Both cards' images kept                         |
+| MiscInfo | Both cards' source info kept as grouped entries |
 
 Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.
 
+The merge markup depends on the note type. Kiku entries are wrapped in `<span data-group-id="...">` spans ordered newest first. Senren entries follow the [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md) format: sentence, sentenceFurigana, and miscInfo entries use `group` spans when ordinal order is sufficient and numbered `groupN` spans when they need an absolute scene target. Audio and pictures are appended positionally, and the number of sentenceAudio entries drives Senren's scene count. Ungrouped legacy content is wrapped into a group span on first merge, and source `groupN` spans are rebased after the kept note's existing audio scenes.
+
 ### Keyboard Shortcuts in the Modal
 
 | Key         | Action                             |

docs-site/changelog.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## v0.19.6 (2026-09-04)
+
+**Added**
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+**Changed**
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+**Fixed**
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **Jellyfin Subtitle Sync**: Jellyfin subtitle files now load with zero mpv delay instead of inferring and saving an offset from Japanese and English cue timelines.
+- **Secondary Subtitle Visibility**: Native mpv secondary subtitles stay hidden when switching secondary subtitle tracks during playback.
+
+## v0.19.5 (2026-08-30)
+
+**Fixed**
+
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - Long speech is paged instead of covering the video with a wall of text.
+  - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
+
 ## v0.19.4 (2026-08-25)
 
 **Added**
@@ -10,9 +56,22 @@
 - **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
 
 **Fixed**
-- **Subtitle & Karaoke Duplication**: Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, or repeated animation events. Lines are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved. Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly. Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container. Secondary subtitles now go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines. Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
-- **Character Dictionary Reliability**: Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries. Snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path. Dictionaries are reused instead of regenerated when MeCab finds no name splits, and cached portraits now restore correctly after the portrait index finishes loading post-tokenization. Desktop progress notifications on Linux AppImage installs now update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
-- **Overlay Startup & Modals**: Fixed several causes of the overlay getting stuck on "Overlay loading": the macOS window-tracking helper now targets macOS 12.0+ instead of requiring the build machine's exact macOS version (previously crashed on older systems like Ventura), and mpv IPC connection attempts now time out and retry, showing an actionable error if content still isn't ready after 30 seconds. Dedicated overlay modals are also prewarmed on macOS and Windows so shortcuts open them promptly, and on macOS reused modals and the stats window now open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
 - **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
 - **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
 - **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.

docs-site/configuration.md

@@ -148,9 +148,9 @@ The configuration file includes several main sections:
 
 - [**Shared AI Provider**](#shared-ai-provider) - Canonical OpenAI-compatible provider config shared by Anki and YouTube subtitle fixing
 - [**AnkiConnect**](#ankiconnect) - Automatic Anki card creation with media
-- [**Kiku/Lapis Integration**](#kiku-lapis-integration) - Sentence cards and duplicate handling for Kiku/Lapis note types
+- [**Kiku/Lapis Integration**](#kiku-lapis-integration) - Sentence cards and duplicate handling for Kiku/Lapis/Senren note types
 - [**N+1 Word Highlighting**](#n-1-word-highlighting) - Known-word cache and single-target highlighting
-- [**Field Grouping Modes**](#field-grouping-modes) - Kiku/Lapis duplicate card merging
+- [**Field Grouping Modes**](#field-grouping-modes) - Kiku/Senren duplicate card merging
 
 **External Integrations**
 
@@ -873,9 +873,10 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope
 
 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.
 
-Current runtime options cover automatic card updates, known-word highlighting,
-known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
-highlighting, known-word match mode, and Kiku field grouping mode.
+Current runtime options cover automatic card updates, media timing review,
+known-word highlighting, known-word maturity coloring, N+1 annotation, JLPT
+underlines, frequency highlighting, known-word match mode, and Kiku field
+grouping mode.
 
 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
 
@@ -967,6 +968,7 @@ Enable automatic Anki card creation and updates with media generation:
       "animatedCrf": 35,
       "normalizeAudio": true,
       "mirrorMpvVolume": true,
+      "reviewTiming": false,
       "audioPadding": 0,
       "fallbackDuration": 3,
       "maxMediaDuration": 30
@@ -1019,6 +1021,7 @@ This example is intentionally compact. The option table below documents availabl
 | `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. Changes apply live.                                                                          |
 | `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
+| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                                |
 | `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"`)                                                                                                                                                                                                 |
@@ -1051,6 +1054,7 @@ This example is intentionally compact. The option table below documents availabl
 | `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time, `%T`=time with milliseconds, `<br>`=newline                                                                                                           |
 | `isLapis`                                         | object                                      | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                                    |
 | `isKiku`                                          | object                                      | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                                       |
+| `isSenren`                                        | object                                      | Senren-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }`. Merges duplicates using Senren's scene-switching markup. Mutually exclusive with `isKiku.enabled`.                                                      |
 
 `ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
 API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
@@ -1080,6 +1084,7 @@ SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [La
 - Enable `isKiku` to turn on duplicate merge behavior for mined Word/Expression hits.
 - When both are enabled, Kiku behavior is applied for grouping while sentence-card model settings are still read from `isLapis`.
 - `isKiku.fieldGrouping` supports `disabled`, `auto`, and `manual` merge modes; see [Field Grouping Modes](#field-grouping-modes).
+- For [Senren](https://github.com/BrenoAqua/Senren) note types, enable `isSenren` instead of `isKiku`. Duplicate merges then use Senren's scene-switching markup (including grouped `miscInfo` entries), and `isSenren.fieldGrouping` supports the same three modes (default: `auto`). Kiku and Senren are mutually exclusive; if both are enabled, Kiku wins and Senren is turned off with a config warning.
 - `lapisKiku.wordCardKind` picks the card-type flag set on word cards; see [Word Card Type](#word-card-type). It is read only while `isLapis` or `isKiku` is enabled.
 
 ### Word Card Type

docs-site/jellyfin-integration.md

@@ -54,7 +54,7 @@ From then on, pause / resume / seek / stop and audio or subtitle track changes y
 - **Resume works.** If Jellyfin has a saved position for the item, SubMiner seeks there on load.
 - **Direct play first.** When the source allows it and the container is in your direct-play allowlist, SubMiner streams the original file; otherwise it requests a transcoded stream from Jellyfin.
 - **Japanese subtitles are auto-selected,** preferring Jellyfin's default and embedded tracks over external sidecar files when several match.
-- **Subtitle timing is corrected when possible.** SubMiner removes Jellyfin's server-selected subtitle stream from the mpv load URL, suppresses the mpv plugin's one-shot subtitle auto-selection and overlay auto-start for managed Jellyfin loads, stages downloaded subtitle tracks without letting mpv auto-switch between tracks, then selects the Japanese track once after applying any saved or inferred timing delay. When Jellyfin provides both Japanese and English subtitle files, SubMiner compares their cue timelines and applies a global delay if one track is clearly offset. Manual delay shifts you make with SubMiner's adjacent-cue controls are saved per item and subtitle track, then restored the next time you select that track.
+- **Downloaded subtitles keep their original timing.** SubMiner removes Jellyfin's server-selected subtitle stream from the mpv load URL, suppresses the mpv plugin's one-shot subtitle auto-selection and overlay auto-start for managed Jellyfin loads, stages the subtitle files exposed by Jellyfin without letting mpv auto-switch between tracks, resets mpv's subtitle delay to zero, then selects the Japanese track. SubMiner does not compare Japanese and English cue timelines or save an inferred delay.
 
 ## Settings
 

docs-site/mining-workflow.md

@@ -41,7 +41,7 @@ If you prefer a hands-on approach (animecards-style), you can copy the current s
    - For multiple lines: press `Ctrl/Cmd+Shift+C`, then a digit `1`–`9` to select how many recent subtitle lines to combine. The combined text is copied to the clipboard.
 3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation - the same fields auto-update would fill.
 
-Manual clipboard updates always replace generated sentence audio, even when `ankiConnect.behavior.overwriteAudio` is disabled. The word audio field is left unchanged because the word itself does not change in this flow.
+Manual clipboard updates always replace generated sentence audio in `ankiConnect.fields.audio`, even when `ankiConnect.behavior.overwriteAudio` is disabled. Normal word-card updates use the configured sentence and audio fields even when Lapis or Kiku support is enabled.
 
 This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
 
@@ -72,17 +72,17 @@ After adding a word via Yomitan, press the audio card shortcut (`Ctrl/Cmd+Shift+
 Audio card marking uses the same `ankiConnect.isLapis.sentenceCardModel` note type as sentence cards. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::
 
-### Field Grouping (Kiku)
+### Field Grouping (Kiku/Senren)
 
-If you mine the same word from different sentences, SubMiner can merge the cards instead of creating duplicates. This feature is designed for use with [Kiku](https://github.com/youyoumu/kiku) and similar note types that support grouped fields.
+If you mine the same word from different sentences, SubMiner can merge the cards instead of creating duplicates. This feature is designed for use with [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) note types that support grouped fields (Senren calls it scene switching).
 
 1. You add a word via Yomitan.
 2. SubMiner detects the new card and checks if a card with the same expression already exists.
-3. If a duplicate is found (this requires `ankiConnect.isKiku.fieldGrouping` to be set to `"auto"` or `"manual"`; it defaults to `"disabled"`):
-   - **Auto mode** (`ankiConnect.isKiku.fieldGrouping: "auto"`): Merges automatically. Both sentences, audio clips, and images are combined into the existing card. The duplicate is optionally deleted.
-   - **Manual mode** (`ankiConnect.isKiku.fieldGrouping: "manual"`): A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.
+3. If a duplicate is found (this requires Kiku or Senren to be enabled with a field grouping mode of `"auto"` or `"manual"`):
+   - **Auto mode**: Merges automatically. Both sentences, audio clips, images, and source info are combined into the existing card. The duplicate is optionally deleted.
+   - **Manual mode**: A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.
 
-See [Anki Integration - Field Grouping](/anki-integration#field-grouping-kiku) for configuration options, merge behavior, and modal keyboard shortcuts.
+See [Anki Integration - Field Grouping](/anki-integration#field-grouping-kiku-senren) for configuration options, merge behavior, and modal keyboard shortcuts.
 
 ## Overlay Model
 

docs-site/public/config.example.jsonc

@@ -523,7 +523,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -569,6 +569,7 @@
       "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. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. 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.
@@ -606,6 +607,11 @@
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
     "lapisKiku": {
       "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
     } // Lapis kiku setting.

docs-site/shortcuts.md

@@ -35,7 +35,7 @@ These work when the overlay window has focus.
 | `Ctrl/Cmd+G`       | Trigger field grouping (Kiku merge check)       | `shortcuts.triggerFieldGrouping`        |
 | `Ctrl/Cmd+Shift+A` | Mark last card as audio card                    | `shortcuts.markAudioCard`               |
 
-The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcuts.multiCopyTimeoutMs`). Press `1`–`9` to select how many recent subtitle lines to combine. When the shortcut starts from mpv, SubMiner focuses the visible overlay for that selector instead of reserving the number keys in the mpv plugin.
+The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcuts.multiCopyTimeoutMs`). Press `1`–`9` to select the total number of subtitle lines to combine, ending at the current line and moving backward through the subtitle timeline. The current line counts toward the selected total. When the shortcut starts from mpv, SubMiner focuses the visible overlay for that selector instead of reserving the number keys in the mpv plugin.
 
 ## Overlay Controls
 

docs-site/tsukihime-integration.md

@@ -14,7 +14,7 @@ Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is th
 
 ## How It Works
 
-The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Tracks with no language tag stay visible on the secondary tab.
+The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter both the release list and the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Each tab lists only the releases whose reported subtitle languages include the tab's language, so the Japanese tab hides the many releases that ship English subtitles only. Releases and tracks with no language tag stay visible on the secondary tab. If nothing on the active tab qualifies, the status line says so and points at the other tab.
 
 When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.
 
@@ -76,6 +76,7 @@ The previous `--open-animetosho` flag and `__animetosho-open` keybinding command
 ## Troubleshooting
 
 - **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
+- **"No releases with Japanese subtitles"** - none of the search results carry a Japanese track. Most releases only ship English subtitles; try another search, or use the [Jimaku integration](/jimaku-integration) for Japanese subtitles.
 - **"Batch releases are not supported"** - TsukiHime only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
 - **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
 - **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.

docs/architecture/subtitle-overlay-priming.md

@@ -129,6 +129,21 @@ coming and prefetching would otherwise idle for the rest of the cue.
   between ordinary, hard, or ideographic spaces appear once.
 - Simultaneous ASS lines are flattened in top-to-bottom positioned order, falling back to their
   authored source order when no usable position exists.
+- Half-size kana positioned directly above a same-timed kanji caption is treated as ASS
+  furigana. The parser omits it from published cues but retains hidden matching metadata so
+  mpv's raw live text can be reconciled without displaying or mining the reading. The
+  timing tracker (clipboard copy, recent-line mining) and immersion recorders run the same
+  reconciliation on the `sub-start`/`sub-end` sample, so they record what the overlay shows.
+- Broadcast-caption rows that spell one utterance across several same-timed positioned events
+  (same style, layer, and vertical band, stacked at most two text rows apart) are joined into
+  one cue with a single line break, so `preserveLineBreaks` treats them like an authored `\N`,
+  and the recorders above see the whole sentence. A row continues the one above it when that row
+  is a bare speaker label, ends without terminal punctuation, or leaves a ≪…≫ / ⸨…⸩ span open; a
+  lower row that opens its own label or span always starts a new cue, which keeps two speakers
+  sharing the screen on separate lines. The pass runs only on scripts that read as broadcast
+  captions (a meaningful share of events carry speaker labels or ≪…≫ / ⸨…⸩ spans) and only on
+  rows containing Japanese, because fansub typesetting stacks positioned rows for signs, chat
+  bubbles, and headlines where that punctuation convention does not hold.
 - Fragment-only ASS karaoke is reconstructed per style before publication. Explicit spaces
   survive concatenation. Latin fragment typesetting with no literal spaces also recovers word
   boundaries represented only by materially larger horizontal `\pos` or `\move` gaps within that

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.19.4",
+  "version": "0.19.6",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -87,7 +87,7 @@
     "app-builder-lib": "26.15.3",
     "brace-expansion": "5.0.9",
     "electron-builder-squirrel-windows": "26.15.3",
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.6",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
     "js-yaml": "4.3.1",

release/release-notes.md

@@ -1,68 +1,41 @@
 ## Highlights
 ### Added
-- **Library Duplicate & Misfiled Episode Tools**
-  - Merge duplicate show cards from the Library grid: select cards and use "Merge Selected" to combine sessions, mined cards, and watch time onto one entry while keeping remembered title aliases.
-  - Reassign a misfiled episode to the correct show with the "→" button on an episode row; the fix survives later filename parsing, Jellyfin refreshes, and season repair.
-  - Exact AniList matches merge automatically, while likely (fuzzy) matches surface as a dismissible "Possible duplicate" suggestion instead of merging without confirmation.
-- **Stats Duplicate-Line Cleanup Tool**
-  - The Vocabulary tab's new Duplicates button scans a chosen time window for old karaoke/animation duplicate bursts and collapses each one to a single line after you confirm, without touching watch time or lines-seen totals.
-  - The same cleanup is available from the terminal via `subminer stats cleanup --duplicate-lines`, with `--dry-run` and `--lookback-days` options.
+- **Pre-Mining Timing Review**:
+  - Optional review step before creating word, sentence, or audio cards, with a speech-focused waveform that filters out steady background noise so dialogue is easy to spot.
+  - The clip end automatically snaps back to where dialogue actually ends, since subtitles often linger after speech stops.
+  - Drag or use the keyboard to adjust clip boundaries, and preview audio with a sweeping playhead that plays to the true end even on high-latency outputs like Bluetooth headphones.
+  - Pull extra previous or next subtitle lines onto the card with `P`/`N` (or the Prev/Next steppers); a live preview shows exactly what the card will contain.
+  - You can cancel and still keep the card without media, and the review can be toggled on or off for the session.
+- **Senren Note Type Support**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, combining sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled grouping modes as Kiku, including the manual merge modal. Senren and Kiku are mutually exclusive, so only one can be enabled at a time.
 
 ### Changed
-- **Prerelease Notes "Changes Since" Section**
-  - Prerelease release notes now open with a "Changes since" section listing only what changed since the previous beta/RC of the same version, shown above the full cumulative highlights.
+- **Remote Streaming Mining**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream for every step. No action needed; the temporary download is cleaned up automatically after ten minutes of inactivity.
+- **TsukiHime Release Picker**: The Japanese and secondary-language tabs now filter releases down to ones that actually carry subtitles for that language, and tell you when none do.
 
 ### Fixed
-- **Subtitle Deduplication & Karaoke Reconstruction**
-  - Typeset ASS karaoke and animated signs are reconstructed into their authored line and shown once, instead of flooding the overlay, subtitle sidebar, immersion history, sentence mining, and stats with per-frame glyph fragments and repeated lyric bursts (a lyric could previously pin itself to the top of "Top Repeated Words").
-  - The same deduplication now applies consistently everywhere, including embedded subtitles extracted from network-mounted (SMB/NFS) media and the secondary subtitle overlay, while ordinary repeated dialogue, signs, and rewatches remain unaffected.
-  - Secondary subtitle overlays no longer clip long lines after about four rows, and no longer show scattered-letter or duplicated text while embedded subtitles are still being extracted.
-- **Character Dictionary Reliability & Notifications**
-  - Character dictionary generation, rebuilds, and imports no longer freeze the app or trigger "not responding" dialogs on large dictionaries; the heavy work now runs off the main UI thread.
-  - Dictionaries are reused instead of being regenerated on every launch when no name splits were found, and portraits reappear correctly once the cached portrait index finishes loading.
-  - Linux desktop progress notifications, including on AppImage installs, now update in place instead of flickering closed and reopening.
-- **Overlay Startup Reliability**
-  - The overlay no longer gets stuck on an endless "Overlay loading" screen when mpv's connection stalls at startup; connections now time out and retry, and a clear error appears if content still isn't ready after 30 seconds.
-- **Overlay Modal Windows (macOS & Windows)**
-  - Modal windows such as Settings prewarm so shortcuts open them promptly on first press.
-  - On Windows, the hidden modal renderer now refreshes between sessions so later modals stay interactive.
-  - On macOS, reused modals and the stats window open above fullscreen mpv on the correct Space instead of jumping to another desktop; the overlay-attach helper also now supports macOS 12.0+, fixing "Overlay loading" getting stuck on older macOS versions.
-- **Windows Mouse Lag**
-  - Fixed system-wide mouse lag while SubMiner is running: the overlay no longer installs a global mouse hook, and the mpv window tracker no longer blocks the app with repeated command-line lookups.
-- **Linux Overlay & Launcher Fixes**
-  - Native Wayland drag-and-drop from file managers such as Thunar now works, so subtitle and video files dropped on the overlay reach mpv.
-  - Fixed missing MKV thumbnails in the rofi file picker on systems that only advertise legacy Matroska MIME aliases.
-- **Sentence Mining Audio & Clip Accuracy**
-  - Sentence-audio generation no longer times out on slow network-mounted MKV files with many subtitle/font streams; probing is now bounded with a two-minute extraction budget and a clear error instead of a raw failure.
-  - Mined audio and animated clips now capture the exact subtitle line that was mined, instead of whatever line was on screen after audio extraction finished, fixing too-short or misaligned clips.
-- **Stats Reliability & Performance**
-  - Fixed transient database-lock errors when multiple stats workers wrote at once.
-  - Stats deletes, library merges, video moves, and AniList reassignments no longer freeze the dashboard or rebuild lifetime totals from scratch, so they're fast and preserve lifetime totals older than the recent session-retention window; session deletes on large databases dropped from minutes to milliseconds.
-- **Vocabulary Tab Accuracy**
-  - Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, with new-word history rebuilt from corrected daily rollups to match.
-  - Calendar charts keep the correct local date in time zones west of UTC, and vocabulary cards/charts now refresh automatically and retry after the word exclusion list changes.
+- **Broadcast Caption Accuracy**:
+  - Japanese caption tracks split across two positioned lines (e.g. Crunchyroll) now merge into one, so mined sentences, the sidebar, and line-break settings treat them as a single line; lines from different speakers or sound effects still stay separate.
+  - Mining from the overlay no longer picks up a leftover line from the previous caption, so the mined sentence and clip timing match what's actually on screen.
+  - Copying or mining subtitles no longer includes the separate furigana line that some broadcast subtitle files place above kanji.
+- **Multi-line Copy After Seeking**: Selecting multiple subtitle lines to copy or mine now selects backward in timeline order after a seek, rather than in playback encounter order.
+- **Overlay Stability**:
+  - On Hyprland, opening a modal (timing review, Jimaku, session help, and others) over fullscreen mpv no longer makes the overlay flicker while the modal loads.
+  - Switching secondary subtitle tracks no longer causes mpv's native secondary subtitles to flash on screen.
+- **Anki Update Notifications**: Switching notification settings to on-screen display while a card update is still in progress now correctly dismisses the old overlay progress indicator.
+- **Jellyfin Subtitles**: Subtitle files now load with zero delay in mpv instead of Jellyfin inferring and applying a sync offset.
 
 ## What's Changed
 
-- feat(stats): add library entry merge and episode move by @ksyasuda in #190
-- fix(stats): stop counting duplicate typeset subtitle lines by @ksyasuda in #191
-- fix(media): tolerate slow MKV audio extraction by @ksyasuda in #195
-- fix(stats): subtract lifetime totals incrementally on delete by @ksyasuda in #196
-- fix(anki): snapshot mining media clip timing by @ksyasuda in #197
-- fix(notifications): replace Linux progress updates in place by @ksyasuda in #198
-- fix(overlay): support native Wayland file drag-and-drop by @ksyasuda in #199
-- fix(overlay): keep macOS modal windows on fullscreen Spaces by @ksyasuda in #200
-- fix(overlay): prevent Windows mouse lag during click-through tracking by @ksyasuda in #201
-- fix(stats): report complete vocabulary totals and new-word history by @ksyasuda in #202
-- fix(mpv): recover from stalled IPC connects by @ksyasuda in #204
-- fix(dictionary): prevent freezes and restore AppImage notifications by @ksyasuda in #205
-- fix(subtitles): recover canonical lines from ASS animation by @ksyasuda in #207
-- fix(overlay): deduplicate secondary subtitle rendering by @ksyasuda in #208
-- fix(launcher): restore Matroska thumbnails in Linux rofi picker by @ksyasuda in #210
-- fix(character-dictionary): cache completed MeCab refreshes by @ksyasuda in #212
-- fix(subtitles): improve secondary subtitle extraction and display by @ksyasuda in #215
-- feat(release): track prerelease deltas and validate committed notes by @ksyasuda in #216
-- fix(subtitles): recover positioned ASS word spacing and drop control debris by @ksyasuda in #217
+- feat(anki): add media timing review before card creation by @ksyasuda in #203
+- fix(jellyfin): stop inferring subtitle delays by @ksyasuda in #227
+- feat(anki): support Senren scene-switching field grouping by @ksyasuda in #230
+- fix(mining): copy multi-line subtitles backward from current line by @ksyasuda in #231
+- fix(subtitles): keep native secondary subtitles hidden by @ksyasuda in #232
+- fix(subtitles): drop ASS furigana from recorded cues by @ksyasuda in #233
+- fix(subtitles): merge wrapped positioned caption rows by @ksyasuda in #234
+- fix(tsukihime): filter releases by subtitle language by @ksyasuda in #235
 
 ## Installation
 

scripts/build-changelog.test.ts

@@ -44,14 +44,22 @@ function fragmentTypesInPrompt(input: string): string[] {
     .map((line) => line.slice('type: '.length).trim());
 }
 
-function assertReleaseNotesPromptRequestsNestedBullets(input: string): void {
-  assert.match(input, /In MODE: release-notes, use short top-level change bullets/);
-  assert.match(input, /Nested bullets should cover the change, user benefit, and any user action/);
-  assert.match(input, /Do not require the exact nested labels/);
+function assertPromptRequestsNestedBullets(input: string): void {
+  assert.match(input, /In both modes, split every item into one nested bullet per distinct change/);
+  assert.match(input, /Never stack several distinct changes into one long paragraph-shaped bullet/);
   assert.match(input, /Keep nested bullets short, concrete, and readable by non-technical users/);
   assert.match(input, /Avoid paragraph-style release-note bullets/);
 }
 
+function assertReleaseNotesPromptRequestsNestedBullets(input: string): void {
+  assertPromptRequestsNestedBullets(input);
+  assert.match(
+    input,
+    /In MODE: release-notes, nested bullets should also cover user benefit and any user action/,
+  );
+  assert.match(input, /Do not require the exact nested labels/);
+}
+
 function defaultPolishedBody(input: string): string {
   const mode = modeFromPrompt(input);
   const types = fragmentTypesInPrompt(input);
@@ -446,6 +454,7 @@ test('writeChangelogArtifacts prompts Claude to summarize the final stable outco
         prompt,
         /Multiple fixes within the same prerelease cycle should collapse into one current-state bullet/,
       );
+      assertPromptRequestsNestedBullets(prompt);
     }
 
     const releaseNotesPrompt = stub.calls.find(

scripts/build-changelog.ts

@@ -480,10 +480,15 @@ You will receive a list of FRAGMENT entries below. Each fragment has metadata (t
    - Be merged with related bullets when possible. If five fragments all touch Windows overlay z-order/focus/restore, write one or two bullets that summarize the overall improvement instead of five.
    - Drop bullets that only describe PR housekeeping, CodeRabbit follow-ups, or test-only changes that don't affect users.
    - Preserve the substance of breaking changes that remain breaking after applying the Release Outcome Rules. Do not soften or omit them.
-5. In MODE: changelog, each item may be a conventional single-level bullet, e.g. "- Playlist Browser: Adds faster saved-show browsing."
-6. In MODE: release-notes, use short top-level change bullets with two or three nested bullets when an item needs explanation.
-   Nested bullets should cover the change, user benefit, and any user action or compatibility note when useful. Do not require the exact nested labels; natural phrasing is fine. Omit the action bullet when no action is needed.
+5. In both modes, split every item into one nested bullet per distinct change. Write a short bold name on the top-level bullet, then indent the details two spaces:
+   - **Playlist Browser**:
+     - Saved shows now open without rescanning the library.
+     - The picker remembers the last folder you browsed between launches.
+   Each nested bullet covers exactly one change, behavior, or user-visible outcome. Never stack several distinct changes into one long paragraph-shaped bullet.
+   Aim for two to five nested bullets per item. When an item genuinely has only one thing to say, put it inline on the top-level bullet ("- **Playlist Browser**: Saved shows now open without rescanning the library.") instead of emitting a single nested bullet.
    Keep nested bullets short, concrete, and readable by non-technical users. Avoid paragraph-style release-note bullets.
+   Bullets inside the Internal section may stay single-level.
+6. In MODE: release-notes, nested bullets should also cover user benefit and any user action or compatibility note when useful. Do not require the exact nested labels; natural phrasing is fine. Omit the action bullet when no action is needed.
 7. Do not invent features. Every bullet must be grounded in the input fragments.
 8. Do not include the version heading (## v...) — that wrapper is added by the caller.
 

src/anki-integration.test.ts

@@ -11,10 +11,12 @@ import type { MediaInput } from './media-input';
 import { AnkiConnectConfig } from './types';
 
 type TestOverlayNotificationPayload = {
+  id?: string;
   title: string;
   body?: string;
   image?: string;
   variant?: string;
+  persistent?: boolean;
   actions?: Array<{ id: string; label: string; noteId?: number }>;
 };
 
@@ -153,6 +155,7 @@ function createFieldGroupingMergeCollaborator(options?: {
     getEffectiveSentenceCardConfig: () => ({
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
+      fieldGroupingProvider: 'kiku' as const,
     }),
     getCurrentSubtitleText: () => options?.currentSubtitleText,
     resolveFieldName,
@@ -606,6 +609,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
   const integration = new AnkiIntegration(
     {
       fields: {
+        audio: 'ExpressionAudio',
         image: 'Picture',
       },
       media: {
@@ -659,7 +663,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
       noteIds.map((noteId) => ({
         noteId,
         fields: {
-          SentenceAudio: { value: '' },
+          ExpressionAudio: { value: '' },
           Picture: { value: '' },
         },
       })),
@@ -944,7 +948,7 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
     noteInfo: {
       noteId: 404,
       fields: {
-        SentenceAudio: { value: '' },
+        ExpressionAudio: { value: '' },
         Picture: { value: '' },
       },
     },
@@ -956,7 +960,8 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
   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.ExpressionAudio ?? '', /^\[sound:audio_/);
+  assert.equal(updatedNotes[0]?.fields.SentenceAudio, undefined);
   assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
   assert.equal(storedMedia.length, 2);
   assert.deepEqual(audioVolumeScales, [0.3 ** 3]);
@@ -1182,6 +1187,117 @@ test('AnkiIntegration embeds generated notification image on overlay mined-card
   assert.deepEqual(cleanupPaths, [notificationIconPath]);
 });
 
+test('AnkiIntegration keeps overlay card-update progress visible until the terminal 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);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    showNotification: (noteId: number, label: string | number) => Promise<void>;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  await updateNotifications.showNotification(42, '食べる');
+
+  assert.deepEqual(
+    overlayNotifications.map(({ id, variant, persistent }) => ({ id, variant, persistent })),
+    [
+      { id: 'anki-update-progress', variant: 'progress', persistent: true },
+      { id: 'anki-update-progress', variant: 'success', persistent: false },
+    ],
+  );
+});
+
+test('AnkiIntegration dismisses persistent overlay update progress when no terminal notification replaces it', () => {
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+  const dismissedIds: string[] = [];
+  const integration = new AnkiIntegration(
+    {
+      behavior: {
+        notificationType: 'overlay',
+      },
+    },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload);
+    },
+    undefined,
+    undefined,
+    undefined,
+    (id) => {
+      dismissedIds.push(id);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    endUpdateProgress: () => void;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  updateNotifications.endUpdateProgress();
+
+  assert.equal(overlayNotifications[0]?.persistent, true);
+  assert.deepEqual(dismissedIds, ['anki-update-progress']);
+});
+
+test('AnkiIntegration dismisses overlay update progress after notifications switch to OSD', () => {
+  const behavior: NonNullable<AnkiConnectConfig['behavior']> = {
+    notificationType: 'overlay',
+  };
+  const dismissedIds: string[] = [];
+  const integration = new AnkiIntegration(
+    { behavior },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    () => {},
+    undefined,
+    undefined,
+    undefined,
+    (id) => {
+      dismissedIds.push(id);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    endUpdateProgress: () => void;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  behavior.notificationType = 'osd';
+  updateNotifications.endUpdateProgress();
+
+  assert.deepEqual(dismissedIds, ['anki-update-progress']);
+});
+
 test('AnkiIntegration keeps overlay notification image when temp icon write fails', async () => {
   const desktopNotifications: Array<{ title: string; body?: string; icon?: string }> = [];
   const overlayNotifications: TestOverlayNotificationPayload[] = [];

src/anki-integration.ts

@@ -28,6 +28,8 @@ import {
   KikuMergePreviewResponse,
   NotificationOptions,
   type WordCardKind,
+  type MediaTimingReviewDecision,
+  type MediaTimingReviewRequest,
 } from './types/anki';
 import { AiConfig } from './types/integrations';
 import type { KnownWordMaturityTier } from './types/subtitle';
@@ -218,6 +220,8 @@ export class AnkiIntegration {
     null;
   private overlayNotificationCallback: ((payload: OverlayNotificationPayload) => void) | null =
     null;
+  private overlayNotificationDismissCallback: ((id: string) => void) | null = null;
+  private overlayUpdateProgressActive = false;
   private updateInProgress = false;
   private uiFeedbackState: UiFeedbackState = createUiFeedbackState();
   private parseWarningKeys = new Set<string>();
@@ -238,6 +242,9 @@ export class AnkiIntegration {
   private recordCardsMinedCallback: ((count: number, noteIds?: number[]) => void) | null = null;
   private knownWordCacheUpdatedCallback: (() => void) | null = null;
   private consumeSubtitleMiningContextCallback: (() => SubtitleMiningContext | null) | null = null;
+  private mediaTimingReviewCallback:
+    | ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>)
+    | null = null;
   private noteIdRedirects = new Map<number, number>();
   private trackedDuplicateNoteIds = new Map<number, number[]>();
   private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
@@ -265,6 +272,7 @@ export class AnkiIntegration {
     getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'],
     shouldRequireRemoteMediaCache?: () => boolean,
     getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined,
+    overlayNotificationDismissCallback?: (id: string) => void,
   ) {
     this.config = normalizeAnkiIntegrationConfig(config);
     this.aiConfig = { ...aiConfig };
@@ -280,6 +288,7 @@ export class AnkiIntegration {
     this.getCachedMediaPath = getCachedMediaPath ?? null;
     this.shouldRequireRemoteMediaCache = shouldRequireRemoteMediaCache ?? null;
     this.getYoutubeMediaSourceUrl = getYoutubeMediaSourceUrl ?? null;
+    this.overlayNotificationDismissCallback = overlayNotificationDismissCallback ?? null;
     this.pendingYoutubeMediaQueue = this.createPendingYoutubeMediaQueue();
     this.knownWordCache = this.createKnownWordCache(knownWordCacheStatePath);
     this.pollingRunner = this.createPollingRunner();
@@ -379,8 +388,6 @@ export class AnkiIntegration {
       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) =>
@@ -509,6 +516,7 @@ export class AnkiIntegration {
         findNotes: async (query, options) =>
           (await this.client.findNotes(query, options)) as number[],
         retrieveMediaFile: (filename) => this.client.retrieveMediaFile(filename),
+        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       mediaGenerator: {
         generateAudio: (
@@ -566,6 +574,7 @@ export class AnkiIntegration {
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       getFallbackDurationSeconds: () => this.getFallbackDurationSeconds(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
+      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       isUpdateInProgress: () => this.updateInProgress,
       setUpdateInProgress: (value) => {
         this.updateInProgress = value;
@@ -581,6 +590,7 @@ export class AnkiIntegration {
       recordCardsMinedCallback: (count, noteIds) => {
         this.recordCardsMinedSafely(count, noteIds, 'card creation');
       },
+      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -637,12 +647,14 @@ export class AnkiIntegration {
         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),
+        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       getConfig: () => this.config,
       getCurrentSubtitleText: () => this.mpvClient.currentSubText,
       getCurrentSubtitleStart: () => this.mpvClient.currentSubStart,
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
+      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       extractFields: (fields) => this.extractFields(fields),
       findDuplicateNote: (expression, excludeNoteId, noteInfo) =>
         this.findDuplicateNote(expression, excludeNoteId, noteInfo),
@@ -657,8 +669,6 @@ export class AnkiIntegration {
         this.setCardTypeFields(updatedFields, availableFieldNames, cardKind),
       resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
         this.resolveConfiguredFieldName(noteInfo, ...preferredNames),
-      getResolvedSentenceAudioFieldName: (noteInfo) =>
-        this.getResolvedSentenceAudioFieldName(noteInfo),
       getAnimatedImageLeadInSeconds: (noteInfo) => this.getAnimatedImageLeadInSeconds(noteInfo),
       mergeFieldValue: (existing, newValue, overwrite) =>
         this.mergeFieldValue(existing, newValue, overwrite),
@@ -680,6 +690,7 @@ export class AnkiIntegration {
       logWarn: (...args) => log.warn(args[0] as string, ...args.slice(1)),
       logInfo: (...args) => log.info(args[0] as string, ...args.slice(1)),
       logError: (...args) => log.error(args[0] as string, ...args.slice(1)),
+      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -799,6 +810,12 @@ export class AnkiIntegration {
     }
   }
 
+  private removeKnownWordNote(noteId: number): void {
+    if (this.knownWordCache.removeNote(noteId)) {
+      this.notifyKnownWordCacheUpdated();
+    }
+  }
+
   private notifyKnownWordCacheUpdated(): void {
     if (!this.knownWordCacheUpdatedCallback) {
       return;
@@ -835,6 +852,19 @@ export class AnkiIntegration {
     };
   }
 
+  private getSenrenConfig(): {
+    enabled: boolean;
+    fieldGrouping?: 'auto' | 'manual' | 'disabled';
+    deleteDuplicateInAuto?: boolean;
+  } {
+    const senren = this.config.isSenren;
+    return {
+      enabled: senren?.enabled === true,
+      fieldGrouping: senren?.fieldGrouping,
+      deleteDuplicateInAuto: senren?.deleteDuplicateInAuto,
+    };
+  }
+
   private getEffectiveSentenceCardConfig(): {
     model?: string;
     sentenceField: string;
@@ -843,10 +873,27 @@ export class AnkiIntegration {
     kikuEnabled: boolean;
     kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
     kikuDeleteDuplicateInAuto: boolean;
+    senrenEnabled: boolean;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
+    fieldGroupingDeleteDuplicateInAuto: boolean;
     wordCardKind: WordCardKind;
   } {
     const lapis = this.getLapisConfig();
     const kiku = this.getKikuConfig();
+    const senren = this.getSenrenConfig();
+
+    const kikuFieldGrouping = (kiku.fieldGrouping || 'disabled') as 'auto' | 'manual' | 'disabled';
+    const senrenFieldGrouping = (senren.fieldGrouping || 'auto') as 'auto' | 'manual' | 'disabled';
+    // Kiku and Senren are mutually exclusive; config resolution enforces it, and
+    // Kiku wins here too in case a runtime patch re-enables both.
+    const fieldGroupingProvider = kiku.enabled ? 'kiku' : senren.enabled ? 'senren' : null;
+    const fieldGroupingMode =
+      fieldGroupingProvider === 'kiku'
+        ? kikuFieldGrouping
+        : fieldGroupingProvider === 'senren'
+          ? senrenFieldGrouping
+          : 'disabled';
 
     return {
       model: lapis.sentenceCardModel,
@@ -854,8 +901,15 @@ export class AnkiIntegration {
       audioField: 'SentenceAudio',
       lapisEnabled: lapis.enabled,
       kikuEnabled: kiku.enabled,
-      kikuFieldGrouping: (kiku.fieldGrouping || 'disabled') as 'auto' | 'manual' | 'disabled',
+      kikuFieldGrouping,
       kikuDeleteDuplicateInAuto: kiku.deleteDuplicateInAuto !== false,
+      senrenEnabled: senren.enabled,
+      fieldGroupingProvider,
+      fieldGroupingMode,
+      fieldGroupingDeleteDuplicateInAuto:
+        fieldGroupingProvider === 'senren'
+          ? senren.deleteDuplicateInAuto !== false
+          : kiku.deleteDuplicateInAuto !== false,
       wordCardKind: resolveWordCardKindSetting(this.config.lapisKiku?.wordCardKind),
     };
   }
@@ -874,7 +928,7 @@ export class AnkiIntegration {
 
   private async processNewCard(
     noteId: number,
-    options?: { skipKikuFieldGrouping?: boolean },
+    options?: { skipFieldGrouping?: boolean },
   ): Promise<void> {
     await this.noteUpdateWorkflow.execute(noteId, options);
   }
@@ -1039,7 +1093,7 @@ export class AnkiIntegration {
       videoPath,
       startTime,
       endTime,
-      this.config.media?.audioPadding,
+      context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
       this.config.media?.normalizeAudio !== false,
       await this.getMpvVolumeScale(),
@@ -1072,7 +1126,7 @@ export class AnkiIntegration {
         videoPath,
         mediaRange.startTime,
         mediaRange.endTime,
-        this.config.media?.audioPadding,
+        context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
         {
           fps: this.config.media?.animatedFps,
           maxWidth: this.config.media?.animatedMaxWidth,
@@ -1203,12 +1257,13 @@ export class AnkiIntegration {
   private beginUpdateProgress(initialMessage: string): void {
     if (!this.shouldUseOsdNotifications()) {
       if (this.shouldUseOverlayNotifications()) {
+        this.overlayUpdateProgressActive = true;
         this.overlayNotificationCallback?.({
           id: 'anki-update-progress',
           title: 'Anki update',
           body: initialMessage,
           variant: 'progress',
-          persistent: false,
+          persistent: true,
         });
       }
       return;
@@ -1219,6 +1274,10 @@ export class AnkiIntegration {
   }
 
   private endUpdateProgress(): void {
+    if (this.overlayUpdateProgressActive) {
+      this.overlayUpdateProgressActive = false;
+      this.overlayNotificationDismissCallback?.('anki-update-progress');
+    }
     if (!this.shouldUseOsdNotifications()) {
       return;
     }
@@ -1243,18 +1302,20 @@ export class AnkiIntegration {
     if (!this.shouldUseOsdNotifications()) {
       this.updateInProgress = true;
       if (this.shouldUseOverlayNotifications()) {
+        this.overlayUpdateProgressActive = true;
         this.overlayNotificationCallback?.({
           id: 'anki-update-progress',
           title: 'Anki update',
           body: initialMessage,
           variant: 'progress',
-          persistent: false,
+          persistent: true,
         });
       }
       try {
         return await action();
       } finally {
         this.updateInProgress = false;
+        this.endUpdateProgress();
       }
     }
     return withUpdateProgress(
@@ -1353,6 +1414,7 @@ export class AnkiIntegration {
         : undefined;
 
     if (shouldShowOverlayNotification && this.overlayNotificationCallback) {
+      this.overlayUpdateProgressActive = false;
       this.overlayNotificationCallback({
         id: 'anki-update-progress',
         title: 'Anki Card Updated',
@@ -1496,7 +1558,7 @@ export class AnkiIntegration {
     trackedDuplicateNoteIdsBeforeCreate: Set<number>,
   ): boolean {
     const sentenceCardConfig = this.getEffectiveSentenceCardConfig();
-    if (!sentenceCardConfig.kikuEnabled || sentenceCardConfig.kikuFieldGrouping === 'disabled') {
+    if (sentenceCardConfig.fieldGroupingMode === 'disabled') {
       return false;
     }
 
@@ -1555,13 +1617,6 @@ export class AnkiIntegration {
     return sentenceCardConfig.audioField || 'SentenceAudio';
   }
 
-  private getResolvedSentenceAudioFieldName(noteInfo: NoteInfo): string | null {
-    return (
-      this.resolveNoteFieldName(noteInfo, this.getPreferredSentenceAudioFieldName()) ||
-      this.resolveConfiguredFieldName(noteInfo, this.config.fields?.audio)
-    );
-  }
-
   private getConfiguredWordFieldName(): string {
     return getConfiguredWordFieldName(this.config);
   }
@@ -1723,6 +1778,25 @@ export class AnkiIntegration {
     this.consumeSubtitleMiningContextCallback = callback;
   }
 
+  setMediaTimingReviewCallback(
+    callback: ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>) | null,
+  ): void {
+    this.mediaTimingReviewCallback = callback;
+  }
+
+  private async reviewMediaTiming(
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ): Promise<MediaTimingReviewDecision> {
+    if (this.config.media?.reviewTiming !== true || !this.mediaTimingReviewCallback) {
+      return { action: 'use-original' };
+    }
+    return await this.mediaTimingReviewCallback({
+      ...request,
+      audioPadding: Math.max(0, this.config.media.audioPadding ?? 0),
+      maxMediaDuration: Math.max(0, this.config.media.maxMediaDuration ?? 30),
+    });
+  }
+
   resolveCurrentNoteId(noteId: number): number {
     let resolved = noteId;
     const seen = new Set<number>();

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

@@ -85,6 +85,7 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => Buffer.from('audio'),
@@ -124,11 +125,11 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -143,7 +144,7 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
   };
 }
 
-test('manual clipboard subtitle update replaces sentence audio without touching expression audio', async () => {
+test('manual clipboard subtitle update replaces audio in the configured field', async () => {
   const { service, updatedFields, mergeCalls, storedMedia } = createManualUpdateService();
 
   await service.updateLastAddedFromClipboard('字幕');
@@ -151,14 +152,144 @@ test('manual clipboard subtitle update replaces sentence audio without touching
   assert.equal(updatedFields.length, 1);
   assert.equal(storedMedia.length, 1);
   const audioValue = `[sound:${storedMedia[0]}]`;
-  assert.equal(updatedFields[0]?.SentenceAudio, audioValue);
-  assert.equal('ExpressionAudio' in updatedFields[0]!, false);
+  assert.equal(updatedFields[0]?.ExpressionAudio, audioValue);
+  assert.equal('SentenceAudio' in updatedFields[0]!, false);
   assert.deepEqual(
     mergeCalls.map((call) => call.overwrite),
     [true],
   );
 });
 
+test('manual clipboard word-card update uses configured fields with Lapis and Kiku enabled', async () => {
+  const { service, updatedFields } = createManualUpdateService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          word: 'Expression',
+          sentence: 'Context',
+          audio: 'ContextAudio',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          maxMediaDuration: 30,
+        },
+        behavior: {
+          overwriteAudio: false,
+          overwriteImage: false,
+        },
+        ai: false,
+      }) as AnkiConnectConfig,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: '単語' },
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Context: { value: '' },
+            ContextAudio: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async (_noteId, fields) => {
+        updatedFields.push(fields);
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
+    },
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: true,
+      kikuEnabled: true,
+      fieldGroupingMode: 'disabled',
+    }),
+  });
+
+  await service.updateLastAddedFromClipboard('字幕');
+
+  assert.equal(updatedFields.length, 1);
+  assert.match(updatedFields[0]?.ContextAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.deepEqual(Object.keys(updatedFields[0] ?? {}).sort(), ['Context', 'ContextAudio']);
+  assert.equal(updatedFields[0]?.Context, '字幕');
+});
+
+test('audio-card action keeps Lapis and Kiku sentence fields', async () => {
+  const { service, updatedFields } = createManualUpdateService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          word: 'Expression',
+          sentence: 'Context',
+          audio: 'ContextAudio',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          maxMediaDuration: 30,
+        },
+        behavior: {},
+        ai: false,
+      }) as AnkiConnectConfig,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentAudioStreamIndex: 0,
+        currentSubText: '字幕',
+        currentSubStart: 12,
+        currentSubEnd: 14,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: '単語' },
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Context: { value: '' },
+            ContextAudio: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async (_noteId, fields) => {
+        updatedFields.push(fields);
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
+    },
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: true,
+      kikuEnabled: true,
+      fieldGroupingMode: 'disabled',
+    }),
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.equal(updatedFields.length, 1);
+  assert.equal(updatedFields[0]?.Sentence, '字幕');
+  assert.match(updatedFields[0]?.SentenceAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.equal('Context' in (updatedFields[0] ?? {}), false);
+  assert.equal('ContextAudio' in (updatedFields[0] ?? {}), false);
+});
+
 test('manual clipboard subtitle update marks Kiku word cards as word-and-sentence cards when enabled', async () => {
   const { service, updatedFields } = createManualUpdateService({
     getConfig: () =>
@@ -201,6 +332,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       storeMediaFile: async () => undefined,
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     getEffectiveSentenceCardConfig: () => ({
       model: 'Sentence',
@@ -208,8 +340,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     setCardTypeFields,
   });
@@ -225,7 +356,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
   });
 });
 
-test('manual clipboard subtitle update skips audio when sentence audio field is missing', async () => {
+test('manual clipboard subtitle update uses configured audio when SentenceAudio is missing', async () => {
   const { service, updatedFields, mergeCalls, storedMedia } = createManualUpdateService({
     client: {
       addNote: async () => 0,
@@ -248,6 +379,7 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
   });
 
@@ -255,8 +387,9 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
 
   assert.equal(storedMedia.length, 1);
   assert.equal(updatedFields.length, 1);
-  assert.deepEqual(updatedFields[0], { Sentence: '字幕' });
-  assert.equal(mergeCalls.length, 0);
+  assert.match(updatedFields[0]?.ExpressionAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.equal(updatedFields[0]?.Sentence, '字幕');
+  assert.equal(mergeCalls.length, 1);
 });
 
 test('manual clipboard subtitle update uses resolved mpv stream URLs for remote media', async () => {
@@ -335,6 +468,7 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -383,3 +517,98 @@ test('createSentenceCard relies on Anki progress notification without standalone
   assert.deepEqual(progressMessages, ['Creating sentence card']);
   assert.deepEqual(statusMessages, []);
 });
+
+test('discarding an audio-card timing review deletes the note before evicting its cache entry', async () => {
+  const events: string[] = [];
+  const statusMessages: string[] = [];
+  const { service } = createManualUpdateService({
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentSubText: '字幕',
+        currentSubStart: 4,
+        currentSubEnd: 6,
+        currentTimePos: 5,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: { Expression: { value: '単語' } },
+        },
+      ],
+      updateNoteFields: async () => undefined,
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async (noteIds) => {
+        events.push(`delete:${noteIds.join(',')}`);
+      },
+    },
+    reviewMediaTiming: async () => ({ action: 'discard' }),
+    removeKnownWordNote: (noteId) => {
+      events.push(`cache:${noteId}`);
+    },
+    showStatusNotification: (message) => {
+      statusMessages.push(message);
+    },
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.deepEqual(events, ['delete:42', 'cache:42']);
+  assert.deepEqual(statusMessages, ['Card deleted.']);
+});
+
+test('keeping an audio card without media skips generation and preserves the note', async () => {
+  let generatedAudio = false;
+  let deleted = false;
+  const updates: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const { service, storedMedia } = createManualUpdateService({
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentSubText: '字幕',
+        currentSubStart: 4,
+        currentSubEnd: 6,
+        currentTimePos: 5,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: { Expression: { value: '単語' }, Sentence: { value: '' } },
+        },
+      ],
+      updateNoteFields: async (noteId, fields) => {
+        updates.push({ noteId, fields });
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => {
+        deleted = true;
+      },
+    },
+    mediaGenerator: {
+      generateAudio: async () => {
+        generatedAudio = true;
+        return Buffer.from('audio');
+      },
+      generateScreenshot: async () => null,
+      generateAnimatedImage: async () => null,
+    },
+    reviewMediaTiming: async () => ({ action: 'skip-media' }),
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.equal(generatedAudio, false);
+  assert.equal(deleted, false);
+  assert.deepEqual(storedMedia, []);
+  assert.deepEqual(updates, [{ noteId: 42, fields: { Sentence: '字幕' } }]);
+});

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

@@ -12,6 +12,7 @@ test('sentence card writes generated audio only to sentence audio field', async
   const storedMedia: string[] = [];
   const requestedProperties: string[] = [];
   const audioVolumeScales: Array<number | undefined> = [];
+  const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
 
   const deps: CardCreationDeps = {
     getConfig: () =>
@@ -73,17 +74,19 @@ test('sentence card writes generated audio only to sentence audio field', async
       },
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (
         _path,
-        _startTime,
-        _endTime,
-        _audioPadding,
+        startTime,
+        endTime,
+        audioPadding,
         _audioStreamIndex,
         _normalizeAudio,
         volumeScale,
       ) => {
+        audioRanges.push({ start: startTime, end: endTime, padding: audioPadding });
         audioVolumeScales.push(volumeScale);
         return Buffer.from('audio');
       },
@@ -117,22 +120,19 @@ test('sentence card writes generated audio only to sentence audio field', async
       audioField: 'SentenceAudio',
       lapisEnabled: true,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
+    reviewMediaTiming: async () => ({ action: 'confirm', startTime: 11.4, endTime: 14.2 }),
   };
 
-  const created = await new CardCreationService(deps).createSentenceCard(
-    '字幕',
-    12,
-    14,
-    'Subtitle',
-  );
+  const service = new CardCreationService(deps);
+  const created = await service.createSentenceCard('字幕', 12, 14, 'Subtitle');
 
   assert.equal(created, true);
   assert.deepEqual(addedFields[0], {
@@ -144,7 +144,19 @@ test('sentence card writes generated audio only to sentence audio field', async
   assert.equal(storedMedia.length, 1);
   assert.deepEqual(requestedProperties, ['volume']);
   assert.deepEqual(audioVolumeScales, [0.4 ** 3]);
+  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
   const mediaUpdate = updatedFields.find((fields) => 'SentenceAudio' in fields);
   assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
   assert.equal('ExpressionAudio' in mediaUpdate!, false);
+
+  deps.reviewMediaTiming = async () => ({ action: 'discard' });
+  assert.equal(await service.createSentenceCard('作らない', 20, 22), false);
+  assert.equal(addedFields.length, 1);
+
+  deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
+  assert.equal(await service.createSentenceCard('メディアなし', 30, 32), true);
+  assert.equal(addedFields.length, 2);
+  assert.equal(storedMedia.length, 1);
+  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
+  assert.deepEqual(requestedProperties, ['volume']);
 });

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

@@ -42,6 +42,7 @@ test('CardCreationService counts locally created sentence cards', async () => {
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -69,11 +70,11 @@ test('CardCreationService counts locally created sentence cards', async () => {
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -139,6 +140,7 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -168,11 +170,11 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => {
@@ -238,6 +240,7 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -267,11 +270,11 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     recordCardsMinedCallback: () => {
@@ -348,6 +351,7 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -387,11 +391,11 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -454,6 +458,7 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
@@ -490,11 +495,11 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -590,6 +595,7 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => {
@@ -629,11 +635,11 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -701,6 +707,7 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -728,11 +735,11 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'manual',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'manual',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -790,6 +797,7 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -817,11 +825,11 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'manual',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'manual',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,

src/anki-integration/card-creation.ts

@@ -3,7 +3,13 @@ import {
   getConfiguredWordFieldName,
   getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import { AnkiConnectConfig, type CardKind, type WordCardKind } from '../types/anki';
+import {
+  AnkiConnectConfig,
+  type CardKind,
+  type MediaTimingReviewDecision,
+  type MediaTimingReviewRequest,
+  type WordCardKind,
+} from '../types/anki';
 import { createLogger } from '../logger';
 import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
@@ -55,6 +61,7 @@ interface CardCreationClient {
   storeMediaFile(filename: string, data: Buffer): Promise<void>;
   findNotes(query: string, options?: { maxRetries?: number }): Promise<number[]>;
   retrieveMediaFile(filename: string): Promise<string>;
+  deleteNotes(noteIds: number[]): Promise<void>;
 }
 
 interface CardCreationMediaGenerator {
@@ -132,18 +139,21 @@ interface CardCreationDeps {
     audioField: string;
     lapisEnabled: boolean;
     kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
     wordCardKind?: WordCardKind;
   };
   getFallbackDurationSeconds: () => number;
   appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
+  removeKnownWordNote: (noteId: number) => void;
   isUpdateInProgress: () => boolean;
   setUpdateInProgress: (value: boolean) => void;
   trackLastAddedNoteId?: (noteId: number) => void;
   trackLastAddedDuplicateNoteIds?: (noteId: number, duplicateNoteIds: number[]) => void;
   findDuplicateNoteIds?: (expression: string, noteInfo: CardCreationNoteInfo) => Promise<number[]>;
   recordCardsMinedCallback?: (count: number, noteIds?: number[]) => void;
+  reviewMediaTiming?: (
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ) => Promise<MediaTimingReviewDecision>;
 }
 
 export class CardCreationService {
@@ -260,9 +270,16 @@ export class CardCreationService {
           fields,
           this.deps.getConfig(),
         );
-        const sentenceAudioField = this.getResolvedSentenceOnlyAudioFieldName(noteInfo);
+        const config = this.deps.getConfig();
+        const sentenceAudioField = this.deps.resolveConfiguredFieldName(
+          noteInfo,
+          config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+        );
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
-        const sentenceField = sentenceCardConfig.sentenceField;
+        const sentenceField = this.deps.resolveConfiguredFieldName(
+          noteInfo,
+          config.fields?.sentence ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.sentence,
+        );
 
         const sentence = blocks.join(' ');
         const updatedFields: Record<string, string> = {};
@@ -284,7 +301,6 @@ export class CardCreationService {
           `Clipboard update: timing range ${rangeStart.toFixed(2)}s - ${rangeEnd.toFixed(2)}s`,
         );
 
-        const config = this.deps.getConfig();
         const generateAudio = shouldGenerateAudio(config);
         const generateImage = shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
@@ -451,26 +467,52 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
 
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'audio',
+              text: mpvClient.currentSubText,
+              startTime,
+              endTime,
+              noteId,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          await this.deps.client.deleteNotes([noteId]);
+          this.deps.removeKnownWordNote(noteId);
+          this.deps.showStatusNotification('Card deleted.');
+          return;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        let sentenceText = mpvClient.currentSubText;
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentenceText = timingDecision.text?.trim() || sentenceText;
+        }
+
         const updatedFields: Record<string, string> = {};
         const errors: string[] = [];
         let miscInfoFilename: string | null = null;
 
         this.deps.setCardTypeFields(updatedFields, Object.keys(noteInfo.fields), 'audio');
 
-        const sentenceField = this.deps.getConfig().fields?.sentence;
+        const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
+        const sentenceField = sentenceCardConfig.sentenceField;
         if (sentenceField) {
-          const processedSentence = this.deps.processSentence(mpvClient.currentSubText, fields);
+          const processedSentence = this.deps.processSentence(sentenceText, fields);
           updatedFields[sentenceField] = processedSentence;
         }
 
-        const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const audioFieldName = sentenceCardConfig.audioField;
+        if (!skipMedia) {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = await this.mediaGenerateAudio(
               mpvClient.currentVideoPath,
               startTime,
               endTime,
+              exactReviewedRange ? 0 : undefined,
             );
 
             if (audioBuffer) {
@@ -482,8 +524,9 @@ export class CardCreationService {
             log.error('Failed to generate audio for audio card:', (error as Error).message);
             errors.push('audio');
           }
+        }
 
-        if (shouldGenerateImage(this.deps.getConfig())) {
+        if (!skipMedia && shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -492,6 +535,7 @@ export class CardCreationService {
               startTime,
               endTime,
               animatedLeadInSeconds,
+              exactReviewedRange,
             );
 
             const imageField = this.deps.getConfig().fields?.image;
@@ -564,9 +608,29 @@ export class CardCreationService {
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'sentence',
+              text: sentence,
+              startTime,
+              endTime,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          this.deps.showStatusNotification('Card creation cancelled.');
+          return false;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentence = timingDecision.text?.trim() || sentence;
+        }
+
         const config = this.deps.getConfig();
-        const generateAudio = shouldGenerateAudio(config);
-        const generateImage = shouldGenerateImage(config);
+        const generateAudio = !skipMedia && shouldGenerateAudio(config);
+        const generateImage = !skipMedia && shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
         const videoPath = generateImage
           ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
@@ -632,8 +696,7 @@ export class CardCreationService {
         ).trim();
         let duplicateNoteIds: number[] = [];
         if (
-          sentenceCardConfig.kikuEnabled &&
-          sentenceCardConfig.kikuFieldGrouping !== 'disabled' &&
+          sentenceCardConfig.fieldGroupingMode !== 'disabled' &&
           pendingExpressionText &&
           this.deps.findDuplicateNoteIds
         ) {
@@ -732,6 +795,7 @@ export class CardCreationService {
             generateAudio,
             generateImage,
             volumeScale,
+            ...(exactReviewedRange ? { mediaPaddingSeconds: 0 } : {}),
           });
           await this.deps.showNotification(noteId, label, 'media queued');
           return true;
@@ -747,7 +811,12 @@ export class CardCreationService {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
-              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
+              ? await this.mediaGenerateAudio(
+                  audioSourcePath,
+                  startTime,
+                  endTime,
+                  exactReviewedRange ? 0 : undefined,
+                )
               : null;
 
             if (audioBuffer) {
@@ -765,7 +834,13 @@ export class CardCreationService {
         if (generateImage) {
           try {
             const imageFilename = this.generateImageFilename();
-            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
+            const imageBuffer = await this.generateImageBuffer(
+              videoPath!,
+              startTime,
+              endTime,
+              0,
+              exactReviewedRange,
+            );
 
             const imageField = config.fields?.image;
             if (imageBuffer && imageField) {
@@ -806,22 +881,6 @@ export class CardCreationService {
     }
   }
 
-  private getResolvedSentenceAudioFieldName(noteInfo: CardCreationNoteInfo): string | null {
-    return (
-      this.deps.resolveNoteFieldName(
-        noteInfo,
-        this.deps.getEffectiveSentenceCardConfig().audioField || 'SentenceAudio',
-      ) || this.deps.resolveConfiguredFieldName(noteInfo, this.deps.getConfig().fields?.audio)
-    );
-  }
-
-  private getResolvedSentenceOnlyAudioFieldName(noteInfo: CardCreationNoteInfo): string | null {
-    return this.deps.resolveNoteFieldName(
-      noteInfo,
-      this.deps.getEffectiveSentenceCardConfig().audioField || 'SentenceAudio',
-    );
-  }
-
   private createPendingNoteInfo(fields: Record<string, string>): CardCreationNoteInfo {
     return {
       noteId: -1,
@@ -833,6 +892,7 @@ export class CardCreationService {
     videoPath: MediaInput,
     startTime: number,
     endTime: number,
+    audioPaddingOverride?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
@@ -843,7 +903,7 @@ export class CardCreationService {
       videoPath,
       startTime,
       endTime,
-      this.deps.getConfig().media?.audioPadding,
+      audioPaddingOverride ?? this.deps.getConfig().media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
@@ -861,13 +921,16 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
+    exactReviewedRange = false,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
       return null;
     }
 
-    const timestamp = mpvClient.currentTimePos || 0;
+    const timestamp = exactReviewedRange
+      ? startTime + (endTime - startTime) / 2
+      : mpvClient.currentTimePos || 0;
 
     if (this.deps.getConfig().media?.imageType === 'avif') {
       let imageStart = startTime;
@@ -883,7 +946,7 @@ export class CardCreationService {
         videoPath,
         imageStart,
         imageEnd,
-        this.deps.getConfig().media?.audioPadding,
+        exactReviewedRange ? 0 : this.deps.getConfig().media?.audioPadding,
         {
           fps: this.deps.getConfig().media?.animatedFps,
           maxWidth: this.deps.getConfig().media?.animatedMaxWidth,

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

@@ -26,6 +26,7 @@ function createCollaborator(
       miscInfoValue?: string;
     };
     warnings?: Array<{ fieldName: string; reason: string; detail?: string }>;
+    fieldGroupingProvider?: 'kiku' | 'senren' | null;
   } = {},
 ) {
   const warnings = options.warnings ?? [];
@@ -46,6 +47,8 @@ function createCollaborator(
       getEffectiveSentenceCardConfig: () => ({
         sentenceField: 'Sentence',
         audioField: 'SentenceAudio',
+        fieldGroupingProvider:
+          options.fieldGroupingProvider === undefined ? 'kiku' : options.fieldGroupingProvider,
       }),
       getCurrentSubtitleText: () => options.currentSubtitleText,
       resolveFieldName,
@@ -251,7 +254,218 @@ test('computeFieldGroupingMergedFields uses generated media only when includeGen
   assert.equal(withMedia.MiscInfo, '<span data-group-id="11">generated misc</span>');
 });
 
-test('computeFieldGroupingMergedFields clears SentenceFurigana when either note lacks it', async () => {
+test('computeFieldGroupingMergedFields merges Senren notes into scene-switching markup', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      word: '語',
+      sentence: '<span class="group">前<span class="highlight">語</span>後</span>',
+      sentenceAudio: '[sound:original.opus]',
+      picture: '<img src="original.webp">',
+      miscInfo: '<span class="group">Show EP1 (0:01:00)</span>',
+    }),
+    makeNote(200, {
+      word: '語',
+      sentence: '<span class="group">次<span class="highlight">語</span>文</span>',
+      sentenceAudio: '[sound:new.opus]',
+      picture: '<img src="new.webp">',
+      miscInfo: 'Show EP2 (0:02:00)',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentence,
+    '<span class="group">前<span class="highlight">語</span>後</span>' +
+      '<span class="group2">次<span class="highlight">語</span>文</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:original.opus][sound:new.opus]');
+  assert.equal(merged.picture, '<img src="original.webp"><img src="new.webp">');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">Show EP1 (0:01:00)</span><span class="group2">Show EP2 (0:02:00)</span>',
+  );
+});
+
+test('Senren merge warns for invalid source audio when kept audio is empty', async () => {
+  const warnings: Array<{ fieldName: string; reason: string; detail?: string }> = [];
+  const { collaborator } = createCollaborator({
+    fieldGroupingProvider: 'senren',
+    warnings,
+  });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { SentenceAudio: '' }),
+    makeNote(200, { SentenceAudio: 'invalid audio' }),
+    false,
+  );
+
+  assert.equal(merged.SentenceAudio, 'invalid audio');
+  assert.deepEqual(warnings, [
+    {
+      fieldName: 'SentenceAudio',
+      reason: 'missing-sound-tag',
+      detail: undefined,
+    },
+  ]);
+});
+
+test('Senren merge wraps ungrouped legacy content and preserves numbered groups', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentence: 'plain legacy sentence',
+      sentenceAudio: '[sound:a.opus][sound:b.opus]',
+      miscInfo: '<span class="group2">pinned</span> stray text',
+    }),
+    makeNote(200, {
+      sentence: '<span class="group">new sentence</span>',
+      sentenceAudio: '[sound:c.opus]',
+      miscInfo: '<span class="group">new misc</span>',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentence,
+    '<span class="group">plain legacy sentence</span><span class="group3">new sentence</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:a.opus][sound:b.opus][sound:c.opus]');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group2">pinned</span><span class="group">stray text</span>' +
+      '<span class="group3">new misc</span>',
+  );
+});
+
+test('Senren merge rebases numbered groups from an appended source note', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentenceAudio: '[sound:keep-a.opus][sound:keep-b.opus]',
+      miscInfo: '<span class="group">keep one</span><span class="group">keep two</span>',
+    }),
+    makeNote(200, {
+      sentenceAudio: '[sound:source-a.opus][sound:source-b.opus]',
+      miscInfo: '<span class="group2">source two</span>',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentenceAudio,
+    '[sound:keep-a.opus][sound:keep-b.opus][sound:source-a.opus][sound:source-b.opus]',
+  );
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">keep one</span><span class="group">keep two</span>' +
+      '<span class="group4">source two</span>',
+  );
+});
+
+test('Senren merge rebases plain source groups after empty and sparse kept fields', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentenceAudio: '[sound:keep-a.opus][sound:keep-b.opus]',
+      sentence: '',
+      miscInfo: '<span class="group">keep first</span>',
+    }),
+    makeNote(200, {
+      sentenceAudio: '[sound:source-a.opus][sound:source-b.opus]',
+      sentence: '<span class="group">source first</span>',
+      miscInfo: '<span class="group">source first</span><span class="group2">source second</span>',
+    }),
+    false,
+  );
+
+  assert.equal(merged.sentence, '<span class="group3">source first</span>');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">keep first</span><span class="group3">source first</span>' +
+      '<span class="group4">source second</span>',
+  );
+});
+
+test('Senren merge keeps ungrouped text in place around an existing group span', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      miscInfo: 'leading<span class="group">middle</span>trailing',
+      sentenceAudio: '[sound:a.opus][sound:b.opus][sound:c.opus]',
+    }),
+    makeNote(200, {
+      miscInfo: '<span class="group">appended</span>',
+      sentenceAudio: '[sound:d.opus]',
+    }),
+    false,
+  );
+
+  // Order must follow the source field, and the two ungrouped runs must stay separate.
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">leading</span><span class="group">middle</span>' +
+      '<span class="group">trailing</span><span class="group4">appended</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:a.opus][sound:b.opus][sound:c.opus][sound:d.opus]');
+});
+
+test('Senren merge closes unclosed group spans so later scenes stay siblings', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { miscInfo: '<span class="group">a<span class="highlight">b' }),
+    makeNote(200, { miscInfo: '<span class="group">next</span>' }),
+    false,
+  );
+
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">a<span class="highlight">b</span></span><span class="group">next</span>',
+  );
+  const openTags = merged.miscInfo!.match(/<span\b/g)?.length ?? 0;
+  const closeTags = merged.miscInfo!.match(/<\/span>/g)?.length ?? 0;
+  assert.equal(openTags, closeTags);
+});
+
+test('Senren merge closes unclosed trailing markup before appending later scenes', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { miscInfo: 'leading<span class="highlight">tail' }),
+    makeNote(200, { miscInfo: '<span class="group">next</span>' }),
+    false,
+  );
+
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">leading<span class="highlight">tail</span></span>' +
+      '<span class="group">next</span>',
+  );
+});
+
+test('Kiku merge clears SentenceFurigana when either note lacks it', async () => {
   const { collaborator } = createCollaborator();
 
   const merged = await collaborator.computeFieldGroupingMergedFields(
@@ -268,3 +482,21 @@ test('computeFieldGroupingMergedFields clears SentenceFurigana when either note
 
   assert.equal(merged.SentenceFurigana, '');
 });
+
+test('Senren merge keeps duplicate SentenceFurigana when the kept field is empty', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      SentenceFurigana: '',
+    }),
+    makeNote(200, {
+      SentenceFurigana: 'duplicate furigana',
+    }),
+    false,
+  );
+
+  assert.equal(merged.SentenceFurigana, '<span class="group">duplicate furigana</span>');
+});

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

@@ -19,6 +19,7 @@ interface FieldGroupingMergeDeps {
   getEffectiveSentenceCardConfig: () => {
     sentenceField: string;
     audioField: string;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
   };
   getCurrentSubtitleText: () => string | undefined;
   resolveFieldName: (availableFieldNames: string[], preferredName: string) => string | null;
@@ -78,6 +79,13 @@ export class FieldGroupingMergeCollaborator {
     const configuredWordField = getConfiguredWordFieldName(config);
     const groupableFields = this.getGroupableFieldNames();
     const keepFieldNames = Object.keys(keepNoteInfo.fields);
+    const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
+    const senrenSourceSceneOffset =
+      sentenceCardConfig.fieldGroupingProvider === 'senren'
+        ? this.countSenrenAudioScenes(
+            this.getResolvedFieldValue(keepNoteInfo, sentenceCardConfig.audioField),
+          )
+        : 0;
     const sourceFields: Record<string, string> = {};
     const resolvedKeepFieldByPreferred = new Map<string, string>();
     for (const preferredFieldName of groupableFields) {
@@ -154,14 +162,18 @@ export class FieldGroupingMergeCollaborator {
       if (!existingValue.trim() && !newValue.trim()) continue;
 
       if (keepFieldNormalized === 'sentencefurigana') {
+        const hasBothValues = existingValue.trim().length > 0 && newValue.trim().length > 0;
+        const usesSenrenGrouping =
+          this.deps.getEffectiveSentenceCardConfig().fieldGroupingProvider === 'senren';
         mergedFields[keepFieldName] =
-          existingValue.trim() && newValue.trim()
+          hasBothValues || usesSenrenGrouping
             ? this.applyFieldGrouping(
                 existingValue,
                 newValue,
                 keepNoteId,
                 deleteNoteId,
                 keepFieldName,
+                senrenSourceSceneOffset,
               )
             : '';
         continue;
@@ -174,6 +186,7 @@ export class FieldGroupingMergeCollaborator {
           keepNoteId,
           deleteNoteId,
           keepFieldName,
+          senrenSourceSceneOffset,
         );
       } else if (existingValue.trim() && newValue.trim()) {
         mergedFields[keepFieldName] = this.applyFieldGrouping(
@@ -182,6 +195,7 @@ export class FieldGroupingMergeCollaborator {
           keepNoteId,
           deleteNoteId,
           keepFieldName,
+          senrenSourceSceneOffset,
         );
       } else {
         if (!newValue.trim()) continue;
@@ -342,13 +356,152 @@ export class FieldGroupingMergeCollaborator {
     return [...entries].sort((a, b) => b.groupId - a.groupId);
   }
 
+  private isSentenceAudioField(fieldName: string): boolean {
+    const normalized = fieldName.toLowerCase();
+    const audioField = (
+      this.deps.getEffectiveSentenceCardConfig().audioField || 'sentenceaudio'
+    ).toLowerCase();
+    return normalized === 'sentenceaudio' || normalized === audioField;
+  }
+
+  private isSenrenGroupOpenTag(openTag: string): boolean {
+    const classMatch =
+      openTag.match(/class\s*=\s*"([^"]*)"/i) || openTag.match(/class\s*=\s*'([^']*)'/i);
+    if (!classMatch) return false;
+    // Senren's templates match class tokens case-sensitively (/^group\d*$/).
+    return classMatch[1]!.split(/\s+/).some((token) => /^group\d*$/.test(token));
+  }
+
+  private countSenrenAudioScenes(value: string): number {
+    const soundEntries = value.match(/\[sound:[^\]]+\]/g)?.length ?? 0;
+    if (soundEntries > 0) return soundEntries;
+    return this.parseSenrenSceneEntries(value).length;
+  }
+
+  private rebaseSenrenGroup(entry: string, sceneOffset: number, sourceEntryIndex: number): string {
+    if (sceneOffset <= 0) return entry;
+
+    return entry.replace(
+      /^(\s*<span\b[^>]*?\bclass\s*=\s*)(["'])([^"']*)\2/i,
+      (_match: string, prefix: string, quote: string, rawClasses: string) => {
+        const classes = rawClasses
+          .split(/(\s+)/)
+          .map((classToken) => {
+            if (classToken === 'group') {
+              return `group${sceneOffset + sourceEntryIndex + 1}`;
+            }
+            const groupMatch = classToken.match(/^group(\d+)$/);
+            if (!groupMatch) return classToken;
+            const targetScene = Number(groupMatch[1]);
+            if (!Number.isSafeInteger(targetScene) || targetScene <= 0) return classToken;
+            return `group${targetScene + sceneOffset}`;
+          })
+          .join('');
+        return `${prefix}${quote}${classes}${quote}`;
+      },
+    );
+  }
+
+  /**
+   * Splits a Senren field into ordered scene entries. Top-level
+   * `<span class="group">`/`"groupN"` spans are kept verbatim (nested markup like
+   * `<span class="highlight">` included); ungrouped runs are wrapped in a group
+   * span at their original position, because Senren discards anything outside a
+   * group span once scene switching activates.
+   */
+  private parseSenrenSceneEntries(value: string): string[] {
+    const tokenRegex = /<span\b[^>]*>|<\/span>/gi;
+    const entries: string[] = [];
+    const pushUngrouped = (raw: string): void => {
+      const text = raw.replace(/<br\s*\/?>/gi, ' ').trim();
+      if (text) entries.push(`<span class="group">${text}</span>`);
+    };
+    let cursor = 0;
+    let depth = 0;
+    let entryStart = -1;
+    let match;
+    while ((match = tokenRegex.exec(value)) !== null) {
+      const token = match[0]!;
+      if (token[1] !== '/') {
+        if (depth === 0 && this.isSenrenGroupOpenTag(token)) {
+          pushUngrouped(value.slice(cursor, match.index));
+          entryStart = match.index;
+          cursor = match.index;
+        }
+        depth += 1;
+      } else {
+        depth = Math.max(0, depth - 1);
+        if (depth === 0 && entryStart !== -1) {
+          const end = match.index + token.length;
+          entries.push(value.slice(entryStart, end));
+          entryStart = -1;
+          cursor = end;
+        }
+      }
+    }
+    if (entryStart !== -1) {
+      // Unclosed group span: close every span still open (the group and any nested
+      // markup) so the following scenes are siblings rather than nested inside it.
+      entries.push(`${value.slice(entryStart)}${'</span>'.repeat(depth)}`);
+    } else {
+      pushUngrouped(`${value.slice(cursor)}${'</span>'.repeat(depth)}`);
+    }
+    return entries;
+  }
+
+  /**
+   * Merges two notes' field values in Senren's scene-switching format. Scenes are
+   * appended in order (existing first, never resorted) so indices stay aligned
+   * across sentence/picture/miscInfo with the sentenceAudio entries, which alone
+   * drive Senren's scene count.
+   */
+  private applySenrenFieldGrouping(
+    existingValue: string,
+    newValue: string,
+    fieldName: string,
+    sourceSceneOffset: number,
+  ): string {
+    if (this.isPictureField(fieldName)) {
+      const tags = [...this.extractImageTags(existingValue), ...this.extractImageTags(newValue)];
+      if (tags.length === 0) return existingValue || newValue;
+      return tags.join('');
+    }
+
+    if (this.isSentenceAudioField(fieldName)) {
+      const existing = existingValue.trim();
+      const added = newValue.trim();
+      if (added && !/\[sound:[^\]]+\]/.test(added)) {
+        this.deps.warnFieldParseOnce(fieldName, 'missing-sound-tag');
+      }
+      if (!existing || !added) return existing || added;
+      return existing + added;
+    }
+
+    const sourceEntries = this.parseSenrenSceneEntries(newValue).map((entry, sourceEntryIndex) =>
+      this.rebaseSenrenGroup(entry, sourceSceneOffset, sourceEntryIndex),
+    );
+    const merged = [...this.parseSenrenSceneEntries(existingValue), ...sourceEntries];
+    if (merged.length === 0) return existingValue || newValue;
+    return merged.join('');
+  }
+
   private applyFieldGrouping(
     existingValue: string,
     newValue: string,
     keepGroupId: number,
     sourceGroupId: number,
     fieldName: string,
+    senrenSourceSceneOffset: number,
   ): string {
+    if (this.deps.getEffectiveSentenceCardConfig().fieldGroupingProvider === 'senren') {
+      return this.applySenrenFieldGrouping(
+        existingValue,
+        newValue,
+        fieldName,
+        senrenSourceSceneOffset,
+      );
+    }
+
     if (this.shouldUseStrictSpanGrouping(fieldName)) {
       if (this.isPictureField(fieldName)) {
         const keepEntries = this.parsePictureEntries(existingValue, keepGroupId);

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

@@ -71,7 +71,7 @@ function createWorkflowHarness() {
     getEffectiveSentenceCardConfig: () => ({
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingDeleteDuplicateInAuto: true,
     }),
     getCurrentSubtitleText: () => 'subtitle-text',
     getFieldGroupingCallback: (): FieldGroupingCallback | null => {

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

@@ -24,7 +24,7 @@ export interface FieldGroupingWorkflowDeps {
   getEffectiveSentenceCardConfig: () => {
     sentenceField: string;
     audioField: string;
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingDeleteDuplicateInAuto: boolean;
   };
   getCurrentSubtitleText: () => string | undefined;
   getFieldGroupingCallback:
@@ -75,7 +75,7 @@ export class FieldGroupingWorkflow {
         originalNoteId,
         newNoteId,
         this.getExpression(newNoteInfo),
-        sentenceCardConfig.kikuDeleteDuplicateInAuto,
+        sentenceCardConfig.fieldGroupingDeleteDuplicateInAuto,
       );
     } catch (error) {
       this.deps.logError('Field grouping auto merge failed:', (error as Error).message);

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

@@ -21,14 +21,14 @@ function createHarness(
     manualHandled?: boolean;
     expression?: string | null;
     currentSentenceImageField?: string | undefined;
-    onProcessNewCard?: (noteId: number, options?: { skipKikuFieldGrouping?: boolean }) => void;
+    onProcessNewCard?: (noteId: number, options?: { skipFieldGrouping?: boolean }) => void;
   } = {},
 ) {
   const calls: string[] = [];
   const findNotesQueries: Array<{ query: string; maxRetries?: number }> = [];
   const noteInfoRequests: number[][] = [];
   const duplicateRequests: Array<{ expression: string; excludeNoteId: number }> = [];
-  const processCalls: Array<{ noteId: number; options?: { skipKikuFieldGrouping?: boolean } }> = [];
+  const processCalls: Array<{ noteId: number; options?: { skipFieldGrouping?: boolean } }> = [];
   const autoCalls: Array<{ originalNoteId: number; newNoteId: number; expression: string }> = [];
   const manualCalls: Array<{ originalNoteId: number; newNoteId: number; expression: string }> = [];
 
@@ -46,9 +46,8 @@ function createHarness(
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: options.kikuEnabled ?? true,
-      kikuFieldGrouping: options.kikuFieldGrouping ?? 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: (options.kikuEnabled ?? true) ? ('kiku' as const) : null,
+      fieldGroupingMode: options.kikuFieldGrouping ?? 'auto',
     }),
     isUpdateInProgress: () => false,
     getDeck: options.deck ? () => options.deck : undefined,
@@ -134,7 +133,7 @@ test('triggerFieldGroupingForLastAddedCard stops when kiku mode is disabled', as
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(harness.calls, ['osd:Kiku mode is not enabled']);
+  assert.deepEqual(harness.calls, ['osd:Field grouping requires Kiku or Senren mode']);
   assert.equal(harness.findNotesQueries.length, 0);
 });
 
@@ -143,7 +142,7 @@ test('triggerFieldGroupingForLastAddedCard stops when field grouping is disabled
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(harness.calls, ['osd:Kiku field grouping is disabled']);
+  assert.deepEqual(harness.calls, ['osd:Field grouping is disabled']);
   assert.equal(harness.findNotesQueries.length, 0);
 });
 
@@ -155,9 +154,8 @@ test('triggerFieldGroupingForLastAddedCard stops when an update is already in pr
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => true,
     withUpdateProgress: async () => {
@@ -266,7 +264,7 @@ test('triggerFieldGroupingForLastAddedCard prefers tracked duplicate note ids be
 });
 
 test('triggerFieldGroupingForLastAddedCard refreshes the card when configured fields are missing', async () => {
-  const processCalls: Array<{ noteId: number; options?: { skipKikuFieldGrouping?: boolean } }> = [];
+  const processCalls: Array<{ noteId: number; options?: { skipFieldGrouping?: boolean } }> = [];
   const harness = createHarness({
     noteIds: [11],
     notesInfo: [
@@ -298,7 +296,7 @@ test('triggerFieldGroupingForLastAddedCard refreshes the card when configured fi
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(processCalls, [{ noteId: 11, options: { skipKikuFieldGrouping: true } }]);
+  assert.deepEqual(processCalls, [{ noteId: 11, options: { skipFieldGrouping: true } }]);
   assert.deepEqual(harness.manualCalls, []);
 });
 
@@ -352,9 +350,8 @@ test('buildFieldGroupingPreview returns merged compact and full previews', async
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => false,
     withUpdateProgress: async (_message, action) => action(),
@@ -417,9 +414,8 @@ test('buildFieldGroupingPreview reports missing notes cleanly', async () => {
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => false,
     withUpdateProgress: async (_message, action) => action(),

src/anki-integration/field-grouping.ts

@@ -20,9 +20,8 @@ interface FieldGroupingDeps {
     sentenceField: string;
     audioField: string;
     lapisEnabled: boolean;
-    kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
   };
   isUpdateInProgress: () => boolean;
   getDeck?: () => string | undefined;
@@ -46,7 +45,7 @@ interface FieldGroupingDeps {
     noteInfo: FieldGroupingNoteInfo,
     configuredFieldNames: (string | undefined)[],
   ) => boolean;
-  processNewCard: (noteId: number, options?: { skipKikuFieldGrouping?: boolean }) => Promise<void>;
+  processNewCard: (noteId: number, options?: { skipFieldGrouping?: boolean }) => Promise<void>;
   getSentenceCardImageFieldName: () => string | undefined;
   resolveFieldName: (availableFieldNames: string[], preferredName: string) => string | null;
   computeFieldGroupingMergedFields: (
@@ -76,12 +75,12 @@ export class FieldGroupingService {
 
   async triggerFieldGroupingForLastAddedCard(): Promise<void> {
     const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
-    if (!sentenceCardConfig.kikuEnabled) {
-      this.deps.showOsdNotification('Kiku mode is not enabled');
+    if (sentenceCardConfig.fieldGroupingProvider === null) {
+      this.deps.showOsdNotification('Field grouping requires Kiku or Senren mode');
       return;
     }
-    if (sentenceCardConfig.kikuFieldGrouping === 'disabled') {
-      this.deps.showOsdNotification('Kiku field grouping is disabled');
+    if (sentenceCardConfig.fieldGroupingMode === 'disabled') {
+      this.deps.showOsdNotification('Field grouping is disabled');
       return;
     }
 
@@ -134,7 +133,7 @@ export class FieldGroupingService {
           ])
         ) {
           await this.deps.processNewCard(noteId, {
-            skipKikuFieldGrouping: true,
+            skipFieldGrouping: true,
           });
         }
 
@@ -147,7 +146,7 @@ export class FieldGroupingService {
 
         const noteInfo = refreshedInfo[0]!;
 
-        if (sentenceCardConfig.kikuFieldGrouping === 'auto') {
+        if (sentenceCardConfig.fieldGroupingMode === 'auto') {
           await this.deps.handleFieldGroupingAuto(
             duplicateNoteId,
             noteId,

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

@@ -261,6 +261,32 @@ test('KnownWordCacheManager invalidates persisted cache when fields.word changes
   }
 });
 
+test('KnownWordCacheManager removes a deleted note from memory and persisted state', () => {
+  const config: AnkiConnectConfig = {
+    fields: { word: 'Word' },
+    knownWords: { highlightEnabled: true },
+  };
+  const { manager, statePath, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    manager.appendFromNoteInfo({
+      noteId: 42,
+      fields: { Word: { value: '猫' } },
+    });
+
+    assert.equal(manager.removeNote(42), true);
+    assert.equal(manager.removeNote(42), false);
+    assert.equal(manager.isKnownWord('猫'), false);
+
+    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
+      notes?: Record<string, unknown>;
+    };
+    assert.deepEqual(persisted.notes, {});
+  } finally {
+    cleanup();
+  }
+});
+
 test('KnownWordCacheManager refresh incrementally reconciles deleted and edited note words', async () => {
   const config: AnkiConnectConfig = {
     fields: {

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

@@ -350,6 +350,17 @@ export class KnownWordCacheManager {
     return true;
   }
 
+  removeNote(noteId: number): boolean {
+    if (!this.noteEntriesById.has(noteId)) {
+      return false;
+    }
+
+    this.removeNoteSnapshot(noteId);
+    this.persistKnownWordCacheState();
+    log.info('Known-word cache removed deleted note', `noteId=${noteId}`);
+    return true;
+  }
+
   clearKnownWordCacheState(): void {
     this.clearInMemoryState();
     this.knownWordsStateKey = this.getKnownWordCacheStateKey();

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

@@ -44,6 +44,7 @@ function createWorkflowHarness() {
         updates.push({ noteId, fields });
       },
       storeMediaFile: async () => undefined,
+      deleteNotes: async () => undefined,
     },
     getConfig: () => ({
       fields: {
@@ -58,9 +59,10 @@ function createWorkflowHarness() {
       sentenceField: 'Sentence',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled' as const,
+      fieldGroupingMode: 'disabled' as const,
     }),
     appendKnownWordsFromNoteInfo: (_noteInfo: NoteUpdateWorkflowNoteInfo) => undefined,
+    removeKnownWordNote: (_noteId: number) => undefined,
     extractFields: (fields: Record<string, { value: string }>) => {
       const out: Record<string, string> = {};
       for (const [key, value] of Object.entries(fields)) {
@@ -80,7 +82,6 @@ function createWorkflowHarness() {
       const names = Object.keys(noteInfo.fields);
       return names.find((name) => name.toLowerCase() === preferred.toLowerCase()) ?? null;
     },
-    getResolvedSentenceAudioFieldName: () => null,
     getAnimatedImageLeadInSeconds: async () => 0,
     mergeFieldValue: (_existing: string, next: string, _overwrite: boolean) => next,
     generateAudioFilename: () => 'audio_1.mp3',
@@ -120,6 +121,49 @@ test('NoteUpdateWorkflow updates sentence field and emits notification', async (
   assert.equal(harness.notifications.length, 1);
 });
 
+test('NoteUpdateWorkflow uses configured fields for word-card enrichment with Lapis and Kiku enabled', async () => {
+  const harness = createWorkflowHarness();
+  harness.deps.getConfig = () => ({
+    fields: {
+      sentence: 'Context',
+      audio: 'ContextAudio',
+    },
+    media: {
+      generateAudio: true,
+      generateImage: false,
+    },
+    behavior: {},
+  });
+  harness.deps.getEffectiveSentenceCardConfig = () => ({
+    sentenceField: 'Sentence',
+    lapisEnabled: true,
+    kikuEnabled: true,
+    fieldGroupingMode: 'disabled',
+  });
+  harness.deps.client.notesInfo = async () =>
+    [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: 'taberu' },
+          Sentence: { value: '' },
+          SentenceAudio: { value: '' },
+          Context: { value: '' },
+          ContextAudio: { value: '' },
+        },
+      },
+    ] satisfies NoteUpdateWorkflowNoteInfo[];
+  harness.deps.generateAudio = async () => Buffer.from('audio');
+
+  await harness.workflow.execute(42);
+
+  assert.equal(harness.updates.length, 1);
+  assert.deepEqual(harness.updates[0]?.fields, {
+    Context: 'subtitle-text',
+    ContextAudio: '[sound:audio_1.mp3]',
+  });
+});
+
 test('NoteUpdateWorkflow updates sentence furigana when highlight processor changes it', async () => {
   const harness = createWorkflowHarness();
   harness.deps.client.notesInfo = async () =>
@@ -151,7 +195,7 @@ test('NoteUpdateWorkflow marks enriched Kiku word cards as word-and-sentence car
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
   });
   harness.deps.client.notesInfo = async () =>
     [
@@ -184,7 +228,7 @@ test('NoteUpdateWorkflow marks the configured word card kind instead of word-and
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
     wordCardKind: 'click',
   });
   harness.deps.client.notesInfo = async () =>
@@ -220,7 +264,7 @@ test('NoteUpdateWorkflow leaves card type flags alone when the word card kind is
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
     wordCardKind: 'none',
   });
   harness.deps.client.notesInfo = async () =>
@@ -275,7 +319,7 @@ test('NoteUpdateWorkflow preserves explicit sentence card type during sentence e
     sentenceField: 'Sentence',
     lapisEnabled: true,
     kikuEnabled: false,
-    kikuFieldGrouping: 'disabled',
+    fieldGroupingMode: 'disabled',
   });
   harness.deps.client.notesInfo = async () =>
     [
@@ -318,7 +362,7 @@ test('NoteUpdateWorkflow updates note before auto field grouping merge', async (
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'auto',
+    fieldGroupingMode: 'auto',
   });
   harness.deps.findDuplicateNote = async () => 99;
   harness.deps.client.notesInfo = async () => {
@@ -432,6 +476,7 @@ test('NoteUpdateWorkflow uses subtitle sidebar context for sentence media timing
   harness.deps.getConfig = () => ({
     fields: {
       sentence: 'Sentence',
+      audio: 'SentenceAudio',
       image: 'Picture',
       miscInfo: 'MiscInfo',
     },
@@ -444,7 +489,6 @@ test('NoteUpdateWorkflow uses subtitle sidebar context for sentence media timing
   });
   harness.deps.getCurrentSubtitleText = () => 'current primary line';
   harness.deps.getCurrentSubtitleStart = () => 20;
-  harness.deps.getResolvedSentenceAudioFieldName = () => 'SentenceAudio';
   harness.deps.generateAudio = async (context?: SubtitleMiningContext) => {
     audioContext = context ?? null;
     return Buffer.from('audio');
@@ -501,6 +545,7 @@ test('NoteUpdateWorkflow snapshots one media range for audio and image without a
   harness.deps.getConfig = () => ({
     fields: {
       sentence: 'Sentence',
+      audio: 'SentenceAudio',
       image: 'Picture',
       miscInfo: 'MiscInfo',
     },
@@ -511,7 +556,6 @@ test('NoteUpdateWorkflow snapshots one media range for audio and image without a
     },
     behavior: {},
   });
-  harness.deps.getResolvedSentenceAudioFieldName = () => 'SentenceAudio';
   harness.deps.captureSubtitleMediaContext = () => {
     captureCalls += 1;
     return capturedContext;
@@ -592,3 +636,141 @@ test('NoteUpdateWorkflow queues media updates when YouTube cache is pending', as
   assert.equal(queuedUpdates[0]?.context, undefined);
   assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
 });
+
+test('NoteUpdateWorkflow deletes an existing word card when timing review discards it', async () => {
+  const harness = createWorkflowHarness();
+  const deletedNoteIds: number[][] = [];
+  const removedKnownWordNoteIds: number[] = [];
+  let appendedKnownWords = false;
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.client.deleteNotes = async (noteIds) => {
+    deletedNoteIds.push(noteIds);
+  };
+  harness.deps.appendKnownWordsFromNoteInfo = () => {
+    appendedKnownWords = true;
+  };
+  harness.deps.removeKnownWordNote = (noteId) => {
+    removedKnownWordNoteIds.push(noteId);
+  };
+  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(deletedNoteIds, [[42]]);
+  assert.deepEqual(removedKnownWordNoteIds, [42]);
+  assert.equal(appendedKnownWords, false);
+  assert.deepEqual(harness.updates, []);
+  assert.deepEqual(harness.notifications, []);
+});
+
+test('NoteUpdateWorkflow keeps the word card but skips media after timing review', async () => {
+  const harness = createWorkflowHarness();
+  const mediaCalls: string[] = [];
+  const deletedNoteIds: number[][] = [];
+  const queuedUpdates: unknown[] = [];
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.getConfig = () => ({
+    fields: { sentence: 'Sentence', image: 'Picture' },
+    media: { generateAudio: true, generateImage: true },
+    behavior: {},
+  });
+  harness.deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
+  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 (update) => {
+    queuedUpdates.push(update);
+    return true;
+  };
+  harness.deps.client.deleteNotes = async (noteIds) => {
+    deletedNoteIds.push(noteIds);
+  };
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(mediaCalls, []);
+  assert.deepEqual(queuedUpdates, []);
+  assert.deepEqual(deletedNoteIds, []);
+  assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
+  assert.deepEqual(harness.notifications, [{ noteId: 42, label: 'taberu' }]);
+});
+
+test('NoteUpdateWorkflow uses the combined review sentence for the card and media range', async () => {
+  const harness = createWorkflowHarness();
+  const audioContexts: Array<SubtitleMiningContext | undefined> = [];
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'current-line',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.getConfig = () => ({
+    fields: { sentence: 'Sentence' },
+    media: { generateAudio: true, generateImage: false },
+    behavior: {},
+  });
+  harness.deps.reviewMediaTiming = async () => ({
+    action: 'confirm',
+    startTime: 2,
+    endTime: 7,
+    text: 'previous-line current-line next-line',
+  });
+  harness.deps.generateAudio = async (context) => {
+    audioContexts.push(context);
+    return null;
+  };
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(harness.updates, [
+    { noteId: 42, fields: { Sentence: 'previous-line current-line next-line' } },
+  ]);
+  assert.equal(audioContexts.length, 1);
+  assert.equal(audioContexts[0]?.text, 'previous-line current-line next-line');
+  assert.equal(audioContexts[0]?.startTime, 2);
+  assert.equal(audioContexts[0]?.endTime, 7);
+  assert.equal(audioContexts[0]?.mediaPaddingSeconds, 0);
+});
+
+test('NoteUpdateWorkflow keeps cache unchanged and reports when deletion fails', async () => {
+  const harness = createWorkflowHarness();
+  const statusMessages: string[] = [];
+  let removedKnownWord = false;
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.client.deleteNotes = async () => {
+    throw new Error('delete failed');
+  };
+  harness.deps.removeKnownWordNote = () => {
+    removedKnownWord = true;
+  };
+  harness.deps.showOsdNotification = (message) => {
+    statusMessages.push(message);
+  };
+  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
+
+  await harness.workflow.execute(42);
+
+  assert.equal(removedKnownWord, false);
+  assert.deepEqual(statusMessages, ['Card deletion failed: delete failed']);
+  assert.ok(harness.warnings.length === 0);
+});

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

@@ -1,7 +1,12 @@
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getPreferredWordValueFromExtractedFields } from '../anki-field-config';
 import type { SubtitleMiningContext } from '../types/subtitle';
-import type { CardKind, WordCardKind } from '../types/anki';
+import type {
+  CardKind,
+  MediaTimingReviewDecision,
+  MediaTimingReviewRequest,
+  WordCardKind,
+} from '../types/anki';
 import { resolveWordCardKind } from './note-field-utils';
 
 export interface NoteUpdateWorkflowNoteInfo {
@@ -14,11 +19,13 @@ export interface NoteUpdateWorkflowDeps {
     notesInfo(noteIds: number[]): Promise<unknown>;
     updateNoteFields(noteId: number, fields: Record<string, string>): Promise<void>;
     storeMediaFile(filename: string, data: Buffer): Promise<void>;
+    deleteNotes(noteIds: number[]): Promise<void>;
   };
   getConfig: () => {
     fields?: {
       word?: string;
       sentence?: string;
+      audio?: string;
       image?: string;
       miscInfo?: string;
     };
@@ -39,10 +46,11 @@ export interface NoteUpdateWorkflowDeps {
     sentenceField: string;
     lapisEnabled: boolean;
     kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
     wordCardKind?: WordCardKind;
   };
   appendKnownWordsFromNoteInfo: (noteInfo: NoteUpdateWorkflowNoteInfo) => void;
+  removeKnownWordNote: (noteId: number) => void;
   extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
   findDuplicateNote: (
     expression: string,
@@ -75,7 +83,6 @@ export interface NoteUpdateWorkflowDeps {
     noteInfo: NoteUpdateWorkflowNoteInfo,
     ...preferredNames: (string | undefined)[]
   ) => string | null;
-  getResolvedSentenceAudioFieldName: (noteInfo: NoteUpdateWorkflowNoteInfo) => string | null;
   getAnimatedImageLeadInSeconds: (noteInfo: NoteUpdateWorkflowNoteInfo) => Promise<number>;
   mergeFieldValue: (existing: string, newValue: string, overwrite: boolean) => string;
   generateAudioFilename: () => string;
@@ -102,6 +109,9 @@ export interface NoteUpdateWorkflowDeps {
   logWarn: (message: string, ...args: unknown[]) => void;
   logInfo: (message: string, ...args: unknown[]) => void;
   logError: (message: string, ...args: unknown[]) => void;
+  reviewMediaTiming?: (
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ) => Promise<MediaTimingReviewDecision>;
 }
 
 function normalizeSubtitleContextText(text: string): string {
@@ -160,7 +170,7 @@ export class NoteUpdateWorkflow {
     return null;
   }
 
-  async execute(noteId: number, options?: { skipKikuFieldGrouping?: boolean }): Promise<void> {
+  async execute(noteId: number, options?: { skipFieldGrouping?: boolean }): Promise<void> {
     this.deps.beginUpdateProgress('Updating card');
     try {
       const notesInfoResult = await this.deps.client.notesInfo([noteId]);
@@ -171,7 +181,6 @@ export class NoteUpdateWorkflow {
       }
 
       const noteInfo = notesInfo[0]!;
-      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
       const fields = this.deps.extractFields(noteInfo.fields);
       const config = this.deps.getConfig();
 
@@ -187,9 +196,7 @@ export class NoteUpdateWorkflow {
 
       const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
       const shouldRunFieldGrouping =
-        !options?.skipKikuFieldGrouping &&
-        sentenceCardConfig.kikuEnabled &&
-        sentenceCardConfig.kikuFieldGrouping !== 'disabled';
+        !options?.skipFieldGrouping && sentenceCardConfig.fieldGroupingMode !== 'disabled';
       let duplicateNoteId: number | null = null;
       if (shouldRunFieldGrouping && hasExpressionText) {
         duplicateNoteId = await this.deps.findDuplicateNote(expressionText, noteId, noteInfo);
@@ -198,20 +205,64 @@ export class NoteUpdateWorkflow {
       const updatedFields: Record<string, string> = {};
       let updatePerformed = false;
       let miscInfoFilename: string | null = null;
-      const sentenceField = sentenceCardConfig.sentenceField;
+      const configuredSentenceField =
+        config.fields?.sentence ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.sentence;
+      const sentenceField = this.deps.resolveConfiguredFieldName(noteInfo, configuredSentenceField);
       const subtitleMiningContext = this.consumeMatchingSubtitleMiningContext(
         fields,
-        sentenceField,
-        config.fields?.sentence,
+        sentenceField ?? configuredSentenceField,
+        configuredSentenceField,
       );
       // Audio and image generation run sequentially and audio extraction can take tens of
       // seconds, so resolve the clip range exactly once up front; reading live mpv sub
       // timings per generator clips whichever line is on screen when each one starts.
-      const mediaTimingContext =
+      let mediaTimingContext =
         subtitleMiningContext ?? this.deps.captureSubtitleMediaContext?.() ?? null;
+      let skipMedia = false;
+      let reviewedSentenceText: string | undefined;
       const noteLabel = hasExpressionText ? expressionText : noteId;
 
-      const currentSubtitleText = subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
+      if (mediaTimingContext) {
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'word',
+              text: mediaTimingContext.text,
+              startTime: mediaTimingContext.startTime,
+              endTime: mediaTimingContext.endTime,
+              noteId,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          try {
+            await this.deps.client.deleteNotes([noteId]);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.deps.logError('Failed to delete discarded card:', message);
+            this.deps.showOsdNotification(`Card deletion failed: ${message}`);
+            return;
+          }
+          this.deps.removeKnownWordNote(noteId);
+          this.deps.showOsdNotification('Card deleted.');
+          return;
+        }
+        if (timingDecision.action === 'confirm') {
+          reviewedSentenceText = timingDecision.text?.trim() || undefined;
+          mediaTimingContext = {
+            ...mediaTimingContext,
+            ...(reviewedSentenceText !== undefined ? { text: reviewedSentenceText } : {}),
+            startTime: timingDecision.startTime,
+            endTime: timingDecision.endTime,
+            mediaPaddingSeconds: 0,
+          };
+        } else if (timingDecision.action === 'skip-media') {
+          skipMedia = true;
+        }
+      }
+
+      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
+
+      const currentSubtitleText =
+        reviewedSentenceText ?? subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
       if (sentenceField && currentSubtitleText) {
         const processedSentence = this.deps.processSentence(currentSubtitleText, fields);
         updatedFields[sentenceField] = processedSentence;
@@ -239,8 +290,8 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      const generateAudio = config.media?.generateAudio !== false;
-      const generateImage = config.media?.generateImage !== false;
+      const generateAudio = !skipMedia && config.media?.generateAudio !== false;
+      const generateImage = !skipMedia && config.media?.generateImage !== false;
       const mediaCacheQueued =
         (generateAudio || generateImage) && this.deps.queuePendingYoutubeMediaUpdate
           ? await this.deps.queuePendingYoutubeMediaUpdate({
@@ -258,7 +309,10 @@ export class NoteUpdateWorkflow {
 
           if (audioBuffer) {
             await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-            const sentenceAudioField = this.deps.getResolvedSentenceAudioFieldName(noteInfo);
+            const sentenceAudioField = this.deps.resolveConfiguredFieldName(
+              noteInfo,
+              config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+            );
             if (sentenceAudioField) {
               const existingAudio = noteInfo.fields[sentenceAudioField]?.value || '';
               updatedFields[sentenceAudioField] = this.deps.mergeFieldValue(
@@ -345,7 +399,7 @@ export class NoteUpdateWorkflow {
           noteInfoForGrouping = refreshedInfo[0]!;
         }
 
-        if (sentenceCardConfig.kikuFieldGrouping === 'auto') {
+        if (sentenceCardConfig.fieldGroupingMode === 'auto') {
           await this.deps.handleFieldGroupingAuto(
             duplicateNoteId,
             noteId,
@@ -354,7 +408,7 @@ export class NoteUpdateWorkflow {
           );
           return;
         }
-        if (sentenceCardConfig.kikuFieldGrouping === 'manual') {
+        if (sentenceCardConfig.fieldGroupingMode === 'manual') {
           await this.deps.handleFieldGroupingManual(
             duplicateNoteId,
             noteId,

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

@@ -31,7 +31,6 @@ function createDeps(
     getCachedMediaPath: async () => null,
     shouldRequireRemoteMediaCache: () => true,
     getSubtitleMediaRange: () => ({ startTime: 1, endTime: 2 }),
-    getResolvedSentenceAudioFieldName: () => 'SentenceAudio',
     resolveConfiguredFieldName: () => 'Picture',
     mergeFieldValue: (_existing, newValue) => newValue,
     getAnimatedImageLeadInSeconds: async () => 0,
@@ -133,7 +132,7 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
         noteIds.map((noteId) => ({
           noteId,
           fields: {
-            SentenceAudio: { value: '' },
+            ExpressionAudio: { value: '' },
             Picture: { value: '' },
           },
         })),
@@ -144,13 +143,16 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
         storedMedia.push(filename);
       },
     },
-    getConfig: () => ({ media: {}, fields: { image: 'Picture' } }) as AnkiConnectConfig,
+    getConfig: () =>
+      ({ media: {}, fields: { audio: 'ExpressionAudio', image: 'Picture' } }) as AnkiConnectConfig,
+    resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
+      preferredNames.find((name) => name && name in noteInfo.fields) ?? null,
   });
   const queue = new PendingYoutubeMediaQueue(deps);
 
   const queued = await queue.queueFromNote({
     noteId: 42,
-    noteInfo: { noteId: 42, fields: {} },
+    noteInfo: { noteId: 42, fields: { ExpressionAudio: { value: '' } } },
     label: 'demo',
   });
   await queue.handleReady('https://youtu.be/abc123', '/tmp/media.mkv');
@@ -158,7 +160,8 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
   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.ExpressionAudio ?? '', /^\[sound:audio\.mp3\]$/);
+  assert.equal('SentenceAudio' in (updatedNotes[0]?.fields ?? {}), false);
   assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image\.webp">$/);
 });
 

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

@@ -39,7 +39,6 @@ export interface PendingYoutubeMediaQueueDeps {
     startTime: number;
     endTime: number;
   };
-  getResolvedSentenceAudioFieldName: (noteInfo: PendingYoutubeMediaNoteInfo) => string | null;
   resolveConfiguredFieldName: (
     noteInfo: PendingYoutubeMediaNoteInfo,
     ...preferredNames: (string | undefined)[]
@@ -136,7 +135,7 @@ export class PendingYoutubeMediaQueue {
       startTime: mediaRange.startTime,
       endTime: mediaRange.endTime,
       label: job.label,
-      audioFieldName: this.deps.getResolvedSentenceAudioFieldName(job.noteInfo) ?? undefined,
+      audioFieldName: this.resolveConfiguredAudioFieldName(job.noteInfo) ?? undefined,
       imageFieldName:
         this.deps.resolveConfiguredFieldName(
           job.noteInfo,
@@ -148,6 +147,9 @@ export class PendingYoutubeMediaQueue {
       generateAudio: shouldGenerateAudio(config),
       generateImage: shouldGenerateImage(config),
       volumeScale,
+      ...(job.context?.mediaPaddingSeconds !== undefined
+        ? { mediaPaddingSeconds: job.context.mediaPaddingSeconds }
+        : {}),
     });
     return true;
   }
@@ -247,6 +249,14 @@ export class PendingYoutubeMediaQueue {
     return matched;
   }
 
+  private resolveConfiguredAudioFieldName(noteInfo: PendingYoutubeMediaNoteInfo): string | null {
+    const config = this.deps.getConfig();
+    return this.deps.resolveConfiguredFieldName(
+      noteInfo,
+      config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+    );
+  }
+
   private async applyUpdate(
     job: PendingYoutubeMediaUpdate,
     cachedPath: string,
@@ -275,7 +285,7 @@ export class PendingYoutubeMediaQueue {
           cachedMediaInput,
           job.startTime,
           job.endTime,
-          config.media?.audioPadding,
+          job.mediaPaddingSeconds ?? config.media?.audioPadding,
           undefined,
           config.media?.normalizeAudio !== false,
           job.volumeScale,
@@ -283,7 +293,7 @@ export class PendingYoutubeMediaQueue {
         if (audioBuffer) {
           await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
           const audioField =
-            job.audioFieldName || this.deps.getResolvedSentenceAudioFieldName(noteInfo) || null;
+            job.audioFieldName || this.resolveConfiguredAudioFieldName(noteInfo) || null;
           if (audioField) {
             const existingAudio = noteInfo.fields[audioField]?.value || '';
             mediaFields[audioField] = this.deps.mergeFieldValue(
@@ -309,6 +319,7 @@ export class PendingYoutubeMediaQueue {
           job.startTime,
           job.endTime,
           animatedLeadInSeconds,
+          job.mediaPaddingSeconds,
         );
         if (imageBuffer) {
           await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
@@ -369,6 +380,7 @@ export class PendingYoutubeMediaQueue {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
+    mediaPaddingSeconds?: number,
   ): Promise<Buffer | null> {
     const config = this.deps.getConfig();
     if (config.media?.imageType === 'avif') {
@@ -376,7 +388,7 @@ export class PendingYoutubeMediaQueue {
         videoPath,
         startTime,
         endTime,
-        config.media?.audioPadding,
+        mediaPaddingSeconds ?? config.media?.audioPadding,
         {
           fps: config.media?.animatedFps,
           maxWidth: config.media?.animatedMaxWidth,

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

@@ -10,6 +10,7 @@ export interface PendingYoutubeMediaUpdate {
   generateAudio: boolean;
   generateImage: boolean;
   volumeScale?: number;
+  mediaPaddingSeconds?: number;
 }
 
 function trimToNonEmptyString(value: unknown): string | null {

src/anki-integration/runtime.ts

@@ -116,6 +116,10 @@ export function normalizeAnkiIntegrationConfig(config: AnkiConnectConfig): AnkiC
       ...DEFAULT_ANKI_CONNECT_CONFIG.isKiku,
       ...(config.isKiku ?? {}),
     },
+    isSenren: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.isSenren,
+      ...(config.isSenren ?? {}),
+    },
     lapisKiku: {
       ...DEFAULT_ANKI_CONNECT_CONFIG.lapisKiku,
       ...(config.lapisKiku ?? {}),
@@ -209,6 +213,10 @@ export class AnkiIntegrationRuntime {
         patch.isKiku !== undefined
           ? { ...this.config.isKiku, ...patch.isKiku }
           : this.config.isKiku,
+      isSenren:
+        patch.isSenren !== undefined
+          ? { ...this.config.isSenren, ...patch.isSenren }
+          : this.config.isSenren,
       lapisKiku:
         patch.lapisKiku !== undefined
           ? { ...this.config.lapisKiku, ...patch.lapisKiku }

src/config/config.test.ts

@@ -2181,6 +2181,7 @@ test('runtime options registry is centralized', () => {
   const ids = RUNTIME_OPTION_REGISTRY.map((entry) => entry.id);
   assert.deepEqual(ids, [
     'anki.autoUpdateNewCards',
+    'anki.mediaReviewTiming',
     'subtitle.annotation.knownWords.highlightEnabled',
     'subtitle.annotation.knownWords.maturityEnabled',
     'subtitle.annotation.nPlusOne',
@@ -2188,6 +2189,7 @@ test('runtime options registry is centralized', () => {
     'subtitle.annotation.frequency',
     'anki.nPlusOneMatchMode',
     'anki.kikuFieldGrouping',
+    'anki.senrenFieldGrouping',
   ]);
 });
 
@@ -2775,6 +2777,47 @@ test('accepts a Kiku/Lapis word card kind and warns on an unknown one', () => {
   );
 });
 
+test('forces Senren off when Kiku is also enabled and validates Senren fieldGrouping', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isKiku": { "enabled": true },
+        "isSenren": { "enabled": true }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+  assert.equal(service.getConfig().ankiConnect.isKiku.enabled, true);
+  assert.equal(service.getConfig().ankiConnect.isSenren.enabled, false);
+  assert.ok(
+    service.getWarnings().some((warning) => warning.path === 'ankiConnect.isSenren.enabled'),
+  );
+
+  const senrenOnlyDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(senrenOnlyDir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isSenren": { "enabled": true, "fieldGrouping": "sometimes" }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const senrenOnlyService = new ConfigService(senrenOnlyDir);
+  assert.equal(senrenOnlyService.getConfig().ankiConnect.isSenren.enabled, true);
+  assert.equal(senrenOnlyService.getConfig().ankiConnect.isSenren.fieldGrouping, 'auto');
+  assert.ok(
+    senrenOnlyService
+      .getWarnings()
+      .some((warning) => warning.path === 'ankiConnect.isSenren.fieldGrouping'),
+  );
+});
+
 test('accepts valid ankiConnect knownWords deck object', () => {
   const dir = makeTempDir();
   fs.writeFileSync(

src/config/definitions/defaults-integrations.ts

@@ -54,6 +54,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       syncAnimatedImageToWordAudio: true,
       normalizeAudio: true,
       mirrorMpvVolume: true,
+      reviewTiming: false,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,
@@ -91,6 +92,11 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       fieldGrouping: 'disabled',
       deleteDuplicateInAuto: true,
     },
+    isSenren: {
+      enabled: false,
+      fieldGrouping: 'auto',
+      deleteDuplicateInAuto: true,
+    },
     lapisKiku: {
       wordCardKind: 'word-and-sentence',
     },

src/config/definitions/options-integrations.ts

@@ -196,6 +196,14 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         "Apply mpv's current software volume curve to generated sentence audio. Changes apply live.",
     },
+    {
+      path: 'ankiConnect.media.reviewTiming',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
+      description:
+        'Review and preview subtitle media timing before SubMiner creates or enriches a mined card.',
+      runtime: runtimeOptionById.get('anki.mediaReviewTiming'),
+    },
     {
       path: 'ankiConnect.media.generateImage',
       kind: 'boolean',
@@ -363,6 +371,28 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'When Kiku field grouping is "auto", delete the duplicate source card after grouping completes.',
     },
+    {
+      path: 'ankiConnect.isSenren.fieldGrouping',
+      kind: 'enum',
+      enumValues: ['auto', 'manual', 'disabled'],
+      defaultValue: defaultConfig.ankiConnect.isSenren.fieldGrouping,
+      description: 'Senren duplicate-card field grouping mode (scene switching).',
+      runtime: runtimeOptionById.get('anki.senrenFieldGrouping'),
+    },
+    {
+      path: 'ankiConnect.isSenren.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isSenren.enabled,
+      description:
+        'Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled.',
+    },
+    {
+      path: 'ankiConnect.isSenren.deleteDuplicateInAuto',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isSenren.deleteDuplicateInAuto,
+      description:
+        'When Senren field grouping is "auto", delete the duplicate source card after grouping completes.',
+    },
     {
       path: 'ankiConnect.isLapis.enabled',
       kind: 'boolean',

src/config/definitions/runtime-options.ts

@@ -19,6 +19,20 @@ export function buildRuntimeOptionRegistry(
         behavior: { autoUpdateNewCards: value === true },
       }),
     },
+    {
+      id: 'anki.mediaReviewTiming',
+      path: 'ankiConnect.media.reviewTiming',
+      label: 'Review Media Timing',
+      scope: 'ankiConnect',
+      valueType: 'boolean',
+      allowedValues: [true, false],
+      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
+      requiresRestart: false,
+      formatValueForOsd: (value) => (value === true ? 'On' : 'Off'),
+      toAnkiPatch: (value) => ({
+        media: { reviewTiming: value === true },
+      }),
+    },
     {
       id: 'subtitle.annotation.knownWords.highlightEnabled',
       path: 'ankiConnect.knownWords.highlightEnabled',
@@ -124,5 +138,22 @@ export function buildRuntimeOptionRegistry(
         },
       }),
     },
+    {
+      id: 'anki.senrenFieldGrouping',
+      path: 'ankiConnect.isSenren.fieldGrouping',
+      label: 'Senren Field Grouping',
+      scope: 'ankiConnect',
+      valueType: 'enum',
+      allowedValues: ['auto', 'manual', 'disabled'],
+      defaultValue: 'auto',
+      requiresRestart: false,
+      formatValueForOsd: (value) => String(value),
+      toAnkiPatch: (value) => ({
+        isSenren: {
+          fieldGrouping:
+            value === 'auto' || value === 'manual' || value === 'disabled' ? value : 'auto',
+        },
+      }),
+    },
   ];
 }

src/config/definitions/template-sections.ts

@@ -135,7 +135,7 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     title: 'AnkiConnect Integration',
     description: ['Automatic Anki updates and media generation options.'],
     notes: [
-      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
+      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
       'Shared AI provider transport settings are read from top-level ai and typically require restart.',
       'Most other AnkiConnect settings still require restart.',
     ],

src/config/resolve/anki-connect.test.ts

@@ -21,6 +21,34 @@ function makeContext(ankiConnect: unknown): {
   return { context, warnings };
 }
 
+test('media timing review is disabled by default and accepts a boolean override', () => {
+  const defaultContext = makeContext({});
+  applyAnkiConnectResolution(defaultContext.context);
+  assert.equal(defaultContext.context.resolved.ankiConnect.media.reviewTiming, false);
+
+  const enabledContext = makeContext({ media: { reviewTiming: true } });
+  applyAnkiConnectResolution(enabledContext.context);
+  assert.equal(enabledContext.context.resolved.ankiConnect.media.reviewTiming, true);
+  assert.deepEqual(enabledContext.warnings, []);
+});
+
+test('modern media duration accepts zero as the disabled cap sentinel', () => {
+  const disabledCap = makeContext({ media: { maxMediaDuration: 0 } });
+  applyAnkiConnectResolution(disabledCap.context);
+  assert.equal(disabledCap.context.resolved.ankiConnect.media.maxMediaDuration, 0);
+  assert.deepEqual(disabledCap.warnings, []);
+
+  const invalidCap = makeContext({ media: { maxMediaDuration: -1 } });
+  applyAnkiConnectResolution(invalidCap.context);
+  assert.equal(
+    invalidCap.context.resolved.ankiConnect.media.maxMediaDuration,
+    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
+  );
+  assert.ok(
+    invalidCap.warnings.some((warning) => warning.path === 'ankiConnect.media.maxMediaDuration'),
+  );
+});
+
 test('modern invalid knownWords.highlightEnabled warns modern key and does not fallback to legacy', () => {
   const { context, warnings } = makeContext({
     nPlusOne: { highlightEnabled: true },

src/config/resolve/anki-connect.ts

@@ -1,6 +1,7 @@
 import type { ResolveContext } from './context';
 import { initializeAnkiConnectResolution } from './anki-connect/initialize';
 import { applyAnkiKikuResolution } from './anki-connect/kiku';
+import { applyAnkiSenrenResolution } from './anki-connect/senren';
 import { applyAnkiLapisKikuResolution } from './anki-connect/lapis-kiku';
 import { applyAnkiKnownWordsResolution } from './anki-connect/known-words';
 import { applyAnkiLegacyResolution } from './anki-connect/legacy';
@@ -23,5 +24,6 @@ export function applyAnkiConnectResolution(context: ResolveContext): void {
   applyAnkiLegacyResolution(context, ankiConnect, behavior, fields, media, metadata);
   applyAnkiKnownWordsResolution(context, ankiConnect, behavior);
   applyAnkiKikuResolution(context);
+  applyAnkiSenrenResolution(context);
   applyAnkiLapisKikuResolution(context, ankiConnect);
 }

src/config/resolve/anki-connect/initialize.ts

@@ -77,6 +77,12 @@ export function initializeAnkiConnectResolution(
         ? (ankiConnect.isKiku as (typeof context.resolved)['ankiConnect']['isKiku'])
         : {}),
     },
+    isSenren: {
+      ...context.resolved.ankiConnect.isSenren,
+      ...(isObject(ankiConnect.isSenren)
+        ? (ankiConnect.isSenren as (typeof context.resolved)['ankiConnect']['isSenren'])
+        : {}),
+    },
     lapisKiku: {
       ...context.resolved.ankiConnect.lapisKiku,
     },

src/config/resolve/anki-connect/modern-media.ts

@@ -19,6 +19,7 @@ export function applyModernMediaResolution(
     'syncAnimatedImageToWordAudio',
     'normalizeAudio',
     'mirrorMpvVolume',
+    'reviewTiming',
   ] as const) {
     applyModernValue(
       context,
@@ -128,18 +129,28 @@ export function applyModernMediaResolution(
     'Expected non-negative number.',
   );
 
-  for (const key of ['fallbackDuration', 'maxMediaDuration'] as const) {
   applyModernValue(
     context,
     media,
-      key,
-      `ankiConnect.media.${key}`,
+    'fallbackDuration',
+    'ankiConnect.media.fallbackDuration',
     asPositiveNumber,
-      DEFAULT_CONFIG.ankiConnect.media[key],
+    DEFAULT_CONFIG.ankiConnect.media.fallbackDuration,
     (value) => {
-        context.resolved.ankiConnect.media[key] = value;
+      context.resolved.ankiConnect.media.fallbackDuration = value;
     },
     'Expected positive number.',
   );
-  }
+  applyModernValue(
+    context,
+    media,
+    'maxMediaDuration',
+    'ankiConnect.media.maxMediaDuration',
+    asNonNegativeNumber,
+    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
+    (value) => {
+      context.resolved.ankiConnect.media.maxMediaDuration = value;
+    },
+    'Expected non-negative number.',
+  );
 }

src/config/resolve/anki-connect/senren.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_CONFIG } from '../../definitions';
+import type { ResolveContext } from '../context';
+
+export function applyAnkiSenrenResolution(context: ResolveContext): void {
+  if (
+    context.resolved.ankiConnect.isSenren.fieldGrouping !== 'auto' &&
+    context.resolved.ankiConnect.isSenren.fieldGrouping !== 'manual' &&
+    context.resolved.ankiConnect.isSenren.fieldGrouping !== 'disabled'
+  ) {
+    context.warn(
+      'ankiConnect.isSenren.fieldGrouping',
+      context.resolved.ankiConnect.isSenren.fieldGrouping,
+      DEFAULT_CONFIG.ankiConnect.isSenren.fieldGrouping,
+      'Expected auto, manual, or disabled.',
+    );
+    context.resolved.ankiConnect.isSenren.fieldGrouping =
+      DEFAULT_CONFIG.ankiConnect.isSenren.fieldGrouping;
+  }
+
+  // Kiku and Senren field grouping write incompatible markup into the same note
+  // fields, so only one may be active; Kiku wins to preserve pre-existing setups.
+  if (
+    context.resolved.ankiConnect.isSenren.enabled === true &&
+    context.resolved.ankiConnect.isKiku.enabled === true
+  ) {
+    context.warn(
+      'ankiConnect.isSenren.enabled',
+      true,
+      false,
+      'Kiku and Senren are mutually exclusive; disable isKiku.enabled to use Senren field grouping.',
+    );
+    context.resolved.ankiConnect.isSenren.enabled = false;
+  }
+}

src/config/settings/registry.test.ts

@@ -298,10 +298,12 @@ test('settings registry puts feature toggles first, then other toggles alphabeti
   ];
   assert.equal(miningSections[0], 'AnkiConnect');
 
-  const kikuLapis = fields.filter((candidate) => candidate.section === 'Kiku/Lapis Features');
+  const kikuLapis = fields.filter(
+    (candidate) => candidate.section === 'Kiku/Lapis/Senren Features',
+  );
   assert.deepEqual(
-    kikuLapis.slice(0, 2).map((candidate) => candidate.configPath),
-    ['ankiConnect.isLapis.enabled', 'ankiConnect.isKiku.enabled'],
+    kikuLapis.slice(0, 3).map((candidate) => candidate.configPath),
+    ['ankiConnect.isLapis.enabled', 'ankiConnect.isKiku.enabled', 'ankiConnect.isSenren.enabled'],
   );
 });
 
@@ -352,6 +354,7 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.deck',
     'ankiConnect.media.normalizeAudio',
     'ankiConnect.media.mirrorMpvVolume',
+    'ankiConnect.media.reviewTiming',
     'ankiConnect.knownWords.highlightEnabled',
     'ankiConnect.knownWords.refreshMinutes',
     'ankiConnect.knownWords.addMinedWordsImmediately',
@@ -366,6 +369,7 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.fields.miscInfo',
     'ankiConnect.isLapis.sentenceCardModel',
     'ankiConnect.isKiku.fieldGrouping',
+    'ankiConnect.isSenren.fieldGrouping',
   ]) {
     assert.equal(field(path).restartBehavior, 'hot-reload', path);
   }

src/config/settings/registry.ts

@@ -131,7 +131,7 @@ const SECTION_ORDER = new Map<string, number>(
     'AnkiConnect',
     'Note Fields',
     'Media Capture',
-    'Kiku/Lapis Features',
+    'Kiku/Lapis/Senren Features',
     'Anki AI',
     'AnkiConnect Proxy',
     'Jimaku',
@@ -163,6 +163,7 @@ const PATH_ORDER = new Map<string, number>(
     'ankiConnect.proxy.enabled',
     'ankiConnect.isLapis.enabled',
     'ankiConnect.isKiku.enabled',
+    'ankiConnect.isSenren.enabled',
     'subtitleStyle.knownWordColor',
     'ankiConnect.knownWords.matureThresholdDays',
     'subtitleStyle.knownWordMaturityColors.new',
@@ -221,6 +222,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'ankiConnect.nPlusOne.enabled': 'Enabled',
   'ankiConnect.isLapis.enabled': 'Enable Lapis Features',
   'ankiConnect.isKiku.enabled': 'Enable Kiku Features',
+  'ankiConnect.isSenren.enabled': 'Enable Senren Features',
   'ankiConnect.lapisKiku.wordCardKind': 'Word Card Type',
   'stats.toggleKey': 'Toggle Stats Overlay',
   'shortcuts.openCharacterDictionaryManager': 'Open Character Dictionary Manager',
@@ -244,6 +246,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'mpv.aniskipEnabled': 'Enable AniSkip',
   'mpv.aniskipButtonKey': 'AniSkip Button Key',
   'ankiConnect.media.mirrorMpvVolume': 'Mirror mpv Volume',
+  'ankiConnect.media.reviewTiming': 'Review Media Timing',
   'discordPresence.updateIntervalMs': 'Update Interval (ms)',
 };
 
@@ -251,7 +254,9 @@ const DESCRIPTION_OVERRIDES: Record<string, string> = {
   'ankiConnect.pollingRate':
     'Polling interval in milliseconds. Ignored while the local AnkiConnect proxy is enabled because push-based enrichment is used instead.',
   'ankiConnect.isKiku.enabled':
-    'Enable Kiku-specific mining behavior. Kiku supersedes Lapis: Lapis features still work, and Kiku adds duplicate handling and field grouping.',
+    'Enable Kiku-specific mining behavior. Kiku supersedes Lapis: Lapis features still work, and Kiku adds duplicate handling and field grouping. Mutually exclusive with Senren.',
+  'ankiConnect.isSenren.enabled':
+    'Enable Senren-specific duplicate handling: field grouping merges duplicates into Senren scene-switching markup (including miscInfo grouping). Mutually exclusive with Kiku; only one can be enabled at a time.',
   'ankiConnect.isLapis.enabled':
     'Enable Lapis-specific mining behavior and sentence-card model targeting. When Kiku is enabled, Lapis features still work and Kiku-specific features are added on top.',
   'ankiConnect.isLapis.sentenceCardModel':
@@ -407,9 +412,10 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
   if (
     path.startsWith('ankiConnect.isKiku.') ||
     path.startsWith('ankiConnect.isLapis.') ||
+    path.startsWith('ankiConnect.isSenren.') ||
     path.startsWith('ankiConnect.lapisKiku.')
   ) {
-    return { category: 'mining-anki', section: 'Kiku/Lapis Features' };
+    return { category: 'mining-anki', section: 'Kiku/Lapis/Senren Features' };
   }
   if (path.startsWith('ankiConnect.ai.')) {
     return { category: 'mining-anki', section: 'Anki AI' };
@@ -694,6 +700,7 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
     path === 'ankiConnect.ai.enabled' ||
     path === 'ankiConnect.media.normalizeAudio' ||
     path === 'ankiConnect.media.mirrorMpvVolume' ||
+    path === 'ankiConnect.media.reviewTiming' ||
     path === 'ankiConnect.behavior.autoUpdateNewCards' ||
     path === 'ankiConnect.knownWords.highlightEnabled' ||
     path === 'ankiConnect.knownWords.refreshMinutes' ||
@@ -709,6 +716,7 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
     path === 'ankiConnect.fields.miscInfo' ||
     path === 'ankiConnect.isLapis.sentenceCardModel' ||
     path === 'ankiConnect.isKiku.fieldGrouping' ||
+    path === 'ankiConnect.isSenren.fieldGrouping' ||
     path === 'ankiConnect.lapisKiku.wordCardKind' ||
     path === 'mpv.aniskipEnabled' ||
     path === 'mpv.aniskipButtonKey' ||

src/core/services/anki-jimaku.ts

@@ -65,6 +65,7 @@ export interface AnkiJimakuIpcRuntimeOptions {
   getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -166,6 +167,7 @@ export function registerAnkiJimakuIpcRuntime(
           options.getCachedMediaPath,
           options.shouldRequireRemoteMediaCache,
           options.getYoutubeMediaSourceUrl,
+          options.dismissOverlayNotification,
         );
         integration.start();
         options.setAnkiIntegration(integration);

src/core/services/ass-text.test.ts

@@ -218,3 +218,18 @@ test('removeLiveGlyphFragmentLines leaves ordinary short lines alone', () => {
   const text = 'え\nはい。\nそうだな';
   assert.equal(removeLiveGlyphFragmentLines(text), text);
 });
+
+test('normalizePlainSubtitleText folds cue-boundary blank lines for text consumers', () => {
+  // The display layer splits on the blank line before normalizing; everyone else --
+  // tokenizer, cache key, dedup gate, mined sentence -- wants the plain line form.
+  assert.equal(
+    normalizePlainSubtitleText('\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee'),
+    '\u4e00\u884c\u76ee\n\u4e8c\u884c\u76ee',
+  );
+  assert.equal(
+    normalizePlainSubtitleText('\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee', {
+      collapseLineBreaks: true,
+    }),
+    '\u4e00\u884c\u76ee \u4e8c\u884c\u76ee',
+  );
+});

src/core/services/ass-text.ts

@@ -153,6 +153,10 @@ export function normalizePlainSubtitleText(
   );
   if (collapseLineBreaks) {
     normalized = normalized.replace(/\n/g, ' ').replace(/\s+/g, ' ');
+  } else {
+    // Simultaneous cues reach the display layer separated by a blank line; every other
+    // consumer wants the plain one-break-per-line form.
+    normalized = normalized.replace(/\n{2,}/g, '\n');
   }
 
   return trim ? normalized.trim() : normalized;

src/core/services/config-hot-reload.test.ts

@@ -33,6 +33,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
   next.ankiConnect.deck = 'Mining';
   next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
   next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
+  next.ankiConnect.media.reviewTiming = !prev.ankiConnect.media.reviewTiming;
   next.ankiConnect.behavior.autoUpdateNewCards = !prev.ankiConnect.behavior.autoUpdateNewCards;
   next.ankiConnect.knownWords.highlightEnabled = !prev.ankiConnect.knownWords.highlightEnabled;
   next.ankiConnect.knownWords.refreshMinutes = prev.ankiConnect.knownWords.refreshMinutes + 5;
@@ -69,6 +70,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
       'ankiConnect.deck',
       'ankiConnect.media.normalizeAudio',
       'ankiConnect.media.mirrorMpvVolume',
+      'ankiConnect.media.reviewTiming',
       'ankiConnect.behavior.autoUpdateNewCards',
       'ankiConnect.knownWords.highlightEnabled',
       'ankiConnect.knownWords.refreshMinutes',

src/core/services/config-hot-reload.ts

@@ -70,6 +70,7 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
   'ankiConnect.deck',
   'ankiConnect.media.normalizeAudio',
   'ankiConnect.media.mirrorMpvVolume',
+  'ankiConnect.media.reviewTiming',
   'ankiConnect.behavior.autoUpdateNewCards',
   'ankiConnect.knownWords.highlightEnabled',
   'ankiConnect.knownWords.refreshMinutes',
@@ -85,6 +86,7 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
   'ankiConnect.fields.miscInfo',
   'ankiConnect.isLapis.sentenceCardModel',
   'ankiConnect.isKiku.fieldGrouping',
+  'ankiConnect.isSenren.fieldGrouping',
   'ankiConnect.lapisKiku.wordCardKind',
 ] as const;
 

src/core/services/immersion-tracker/lexical-rollups.test.ts

@@ -306,9 +306,11 @@ test('vocabulary charts use complete top-word and lexical rollup data', () => {
       `INSERT INTO imm_words(headword, word, reading, first_seen, last_seen, frequency)
        VALUES (?, ?, '', 1700000000, 1700000000, ?)`,
     );
+    db.exec('BEGIN');
     for (let index = 0; index < 501; index += 1) {
       insertWord.run(`語${index}`, `語${index}`, index === 500 ? 10_000 : 1);
     }
+    db.exec('COMMIT');
 
     const charts = getVocabularyChartData(db);
 

src/core/services/index.ts

@@ -131,12 +131,6 @@ export {
   resolvePlaybackPlan as resolveJellyfinPlaybackPlanRuntime,
   ticksToSeconds as jellyfinTicksToSecondsRuntime,
 } from './jellyfin';
-export { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
-export {
-  estimateSubtitleTimingOffset,
-  type SubtitleTimingOffsetOptions,
-  type SubtitleTimingOffsetResult,
-} from './subtitle-timing-offset';
 export { buildJellyfinTimelinePayload, JellyfinRemoteSessionService } from './jellyfin-remote';
 export {
   broadcastRuntimeOptionsChangedRuntime,

src/core/services/ipc.test.ts

@@ -648,6 +648,83 @@ test('registerIpcHandlers exposes playback window activation request', async ()
   assert.deepEqual(calls, ['activate']);
 });
 
+test('registerIpcHandlers accepts the keep-without-media timing decision', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const requests: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      resolveMediaTimingReview: async (request) => {
+        requests.push(request);
+        return { ok: true };
+      },
+    }),
+    registrar,
+  );
+
+  const handler = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewResolve);
+  assert.ok(handler);
+  assert.deepEqual(
+    await handler!({}, { reviewId: 'review-1', decision: { action: 'skip-media' } }),
+    { ok: true },
+  );
+  assert.deepEqual(requests, [{ reviewId: 'review-1', decision: { action: 'skip-media' } }]);
+});
+
+test('registerIpcHandlers validates and forwards combined timing review text', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const requests: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      resolveMediaTimingReview: async (request) => {
+        requests.push(request);
+        return { ok: true };
+      },
+    }),
+    registrar,
+  );
+
+  const handler = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewResolve);
+  assert.ok(handler);
+  assert.deepEqual(
+    await handler!(
+      {},
+      {
+        reviewId: 'review-1',
+        decision: {
+          action: 'confirm',
+          startTime: 10,
+          endTime: 12,
+          text: '前の行 対象の行',
+        },
+      },
+    ),
+    { ok: true },
+  );
+  assert.deepEqual(requests, [
+    {
+      reviewId: 'review-1',
+      decision: {
+        action: 'confirm',
+        startTime: 10,
+        endTime: 12,
+        text: '前の行 対象の行',
+      },
+    },
+  ]);
+
+  assert.deepEqual(
+    await handler!(
+      {},
+      {
+        reviewId: 'review-1',
+        decision: { action: 'confirm', startTime: 10, endTime: 12, text: '   ' },
+      },
+    ),
+    { ok: false, message: 'Timing review is unavailable.' },
+  );
+  assert.equal(requests.length, 1);
+});
+
 test('registerIpcHandlers forwards yomitan lookup tracking commands to immersion tracker', () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: string[] = [];

src/core/services/ipc.ts

@@ -19,6 +19,13 @@ import type {
   YoutubePickerResolveRequest,
   YoutubePickerResolveResult,
 } from '../../types';
+import type {
+  MediaTimingReviewActionResult,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewWaveformRequest,
+  MediaTimingReviewWaveformResult,
+} from '../../types/anki';
 import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
 import {
   parseMpvCommand,
@@ -99,6 +106,16 @@ export interface IpcServiceDeps {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
+  previewMediaTimingReview?: (
+    request: MediaTimingReviewPreviewRequest,
+  ) => Promise<MediaTimingReviewActionResult>;
+  getMediaTimingReviewWaveform?: (
+    request: MediaTimingReviewWaveformRequest,
+  ) => Promise<MediaTimingReviewWaveformResult>;
+  stopMediaTimingReviewPreview?: (reviewId: string) => Promise<MediaTimingReviewActionResult>;
+  resolveMediaTimingReview?: (
+    request: MediaTimingReviewResolveRequest,
+  ) => MediaTimingReviewActionResult | Promise<MediaTimingReviewActionResult>;
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -222,6 +239,72 @@ function parseOverlayNotificationActionPayload(
   return { notificationId, actionId, ...(typeof noteId === 'number' ? { noteId } : {}) };
 }
 
+function parseMediaTimingReviewPreviewRequest(
+  payload: unknown,
+): MediaTimingReviewPreviewRequest | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  if (
+    typeof record.reviewId !== 'string' ||
+    !record.reviewId ||
+    typeof record.startTime !== 'number' ||
+    !Number.isFinite(record.startTime) ||
+    typeof record.endTime !== 'number' ||
+    !Number.isFinite(record.endTime)
+  ) {
+    return null;
+  }
+  return {
+    reviewId: record.reviewId,
+    startTime: record.startTime,
+    endTime: record.endTime,
+  };
+}
+
+function parseMediaTimingReviewWaveformRequest(
+  payload: unknown,
+): MediaTimingReviewWaveformRequest | null {
+  return parseMediaTimingReviewPreviewRequest(payload);
+}
+
+function parseMediaTimingReviewResolveRequest(
+  payload: unknown,
+): MediaTimingReviewResolveRequest | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.reviewId !== 'string' || !record.reviewId) return null;
+  const decision = record.decision;
+  if (!decision || typeof decision !== 'object') return null;
+  const decisionRecord = decision as Record<string, unknown>;
+  if (
+    decisionRecord.action === 'use-original' ||
+    decisionRecord.action === 'skip-media' ||
+    decisionRecord.action === 'discard'
+  ) {
+    return { reviewId: record.reviewId, decision: { action: decisionRecord.action } };
+  }
+  if (
+    decisionRecord.action === 'confirm' &&
+    typeof decisionRecord.startTime === 'number' &&
+    Number.isFinite(decisionRecord.startTime) &&
+    typeof decisionRecord.endTime === 'number' &&
+    Number.isFinite(decisionRecord.endTime) &&
+    (decisionRecord.text === undefined ||
+      (typeof decisionRecord.text === 'string' && decisionRecord.text.trim().length > 0))
+  ) {
+    return {
+      reviewId: record.reviewId,
+      decision: {
+        action: 'confirm',
+        startTime: decisionRecord.startTime,
+        endTime: decisionRecord.endTime,
+        ...(decisionRecord.text === undefined ? {} : { text: decisionRecord.text }),
+      },
+    };
+  }
+  return null;
+}
+
 export interface IpcDepsRuntimeOptions {
   getMainWindow: () => WindowLike | null;
   getVisibleOverlayVisibility: () => boolean;
@@ -278,6 +361,10 @@ export interface IpcDepsRuntimeOptions {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
+  previewMediaTimingReview?: IpcServiceDeps['previewMediaTimingReview'];
+  getMediaTimingReviewWaveform?: IpcServiceDeps['getMediaTimingReviewWaveform'];
+  stopMediaTimingReviewPreview?: IpcServiceDeps['stopMediaTimingReviewPreview'];
+  resolveMediaTimingReview?: IpcServiceDeps['resolveMediaTimingReview'];
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -371,6 +458,10 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
       options.activatePlaybackWindowForOverlayInteraction ?? (() => false),
     runSubsyncManual: options.runSubsyncManual,
     onYoutubePickerResolve: options.onYoutubePickerResolve,
+    previewMediaTimingReview: options.previewMediaTimingReview,
+    getMediaTimingReviewWaveform: options.getMediaTimingReviewWaveform,
+    stopMediaTimingReviewPreview: options.stopMediaTimingReviewPreview,
+    resolveMediaTimingReview: options.resolveMediaTimingReview,
     getAnkiConnectStatus: options.getAnkiConnectStatus,
     getRuntimeOptions: options.getRuntimeOptions,
     setRuntimeOption: options.setRuntimeOption,
@@ -498,6 +589,46 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     },
   );
 
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewPreview,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewPreviewRequest(payload);
+      if (!request || !deps.previewMediaTimingReview) {
+        return { ok: false, message: 'Timing preview is unavailable.' };
+      }
+      return await deps.previewMediaTimingReview(request);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewWaveform,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewWaveformRequest(payload);
+      if (!request || !deps.getMediaTimingReviewWaveform) {
+        return { ok: false, message: 'Timing waveform is unavailable.' };
+      }
+      return await deps.getMediaTimingReviewWaveform(request);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewStopPreview,
+    async (_event: unknown, reviewId: unknown) => {
+      if (typeof reviewId !== 'string' || !reviewId || !deps.stopMediaTimingReviewPreview) {
+        return { ok: false, message: 'Timing preview is unavailable.' };
+      }
+      return await deps.stopMediaTimingReviewPreview(reviewId);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewResolve,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewResolveRequest(payload);
+      if (!request || !deps.resolveMediaTimingReview) {
+        return { ok: false, message: 'Timing review is unavailable.' };
+      }
+      return await deps.resolveMediaTimingReview(request);
+    },
+  );
+
   ipc.on(IPC_CHANNELS.command.openYomitanSettings, () => {
     deps.openYomitanSettings();
   });

src/core/services/jellyfin-subtitle-delay.test.ts

@@ -1,54 +0,0 @@
-import assert from 'node:assert/strict';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import test from 'node:test';
-import { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
-
-function statePath(name: string): string {
-  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jellyfin-delay-')), name);
-}
-
-test('jellyfin subtitle delay store saves and loads delay by item and stream', () => {
-  const filePath = statePath('delays.json');
-
-  assert.equal(
-    saveJellyfinSubtitleDelay({
-      filePath,
-      itemId: 'episode-1',
-      streamIndex: 3,
-      delaySeconds: 1.25,
-    }),
-    true,
-  );
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 1.25);
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), null);
-});
-
-test('jellyfin subtitle delay store preserves other stream delays when updating one stream', () => {
-  const filePath = statePath('delays.json');
-
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 1.25 });
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4, delaySeconds: -0.5 });
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 2 });
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 2);
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), -0.5);
-});
-
-test('jellyfin subtitle delay store ignores invalid files and values', () => {
-  const filePath = statePath('delays.json');
-  fs.writeFileSync(filePath, '{');
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), null);
-  assert.equal(
-    saveJellyfinSubtitleDelay({
-      filePath,
-      itemId: 'episode-1',
-      streamIndex: 3,
-      delaySeconds: Number.NaN,
-    }),
-    false,
-  );
-});

src/core/services/jellyfin-subtitle-delay.ts

@@ -1,66 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-type JellyfinSubtitleDelayStore = {
-  version?: unknown;
-  delays?: unknown;
-};
-
-type JellyfinSubtitleDelayParams = {
-  filePath: string;
-  itemId: string;
-  streamIndex: number;
-};
-
-type SaveJellyfinSubtitleDelayParams = JellyfinSubtitleDelayParams & {
-  delaySeconds: number;
-};
-
-function storeKey(itemId: string, streamIndex: number): string {
-  return JSON.stringify([itemId, streamIndex]);
-}
-
-function readDelayMap(filePath: string): Record<string, number> {
-  try {
-    if (!fs.existsSync(filePath)) return {};
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as JellyfinSubtitleDelayStore;
-    if (
-      !parsed ||
-      typeof parsed !== 'object' ||
-      !parsed.delays ||
-      typeof parsed.delays !== 'object'
-    ) {
-      return {};
-    }
-    const delays: Record<string, number> = {};
-    for (const [key, value] of Object.entries(parsed.delays as Record<string, unknown>)) {
-      if (typeof value === 'number' && Number.isFinite(value)) {
-        delays[key] = value;
-      }
-    }
-    return delays;
-  } catch {
-    return {};
-  }
-}
-
-export function loadJellyfinSubtitleDelay(params: JellyfinSubtitleDelayParams): number | null {
-  const delay = readDelayMap(params.filePath)[storeKey(params.itemId, params.streamIndex)];
-  return typeof delay === 'number' && Number.isFinite(delay) ? delay : null;
-}
-
-export function saveJellyfinSubtitleDelay(params: SaveJellyfinSubtitleDelayParams): boolean {
-  if (!Number.isFinite(params.delaySeconds)) return false;
-  try {
-    const delays = readDelayMap(params.filePath);
-    delays[storeKey(params.itemId, params.streamIndex)] = params.delaySeconds;
-    const dir = path.dirname(params.filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(params.filePath, JSON.stringify({ version: 1, delays }, null, 2));
-    return true;
-  } catch {
-    return false;
-  }
-}

src/core/services/media-timing-preview.test.ts

@@ -0,0 +1,291 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import net from 'node:net';
+import { describe, test } from 'node:test';
+import { buildMediaTimingPreviewArgs, MediaTimingPreviewSession } from './media-timing-preview';
+
+describe('buildMediaTimingPreviewArgs', () => {
+  test('creates a hidden audio-only reusable mpv session', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '/video/show.mkv',
+      audioTrackId: 3,
+      volume: 55,
+    });
+
+    assert.ok(args.includes('--no-video'));
+    assert.ok(args.includes('--force-window=no'));
+    assert.ok(args.includes('--idle=yes'));
+    assert.ok(args.includes('--pause=yes'));
+    assert.ok(args.includes('--input-ipc-server=/tmp/review.sock'));
+    assert.ok(args.includes('--aid=3'));
+    assert.ok(args.includes('--volume=55'));
+    assert.equal(args.at(-2), '--');
+    assert.equal(args.at(-1), '/video/show.mkv');
+  });
+
+  test('keeps source timestamps for cached remote windows', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '/tmp/window.mkv',
+      absoluteTimestamps: true,
+    });
+
+    assert.ok(args.includes('--rebase-start-time=no'));
+    assert.equal(
+      buildMediaTimingPreviewArgs('/tmp/review.sock', { mediaPath: '/video/show.mkv' }).includes(
+        '--rebase-start-time=no',
+      ),
+      false,
+    );
+  });
+
+  test('separates an option-like media path without adding optional audio arguments', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '--fullscreen',
+    });
+
+    assert.equal(args.at(-2), '--');
+    assert.equal(args.at(-1), '--fullscreen');
+    assert.equal(
+      args.some((arg) => arg.startsWith('--aid=')),
+      false,
+    );
+    assert.equal(
+      args.some((arg) => arg.startsWith('--volume=')),
+      false,
+    );
+  });
+});
+
+test('preview session handles socket errors after connecting', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.doesNotThrow(() => socket.emit('error', new Error('pipe closed')));
+  await assert.rejects(session.play(1, 2), /not ready/);
+  session.dispose();
+});
+
+test('preview session keeps failed connection errors handled through destruction', async () => {
+  const socket = new EventEmitter() as EventEmitter & {
+    destroy: () => void;
+  };
+  socket.destroy = () => {
+    socket.emit('error', new Error('socket failed again while closing'));
+  };
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const times = [0, 0, 0, 6_000];
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('error', new Error('connection failed')));
+      return socket as never;
+    },
+    now: () => times.shift() ?? 6_000,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
+});
+
+test('preview session rejects a connection that finishes after disposal', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => socket,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  const pendingStart = session.start({ mediaPath: '-playlist' });
+  session.dispose();
+  socket.emit('connect');
+
+  await assert.rejects(pendingStart, /closed/);
+  assert.equal(socket.destroyed, true);
+});
+
+test('preview session shares one startup across concurrent start calls', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let spawnCount = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => {
+      spawnCount += 1;
+      return child as never;
+    },
+    connectSocket: () => socket,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  const firstStart = session.start({ mediaPath: '/video/show.mkv' });
+  const secondStart = session.start({ mediaPath: '/video/show.mkv' });
+  socket.emit('connect');
+
+  await Promise.all([firstStart, secondStart]);
+  assert.equal(spawnCount, 1);
+  session.dispose();
+});
+
+test('preview session can start again after a startup failure', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let spawnCount = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => {
+      spawnCount += 1;
+      if (spawnCount === 1) throw new Error('spawn failed');
+      return child as never;
+    },
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /spawn failed/);
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.equal(spawnCount, 2);
+  session.dispose();
+});
+
+test('preview session bounds a connection attempt that never settles', async () => {
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let nowMs = 0;
+  let connectAttempts = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      connectAttempts += 1;
+      const socket = new net.Socket();
+      socket.destroy = (() => {
+        socket.emit('error', new Error('socket failed while timing out'));
+        return socket;
+      }) as typeof socket.destroy;
+      return socket;
+    },
+    now: () => {
+      const current = nowMs;
+      nowMs += 1_000;
+      return current;
+    },
+    schedule: (callback) => setTimeout(callback, 0),
+    cancelSchedule: (timeout) => clearTimeout(timeout),
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
+  assert.equal(connectAttempts, 1);
+});
+
+function createFakeSocket() {
+  const socket = new EventEmitter() as EventEmitter & {
+    destroyed: boolean;
+    write: (data: string) => boolean;
+    end: () => void;
+    destroy: () => void;
+    off: EventEmitter['off'];
+  };
+  const writes: string[] = [];
+  socket.destroyed = false;
+  socket.write = (data) => {
+    writes.push(data);
+    return true;
+  };
+  socket.end = () => undefined;
+  socket.destroy = () => {
+    socket.destroyed = true;
+  };
+  return { socket, writes };
+}
+
+test('preview session plays once to the clip end and reports when mpv has drained it', async () => {
+  const { socket, writes } = createFakeSocket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket as never;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+  let endedCount = 0;
+  session.onPlaybackEnded(() => {
+    endedCount += 1;
+  });
+  const property = (name: string, data: boolean): string =>
+    `${JSON.stringify({ event: 'property-change', name, data })}\n`;
+
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.deepEqual(
+    writes.map((line) => JSON.parse(line).command),
+    [
+      ['observe_property', 1, 'eof-reached'],
+      ['observe_property', 2, 'pause'],
+    ],
+  );
+  // The observers' initial replies describe the idle paused player, not a finished preview.
+  socket.emit('data', property('eof-reached', false) + property('pause', true));
+  assert.equal(endedCount, 0);
+
+  writes.length = 0;
+  await session.play(12.25, 14.5);
+  assert.deepEqual(
+    writes.map((line) => JSON.parse(line).command),
+    [
+      ['set_property', 'pause', true],
+      ['seek', 12.25, 'absolute+exact'],
+      ['set_property', 'end', '14.500'],
+      ['set_property', 'pause', false],
+    ],
+  );
+
+  // Events may arrive split across chunks. The decoder passing `end` flips eof-reached while
+  // audio still drains; only the keep-open pause that follows marks the preview as finished.
+  socket.emit('data', property('eof-reached', false) + property('pause', false).slice(0, 20));
+  socket.emit('data', property('pause', false).slice(20) + property('eof-reached', true));
+  assert.equal(endedCount, 0);
+  socket.emit('data', property('pause', true));
+  assert.equal(endedCount, 1);
+  socket.emit('data', property('pause', true));
+  assert.equal(endedCount, 1);
+
+  // Stopping early pauses without an end signal, and a later real EOF is not a preview end.
+  await session.play(1, 2);
+  socket.emit('data', property('eof-reached', false) + property('pause', false));
+  await session.stop();
+  socket.emit('data', property('pause', true) + property('eof-reached', true));
+  assert.equal(endedCount, 1);
+  session.dispose();
+});

src/core/services/media-timing-preview.ts

@@ -0,0 +1,394 @@
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import net, { type Socket } from 'net';
+import os from 'os';
+import path from 'path';
+import { randomUUID } from 'crypto';
+
+const CONNECT_TIMEOUT_MS = 5_000;
+const CONNECT_ATTEMPT_TIMEOUT_MS = 500;
+const CONNECT_RETRY_MS = 40;
+/**
+ * mpv flips eof-reached as soon as the decoder passes `end`, while its audio buffer is still
+ * draining; keep-open then pauses once the buffer has played out. A preview has ended when
+ * both have happened.
+ */
+const EOF_OBSERVER_ID = 1;
+const PAUSE_OBSERVER_ID = 2;
+
+export interface MediaTimingPreviewStartOptions {
+  mediaPath: string;
+  executablePath?: string;
+  audioTrackId?: number;
+  volume?: number;
+  /** The file keeps source timestamps (a cached remote window); seek with the original times. */
+  absoluteTimestamps?: boolean;
+}
+
+type PreviewProcess = Pick<ChildProcess, 'kill' | 'once'>;
+
+interface MediaTimingPreviewDeps {
+  platform: NodeJS.Platform;
+  spawnProcess: (command: string, args: string[]) => PreviewProcess;
+  connectSocket: (socketPath: string) => Socket;
+  now: () => number;
+  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  cancelSchedule: (timeout: ReturnType<typeof setTimeout>) => void;
+  removeSocketFile: (socketPath: string) => void;
+  createSocketPath: () => string;
+}
+
+export function buildMediaTimingPreviewArgs(
+  socketPath: string,
+  options: MediaTimingPreviewStartOptions,
+): string[] {
+  const args = [
+    '--no-config',
+    '--no-video',
+    '--audio-display=no',
+    '--force-window=no',
+    '--idle=yes',
+    '--keep-open=yes',
+    '--pause=yes',
+    '--terminal=no',
+    '--msg-level=all=warn',
+    `--input-ipc-server=${socketPath}`,
+  ];
+  if (typeof options.audioTrackId === 'number' && Number.isInteger(options.audioTrackId)) {
+    args.push(`--aid=${options.audioTrackId}`);
+  }
+  if (typeof options.volume === 'number' && Number.isFinite(options.volume)) {
+    args.push(`--volume=${Math.max(0, options.volume)}`);
+  }
+  if (options.absoluteTimestamps) {
+    args.push('--rebase-start-time=no');
+  }
+  args.push('--', options.mediaPath);
+  return args;
+}
+
+function createDefaultSocketPath(): string {
+  const suffix = `${process.pid}-${randomUUID()}`;
+  return process.platform === 'win32'
+    ? `\\\\.\\pipe\\subminer-timing-preview-${suffix}`
+    : path.join(
+        // macOS limits Unix socket paths to 104 bytes, while its temp directory can be long.
+        process.platform === 'darwin' ? '/tmp' : os.tmpdir(),
+        `subminer-timing-preview-${suffix}.sock`,
+      );
+}
+
+function removePosixSocketFile(socketPath: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    fs.unlinkSync(socketPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+export class MediaTimingPreviewSession {
+  private readonly deps: MediaTimingPreviewDeps;
+  private socketPath: string | null = null;
+  private socket: Socket | null = null;
+  private process: PreviewProcess | null = null;
+  private startupError: Error | null = null;
+  private startPromise: Promise<void> | null = null;
+  private retryWait: {
+    timeout: ReturnType<typeof setTimeout>;
+    resolve: () => void;
+  } | null = null;
+  private disposed = false;
+  private readBuffer = '';
+  private playing = false;
+  private eofReached = false;
+  private paused = true;
+  private readonly endedListeners = new Set<() => void>();
+
+  constructor(deps: Partial<MediaTimingPreviewDeps> = {}) {
+    this.deps = {
+      platform: process.platform,
+      spawnProcess: (command, args) => spawn(command, args, { stdio: 'ignore' }),
+      connectSocket: (socketPath) => net.createConnection(socketPath),
+      now: Date.now,
+      schedule: (callback, delayMs) => setTimeout(callback, delayMs),
+      cancelSchedule: (timeout) => clearTimeout(timeout),
+      removeSocketFile: removePosixSocketFile,
+      createSocketPath: createDefaultSocketPath,
+      ...deps,
+    };
+  }
+
+  async start(options: MediaTimingPreviewStartOptions): Promise<void> {
+    if (this.disposed) throw new Error('Preview session is closed');
+    if (this.socket) return;
+    if (this.startPromise) return await this.startPromise;
+
+    const startPromise = this.startOnce(options);
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+    } catch (error) {
+      this.releaseResources();
+      throw error;
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = null;
+    }
+  }
+
+  private async startOnce(options: MediaTimingPreviewStartOptions): Promise<void> {
+    const mediaPath = options.mediaPath.trim();
+    if (!mediaPath) throw new Error('No media source is available for preview');
+
+    const socketPath = this.deps.createSocketPath();
+    this.socketPath = socketPath;
+    if (this.deps.platform !== 'win32') {
+      this.deps.removeSocketFile(socketPath);
+    }
+
+    const command = options.executablePath?.trim() || 'mpv';
+    this.startupError = null;
+    const child = this.deps.spawnProcess(
+      command,
+      buildMediaTimingPreviewArgs(socketPath, { ...options, mediaPath }),
+    );
+    this.process = child;
+    child.once('error', (error) => {
+      if (this.process !== child) return;
+      this.startupError = error;
+    });
+    child.once('exit', () => {
+      if (this.process !== child) return;
+      if (!this.socket && !this.disposed && !this.startupError) {
+        this.startupError = new Error('The hidden mpv preview player exited during startup');
+      }
+      this.socket?.destroy();
+      this.socket = null;
+      this.process = null;
+    });
+
+    await this.connectWithRetry(socketPath);
+  }
+
+  /**
+   * Plays [startTime, endTime) once. mpv stops itself at `end` and, thanks to keep-open,
+   * pauses after draining the audio device, so the listener hears the whole clip even on
+   * high-latency outputs. onPlaybackEnded fires when mpv reports the end was reached.
+   */
+  async play(startTime: number, endTime: number): Promise<void> {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error('Preview player is not ready');
+    }
+    if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) {
+      throw new Error('Preview timing is invalid');
+    }
+
+    this.playing = false;
+    this.send(['set_property', 'pause', true]);
+    this.send(['seek', startTime, 'absolute+exact']);
+    // The option parser wants a time string; a raw JSON number is not accepted for `end`.
+    this.send(['set_property', 'end', endTime.toFixed(3)]);
+    this.send(['set_property', 'pause', false]);
+    // Only the seek's eof-reached=false and the later keep-open pause count for this play.
+    this.eofReached = false;
+    this.paused = false;
+    this.playing = true;
+  }
+
+  async stop(): Promise<void> {
+    this.playing = false;
+    if (!this.socket || this.socket.destroyed) return;
+    this.send(['set_property', 'pause', true]);
+  }
+
+  onPlaybackEnded(listener: () => void): void {
+    this.endedListeners.add(listener);
+  }
+
+  private finishPlayback(): void {
+    if (!this.playing) return;
+    this.playing = false;
+    for (const listener of this.endedListeners) listener();
+  }
+
+  private handleSocketData(chunk: Buffer | string): void {
+    this.readBuffer += chunk.toString();
+    let newline = this.readBuffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = this.readBuffer.slice(0, newline).trim();
+      this.readBuffer = this.readBuffer.slice(newline + 1);
+      newline = this.readBuffer.indexOf('\n');
+      if (!line) continue;
+      let message: unknown;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (
+        typeof message === 'object' &&
+        message !== null &&
+        'event' in message &&
+        message.event === 'property-change' &&
+        'name' in message &&
+        'data' in message
+      ) {
+        this.handlePropertyChange(message.name, message.data);
+      }
+    }
+  }
+
+  private handlePropertyChange(name: unknown, data: unknown): void {
+    if (name === 'eof-reached') this.eofReached = data === true;
+    else if (name === 'pause') this.paused = data === true;
+    else return;
+    if (this.playing && this.eofReached && this.paused) this.finishPlayback();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.releaseResources();
+  }
+
+  private releaseResources(): void {
+    this.cancelRetryWait();
+    try {
+      this.send(['quit']);
+    } catch {
+      // The process may already have exited.
+    }
+    this.socket?.end();
+    this.socket?.destroy();
+    this.socket = null;
+    const child = this.process;
+    this.process = null;
+    child?.kill();
+    if (this.socketPath && this.deps.platform !== 'win32') {
+      try {
+        this.deps.removeSocketFile(this.socketPath);
+      } catch {
+        // mpv may still be releasing the socket. The OS temp directory owns cleanup.
+      }
+    }
+    this.socketPath = null;
+  }
+
+  private send(command: Array<string | number | boolean>): void {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error('Preview player is not connected');
+    }
+    this.socket.write(`${JSON.stringify({ command })}\n`);
+  }
+
+  private async connectWithRetry(socketPath: string): Promise<void> {
+    const deadline = this.deps.now() + CONNECT_TIMEOUT_MS;
+    while (!this.disposed && this.deps.now() < deadline) {
+      if (this.startupError) {
+        throw this.startupError;
+      }
+      try {
+        const remainingMs = deadline - this.deps.now();
+        if (remainingMs <= 0) break;
+        const socket = await this.connectOnce(
+          socketPath,
+          Math.min(CONNECT_ATTEMPT_TIMEOUT_MS, remainingMs),
+        );
+        if (this.disposed) {
+          socket.destroy();
+          throw new Error('Preview session is closed');
+        }
+        this.socket = socket;
+        this.readBuffer = '';
+        socket.on('data', (chunk: Buffer | string) => {
+          if (this.socket === socket) this.handleSocketData(chunk);
+        });
+        socket.once('close', () => this.finishPlayback());
+        this.send(['observe_property', EOF_OBSERVER_ID, 'eof-reached']);
+        this.send(['observe_property', PAUSE_OBSERVER_ID, 'pause']);
+        return;
+      } catch {
+        if (this.disposed) {
+          throw new Error('Preview session is closed');
+        }
+        const remainingMs = deadline - this.deps.now();
+        if (remainingMs <= 0) break;
+        await this.waitForRetry(Math.min(CONNECT_RETRY_MS, remainingMs));
+      }
+    }
+    if (this.startupError) {
+      throw this.startupError;
+    }
+    if (this.disposed) {
+      throw new Error('Preview session is closed');
+    }
+    throw new Error('Timed out starting the hidden mpv preview player');
+  }
+
+  private waitForRetry(delayMs: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      const timeout = this.deps.schedule(() => {
+        if (this.retryWait?.timeout === timeout) this.retryWait = null;
+        resolve();
+      }, delayMs);
+      this.retryWait = { timeout, resolve };
+    });
+  }
+
+  private cancelRetryWait(): void {
+    const pending = this.retryWait;
+    this.retryWait = null;
+    if (!pending) return;
+    this.deps.cancelSchedule(pending.timeout);
+    pending.resolve();
+  }
+
+  private connectOnce(socketPath: string, timeoutMs: number): Promise<Socket> {
+    return new Promise<Socket>((resolve, reject) => {
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let settled = false;
+      const clearAttemptTimeout = (): void => {
+        if (timeout !== null) this.deps.cancelSchedule(timeout);
+        timeout = null;
+      };
+      const socket = this.deps.connectSocket(socketPath);
+      const onConnect = (): void => {
+        if (settled) return;
+        settled = true;
+        clearAttemptTimeout();
+        socket.off('error', onError);
+        socket.on('error', () => {
+          socket.destroy();
+          if (this.socket === socket) this.socket = null;
+        });
+        socket.once('close', () => {
+          if (this.socket === socket) this.socket = null;
+        });
+        resolve(socket);
+      };
+      const onError = (error: Error): void => {
+        if (settled) return;
+        settled = true;
+        clearAttemptTimeout();
+        socket.off('connect', onConnect);
+        socket.on('error', () => {});
+        socket.destroy();
+        reject(error);
+      };
+      socket.once('connect', onConnect);
+      socket.once('error', onError);
+      timeout = this.deps.schedule(() => {
+        if (settled) return;
+        settled = true;
+        timeout = null;
+        socket.off('connect', onConnect);
+        socket.off('error', onError);
+        socket.on('error', () => {});
+        socket.destroy();
+        reject(new Error('Timed out connecting to the hidden mpv preview player'));
+      }, timeoutMs);
+    });
+  }
+}

src/core/services/media-timing-waveform.test.ts

@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildSpeechWaveformArgs,
+  computeWaveformPeaks,
+  generateSpeechWaveform,
+} from './media-timing-waveform';
+
+function pcm(samples: number[]): Buffer {
+  const result = Buffer.alloc(samples.length * 2);
+  samples.forEach((sample, index) => result.writeInt16LE(sample, index * 2));
+  return result;
+}
+
+test('speech waveform maps the selected FFmpeg stream and visible range', () => {
+  const args = buildSpeechWaveformArgs(
+    {
+      mediaPath: '/video/show.mkv',
+      startTime: 8,
+      endTime: 15,
+      audioStreamIndex: 3,
+    },
+    'center',
+  );
+
+  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-t') + 2), [
+    '-ss',
+    '8',
+    '-i',
+    '/video/show.mkv',
+    '-t',
+    '7',
+  ]);
+  assert.deepEqual(args.slice(args.indexOf('-map'), args.indexOf('-map') + 2), ['-map', '0:3']);
+  assert.match(args[args.indexOf('-af') + 1] ?? '', /c0=FC/);
+});
+
+test('speech waveform seeks cached windows by source timestamps', () => {
+  const args = buildSpeechWaveformArgs(
+    {
+      mediaPath: { path: '/tmp/window.mkv', absoluteTimestamps: true, singleResolvedStream: true },
+      startTime: 8,
+      endTime: 15,
+    },
+    'downmix',
+  );
+
+  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-t') + 2), [
+    '-ss',
+    '8',
+    '-seek_timestamp',
+    '1',
+    '-i',
+    '/tmp/window.mkv',
+    '-t',
+    '7',
+  ]);
+  assert.equal(args.includes('-map'), false);
+});
+
+test('waveform levels rise with loudness and top out at the reference level', () => {
+  const peaks = computeWaveformPeaks(pcm([0, 1_000, -2_000, 4_000, -8_000, 16_000]), 3);
+
+  assert.equal(peaks.length, 3);
+  assert.equal(peaks[0], 0);
+  assert.ok((peaks[1] ?? 0) > 0);
+  assert.ok((peaks[1] ?? 0) < (peaks[2] ?? 0));
+  assert.equal(peaks[2], 1);
+});
+
+test('waveform flattens steady background noise and keeps speech bursts tall', () => {
+  // 20 slices of steady noise at a fixed level with an 18 dB louder "speech" burst in the middle.
+  const noise = 1_000;
+  const samples: number[] = [];
+  for (let slice = 0; slice < 20; slice += 1) {
+    const level = slice >= 8 && slice < 12 ? noise * 8 : noise;
+    for (let sample = 0; sample < 50; sample += 1) {
+      samples.push(sample % 2 === 0 ? level : -level);
+    }
+  }
+
+  const peaks = computeWaveformPeaks(pcm(samples), 20);
+
+  for (const [index, peak] of peaks.entries()) {
+    if (index >= 8 && index < 12) assert.equal(peak, 1);
+    else assert.equal(peak, 0);
+  }
+});
+
+test('waveform stays flat when the whole range is a single steady level', () => {
+  const peaks = computeWaveformPeaks(
+    pcm(Array.from({ length: 400 }, (_, i) => (i % 2 ? 900 : -900))),
+    40,
+  );
+
+  assert.ok(peaks.every((peak) => peak === 0));
+});
+
+test('speech waveform uses a mono downmix when the source has no center activity', async () => {
+  const calls: string[][] = [];
+  const peaks = await generateSpeechWaveform(
+    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
+    async (args) => {
+      calls.push(args);
+      return calls.length === 1 ? pcm([0, 0, 0, 0]) : pcm([0, 4_000, -8_000, 16_000]);
+    },
+  );
+
+  assert.equal(calls.length, 2);
+  assert.match(calls[1]?.[calls[1].indexOf('-af') + 1] ?? '', /channel_layouts=mono/);
+  assert.equal(Math.max(...peaks), 1);
+});
+
+test('speech waveform keeps an active center channel without doing a second decode', async () => {
+  let calls = 0;
+  await generateSpeechWaveform(
+    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
+    async () => {
+      calls += 1;
+      return pcm([0, 4_000, -8_000, 16_000]);
+    },
+  );
+
+  assert.equal(calls, 1);
+});

src/core/services/media-timing-waveform.ts

@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process';
+import { normalizeMediaInput, type MediaInput } from '../../media-input';
+
+const WAVEFORM_SAMPLE_RATE = 8_000;
+const WAVEFORM_POINT_COUNT = 480;
+const WAVEFORM_TIMEOUT_MS = 15_000;
+const MAX_WAVEFORM_BYTES = 16 * 1024 * 1024;
+// Keep the band where speech intelligibility lives; bass, drums, and hum sit below it.
+const SPEECH_FILTER = 'highpass=f=250,lowpass=f=3500';
+const NOISE_FLOOR_PERCENTILE = 0.2;
+const REFERENCE_PERCENTILE = 0.95;
+const NOISE_GATE_DB = 3;
+const MIN_DISPLAY_RANGE_DB = 12;
+const SILENCE_DB = -100;
+const CENTER_CHANNEL_FILTER = `pan=mono|c0=FC,${SPEECH_FILTER}`;
+const DOWNMIX_FILTER = `aformat=channel_layouts=mono,${SPEECH_FILTER}`;
+
+export interface SpeechWaveformOptions {
+  mediaPath: MediaInput;
+  startTime: number;
+  endTime: number;
+  audioStreamIndex?: number;
+}
+
+type RunFfmpeg = (args: string[]) => Promise<Buffer>;
+
+export function buildSpeechWaveformArgs(
+  options: SpeechWaveformOptions,
+  mode: 'center' | 'downmix',
+): string[] {
+  const duration = options.endTime - options.startTime;
+  const input = normalizeMediaInput(options.mediaPath);
+  const args = [
+    '-hide_banner',
+    '-nostdin',
+    '-loglevel',
+    'error',
+    '-ss',
+    String(options.startTime),
+    ...input.inputArgs,
+    '-i',
+    input.path,
+    '-t',
+    String(duration),
+  ];
+  if (
+    options.audioStreamIndex !== undefined &&
+    Number.isInteger(options.audioStreamIndex) &&
+    options.audioStreamIndex >= 0
+  ) {
+    args.push('-map', `0:${options.audioStreamIndex}`);
+  }
+  args.push(
+    '-vn',
+    '-sn',
+    '-dn',
+    '-af',
+    mode === 'center' ? CENTER_CHANNEL_FILTER : DOWNMIX_FILTER,
+    '-ac',
+    '1',
+    '-ar',
+    String(WAVEFORM_SAMPLE_RATE),
+    '-f',
+    's16le',
+    'pipe:1',
+  );
+  return args;
+}
+
+function runFfmpeg(args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks: Buffer[] = [];
+    let byteLength = 0;
+    let stderr = '';
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGKILL');
+      reject(new Error(`FFmpeg waveform analysis timed out after ${WAVEFORM_TIMEOUT_MS}ms`));
+    }, WAVEFORM_TIMEOUT_MS);
+
+    const settle = (callback: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      callback();
+    };
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      byteLength += chunk.byteLength;
+      if (byteLength > MAX_WAVEFORM_BYTES) {
+        settle(() => {
+          child.kill('SIGKILL');
+          reject(new Error('The visible waveform range is too large to analyze.'));
+        });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < 4_000) stderr += String(chunk);
+    });
+    child.once('error', (error) => settle(() => reject(error)));
+    child.once('close', (code) => {
+      settle(() => {
+        if (code === 0) {
+          resolve(Buffer.concat(chunks, byteLength));
+          return;
+        }
+        reject(new Error(stderr.trim() || `FFmpeg exited with status ${code ?? 'unknown'}`));
+      });
+    });
+  });
+}
+
+function percentile(sortedValues: number[], fraction: number): number {
+  const index = Math.min(sortedValues.length - 1, Math.floor(sortedValues.length * fraction));
+  return sortedValues[index] ?? SILENCE_DB;
+}
+
+/**
+ * Turns mono PCM into 0..1 display heights. Each point is the RMS level of its slice in
+ * dB, measured against the clip's own noise floor (a low percentile of the slices), so
+ * constant background noise draws flat and sustained speech stands out. Peak sampling
+ * would instead follow music transients and lift the floor to nearly speech height.
+ */
+export function computeWaveformPeaks(pcm: Buffer, pointCount = WAVEFORM_POINT_COUNT): number[] {
+  const sampleCount = Math.floor(pcm.byteLength / 2);
+  if (sampleCount === 0 || pointCount <= 0) return [];
+  const resolvedPointCount = Math.min(pointCount, sampleCount);
+  const levelsDb = Array.from({ length: resolvedPointCount }, () => SILENCE_DB);
+
+  for (let point = 0; point < resolvedPointCount; point += 1) {
+    const sampleStart = Math.floor((point * sampleCount) / resolvedPointCount);
+    const sampleEnd = Math.max(
+      sampleStart + 1,
+      Math.floor(((point + 1) * sampleCount) / resolvedPointCount),
+    );
+    let energy = 0;
+    for (let sample = sampleStart; sample < sampleEnd; sample += 1) {
+      const value = pcm.readInt16LE(sample * 2) / 32_768;
+      energy += value * value;
+    }
+    const rms = Math.sqrt(energy / (sampleEnd - sampleStart));
+    levelsDb[point] = rms > 0 ? Math.max(SILENCE_DB, 20 * Math.log10(rms)) : SILENCE_DB;
+  }
+
+  const sortedLevels = [...levelsDb].sort((left, right) => left - right);
+  const floorDb = percentile(sortedLevels, NOISE_FLOOR_PERCENTILE) + NOISE_GATE_DB;
+  const referenceDb = Math.max(
+    percentile(sortedLevels, REFERENCE_PERCENTILE),
+    floorDb + MIN_DISPLAY_RANGE_DB,
+  );
+  return levelsDb.map(
+    (levelDb) =>
+      Math.round(Math.min(1, Math.max(0, (levelDb - floorDb) / (referenceDb - floorDb))) * 1_000) /
+      1_000,
+  );
+}
+
+function hasAudibleSamples(pcm: Buffer): boolean {
+  for (let offset = 0; offset + 1 < pcm.byteLength; offset += 2) {
+    if (Math.abs(pcm.readInt16LE(offset)) >= 164) return true;
+  }
+  return false;
+}
+
+export async function generateSpeechWaveform(
+  options: SpeechWaveformOptions,
+  execute: RunFfmpeg = runFfmpeg,
+): Promise<number[]> {
+  try {
+    const centerPcm = await execute(buildSpeechWaveformArgs(options, 'center'));
+    if (hasAudibleSamples(centerPcm)) return computeWaveformPeaks(centerPcm);
+  } catch {
+    // Sources without a named center channel can reject the center-only filter.
+  }
+
+  const downmixPcm = await execute(buildSpeechWaveformArgs(options, 'downmix'));
+  return computeWaveformPeaks(downmixPcm);
+}

src/core/services/mining.test.ts

@@ -244,6 +244,35 @@ test('handleMultiCopyDigit copies available history and reports truncation', ()
   assert.equal(osd.at(-1), 'Only 2 lines available, copied 2');
 });
 
+test('handleMultiCopyDigit copies backward from the current subtitle after a backward seek', () => {
+  const copied: string[] = [];
+  const tracker = new SubtitleTimingTracker();
+
+  try {
+    tracker.recordSubtitle('A', 1, 2);
+    tracker.recordSubtitle('B', 3, 4);
+    tracker.recordSubtitle('C', 5, 6);
+    tracker.recordSubtitle('B', 3, 4);
+
+    const deps = {
+      subtitleTimingTracker: tracker,
+      writeClipboardText: (text: string) => copied.push(text),
+      showMpvOsd: () => {},
+    };
+
+    handleMultiCopyDigit(1, deps);
+    handleMultiCopyDigit(2, deps);
+
+    assert.deepEqual(copied, ['B', 'A\n\nB']);
+    assert.deepEqual(tracker.getRecentEntries(2), [
+      { displayText: 'A', startTime: 1, endTime: 2, secondaryText: undefined },
+      { displayText: 'B', startTime: 3, endTime: 4, secondaryText: undefined },
+    ]);
+  } finally {
+    tracker.destroy();
+  }
+});
+
 test('handleMineSentenceDigit reports async create failures', async () => {
   const osd: string[] = [];
   const logs: Array<{ message: string; err: unknown }> = [];
@@ -344,6 +373,22 @@ test('handleMineSentenceDigit keeps per-entry timings when subtitle text repeats
   }
 });
 
+test('subtitle timing history preserves adjacent repeated text with distinct timings', () => {
+  const tracker = new SubtitleTimingTracker();
+
+  try {
+    tracker.recordSubtitle('same', 1, 2);
+    tracker.recordSubtitle('same', 3, 4);
+
+    assert.deepEqual(tracker.getRecentEntries(2), [
+      { displayText: 'same', startTime: 1, endTime: 2, secondaryText: undefined },
+      { displayText: 'same', startTime: 3, endTime: 4, secondaryText: undefined },
+    ]);
+  } finally {
+    tracker.destroy();
+  }
+});
+
 test('handleMineSentenceDigit joins per-entry secondary subtitles when available', async () => {
   const created: Array<{ sentence: string; secondarySub?: string }> = [];
   const tracker = new SubtitleTimingTracker();

src/core/services/mpv-protocol.test.ts

@@ -83,6 +83,7 @@ function createDeps(overrides: Partial<MpvProtocolHandleMessageDeps> = {}): {
         state.secondarySubText = text;
       },
       resolvePendingRequest: () => false,
+      shouldEnforceSecondarySubVisibilityHidden: () => true,
       setSecondarySubVisibility: () => {},
       syncCurrentAudioStreamIndex: () => {},
       setCurrentAudioTrackId: () => {},
@@ -198,6 +199,21 @@ test('dispatchMpvProtocolMessage rejects decimal subtitle track IDs', async () =
   assert.deepEqual(state.events, [{ sid: null }, { sid: null }, { sid: null }, { sid: null }]);
 });
 
+test('dispatchMpvProtocolMessage hides native secondary subtitles after a track change', async () => {
+  const visibilityChanges: boolean[] = [];
+  const { deps, state } = createDeps({
+    setSecondarySubVisibility: (visible) => visibilityChanges.push(visible),
+  });
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sid', data: '4' },
+    deps,
+  );
+
+  assert.deepEqual(visibilityChanges, [false]);
+  assert.deepEqual(state.events, [{ sid: 4 }]);
+});
+
 test('dispatchMpvProtocolMessage enforces sub-visibility hidden when overlay suppression is enabled', async () => {
   const { deps, state } = createDeps({
     isVisibleOverlayVisible: () => true,
@@ -239,6 +255,24 @@ test('dispatchMpvProtocolMessage skips sub-visibility suppression when overlay i
   assert.equal(state.commands.length, 0);
 });
 
+test('dispatchMpvProtocolMessage corrects native secondary subtitle visibility', async () => {
+  const visibilityChanges: boolean[] = [];
+  const { deps } = createDeps({
+    setSecondarySubVisibility: (visible) => visibilityChanges.push(visible),
+  });
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sub-visibility', data: 'yes' },
+    deps,
+  );
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sub-visibility', data: 'no' },
+    deps,
+  );
+
+  assert.deepEqual(visibilityChanges, [false]);
+});
+
 test('dispatchMpvProtocolMessage sets secondary subtitle track based on track list response', async () => {
   const { deps, state } = createDeps();
 

src/core/services/mpv-protocol.ts

@@ -72,6 +72,7 @@ export interface MpvProtocolHandleMessageDeps {
   emitSubtitleMetricsChange: (payload: Partial<MpvSubtitleRenderMetrics>) => void;
   setCurrentSecondarySubText: (text: string) => void;
   resolvePendingRequest: (requestId: number, message: MpvMessage) => boolean;
+  shouldEnforceSecondarySubVisibilityHidden: () => boolean;
   setSecondarySubVisibility: (visible: boolean) => void;
   syncCurrentAudioStreamIndex: () => void;
   setCurrentAudioTrackId: (value: number | null) => void;
@@ -285,6 +286,9 @@ export async function dispatchMpvProtocolMessage(
             : null;
       deps.emitSubtitleTrackChange({ sid: sid !== null && Number.isInteger(sid) ? sid : null });
     } else if (msg.name === 'secondary-sid') {
+      if (deps.shouldEnforceSecondarySubVisibilityHidden()) {
+        deps.setSecondarySubVisibility(false);
+      }
       const sid =
         typeof msg.data === 'number'
           ? msg.data
@@ -375,6 +379,11 @@ export async function dispatchMpvProtocolMessage(
       if (deps.isVisibleOverlayVisible() && asBoolean(msg.data, false)) {
         deps.sendCommand({ command: ['set_property', 'sub-visibility', false] });
       }
+    } else if (msg.name === 'secondary-sub-visibility') {
+      const visible = parseVisibilityProperty(msg.data);
+      if (deps.shouldEnforceSecondarySubVisibilityHidden() && visible === true) {
+        deps.setSecondarySubVisibility(false);
+      }
     } else if (msg.name === 'sub-use-margins') {
       deps.emitSubtitleMetricsChange({
         subUseMargins: asBoolean(msg.data, deps.getSubtitleMetrics().subUseMargins),

src/core/services/mpv.test.ts

@@ -652,7 +652,7 @@ test('MpvIpcClient captures and disables secondary subtitle visibility on reques
   ]);
 });
 
-test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tracked value', async () => {
+test('MpvIpcClient restores secondary subtitle visibility and relinquishes suppression', async () => {
   const commands: unknown[] = [];
   const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
   const previous: boolean[] = [];
@@ -671,6 +671,12 @@ test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tra
   });
   client.restorePreviousSecondarySubVisibility();
 
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+
   assert.equal(previous[0], true);
   assert.equal(previous.length, 1);
   assert.deepEqual(commands, [
@@ -682,8 +688,53 @@ test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tra
     },
   ]);
 
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+  assert.equal(commands.length, 2);
+
   client.restorePreviousSecondarySubVisibility();
   assert.equal(commands.length, 2);
+
+  const callbacks = (client as any).transport.callbacks;
+  callbacks.onConnect();
+  commands.length = 0;
+
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+  assert.deepEqual(commands, [{ command: ['set_property', 'secondary-sub-visibility', 'no'] }]);
+});
+
+test('MpvIpcClient keeps secondary subtitle suppression when restoration send fails', async () => {
+  const commands: unknown[] = [];
+  const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
+
+  (client as any).send = (payload: unknown) => {
+    commands.push(payload);
+    return false;
+  };
+
+  await invokeHandleMessage(client, {
+    request_id: MPV_REQUEST_ID_SECONDARY_SUB_VISIBILITY,
+    data: 'yes',
+  });
+  client.restorePreviousSecondarySubVisibility();
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sid',
+    data: 4,
+  });
+
+  assert.deepEqual(commands, [
+    { command: ['set_property', 'secondary-sub-visibility', 'no'] },
+    { command: ['set_property', 'secondary-sub-visibility', 'yes'] },
+    { command: ['set_property', 'secondary-sub-visibility', 'no'] },
+  ]);
 });
 
 test('MpvIpcClient updates current audio stream index from track list', async () => {

src/core/services/mpv.ts

@@ -184,6 +184,7 @@ export class MpvIpcClient implements MpvClient {
     osdDimensions: null,
   };
   private previousSecondarySubVisibility: boolean | null = null;
+  private enforceSecondarySubVisibilityHidden = true;
   private playbackPaused: boolean | null = null;
   private pauseAtTime: number | null = null;
   private pendingPauseAtSubEnd = false;
@@ -199,6 +200,7 @@ export class MpvIpcClient implements MpvClient {
       socketFactory: deps.socketFactory,
       connectTimeoutMs: deps.connectTimeoutMs,
       onConnect: () => {
+        this.enforceSecondarySubVisibilityHidden = true;
         this.connected = true;
         this.connecting = false;
         this.socket = this.transport.getSocket();
@@ -476,6 +478,7 @@ export class MpvIpcClient implements MpvClient {
       },
       resolvePendingRequest: (requestId: number, message: MpvMessage) =>
         this.tryResolvePendingRequest(requestId, message),
+      shouldEnforceSecondarySubVisibilityHidden: () => this.enforceSecondarySubVisibilityHidden,
       setSecondarySubVisibility: (visible: boolean) => this.setSecondarySubVisibility(visible),
       syncCurrentAudioStreamIndex: () => {
         this.syncCurrentAudioStreamIndex();
@@ -647,9 +650,11 @@ export class MpvIpcClient implements MpvClient {
   restorePreviousSecondarySubVisibility(): void {
     const previous = this.previousSecondarySubVisibility;
     if (previous === null) return;
-    this.send({
+    const restored = this.send({
       command: ['set_property', 'secondary-sub-visibility', previous ? 'yes' : 'no'],
     });
+    if (!restored) return;
+    this.enforceSecondarySubVisibilityHidden = false;
     this.previousSecondarySubVisibility = null;
   }
 

src/core/services/overlay-runtime-init.ts

@@ -21,6 +21,7 @@ type CreateAnkiIntegrationArgs = {
   mpvClient: { send?: (payload: { command: string[] }) => void };
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -74,6 +75,7 @@ function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiInte
     args.getCachedMediaPath,
     args.shouldRequireRemoteMediaCache,
     args.getYoutubeMediaSourceUrl,
+    args.dismissOverlayNotification,
   );
 }
 
@@ -137,6 +139,7 @@ export function initializeOverlayRuntime(
     setAnkiIntegration: (integration: unknown | null) => void;
     showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
     showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+    dismissOverlayNotification?: (id: string) => void;
     createFieldGroupingCallback: () => (
       data: KikuFieldGroupingRequestData,
     ) => Promise<KikuFieldGroupingChoice>;
@@ -177,6 +180,7 @@ export function initializeOverlayAnkiIntegration(options: {
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -219,6 +223,7 @@ export function initializeOverlayAnkiIntegration(options: {
     mpvClient,
     showDesktopNotification: options.showDesktopNotification,
     showOverlayNotification: options.showOverlayNotification,
+    dismissOverlayNotification: options.dismissOverlayNotification,
     createFieldGroupingCallback: options.createFieldGroupingCallback,
     knownWordCacheStatePath: options.getKnownWordCacheStatePath(),
     ...(options.getCachedMediaPath ? { getCachedMediaPath: options.getCachedMediaPath } : {}),

src/core/services/remote-media-window-cache.test.ts

@@ -0,0 +1,253 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import test from 'node:test';
+import {
+  buildRemoteMediaWindowArgs,
+  RemoteMediaWindowCache,
+  REMOTE_MEDIA_WINDOW_MAX_SECONDS,
+  type RemoteMediaWindowCacheOptions,
+} from './remote-media-window-cache';
+
+const SOURCE = {
+  path: 'https://jellyfin.example/Videos/abc/stream?static=true',
+  audioStreamIndex: 2,
+};
+
+type ExecFileStub = NonNullable<RemoteMediaWindowCacheOptions['execFile']>;
+
+function createStub(options: { fail?: boolean; empty?: boolean; defer?: boolean } = {}) {
+  const calls: string[][] = [];
+  const pendingCallbacks: Array<() => void> = [];
+  const execFile: ExecFileStub = (_file, args, _options, callback) => {
+    calls.push([...args]);
+    const finish = (): void => {
+      const outputPath = args.at(-1);
+      assert.ok(outputPath);
+      if (options.fail) {
+        callback(Object.assign(new Error('boom'), { code: 1 }));
+        return;
+      }
+      if (!options.empty) {
+        fs.writeFileSync(outputPath, 'mkv', 'utf8');
+      }
+      callback(null);
+    };
+    if (options.defer) {
+      pendingCallbacks.push(finish);
+    } else {
+      queueMicrotask(finish);
+    }
+  };
+  return {
+    calls,
+    execFile,
+    flush: () => {
+      for (const finish of pendingCallbacks.splice(0)) finish();
+    },
+  };
+}
+
+async function withCache(
+  stubOptions: Parameters<typeof createStub>[0],
+  cacheOptions: Omit<RemoteMediaWindowCacheOptions, 'execFile' | 'tempDir'>,
+  run: (cache: RemoteMediaWindowCache, stub: ReturnType<typeof createStub>) => Promise<void>,
+): Promise<void> {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-media-window-test-'));
+  const stub = createStub(stubOptions);
+  const cache = new RemoteMediaWindowCache({
+    tempDir,
+    execFile: stub.execFile,
+    idleTtlMs: 0,
+    logDebug: () => undefined,
+    ...cacheOptions,
+  });
+  try {
+    await run(cache, stub);
+  } finally {
+    cache.cleanup();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function argValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+test('buildRemoteMediaWindowArgs stream-copies the window with source timestamps intact', () => {
+  const args = buildRemoteMediaWindowArgs(
+    { ...SOURCE, inputOptions: { reconnect: true, headers: { Referer: 'https://a.example/' } } },
+    { startTime: 22.75, endTime: 33 },
+    '/tmp/window.mkv',
+  );
+
+  const inputIndex = args.indexOf('-i');
+  assert.equal(args[inputIndex + 1], SOURCE.path);
+  assert.ok(args.indexOf('-reconnect') < inputIndex);
+  assert.ok(args.indexOf('-headers') < inputIndex);
+  assert.equal(argValue(args, '-ss'), '22.75');
+  assert.equal(argValue(args, '-t'), '10.25');
+  assert.ok(args.indexOf('-t') < inputIndex);
+  assert.deepEqual(args.slice(args.indexOf('-map'), args.indexOf('-map') + 4), [
+    '-map',
+    '0:v:0?',
+    '-map',
+    '0:2',
+  ]);
+  assert.equal(argValue(args, '-c'), 'copy');
+  assert.ok(args.includes('-copyts'));
+  assert.ok(args.includes('-start_at_zero'));
+  assert.equal(argValue(args, '-f'), 'matroska');
+  assert.equal(args.at(-1), '/tmp/window.mkv');
+});
+
+test('buildRemoteMediaWindowArgs keeps every audio stream when none is selected', () => {
+  const args = buildRemoteMediaWindowArgs(
+    { path: SOURCE.path, audioStreamIndex: null },
+    { startTime: 0, endTime: 5 },
+    '/tmp/window.mkv',
+  );
+
+  assert.equal(args[args.lastIndexOf('-map') + 1], '0:a');
+});
+
+test('acquire downloads once and reuses the window for covered ranges', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    const window = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+
+    assert.equal(stub.calls.length, 1);
+    assert.equal(argValue(stub.calls[0]!, '-ss'), '9.75');
+    assert.equal(argValue(stub.calls[0]!, '-t'), '5.25');
+    assert.equal(window.startTime, 9.75);
+    assert.equal(window.endTime, 15);
+    assert.equal(window.audioStreamIndex, 2);
+    assert.ok(fs.existsSync(window.path));
+    assert.deepEqual(window.media, {
+      path: window.path,
+      source: 'remote-window',
+      singleResolvedStream: true,
+      absoluteTimestamps: true,
+    });
+
+    assert.equal(await cache.acquire(SOURCE, { startTime: 11, endTime: 15 }), window);
+    assert.equal(await cache.lookup(SOURCE, { startTime: 12, endTime: 12 }), window);
+    assert.equal(
+      await cache.lookup(
+        { path: SOURCE.path, audioStreamIndex: null },
+        { startTime: 12, endTime: 13 },
+      ),
+      window,
+    );
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('lookup never downloads and misses on other ranges, sources, or audio streams', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    assert.equal(await cache.lookup(SOURCE, { startTime: 10, endTime: 14 }), null);
+    assert.equal(stub.calls.length, 0);
+
+    await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    assert.equal(await cache.lookup(SOURCE, { startTime: 14, endTime: 16 }), null);
+    assert.equal(
+      await cache.lookup(
+        { path: 'https://other.example/stream', audioStreamIndex: 2 },
+        {
+          startTime: 11,
+          endTime: 12,
+        },
+      ),
+      null,
+    );
+    assert.equal(
+      await cache.lookup(
+        { path: SOURCE.path, audioStreamIndex: 3 },
+        { startTime: 11, endTime: 12 },
+      ),
+      null,
+    );
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('acquire widens to the union of the old window and replaces the old file', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    const first = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    const second = await cache.acquire(SOURCE, { startTime: 8, endTime: 12 });
+
+    assert.equal(stub.calls.length, 2);
+    assert.equal(argValue(stub.calls[1]!, '-ss'), '7.75');
+    assert.equal(second.startTime, 7.75);
+    assert.equal(second.endTime, 15);
+    assert.notEqual(second.path, first.path);
+    assert.equal(fs.existsSync(first.path), false);
+    assert.ok(fs.existsSync(second.path));
+    assert.equal(cache.currentWindow, second);
+  });
+});
+
+test('acquire shares an in-flight download between concurrent callers', async () => {
+  await withCache({ defer: true }, {}, async (cache, stub) => {
+    const first = cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    await Promise.resolve();
+    const second = cache.acquire(SOURCE, { startTime: 11, endTime: 13 });
+    const lookup = cache.lookup(SOURCE, { startTime: 12, endTime: 12 });
+    await Promise.resolve();
+    assert.equal(stub.calls.length, 1);
+
+    stub.flush();
+    const [a, b, c] = await Promise.all([first, second, lookup]);
+    assert.equal(a, b);
+    assert.equal(a, c);
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('acquire rejects on ffmpeg failure, leaves no file, and can retry', async () => {
+  await withCache({ fail: true }, {}, async (cache, stub) => {
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 10, endTime: 14 }),
+      /FFmpeg media window failed: boom/,
+    );
+    assert.equal(cache.currentWindow, null);
+    assert.equal(await cache.lookup(SOURCE, { startTime: 10, endTime: 14 }), null);
+
+    await assert.rejects(cache.acquire(SOURCE, { startTime: 10, endTime: 14 }));
+    assert.equal(stub.calls.length, 2);
+  });
+  await withCache({ empty: true }, {}, async (cache) => {
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 10, endTime: 14 }),
+      /exited without creating a media window/,
+    );
+  });
+});
+
+test('acquire refuses invalid and oversized ranges without spawning ffmpeg', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    await assert.rejects(cache.acquire(SOURCE, { startTime: 10, endTime: 10 }), /invalid/);
+    await assert.rejects(cache.acquire(SOURCE, { startTime: -1, endTime: 10 }), /invalid/);
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 0, endTime: REMOTE_MEDIA_WINDOW_MAX_SECONDS + 1 }),
+      /too long/,
+    );
+    assert.equal(stub.calls.length, 0);
+  });
+});
+
+test('the window is deleted after the idle timeout and on cleanup', async () => {
+  await withCache({}, { idleTtlMs: 20 }, async (cache) => {
+    const window = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    assert.equal(cache.currentWindow, null);
+    assert.equal(fs.existsSync(window.path), false);
+
+    const again = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    cache.cleanup();
+    assert.equal(fs.existsSync(again.path), false);
+    assert.equal(fs.existsSync(path.dirname(again.path)), false);
+  });
+});

src/core/services/remote-media-window-cache.ts

@@ -0,0 +1,377 @@
+import { execFile as nodeExecFile, type ExecFileException } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createLogger } from '../../logger';
+import { normalizeMediaInput, type MediaInput, type MediaInputOptions } from '../../media-input';
+
+const log = createLogger('media-window');
+
+export const REMOTE_MEDIA_WINDOW_TIMEOUT_MS = 120_000;
+export const REMOTE_MEDIA_WINDOW_MAX_SECONDS = 180;
+const HEAD_SLACK_SECONDS = 0.25;
+const TAIL_SLACK_SECONDS = 1;
+const DEFAULT_IDLE_TTL_MS = 10 * 60_000;
+const COVERAGE_EPSILON_SECONDS = 0.01;
+
+export interface RemoteMediaWindowSource {
+  path: string;
+  inputOptions?: MediaInputOptions;
+  /** FFmpeg stream index to keep; `null`/undefined keeps every audio stream. */
+  audioStreamIndex?: number | null;
+}
+
+export interface RemoteMediaWindowRange {
+  startTime: number;
+  endTime: number;
+}
+
+export interface RemoteMediaWindow {
+  path: string;
+  startTime: number;
+  endTime: number;
+  sourcePath: string;
+  audioStreamIndex: number | null;
+  /** Input descriptor for FFmpeg reads; timestamps stay absolute so callers keep source times. */
+  media: MediaInput;
+}
+
+type WindowExecFile = (
+  file: string,
+  args: readonly string[],
+  options: { timeout: number },
+  callback: (error: ExecFileException | null) => void,
+) => void;
+
+export interface RemoteMediaWindowCacheOptions {
+  tempDir?: string;
+  execFile?: WindowExecFile;
+  idleTtlMs?: number;
+  logDebug?: (message: string) => void;
+}
+
+interface PendingFetch extends RemoteMediaWindowRange {
+  sourcePath: string;
+  audioStreamIndex: number | null;
+  promise: Promise<RemoteMediaWindow>;
+}
+
+export function isRemoteMediaWindowSourcePath(value: string): boolean {
+  return /^https?:\/\//i.test(value.trim());
+}
+
+function describeSourceForDebugLog(sourcePath: string): string {
+  try {
+    return `remote:${new URL(sourcePath).hostname.toLowerCase() || 'unknown'}`;
+  } catch {
+    return 'remote:unknown';
+  }
+}
+
+function isUsableRange(range: RemoteMediaWindowRange, allowEmpty: boolean): boolean {
+  return (
+    Number.isFinite(range.startTime) &&
+    Number.isFinite(range.endTime) &&
+    range.startTime >= 0 &&
+    (allowEmpty ? range.endTime >= range.startTime : range.endTime > range.startTime)
+  );
+}
+
+function audioStreamMatches(
+  windowIndex: number | null,
+  requested: number | null | undefined,
+): boolean {
+  return requested == null || windowIndex === requested;
+}
+
+function covers(
+  candidate: RemoteMediaWindowRange & { sourcePath: string; audioStreamIndex: number | null },
+  source: RemoteMediaWindowSource,
+  range: RemoteMediaWindowRange,
+): boolean {
+  return (
+    candidate.sourcePath === source.path &&
+    audioStreamMatches(candidate.audioStreamIndex, source.audioStreamIndex) &&
+    candidate.startTime <= range.startTime + COVERAGE_EPSILON_SECONDS &&
+    candidate.endTime >= range.endTime - COVERAGE_EPSILON_SECONDS
+  );
+}
+
+/**
+ * Stream-copies `[startTime, endTime]` of a remote source into a local Matroska file.
+ * `-copyts -start_at_zero` keeps the source timestamps, so later reads seek with the
+ * original times via `-seek_timestamp 1` (see `MediaInput.absoluteTimestamps`).
+ */
+export function buildRemoteMediaWindowArgs(
+  source: RemoteMediaWindowSource,
+  range: RemoteMediaWindowRange,
+  outputPath: string,
+): string[] {
+  const input = normalizeMediaInput({ path: source.path, inputOptions: source.inputOptions });
+  const audioMap =
+    typeof source.audioStreamIndex === 'number' && Number.isInteger(source.audioStreamIndex)
+      ? `0:${source.audioStreamIndex}`
+      : '0:a';
+  return [
+    '-hide_banner',
+    '-nostdin',
+    '-loglevel',
+    'error',
+    '-ss',
+    String(range.startTime),
+    '-t',
+    String(range.endTime - range.startTime),
+    ...input.inputArgs,
+    '-i',
+    input.path,
+    '-map',
+    '0:v:0?',
+    '-map',
+    audioMap,
+    '-c',
+    'copy',
+    '-sn',
+    '-dn',
+    '-copyts',
+    '-start_at_zero',
+    '-f',
+    'matroska',
+    '-y',
+    outputPath,
+  ];
+}
+
+/**
+ * Holds one downloaded window of the current remote stream so the timing review,
+ * audio extraction, and screenshot all read the same local bytes instead of each
+ * re-fetching the clip over HTTP. A new window replaces the old one; the file is
+ * deleted after `idleTtlMs` without use, on `clear()`, or on `cleanup()`.
+ */
+export class RemoteMediaWindowCache {
+  private readonly tempDir: string;
+  private readonly execFile: WindowExecFile;
+  private readonly idleTtlMs: number;
+  private readonly logDebug: (message: string) => void;
+  private current: RemoteMediaWindow | null = null;
+  private pending: PendingFetch | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private sequence = 0;
+
+  constructor(options: RemoteMediaWindowCacheOptions = {}) {
+    this.tempDir = options.tempDir ?? path.join(os.tmpdir(), 'subminer-media-windows');
+    this.execFile = options.execFile ?? nodeExecFile;
+    this.idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+    this.logDebug = options.logDebug ?? ((message) => log.debug(message));
+  }
+
+  get currentWindow(): RemoteMediaWindow | null {
+    return this.current;
+  }
+
+  /** Returns a ready or in-flight window covering the range; never starts a download. */
+  async lookup(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow | null> {
+    if (!isUsableRange(range, true)) return null;
+    if (this.current && covers(this.current, source, range)) {
+      this.touch();
+      return this.current;
+    }
+    const pending = this.pending;
+    if (pending && covers(pending, source, range)) {
+      try {
+        const window = await pending.promise;
+        this.touch();
+        return window;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  /** Returns a window covering the range, downloading (and widening) one when needed. */
+  async acquire(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> {
+    if (!isUsableRange(range, false)) {
+      throw new Error('Media window range is invalid.');
+    }
+    if (range.endTime - range.startTime > REMOTE_MEDIA_WINDOW_MAX_SECONDS) {
+      throw new Error('Media window range is too long to download.');
+    }
+
+    for (;;) {
+      const hit = await this.lookup(source, range);
+      if (hit) return hit;
+      const pending = this.pending;
+      if (!pending) break;
+      // Another caller is already downloading; wait for it, then re-check coverage.
+      await pending.promise.catch(() => null);
+    }
+
+    return this.fetch(source, this.planFetchRange(source, range));
+  }
+
+  clear(): void {
+    this.cancelIdleTimer();
+    const current = this.current;
+    this.current = null;
+    if (current) this.removeFile(current.path);
+  }
+
+  cleanup(): void {
+    this.clear();
+    try {
+      fs.rmSync(this.tempDir, { recursive: true, force: true });
+    } catch (error) {
+      log.error('Failed to cleanup media window directory:', error);
+    }
+  }
+
+  private planFetchRange(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): RemoteMediaWindowRange {
+    let startTime = Math.max(0, range.startTime - HEAD_SLACK_SECONDS);
+    let endTime = range.endTime + TAIL_SLACK_SECONDS;
+    const current = this.current;
+    if (
+      current &&
+      current.sourcePath === source.path &&
+      audioStreamMatches(current.audioStreamIndex, source.audioStreamIndex)
+    ) {
+      // Keep what was already downloaded when the review timeline grows in one direction.
+      const unionStart = Math.min(startTime, current.startTime);
+      const unionEnd = Math.max(endTime, current.endTime);
+      if (unionEnd - unionStart <= REMOTE_MEDIA_WINDOW_MAX_SECONDS) {
+        startTime = unionStart;
+        endTime = unionEnd;
+      }
+    }
+    return { startTime, endTime };
+  }
+
+  private fetch(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> {
+    fs.mkdirSync(this.tempDir, { recursive: true });
+    this.sequence += 1;
+    const outputPath = path.join(this.tempDir, `window_${Date.now()}_${this.sequence}.mkv`);
+    const audioStreamIndex =
+      typeof source.audioStreamIndex === 'number' ? source.audioStreamIndex : null;
+    const description = describeSourceForDebugLog(source.path);
+    const startedAt = Date.now();
+    this.logDebug(
+      `[media-window] fetch start ${description} start=${range.startTime} end=${range.endTime} audioStream=${audioStreamIndex ?? 'all'}`,
+    );
+
+    const promise = new Promise<RemoteMediaWindow>((resolve, reject) => {
+      this.execFile(
+        'ffmpeg',
+        buildRemoteMediaWindowArgs(source, range, outputPath),
+        { timeout: REMOTE_MEDIA_WINDOW_TIMEOUT_MS },
+        (error) => {
+          const elapsedMs = Math.max(0, Date.now() - startedAt);
+          const size = error ? 0 : this.fileSize(outputPath);
+          if (error || size === 0) {
+            this.removeFile(outputPath);
+            const reason = error
+              ? error.code === 'ENOENT'
+                ? 'FFmpeg not found. Install FFmpeg to enable media generation.'
+                : `FFmpeg media window failed: ${error.message}`
+              : 'FFmpeg exited without creating a media window.';
+            this.logDebug(`[media-window] fetch failed ${description} elapsedMs=${elapsedMs}`);
+            reject(new Error(reason));
+            return;
+          }
+          const window: RemoteMediaWindow = {
+            path: outputPath,
+            startTime: range.startTime,
+            endTime: range.endTime,
+            sourcePath: source.path,
+            audioStreamIndex,
+            media: {
+              path: outputPath,
+              source: 'remote-window',
+              singleResolvedStream: true,
+              absoluteTimestamps: true,
+            },
+          };
+          this.logDebug(
+            `[media-window] fetch complete ${description} elapsedMs=${elapsedMs} bytes=${size}`,
+          );
+          this.replaceCurrent(window);
+          resolve(window);
+        },
+      );
+    });
+
+    const pending: PendingFetch = {
+      sourcePath: source.path,
+      audioStreamIndex,
+      startTime: range.startTime,
+      endTime: range.endTime,
+      promise,
+    };
+    this.pending = pending;
+    promise
+      .catch(() => undefined)
+      .then(() => {
+        if (this.pending === pending) this.pending = null;
+      });
+    return promise;
+  }
+
+  private replaceCurrent(window: RemoteMediaWindow): void {
+    const previous = this.current;
+    this.current = window;
+    if (previous && previous.path !== window.path) this.removeFile(previous.path);
+    this.touch();
+  }
+
+  private touch(): void {
+    this.cancelIdleTimer();
+    if (this.idleTtlMs <= 0 || !this.current) return;
+    const timer = setTimeout(() => {
+      if (this.idleTimer === timer) this.idleTimer = null;
+      this.clear();
+    }, this.idleTtlMs);
+    timer.unref?.();
+    this.idleTimer = timer;
+  }
+
+  private cancelIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
+  private fileSize(filePath: string): number {
+    try {
+      return fs.statSync(filePath).size;
+    } catch {
+      return 0;
+    }
+  }
+
+  private removeFile(filePath: string): void {
+    try {
+      fs.unlinkSync(filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        log.debug(`Failed to remove media window ${filePath}:`, (error as Error).message);
+      }
+    }
+  }
+}
+
+let sharedCache: RemoteMediaWindowCache | null = null;
+
+/** Process-wide cache so the review modal and card media generation share one download. */
+export function getSharedRemoteMediaWindowCache(): RemoteMediaWindowCache {
+  sharedCache ??= new RemoteMediaWindowCache();
+  return sharedCache;
+}

src/core/services/subtitle-cue-parser.test.ts

@@ -1442,18 +1442,275 @@ const eventsHeader = [
   'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
 ];
 
-test('parseSubtitleCues keeps a tall CC-style dialogue block publishable, not a fragment grid', () => {
+test('parseSubtitleCues keeps tall CC-style base dialogue publishable after removing furigana', () => {
   const content = [
     ...eventsHeader,
     'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(212,383)\\fscx50\\fscy50}たき',
     'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(172,437)\\fscx50}（{\\fscx100}立希{\\fscx50}）',
     'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(332,443)\\fscx50\\fscy50}ともり',
     'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(192,497)}お前…{\\fscx50}　{\\fscx100}燈をバンドに誘ったの？',
+    // A second labeled turn, so the script reads as broadcast captions.
+    'Dialogue: 0,0:00:10.11,0:00:12.00,Default,,0,0,0,,{\\pos(192,497)\\fscx50}（{\\fscx100}燈{\\fscx50}）{\\fscx100}うん。',
   ].join('\n');
 
-  const cue = parseSubtitleCues(content, 'test.ass')[0];
-  assert.equal(cue?.text, 'たき（立希）ともりお前…　燈をバンドに誘ったの？');
-  assert.equal(cue?.assLayout?.kind, 'positioned');
+  const cues = parseSubtitleCues(content, 'test.ass');
+  // The bare speaker label row joins the dialogue row beneath it as one cue.
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['（立希）\nお前…　燈をバンドに誘ったの？', '（燈）うん。'],
+  );
+  assert.deepEqual(cues[0]?.assFurigana, ['たき', 'ともり']);
+  assert.ok(cues.every((cue) => cue.assLayout?.kind === 'positioned'));
+});
+
+test('parseSubtitleCues removes half-size positioned furigana from broadcast captions', () => {
+  const content = [
+    '[Script Info]',
+    'PlayResY: 540',
+    '',
+    ...eventsHeader,
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(192,77)\\fscx50}（{\\fscx100}山田{\\fscx50}）{\\fscx100}ごめん{\\fscx50}　{\\fscx100}結局{\\fscx50}　{\\fscx100}ぬれたな{\\fscx50}。',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,113)\\fscx50\\fscy50}だいじょうぶ',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,167)}大丈夫{\\fscx50}。',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,407)\\fscx50}（{\\fscx100}山田の母{\\fscx50}）{\\fscx100}ほんなら',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,443)\\fscx50\\fscy50}かく',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(312,443)\\fscx50\\fscy50}ちょぞう',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,497)}隠し貯蔵のミルクまんじゅう➡',
+    'Dialogue: 0,0:04:00.00,0:04:03.00,Default,,0,0,0,,{\\pos(232,443)\\fscx50\\fscy50}ぜったい　ちが',
+    'Dialogue: 0,0:04:00.00,0:04:03.00,Default,,0,0,0,,{\\pos(232,497)}絶対違う',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e08.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      '（山田）ごめん　結局　ぬれたな。',
+      '大丈夫。',
+      '（山田の母）ほんなら\n隠し貯蔵のミルクまんじゅう➡',
+      '絶対違う',
+    ],
+  );
+  assert.deepEqual(cues[1]?.assFurigana, ['だいじょうぶ']);
+  assert.deepEqual(cues[2]?.assFurigana, ['かく', 'ちょぞう']);
+  assert.deepEqual(cues[3]?.assFurigana, ['ぜったい　ちが']);
+});
+
+// Broadcast-caption rows from You and I Are Polar Opposites S02E09. Every pair shares
+// timing, style, and the bottom band; only the text tells a wrap from a second speaker.
+const captionRowsHeader = ['[Script Info]', 'PlayResY: 540', '', ...eventsHeader];
+
+function captionRow(start: string, end: string, x: number, y: number, text: string): string {
+  return `Dialogue: 0,${start},${end},Default,,0,0,0,,{\\pos(${x},${y})}${text}`;
+}
+
+test('parseSubtitleCues joins caption rows that wrap one sentence across two events', () => {
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:19.08', '0:00:22.66', 172, 437, '⸨ぶっちゃけ'),
+    captionRow(
+      '0:00:19.08',
+      '0:00:22.66',
+      172,
+      497,
+      '早く{\\fscx50}　{\\fscx100}この勉強生活　終えたいし⸩',
+    ),
+    // No bracket at all: the upper row simply has not reached sentence punctuation.
+    captionRow('0:02:42.33', '0:02:44.43', 232, 437, '（東）≪好きだと'),
+    captionRow('0:02:42.33', '0:02:44.43', 232, 497, '自覚してしまったものの➡'),
+    // Rows are centred independently, so a wrap can change x between rows.
+    captionRow('0:00:42.21', '0:00:45.21', 252, 407, '≪ちょっとしたことで'),
+    captionRow('0:00:42.21', '0:00:45.21', 292, 497, '勝手に落ち込んだり➡'),
+    // A quote closed with 」 inside a still-open ≪…≫ span is not the end of the line.
+    captionRow('0:19:02.84', '0:19:05.00', 212, 437, '≪「つきあえる自信がない」'),
+    captionRow('0:19:02.84', '0:19:05.00', 452, 497, 'じゃない≫'),
+    // An in-sentence 「 quote on the lower row is not a new turn.
+    captionRow('0:18:35.55', '0:18:38.00', 232, 437, '今　「好きだ」と'),
+    captionRow('0:18:35.55', '0:18:38.00', 192, 497, '「心地いい」と感じてるのも➡'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e09.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      '⸨ぶっちゃけ\n早く　この勉強生活　終えたいし⸩',
+      '≪ちょっとしたことで\n勝手に落ち込んだり➡',
+      '（東）≪好きだと\n自覚してしまったものの➡',
+      '今　「好きだ」と\n「心地いい」と感じてるのも➡',
+      '≪「つきあえる自信がない」\nじゃない≫',
+    ],
+  );
+  assert.ok(cues.every((cue) => cue.assLayout?.kind === 'positioned'));
+});
+
+test('parseSubtitleCues keeps simultaneous caption rows from two speakers separate', () => {
+  const content = [
+    ...captionRowsHeader,
+    // Both unlabeled: the upper row finished its sentence.
+    captionRow('0:03:56.10', '0:04:00.04', 172, 437, 'なあ　車両　変えね？'),
+    captionRow('0:03:56.10', '0:04:00.04', 632, 497, 'えっ？➡'),
+    // Lower row opens a labeled turn.
+    captionRow('0:03:38.48', '0:03:42.05', 592, 437, 'おはよう！'),
+    captionRow('0:03:38.48', '0:03:42.05', 272, 497, '（平）あっ　声　でかっ。'),
+    // A closed monologue span above a sound effect.
+    captionRow('0:08:16.83', '0:08:19.50', 372, 437, '≪落ち着け　落ち着け≫'),
+    captionRow('0:08:16.83', '0:08:19.50', 272, 497, 'ドクン　ドクン　ドクン…'),
+    // Two labeled speakers.
+    captionRow('0:09:27.90', '0:09:31.07', 312, 437, '（平）ぐぅ…。'),
+    captionRow('0:09:27.90', '0:09:31.07', 352, 497, '（東）≪ちくしょう～！≫'),
+    // A bare label never swallows a differently labeled row.
+    captionRow('0:11:43.24', '0:11:45.00', 212, 437, '（長谷川）'),
+    captionRow('0:11:43.24', '0:11:45.00', 412, 497, '（早乙女）ん？'),
+    // A short sentence-final 。 closes the upper row like any other.
+    captionRow('0:12:31.55', '0:12:33.55', 172, 437, '⚞（東）平。'),
+    captionRow('0:12:31.55', '0:12:33.55', 532, 497, 'あっ。'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e09.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'おはよう！',
+      '（平）あっ　声　でかっ。',
+      'なあ　車両　変えね？',
+      'えっ？➡',
+      '≪落ち着け　落ち着け≫',
+      'ドクン　ドクン　ドクン…',
+      '（平）ぐぅ…。',
+      '（東）≪ちくしょう～！≫',
+      '（長谷川）',
+      '（早乙女）ん？',
+      '⚞（東）平。',
+      'あっ。',
+    ],
+  );
+});
+
+test('parseSubtitleCues keeps caption rows apart across styles, bands, and timing', () => {
+  const content = [
+    ...captionRowsHeader,
+    // Same wording as a wrap, but the rows sit in different vertical bands.
+    captionRow('0:01:00.00', '0:01:02.00', 172, 77, '≪ちょっとしたことで'),
+    captionRow('0:01:00.00', '0:01:02.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Same band, but a sign style beside dialogue.
+    'Dialogue: 0,0:01:05.00,0:01:07.00,Sign,,0,0,0,,{\\pos(172,437)}ちょっとしたことで',
+    captionRow('0:01:05.00', '0:01:07.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Same rows, but the lower one ends later.
+    captionRow('0:01:10.00', '0:01:12.00', 172, 437, '≪ちょっとしたことで'),
+    captionRow('0:01:10.00', '0:01:13.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Style-aligned rows without \pos are never caption rows.
+    'Dialogue: 0,0:01:15.00,0:01:17.00,Default,,0,0,0,,{\\an8}≪ちょっとしたことで',
+    'Dialogue: 0,0:01:15.00,0:01:17.00,Default,,0,0,0,,{\\an2}勝手に落ち込んだり➡',
+    // Same height: the events sit side by side, not one above the other.
+    captionRow('0:01:20.00', '0:01:22.00', 172, 497, '≪ちょっとしたことで'),
+    captionRow('0:01:20.00', '0:01:22.00', 612, 497, '勝手に落ち込んだり➡'),
+    // Same bottom band, but further apart than two text rows.
+    captionRow('0:01:25.00', '0:01:27.00', 172, 367, '≪ちょっとしたことで'),
+    captionRow('0:01:25.00', '0:01:27.00', 172, 497, '勝手に落ち込んだり➡'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 12);
+  assert.ok(cues.every((cue) => !cue.text.includes('\n')));
+});
+
+test('parseSubtitleCues leaves typeset rows alone in scripts that are not broadcast captions', () => {
+  // Fansub typesetting stacks positioned rows for signs, chat bubbles, and headlines. Such
+  // text carries no caption punctuation, so without the script-level gate every stacked
+  // pair here would read as an unfinished sentence and merge.
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:10.00', '0:00:14.00', 640, 200, 'Shocking Statement Leaves'),
+    captionRow('0:00:10.00', '0:00:14.00', 640, 260, 'Listeners Speechless!'),
+    captionRow('0:01:00.00', '0:01:04.00', 400, 300, 'shes here AGAIN'),
+    captionRow('0:01:00.00', '0:01:04.00', 400, 360, 'make sakiko-chan go home'),
+    // Japanese typesetting in the same script is held back by the same gate.
+    captionRow('0:02:00.00', '0:02:04.00', 300, 400, '定休日'),
+    captionRow('0:02:00.00', '0:02:04.00', 300, 460, '毎週水曜日'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'Shocking Statement Leaves',
+      'Listeners Speechless!',
+      'shes here AGAIN',
+      'make sakiko-chan go home',
+      '定休日',
+      '毎週水曜日',
+    ],
+  );
+});
+
+test('parseSubtitleCues never joins caption rows that carry no Japanese', () => {
+  // Even inside a caption script, romaji or English rows are not the wrapped Japanese
+  // sentences this pass targets.
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:10.00', '0:00:13.00', 172, 437, '（東）≪好きだと'),
+    captionRow('0:00:10.00', '0:00:13.00', 172, 497, '自覚してしまったものの➡'),
+    captionRow('0:00:20.00', '0:00:23.00', 172, 437, '（平）ん？'),
+    captionRow('0:00:30.00', '0:00:34.00', 640, 437, 'NOW LOADING'),
+    captionRow('0:00:30.00', '0:00:34.00', 640, 497, 'please wait'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['（東）≪好きだと\n自覚してしまったものの➡', '（平）ん？', 'NOW LOADING', 'please wait'],
+  );
+});
+
+test('parseSubtitleCues scales furigana geometry by PlayResY', () => {
+  const content = [
+    '[Script Info]',
+    'PlayResY: 1080',
+    '',
+    ...eventsHeader,
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(1104,226)\\fscx50\\fscy50}だいじょうぶ',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(1104,334)}大丈夫{\\fscx50}。',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['大丈夫。'],
+  );
+  assert.deepEqual(cues[0]?.assFurigana, ['だいじょうぶ']);
+});
+
+test('parseSubtitleCues preserves small kana without a matching kanji base caption', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,200)\\fscx50\\fscy50}ひそひそ',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,254)}ordinary dialogue',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['ひそひそ', 'ordinary dialogue'],
+  );
+});
+
+test('parseSubtitleCues preserves small kana horizontally separated from a kanji caption', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(800,200)\\fscx50\\fscy50}ひそひそ',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,254)}漢字',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.match(cues.map((cue) => cue.text).join('\n'), /ひそひそ/);
+  assert.deepEqual(
+    cues.flatMap((cue) => cue.assFurigana ?? []),
+    [],
+  );
 });
 
 test('parseSubtitleCues marks re-shown countdown frames as a fragment grid', () => {
@@ -1927,9 +2184,7 @@ test('parseSubtitleCues does not double a line rendered whole beside its glyph s
     ['わ', 1022],
     ['ね', 1064],
   ] as const;
-  const wholeLine = glyphs
-    .map(([glyph]) => `{\\an5\\fad(300,500)\\pos(960,50)}${glyph}`)
-    .join('');
+  const wholeLine = glyphs.map(([glyph]) => `{\\an5\\fad(300,500)\\pos(960,50)}${glyph}`).join('');
   const content = [
     ...eventsHeader,
     `Dialogue: 1,0:00:17.29,0:00:18.99,OP - JP,,0,0,0,,${wholeLine}`,
@@ -1952,7 +2207,7 @@ test('parseSubtitleCues drops a wall of near-invisible positioned texture string
   // faint translation is one or two events and stays published.
   const content = [
     ...eventsHeader,
-    'Dialogue: 90,0:00:12.66,0:00:14.91,Default,,0,0,0,,We\'ll play as a band, and then...',
+    "Dialogue: 90,0:00:12.66,0:00:14.91,Default,,0,0,0,,We'll play as a band, and then...",
     ...Array.from(
       { length: 12 },
       (_, index) =>
@@ -1997,3 +2252,25 @@ test('parseSubtitleCues keeps hidden events hidden when a transform animates an
     ['grows into view', 'wipes into view'],
   );
 });
+
+test('parseAssCues records the vertical band from style alignment, overrides, and \\pos', () => {
+  const ass = [
+    '[Script Info]',
+    'PlayResY: 720',
+    '',
+    '[V4+ Styles]',
+    'Format: Name, Fontname, Fontsize, PrimaryColour, Bold, Alignment, MarginV, Encoding',
+    'Style: Bottom,Arial,54,&H00FFFFFF,0,2,30,1',
+    'Style: TopSong,Arial,54,&H00FFFFFF,0,9,12,1',
+    '',
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,\u4e0b\u306e\u30bb\u30ea\u30d5',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,TopSong,,0,0,0,,\u6b4c\u8a5e\u306e\u884c',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,{\\an8}\u4e0a\u66f8\u304d\u306e\u884c',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,{\\pos(640,20)}\u770b\u677f\u306e\u884c',
+  ].join('\n');
+
+  const bands = parseAssCues(ass).map((cue) => cue.assLayout?.verticalBand);
+  assert.deepEqual(bands, ['bottom', 'top', 'top', 'top']);
+});

src/core/services/subtitle-cue-parser.ts

@@ -10,15 +10,29 @@ import {
 } from './ass-text';
 import { hasAssAnimationEvidence, mergeDuplicateCues } from './subtitle-cue-dedup';
 
+/** Vertical third of the screen a cue is authored to occupy. */
+export type AssVerticalBand = 'top' | 'middle' | 'bottom';
+
 export type AssCueLayout =
-  | { kind: 'positioned'; sourceOrder: number; y: number }
-  | { kind: 'fragment-grid'; sourceOrder: number }
-  | { kind: 'source-order'; sourceOrder: number };
+  | {
+      kind: 'positioned';
+      sourceOrder: number;
+      x?: number;
+      y: number;
+      verticalBand?: AssVerticalBand;
+    }
+  | { kind: 'fragment-grid'; sourceOrder: number; verticalBand?: AssVerticalBand }
+  | { kind: 'source-order'; sourceOrder: number; verticalBand?: AssVerticalBand };
 
 export interface SubtitleCue {
   startTime: number;
   endTime: number;
   text: string;
+  /**
+   * ASS ruby text removed from the published cue. Kept only so live `sub-text` matching
+   * can account for the extra lines mpv still reports from the source track.
+   */
+  assFurigana?: readonly string[];
   /** How a complete line was recovered from generated ASS animation events. */
   source?: 'canonical-ass' | 'reconstructed-ass';
   /**
@@ -97,10 +111,17 @@ function sanitizeAssCueText(text: string): string {
   return removeAssControlDebrisLines(decodeSubtitleCueText(text)).trim();
 }
 
-function attachAssLayout<T extends SubtitleCue>(cue: T, assLayout: AssCueLayout | undefined): T {
+function attachAssMetadata<T extends SubtitleCue>(
+  cue: T,
+  assLayout: AssCueLayout | undefined,
+  assFurigana: readonly string[] | undefined,
+): T {
   if (assLayout) {
     Object.defineProperty(cue, 'assLayout', { value: assLayout, enumerable: false });
   }
+  if (assFurigana?.length) {
+    Object.defineProperty(cue, 'assFurigana', { value: assFurigana, enumerable: false });
+  }
   return cue;
 }
 
@@ -115,6 +136,7 @@ function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
       animationEndTime,
       style,
       assLayout,
+      assFurigana,
     }) => {
       const common = {
         startTime,
@@ -122,7 +144,7 @@ function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
         text,
       };
       if (source === 'reconstructed-ass') {
-        return attachAssLayout(
+        return attachAssMetadata(
           {
             ...common,
             source,
@@ -131,11 +153,13 @@ function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
             assStyle: style,
           },
           assLayout,
+          assFurigana,
         );
       }
-      return attachAssLayout(
+      return attachAssMetadata(
         source ? { ...common, source, animationStartTime, animationEndTime } : common,
         assLayout,
+        assFurigana,
       );
     },
   );
@@ -481,9 +505,7 @@ function structuralOverrideSignature(cue: AnnotatedSubtitleCue): string {
   let signature = structuralSignatureCache.get(cue);
   if (signature === undefined) {
     const names = new Set(
-      cue.overrides.map(
-        (command) => `${command.animated ? '~' : ''}${command.name.toLowerCase()}`,
-      ),
+      cue.overrides.map((command) => `${command.animated ? '~' : ''}${command.name.toLowerCase()}`),
     );
     signature = [...names].sort().join(',');
     structuralSignatureCache.set(cue, signature);
@@ -544,9 +566,7 @@ function buildCoalescedCopy(members: readonly AnnotatedSubtitleCue[]): Annotated
  * while the anchor says one glyph. Merging each stack into a single presence spanning
  * the union window lets timing clusters see the authored line instead of its phases.
  */
-function coalesceAssAnchorCopies(
-  events: readonly AnnotatedSubtitleCue[],
-): AnnotatedSubtitleCue[] {
+function coalesceAssAnchorCopies(events: readonly AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
   const buckets = new Map<string, number[]>();
   const anchorPoints: (AssFragmentPosition[] | null)[] = events.map(() => null);
   events.forEach((event, index) => {
@@ -1362,8 +1382,7 @@ function isRepeatedGlyphText(cue: AnnotatedSubtitleCue): boolean {
 
 function isClippedRepeatedGlyphFragment(cue: AnnotatedSubtitleCue): boolean {
   return (
-    isRepeatedGlyphText(cue) &&
-    (hasStaticOverride(cue, 'clip') || hasStaticOverride(cue, 'iclip'))
+    isRepeatedGlyphText(cue) && (hasStaticOverride(cue, 'clip') || hasStaticOverride(cue, 'iclip'))
   );
 }
 
@@ -2021,6 +2040,9 @@ function recoverCanonicalAssEvents({
     const animationEndTime = latestEndTime(generatedEvents, candidate.endTime);
     const startTime = kind === 'comment' ? candidate.startTime : animationStartTime;
     const endTime = kind === 'comment' ? candidate.endTime : animationEndTime;
+    const assFurigana = [
+      ...new Set([candidate, ...generatedEvents].flatMap((cue) => cue.assFurigana ?? [])),
+    ];
     const recoveredCue: AnnotatedSubtitleCue = {
       ...candidate,
       startTime,
@@ -2028,6 +2050,7 @@ function recoverCanonicalAssEvents({
       animationStartTime,
       animationEndTime,
       source: 'canonical-ass',
+      ...(assFurigana.length === 0 ? {} : { assFurigana }),
     };
     recovered.push(recoveredCue);
     recoveredByOwner.set(candidate, recoveredCue);
@@ -2055,6 +2078,111 @@ function recoverCanonicalAssEvents({
   );
 }
 
+function bandFromNumpadAlignment(alignment: number): AssVerticalBand | null {
+  if (alignment >= 7 && alignment <= 9) return 'top';
+  if (alignment >= 4 && alignment <= 6) return 'middle';
+  if (alignment >= 1 && alignment <= 3) return 'bottom';
+  return null;
+}
+
+// SSA v4 alignment reuses the legacy `\a` codes: 1-3 bottom, +4 top, +8 middle.
+function bandFromLegacyAlignment(alignment: number): AssVerticalBand | null {
+  if (alignment >= 9 && alignment <= 11) return 'middle';
+  if (alignment >= 5 && alignment <= 7) return 'top';
+  if (alignment >= 1 && alignment <= 3) return 'bottom';
+  return null;
+}
+
+interface AssPlacementContext {
+  playResY: number | null;
+  /** Lowercased style name -> vertical band from the style's Alignment column. */
+  styleBands: Map<string, AssVerticalBand>;
+}
+
+const EMPTY_PLACEMENT_CONTEXT: AssPlacementContext = { playResY: null, styleBands: new Map() };
+
+function parseAssPlacementContext(content: string): AssPlacementContext {
+  const styleBands = new Map<string, AssVerticalBand>();
+  let playResY: number | null = null;
+  let section: 'info' | 'v4plus' | 'v4' | null = null;
+  let alignmentIndex = -1;
+  let nameIndex = -1;
+
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      const sectionName = trimmed.toLowerCase();
+      section =
+        sectionName === '[script info]'
+          ? 'info'
+          : sectionName === '[v4+ styles]'
+            ? 'v4plus'
+            : sectionName === '[v4 styles]'
+              ? 'v4'
+              : null;
+      alignmentIndex = -1;
+      nameIndex = -1;
+      continue;
+    }
+    if (section === 'info') {
+      const resMatch = trimmed.match(/^playresy\s*:\s*(\d+(?:\.\d+)?)\s*$/i);
+      if (resMatch) playResY = Number(resMatch[1]);
+      continue;
+    }
+    if (section !== 'v4plus' && section !== 'v4') continue;
+    const separator = trimmed.indexOf(':');
+    if (separator < 0) continue;
+    const key = trimmed.slice(0, separator).trim().toLowerCase();
+    const fields = trimmed.slice(separator + 1).split(',');
+    if (key === 'format') {
+      const names = fields.map((field) => field.trim().toLowerCase());
+      alignmentIndex = names.indexOf('alignment');
+      nameIndex = names.indexOf('name');
+      continue;
+    }
+    if (key !== 'style' || alignmentIndex < 0 || nameIndex < 0) continue;
+    const styleName = fields[nameIndex]?.trim().toLowerCase();
+    const alignment = Number(fields[alignmentIndex]?.trim());
+    if (!styleName || !Number.isFinite(alignment)) continue;
+    const band =
+      section === 'v4plus'
+        ? bandFromNumpadAlignment(alignment)
+        : bandFromLegacyAlignment(alignment);
+    if (band) styleBands.set(styleName, band);
+  }
+
+  return { playResY, styleBands };
+}
+
+/**
+ * Where on screen mpv will draw this event: an explicit `\pos`/`\move` coordinate when
+ * the script declares its coordinate space, else an `\an`/`\a` override, else the
+ * style's Alignment. Constant for the life of the event, which is what lets simultaneous
+ * lines keep a stable stacking order in the overlay.
+ */
+function resolveVerticalBand(
+  overrides: readonly AssOverrideCommand[],
+  y: number | null,
+  style: string,
+  context: AssPlacementContext,
+): AssVerticalBand | undefined {
+  if (y !== null && context.playResY && context.playResY > 0) {
+    const ratio = y / context.playResY;
+    return ratio < 1 / 3 ? 'top' : ratio < 2 / 3 ? 'middle' : 'bottom';
+  }
+  for (const command of overrides) {
+    if (command.animated) continue;
+    const name = command.name.toLowerCase();
+    if (name !== 'an' && name !== 'a') continue;
+    const band =
+      name === 'an'
+        ? bandFromNumpadAlignment(Number(command.args))
+        : bandFromLegacyAlignment(Number(command.args));
+    if (band) return band;
+  }
+  return context.styleBands.get(style.trim().toLowerCase());
+}
+
 function parseAssCoordinate(value: string | undefined): number | null {
   if (!value?.trim()) return null;
   const coordinate = Number(value.trim());
@@ -2064,29 +2192,336 @@ function parseAssCoordinate(value: string | undefined): number | null {
 function buildAssCueLayout(
   overrides: readonly AssOverrideCommand[],
   sourceOrder: number,
+  style: string,
+  placement: AssPlacementContext,
 ): AssCueLayout {
+  let x: number | null = null;
   let y: number | null = null;
   for (const command of overrides) {
     if (command.animated) continue;
     const name = command.name.toLowerCase();
     const args = command.args.split(',');
     if (name === 'pos') {
+      x = parseAssCoordinate(args[0]) ?? x;
       y = parseAssCoordinate(args[1]) ?? y;
       continue;
     }
     if (name !== 'move') continue;
+    const startX = parseAssCoordinate(args[0]);
     const startY = parseAssCoordinate(args[1]);
+    const endX = parseAssCoordinate(args[2]);
     const endY = parseAssCoordinate(args[3]);
+    if (startX !== null && endX !== null) {
+      x = (startX + endX) / 2;
+    }
     if (startY !== null && endY !== null) {
       y = (startY + endY) / 2;
     }
   }
-  return y === null
+  const verticalBand = resolveVerticalBand(overrides, y, style, placement);
+  const base: AssCueLayout =
+    y === null
       ? { kind: 'source-order', sourceOrder }
-    : { kind: 'positioned', sourceOrder, y };
+      : { kind: 'positioned', sourceOrder, ...(x === null ? {} : { x }), y };
+  return verticalBand ? { ...base, verticalBand } : base;
 }
 
-function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
+const ASS_FURIGANA_TEXT_PATTERN = /^[\p{Script=Hiragana}\p{Script=Katakana}ー・ \t\u3000]+$/u;
+const ASS_KANJI_PATTERN = /\p{Script=Han}/u;
+const MAX_ASS_FURIGANA_SCALE_PERCENT = 60;
+// The pixel geometry below is authored in the 540-line coordinate space Caption2Ass-style
+// broadcast CC converters emit, and is multiplied by PlayResY/540 so the same on-screen
+// window applies to scripts declaring other resolutions. Without a declaration the tuned
+// space is assumed.
+const ASS_FURIGANA_REFERENCE_PLAY_RES_Y = 540;
+const MIN_ASS_FURIGANA_BASE_GAP = 40;
+const MAX_ASS_FURIGANA_BASE_GAP = 68;
+const MIN_ASS_FURIGANA_HORIZONTAL_TOLERANCE = 80;
+const ASS_BASE_CHARACTER_WIDTH_ESTIMATE = 40;
+
+function assFuriganaGeometryScale(playResY: number | null): number {
+  return playResY && playResY > 0 ? playResY / ASS_FURIGANA_REFERENCE_PLAY_RES_Y : 1;
+}
+
+function staticAssScalePercent(cue: AnnotatedSubtitleCue, axis: 'fscx' | 'fscy'): number | null {
+  let scale: number | null = null;
+  for (const command of cue.overrides) {
+    if (command.animated || command.name.toLowerCase() !== axis) continue;
+    const value = Number(command.args.trim());
+    if (Number.isFinite(value) && value > 0) {
+      scale = value;
+    }
+  }
+  return scale;
+}
+
+function isAssFuriganaCandidate(cue: AnnotatedSubtitleCue): boolean {
+  const scaleX = staticAssScalePercent(cue, 'fscx');
+  const scaleY = staticAssScalePercent(cue, 'fscy');
+  return (
+    cue.assLayout?.kind === 'positioned' &&
+    ASS_FURIGANA_TEXT_PATTERN.test(cue.text) &&
+    scaleX !== null &&
+    scaleX <= MAX_ASS_FURIGANA_SCALE_PERCENT &&
+    scaleY !== null &&
+    scaleY <= MAX_ASS_FURIGANA_SCALE_PERCENT
+  );
+}
+
+function findAssFuriganaBase(
+  furigana: AnnotatedSubtitleCue,
+  cues: readonly AnnotatedSubtitleCue[],
+  geometryScale: number,
+): AnnotatedSubtitleCue | null {
+  if (furigana.assLayout?.kind !== 'positioned' || furigana.assLayout.x === undefined) {
+    return null;
+  }
+
+  let nearest: { cue: AnnotatedSubtitleCue; gap: number } | null = null;
+  for (const cue of cues) {
+    if (
+      cue === furigana ||
+      cue.startTime !== furigana.startTime ||
+      cue.endTime !== furigana.endTime ||
+      cue.style !== furigana.style ||
+      cue.layer !== furigana.layer ||
+      cue.name !== furigana.name ||
+      cue.assLayout?.kind !== 'positioned' ||
+      !ASS_KANJI_PATTERN.test(cue.text)
+    ) {
+      continue;
+    }
+    const scaleY = staticAssScalePercent(cue, 'fscy');
+    if (scaleY !== null && scaleY <= MAX_ASS_FURIGANA_SCALE_PERCENT) continue;
+
+    const gap = cue.assLayout.y - furigana.assLayout.y;
+    if (
+      gap < MIN_ASS_FURIGANA_BASE_GAP * geometryScale ||
+      gap > MAX_ASS_FURIGANA_BASE_GAP * geometryScale
+    ) {
+      continue;
+    }
+    if (cue.assLayout.x === undefined) continue;
+    const baseCharacterCount = [...cue.text.replace(/[ \t\u3000]/g, '')].length;
+    const horizontalTolerance =
+      Math.max(
+        MIN_ASS_FURIGANA_HORIZONTAL_TOLERANCE,
+        baseCharacterCount * ASS_BASE_CHARACTER_WIDTH_ESTIMATE,
+      ) * geometryScale;
+    if (Math.abs(cue.assLayout.x - furigana.assLayout.x) > horizontalTolerance) continue;
+    if (!nearest || gap < nearest.gap || (gap === nearest.gap && cue.order < nearest.cue.order)) {
+      nearest = { cue, gap };
+    }
+  }
+  return nearest?.cue ?? null;
+}
+
+function removeAssFuriganaFromCueList(
+  cues: AnnotatedSubtitleCue[],
+  geometryScale: number,
+): AnnotatedSubtitleCue[] {
+  const removed = new Set<AnnotatedSubtitleCue>();
+  for (const cue of cues) {
+    if (!isAssFuriganaCandidate(cue)) continue;
+    const base = findAssFuriganaBase(cue, cues, geometryScale);
+    if (!base) continue;
+    base.assFurigana = [...new Set([...(base.assFurigana ?? []), cue.text])];
+    removed.add(cue);
+  }
+  return removed.size === 0 ? cues : cues.filter((cue) => !removed.has(cue));
+}
+
+function removeAssFuriganaEvents(
+  events: ParsedAssEvents,
+  playResY: number | null,
+): ParsedAssEvents {
+  const geometryScale = assFuriganaGeometryScale(playResY);
+  return {
+    dialogue: removeAssFuriganaFromCueList(events.dialogue, geometryScale),
+    comments: removeAssFuriganaFromCueList(events.comments, geometryScale),
+  };
+}
+
+// Broadcast-caption converters give every visual row of one utterance its own positioned
+// event, so a sentence that wraps arrives as two simultaneous cues with the same timing,
+// style, and vertical band. Captions punctuate every finished utterance, and each turn
+// opens with a speaker label or a ≪…≫ / ⸨…⸩ span, which is what tells a wrapped sentence
+// apart from two speakers sharing the screen.
+const CAPTION_SPEAKER_LABEL_ONLY_PATTERN = /^（[^（）]*）$/u;
+const CAPTION_SPEAKER_LABEL_PATTERN = /^（/u;
+const CAPTION_TURN_OPENER_PATTERN = /^[≪⸨（]/u;
+const CAPTION_TERMINAL_PATTERN = /[。？！?!…‥～〜➡⁉⁈≫⸩）」』]$/u;
+const CAPTION_SPANS: ReadonlyArray<readonly [open: string, close: string]> = [
+  ['≪', '≫'],
+  ['⸨', '⸩'],
+];
+// Rows of one utterance sit one text row apart (about 60 units in the 540-line space the
+// furigana geometry is tuned for), or two when a ruby row lies between them. Rows at the
+// same height sit side by side, and rows further apart are separate placements.
+const MAX_CAPTION_ROW_GAP = 120;
+// Only a broadcast-caption script gets rows joined. Typesetters position rows for signs,
+// chat bubbles, and lyric stacks too, and there the continuation rule below has no
+// convention to read: sign text rarely carries sentence punctuation, so unrelated rows
+// would run together. A caption script announces itself by labelling speakers （名） and
+// bracketing off-screen speech in ≪…≫ / ⸨…⸩; typeset scripts use those in a handful of
+// lines at most. Measured over local tracks, caption scripts sit near 25% and every typeset
+// script below 1%, so the threshold has room on both sides. It is deliberately strict: a
+// caption script wrongly held back just keeps one sentence on two rows, while a typeset
+// script wrongly let through concatenates unrelated signs.
+const MIN_CAPTION_EVIDENCE_EVENTS = 2;
+const MIN_CAPTION_EVIDENCE_RATIO = 0.05;
+const CAPTION_EVIDENCE_PATTERN = /^（[^（）]{1,14}）|[≪⸨]/u;
+// Rows that carry no Japanese are not the broadcast captions this pass targets.
+const JAPANESE_SCRIPT_PATTERN = /[\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}]/u;
+
+function hasBroadcastCaptionConventions(cues: readonly AnnotatedSubtitleCue[]): boolean {
+  let evidence = 0;
+  let published = 0;
+  for (const cue of cues) {
+    if (!cue.text.trim()) continue;
+    published += 1;
+    if (CAPTION_EVIDENCE_PATTERN.test(cue.text)) evidence += 1;
+  }
+  return (
+    evidence >= MIN_CAPTION_EVIDENCE_EVENTS && evidence >= published * MIN_CAPTION_EVIDENCE_RATIO
+  );
+}
+
+function captionSpanDepth(text: string, [open, close]: readonly [string, string]): number {
+  let depth = 0;
+  for (const char of text) {
+    if (char === open) depth += 1;
+    else if (char === close) depth -= 1;
+  }
+  return depth;
+}
+
+/**
+ * Whether `lower` continues the utterance `upper` started, both being simultaneous
+ * caption rows. A bare speaker label labels the row beneath it. Otherwise the upper row
+ * must not have finished: it ends without terminal punctuation, or a ≪…≫ / ⸨…⸩ span it
+ * opened is still open (closing 」 inside such a span is not an ending). A lower row that
+ * opens its own turn is always a different line.
+ */
+function isCaptionRowContinuation(upper: string, lower: string): boolean {
+  if (CAPTION_SPEAKER_LABEL_ONLY_PATTERN.test(upper)) {
+    return !CAPTION_SPEAKER_LABEL_PATTERN.test(lower);
+  }
+  if (CAPTION_TURN_OPENER_PATTERN.test(lower)) {
+    return false;
+  }
+  const spanContinues = CAPTION_SPANS.some(
+    (span) => captionSpanDepth(upper, span) > 0 || captionSpanDepth(lower, span) < 0,
+  );
+  return spanContinues || !CAPTION_TERMINAL_PATTERN.test(upper);
+}
+
+// A half-height row is ruby or a whispered aside, not a row of the utterance.
+function isCaptionRowCandidate(cue: AnnotatedSubtitleCue): boolean {
+  const scaleY = staticAssScalePercent(cue, 'fscy');
+  return (
+    cue.source === undefined &&
+    cue.assLayout?.kind === 'positioned' &&
+    cue.effect.trim() === '' &&
+    !cue.text.includes('\n') &&
+    !hasAssTemporalOverride(cue.overrides) &&
+    (scaleY === null || scaleY > MAX_ASS_FURIGANA_SCALE_PERCENT) &&
+    JAPANESE_SCRIPT_PATTERN.test(cue.text)
+  );
+}
+
+function captionRowGroupKey(cue: AnnotatedSubtitleCue): string {
+  return [
+    cue.startTime,
+    cue.endTime,
+    cue.style,
+    cue.layer,
+    cue.name,
+    cue.assLayout?.verticalBand ?? '',
+  ].join('\0');
+}
+
+function mergeCaptionRows(rows: readonly AnnotatedSubtitleCue[]): AnnotatedSubtitleCue {
+  const [first] = rows;
+  if (!first) throw new Error('mergeCaptionRows requires at least one row');
+  const overrides = rows.flatMap((row) => row.overrides);
+  const assFurigana = [...new Set(rows.flatMap((row) => row.assFurigana ?? []))];
+  return {
+    ...first,
+    text: rows.map((row) => row.text).join('\n'),
+    rawText: rows.map((row) => row.rawText).join('\\N'),
+    overrides,
+    overrideSignature: assOverrideSignature(overrides),
+    ...(assFurigana.length === 0 ? {} : { assFurigana }),
+  };
+}
+
+/**
+ * Join simultaneous caption rows that spell one utterance into a single cue, so the
+ * overlay can wrap or flatten it like an authored `\N` line and the sidebar and mining
+ * paths see the whole sentence. Rows stack top to bottom; each row joins the cue above it
+ * only while `isCaptionRowContinuation` holds, so a second speaker starts a new cue. The
+ * whole pass is skipped unless the script reads as broadcast captions.
+ */
+function mergeAssCaptionRows(
+  cues: AnnotatedSubtitleCue[],
+  playResY: number | null,
+): AnnotatedSubtitleCue[] {
+  if (!hasBroadcastCaptionConventions(cues)) return cues;
+
+  const groups = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const cue of cues) {
+    if (!isCaptionRowCandidate(cue)) continue;
+    const key = captionRowGroupKey(cue);
+    const group = groups.get(key);
+    if (group) group.push(cue);
+    else groups.set(key, [cue]);
+  }
+
+  const maxRowGap = MAX_CAPTION_ROW_GAP * assFuriganaGeometryScale(playResY);
+  const rowY = (cue: AnnotatedSubtitleCue): number =>
+    cue.assLayout?.kind === 'positioned' ? cue.assLayout.y : 0;
+  const replacements = new Map<AnnotatedSubtitleCue, AnnotatedSubtitleCue>();
+  const removed = new Set<AnnotatedSubtitleCue>();
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const rows = [...group].sort((a, b) => rowY(a) - rowY(b) || a.order - b.order);
+    let run: AnnotatedSubtitleCue[] = [];
+    const flush = (): void => {
+      if (run.length < 2) return;
+      const anchor = run.reduce((lowest, row) => (row.order < lowest.order ? row : lowest));
+      replacements.set(anchor, mergeCaptionRows(run));
+      for (const row of run) {
+        if (row !== anchor) removed.add(row);
+      }
+    };
+    for (const row of rows) {
+      const previous = run.at(-1);
+      const gap = previous ? rowY(row) - rowY(previous) : 0;
+      if (
+        previous &&
+        gap > 0 &&
+        gap <= maxRowGap &&
+        previous.text !== row.text &&
+        isCaptionRowContinuation(previous.text, row.text)
+      ) {
+        run.push(row);
+        continue;
+      }
+      flush();
+      run = [row];
+    }
+    flush();
+  }
+
+  if (replacements.size === 0) return cues;
+  return cues.flatMap((cue) => {
+    if (removed.has(cue)) return [];
+    return [replacements.get(cue) ?? cue];
+  });
+}
+
+function parseAnnotatedAssEvents(content: string, placement: AssPlacementContext): ParsedAssEvents {
   const cues: AnnotatedSubtitleCue[] = [];
   const comments: AnnotatedSubtitleCue[] = [];
   const lines = content.split(/\r?\n/);
@@ -2185,12 +2620,13 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
     const effect = readField(fields, fieldIndex.effect);
     const layer = Number(readField(fields, fieldIndex.layer));
     const overrides = collectAssOverrideCommands(rawText);
+    const style = readField(fields, fieldIndex.style);
     const cue: AnnotatedSubtitleCue = {
       startTime,
       endTime,
       text,
       rawText,
-      style: readField(fields, fieldIndex.style),
+      style,
       layer: Number.isFinite(layer) ? layer : 0,
       name: readField(fields, fieldIndex.name),
       effect,
@@ -2198,7 +2634,7 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
       overrides,
       overrideSignature: assOverrideSignature(overrides),
       order: eventOrder,
-      assLayout: buildAssCueLayout(overrides, eventOrder),
+      assLayout: buildAssCueLayout(overrides, eventOrder, style, placement),
     };
     eventOrder += 1;
     if (eventPrefix === ASS_COMMENT_PREFIX) {
@@ -2212,8 +2648,17 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
 }
 
 function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
-  const events = removeAssFontTextureEvents(parseAnnotatedAssEvents(content));
-  return recoverFragmentOnlyAssLines(recoverCanonicalAssEvents(events));
+  const placement = content.includes('[')
+    ? parseAssPlacementContext(content)
+    : EMPTY_PLACEMENT_CONTEXT;
+  const events = removeAssFuriganaEvents(
+    removeAssFontTextureEvents(parseAnnotatedAssEvents(content, placement)),
+    placement.playResY,
+  );
+  return mergeAssCaptionRows(
+    recoverFragmentOnlyAssLines(recoverCanonicalAssEvents(events)),
+    placement.playResY,
+  );
 }
 
 export function parseAssCues(content: string): SubtitleCue[] {

src/core/services/subtitle-processing-controller.ts

@@ -134,7 +134,7 @@ export function createSubtitleProcessingController(
         try {
           const cachedTokenized = getCachedTokenization(text);
           if (cachedTokenized) {
-            output = cachedTokenized;
+            output = { ...cachedTokenized, text };
           } else {
             // Cache miss: show the plain line on time; the tokenized payload
             // upgrades it once ready. Skipped on refreshes of an already
@@ -266,7 +266,7 @@ export function createSubtitleProcessingController(
       lastEmittedText = text;
       lastEmittedGeneration = cacheGeneration;
       lastPlainEmittedText = null;
-      return cached;
+      return { ...cached, text };
     },
     hasCachedSubtitle: (text: string) => {
       const cacheKey = normalizeSubtitleCacheKey(text);

src/core/services/subtitle-timing-offset.test.ts

@@ -1,73 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import { estimateSubtitleTimingOffset } from './subtitle-timing-offset';
-
-function cue(startTime: number) {
-  return { startTime, endTime: startTime + 1, text: `cue ${startTime}` };
-}
-
-test('estimate subtitle timing offset detects a late Jellyfin subtitle timeline', () => {
-  const primary = [
-    34.935, 36.937, 41.441, 45.279, 48.115, 52.286, 54.955, 59.793, 63.63, 67.634, 76.643, 80.814,
-    87.988, 90.991, 94.094, 97.097,
-  ].map(cue);
-  const reference = [
-    3.46, 9.48, 13.61, 21.4, 28.16, 32.06, 35.93, 45.1, 56.57, 59.68, 62.44, 65.56,
-  ].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.ok(result);
-  assert.ok(result.offsetSeconds > -32);
-  assert.ok(result.offsetSeconds < -31);
-  assert.ok(result.matchCount >= 8);
-  assert.ok(result.meanErrorSeconds <= 0.75);
-});
-
-test('estimate subtitle timing offset favors the early episode timeline', () => {
-  const primary = [
-    34.935, 36.937, 41.441, 45.279, 48.115, 52.286, 54.955, 59.793, 63.63, 67.634, 76.643, 80.814,
-    87.988, 90.991, 94.094, 97.097, 207.974, 212.579, 222.422, 228.095, 232.432, 238.271, 244.778,
-    246.78, 249.282, 251.284, 253.62, 256.289, 259.626, 262.129, 264.965, 267.634, 270.303, 274.407,
-    277.077, 280.08, 284.084, 288.421, 291.925, 295.262, 298.431, 301.101, 306.773, 308.942,
-    312.946, 316.283, 321.621, 326.626, 331.131, 336.069, 340.407, 343.41, 351.418, 355.422,
-    357.924, 362.429, 365.432, 370.604, 373.273, 377.944, 381.114, 384.618, 387.621, 390.957,
-    396.73, 399.232, 401.568, 403.57, 405.572, 407.574, 409.743, 412.746, 418.752, 425.258, 427.26,
-    435.602, 440.44, 442.942, 445.445, 449.783,
-  ].map(cue);
-  const reference = [
-    3.46, 9.48, 13.61, 21.4, 28.16, 32.06, 35.93, 45.1, 56.57, 59.68, 62.44, 65.56, 165.77, 172.81,
-    176.1, 177.27, 186.33, 191.33, 195.78, 201.83, 212.9, 214.09, 216.73, 220.2, 222.91, 225.65,
-    232.8, 237.92, 242.23, 243.28, 247.53, 252.04, 255.9, 258.86, 262.09, 264.43, 276.07, 278.01,
-    280.98, 285.67, 289.89, 294.57, 300, 303.56, 308.58, 316.37, 318.38, 319.86, 325.38, 328.82,
-    333.68, 335.26, 336.82, 340.11, 342.11, 344.36, 346.39, 347.53, 350.92, 370.18, 372.88, 376.43,
-    388.2, 390.57, 403.96, 406.36, 409.72, 413.78, 425.55, 432.76, 435.03, 438.06, 443.73, 448.31,
-    450.57, 457.62, 463.41, 465.85, 473.79, 480.59,
-  ].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.ok(result);
-  assert.ok(result.offsetSeconds > -32);
-  assert.ok(result.offsetSeconds < -31);
-});
-
-test('estimate subtitle timing offset ignores subtitle timelines that are already aligned', () => {
-  const starts = [1, 5, 9, 14, 20, 25, 31, 38];
-
-  const result = estimateSubtitleTimingOffset(
-    starts.map(cue),
-    starts.map((start) => cue(start + 0.04)),
-  );
-
-  assert.equal(result, null);
-});
-
-test('estimate subtitle timing offset rejects weak timeline matches', () => {
-  const primary = [10, 20, 30, 40, 50, 60, 70, 80].map(cue);
-  const reference = [1, 2, 3, 4, 5, 6, 7, 8].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.equal(result, null);
-});

src/core/services/subtitle-timing-offset.ts

@@ -1,153 +0,0 @@
-import type { SubtitleCue } from './subtitle-cue-parser';
-
-export type SubtitleTimingOffsetResult = {
-  offsetSeconds: number;
-  matchCount: number;
-  meanErrorSeconds: number;
-  maxErrorSeconds: number;
-};
-
-export type SubtitleTimingOffsetOptions = {
-  maxCueCount?: number;
-  maxOffsetSeconds?: number;
-  matchThresholdSeconds?: number;
-  maxMeanErrorSeconds?: number;
-  minMatchCount?: number;
-  minMatchRatio?: number;
-  minUsefulOffsetSeconds?: number;
-};
-
-type OffsetScore = SubtitleTimingOffsetResult;
-
-const DEFAULT_MAX_CUE_COUNT = 60;
-const DEFAULT_MAX_OFFSET_SECONDS = 180;
-const DEFAULT_MATCH_THRESHOLD_SECONDS = 1;
-const DEFAULT_MAX_MEAN_ERROR_SECONDS = 0.75;
-const DEFAULT_MIN_MATCH_COUNT = 8;
-const DEFAULT_MIN_MATCH_RATIO = 0.25;
-const DEFAULT_MIN_USEFUL_OFFSET_SECONDS = 0.25;
-
-function normalizeCueStarts(cues: SubtitleCue[], maxCueCount: number): number[] {
-  const starts = cues
-    .map((cue) => cue.startTime)
-    .filter((start) => Number.isFinite(start) && start >= 0)
-    .sort((a, b) => a - b);
-  const deduped: number[] = [];
-  for (const start of starts) {
-    const previous = deduped[deduped.length - 1];
-    if (previous === undefined || Math.abs(start - previous) > 0.05) {
-      deduped.push(start);
-    }
-    if (deduped.length >= maxCueCount) {
-      break;
-    }
-  }
-  return deduped;
-}
-
-function roundToMillis(value: number): number {
-  return Math.round(value * 1000) / 1000;
-}
-
-function scoreOffset(
-  primaryStarts: number[],
-  referenceStarts: number[],
-  offsetSeconds: number,
-  matchThresholdSeconds: number,
-): OffsetScore {
-  let primaryIndex = 0;
-  let referenceIndex = 0;
-  let matchCount = 0;
-  let totalErrorSeconds = 0;
-  let maxErrorSeconds = 0;
-
-  while (primaryIndex < primaryStarts.length && referenceIndex < referenceStarts.length) {
-    const shiftedPrimary = primaryStarts[primaryIndex]! + offsetSeconds;
-    const reference = referenceStarts[referenceIndex]!;
-    const errorSeconds = Math.abs(shiftedPrimary - reference);
-    if (errorSeconds <= matchThresholdSeconds) {
-      matchCount += 1;
-      totalErrorSeconds += errorSeconds;
-      maxErrorSeconds = Math.max(maxErrorSeconds, errorSeconds);
-      primaryIndex += 1;
-      referenceIndex += 1;
-      continue;
-    }
-
-    if (shiftedPrimary < reference) {
-      primaryIndex += 1;
-    } else {
-      referenceIndex += 1;
-    }
-  }
-
-  return {
-    offsetSeconds,
-    matchCount,
-    meanErrorSeconds: matchCount > 0 ? totalErrorSeconds / matchCount : Number.POSITIVE_INFINITY,
-    maxErrorSeconds,
-  };
-}
-
-function isBetterScore(next: OffsetScore, current: OffsetScore | null): boolean {
-  if (current === null) return true;
-  if (next.matchCount !== current.matchCount) return next.matchCount > current.matchCount;
-  if (next.meanErrorSeconds !== current.meanErrorSeconds) {
-    return next.meanErrorSeconds < current.meanErrorSeconds;
-  }
-  return Math.abs(next.offsetSeconds) < Math.abs(current.offsetSeconds);
-}
-
-export function estimateSubtitleTimingOffset(
-  primaryCues: SubtitleCue[],
-  referenceCues: SubtitleCue[],
-  options: SubtitleTimingOffsetOptions = {},
-): SubtitleTimingOffsetResult | null {
-  const maxCueCount = options.maxCueCount ?? DEFAULT_MAX_CUE_COUNT;
-  const maxOffsetSeconds = options.maxOffsetSeconds ?? DEFAULT_MAX_OFFSET_SECONDS;
-  const matchThresholdSeconds = options.matchThresholdSeconds ?? DEFAULT_MATCH_THRESHOLD_SECONDS;
-  const maxMeanErrorSeconds = options.maxMeanErrorSeconds ?? DEFAULT_MAX_MEAN_ERROR_SECONDS;
-  const minMatchCount = options.minMatchCount ?? DEFAULT_MIN_MATCH_COUNT;
-  const minMatchRatio = options.minMatchRatio ?? DEFAULT_MIN_MATCH_RATIO;
-  const minUsefulOffsetSeconds =
-    options.minUsefulOffsetSeconds ?? DEFAULT_MIN_USEFUL_OFFSET_SECONDS;
-
-  const primaryStarts = normalizeCueStarts(primaryCues, maxCueCount);
-  const referenceStarts = normalizeCueStarts(referenceCues, maxCueCount);
-  const comparableCueCount = Math.min(primaryStarts.length, referenceStarts.length);
-  if (comparableCueCount < minMatchCount) {
-    return null;
-  }
-
-  const candidates = new Set<number>();
-  for (const primaryStart of primaryStarts) {
-    for (const referenceStart of referenceStarts) {
-      const offsetSeconds = roundToMillis(referenceStart - primaryStart);
-      if (Math.abs(offsetSeconds) <= maxOffsetSeconds) {
-        candidates.add(offsetSeconds);
-      }
-    }
-  }
-
-  let best: OffsetScore | null = null;
-  for (const offsetSeconds of candidates) {
-    if (Math.abs(offsetSeconds) < minUsefulOffsetSeconds) {
-      continue;
-    }
-    const score = scoreOffset(primaryStarts, referenceStarts, offsetSeconds, matchThresholdSeconds);
-    if (score.matchCount < minMatchCount) {
-      continue;
-    }
-    if (score.matchCount / comparableCueCount < minMatchRatio) {
-      continue;
-    }
-    if (score.meanErrorSeconds > maxMeanErrorSeconds) {
-      continue;
-    }
-    if (isBetterScore(score, best)) {
-      best = score;
-    }
-  }
-
-  return best;
-}

src/core/services/tokenizer.test.ts

@@ -84,6 +84,17 @@ function createDeferred<T>() {
   };
 }
 
+test('tokenizeSubtitle keeps the blank line separating simultaneous cues', async () => {
+  // The tokenized payload's text drives display; folding the cue boundary would merge
+  // two speakers back onto one line the moment tokenization upgrades the plain emit.
+  const result = await tokenizeSubtitle(
+    '\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee',
+    makeDeps({ getYomitanExt: () => null }),
+  );
+
+  assert.equal(result.text, '\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee');
+});
+
 test('tokenizeSubtitle splits same-line grammar endings before applying annotations', async () => {
   const result = await tokenizeSubtitle(
     '猫です',
@@ -1682,6 +1693,12 @@ test('tokenizeSubtitle normalizes newlines before Yomitan parse request', async
   assert.equal(result.tokens, null);
 });
 
+test('tokenizeSubtitle preserves CRLF boundaries between simultaneous cues', async () => {
+  const result = await tokenizeSubtitle('a\r\n\r\nb', makeDeps());
+
+  assert.deepEqual(result, { text: 'a\n\nb', tokens: null });
+});
+
 test('tokenizeSubtitle collapses zero-width separators before Yomitan parse request', async () => {
   let parseInput = '';
   const result = await tokenizeSubtitle(

src/core/services/tokenizer.ts

@@ -887,7 +887,15 @@ export async function tokenizeSubtitle(
   text: string,
   deps: TokenizerServiceDeps,
 ): Promise<SubtitleData> {
-  const displayText = normalizePlainSubtitleText(text);
+  // Normalize per cue group: the blank line separating simultaneous cues is display
+  // structure the payload text must keep, or the tokenized upgrade re-merges lines the
+  // provisional plain emit already showed apart.
+  const displayText = text
+    .replace(/\r\n/g, '\n')
+    .split(/\n{2,}/)
+    .map((part) => normalizePlainSubtitleText(part))
+    .filter(Boolean)
+    .join('\n\n');
 
   // ASS decoding already happened upstream (cue parser for files, mpv for live text), so
   // all this drops is whitespace -- but a whitespace-only line still normalizes to empty.

src/core/services/youtube/timedtext.test.ts

@@ -39,6 +39,118 @@ test('convertYoutubeTimedTextToVtt does not swallow text after zero-length overl
   );
 });
 
+test('convertYoutubeTimedTextToVtt extends rolling captions to the next window event', () => {
+  // Real-world shape of YouTube's sentence-level auto captions: window-append
+  // filler rows (a="1", sometimes without d) mark the display timeline, while
+  // long text rows carry a placeholder d="3000" far shorter than the speech.
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext><body>',
+      '<p t="98550" d="3010" w="1" a="1">\n</p>',
+      '<p t="98560" d="3000" w="1"><s ac="0">ありがとうって言えないよね。こんなんじゃ。</s></p>',
+      '<p t="106950" w="1" a="1">\n</p>',
+      '<p t="106960" d="3799" w="1"><s ac="0">私だったら無理だよ。</s></p>',
+      '</body></timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    [
+      'WEBVTT',
+      '',
+      '00:01:38.560 --> 00:01:46.950',
+      'ありがとうって言えないよね。こんなんじゃ。',
+      '',
+      '00:01:46.960 --> 00:01:50.759',
+      '私だったら無理だよ。',
+      '',
+    ].join('\n'),
+  );
+});
+
+test('convertYoutubeTimedTextToVtt pages oversized two-row rolling captions', () => {
+  const text =
+    'あの西に結構こう山田がスーパーアプローチしてるんだけど西気づかないからちょっとこっちも気づかない感じでこう接してあげようかなて思ってんだけどあの唇巻き込んじゃうしあの思ってることも全部縁に出ちゃって自分であちゃったって言っちゃうタイプなんで結構なんかこうドライなんだけどそこがおもろいよねみたいな';
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext format="3">',
+      '<head>',
+      '<ws id="1" mh="2" ju="0" sd="3"/>',
+      '<wp id="1" ap="6" ah="20" av="100" rc="2" cc="40"/>',
+      '</head>',
+      '<body>',
+      '<w t="0" id="1" wp="1" ws="1"/>',
+      `<p t="60440" d="3000" w="1"><s ac="0">${text}</s></p>`,
+      '<p t="72695" w="1" a="1">\n</p>',
+      '</body>',
+      '</timedtext>',
+    ].join('\n'),
+  );
+
+  const cues = result
+    .trim()
+    .split(/\n\n/)
+    .filter((block) => block.includes('-->'));
+  const cueText = cues.map((cue) => cue.split('\n').slice(1).join('\n'));
+
+  assert.equal(cues.length, 2);
+  assert.deepEqual(
+    cues.map((cue) => cue.split('\n')[0]),
+    ['00:01:00.440 --> 00:01:07.064', '00:01:07.064 --> 00:01:12.695'],
+  );
+  assert.ok(cueText.every((page) => [...page].length <= 80));
+  assert.equal(cueText.join(''), text);
+});
+
+test('convertYoutubeTimedTextToVtt leaves pop-on captions intact', () => {
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext format="3">',
+      '<head>',
+      '<ws id="1" mh="0"/>',
+      '<wp id="1" rc="2" cc="4"/>',
+      '</head>',
+      '<body>',
+      '<w t="0" id="1" wp="1" ws="1"/>',
+      '<p t="1000" d="3000" w="1">abcdefghijklmnopqrst</p>',
+      '</body>',
+      '</timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    ['WEBVTT', '', '00:00:01.000 --> 00:00:04.000', 'abcdefghijklmnopqrst', ''].join('\n'),
+  );
+});
+
+test('convertYoutubeTimedTextToVtt keeps explicit 3000ms sound-cue durations in rolling documents', () => {
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext><body>',
+      '<p t="20305" d="3000" w="1">[音楽]</p>',
+      '<p t="26269" w="1" a="1">\n</p>',
+      '<p t="26279" d="3000" w="1"><s ac="0">じゃあ、君からお願いします。</s></p>',
+      '</body></timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    [
+      'WEBVTT',
+      '',
+      '00:00:20.305 --> 00:00:23.305',
+      '[音楽]',
+      '',
+      '00:00:26.279 --> 00:00:29.279',
+      'じゃあ、君からお願いします。',
+      '',
+    ].join('\n'),
+  );
+});
+
 test('normalizeYoutubeAutoVtt strips cumulative rolling-caption prefixes', () => {
   const result = normalizeYoutubeAutoVtt(
     [

src/core/services/youtube/timedtext.ts

@@ -2,9 +2,31 @@ interface YoutubeTimedTextRow {
   startMs: number;
   durationMs: number;
   text: string;
+  isGenerated: boolean;
+  rollingWindow: YoutubeRollingWindow | null;
+}
+
+interface YoutubeRollingWindow {
+  rowCount: number;
+  columnCount: number;
+}
+
+interface YoutubeTimedTextWindowDefinitions {
+  rollingStyleIds: Set<string>;
+  positions: Map<string, YoutubeRollingWindow>;
+  windows: Map<string, YoutubeRollingWindow>;
+}
+
+interface YoutubeTimedTextDocument {
+  rows: YoutubeTimedTextRow[];
+  // Start times of every <p> event, including empty window-append fillers.
+  // Rolling speech rows with a 3000ms placeholder display until the next event.
+  eventStartsMs: number[];
+  hasRollingWindowEvents: boolean;
 }
 
 const YOUTUBE_TIMEDTEXT_EXTENSIONS = new Set(['srv1', 'srv2', 'srv3', 'ytsrv3']);
+const YOUTUBE_ROLLING_PLACEHOLDER_DURATION_MS = 3_000;
 
 function decodeNumericEntity(match: string, codePoint: number): string {
   if (
@@ -39,27 +61,129 @@ function parseAttributeMap(raw: string): Map<string, string> {
   return attrs;
 }
 
-function extractYoutubeTimedTextRows(xml: string): YoutubeTimedTextRow[] {
+function parsePositiveInteger(value: string | undefined): number | null {
+  if (value === undefined) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function extractYoutubeTimedTextWindowDefinitions(xml: string): YoutubeTimedTextWindowDefinitions {
+  const rollingStyleIds = new Set<string>();
+  for (const match of xml.matchAll(/<ws\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    if (id !== undefined && attrs.get('mh') === '2') {
+      rollingStyleIds.add(id);
+    }
+  }
+
+  const positions = new Map<string, YoutubeRollingWindow>();
+  for (const match of xml.matchAll(/<wp\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    const rowCount = parsePositiveInteger(attrs.get('rc'));
+    const columnCount = parsePositiveInteger(attrs.get('cc'));
+    if (id !== undefined && rowCount !== null && columnCount !== null) {
+      positions.set(id, { rowCount, columnCount });
+    }
+  }
+
+  const windows = new Map<string, YoutubeRollingWindow>();
+  for (const match of xml.matchAll(/<w\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    const styleId = attrs.get('ws');
+    const positionId = attrs.get('wp');
+    const position = positionId === undefined ? undefined : positions.get(positionId);
+    if (
+      id !== undefined &&
+      styleId !== undefined &&
+      rollingStyleIds.has(styleId) &&
+      position !== undefined
+    ) {
+      windows.set(id, position);
+    }
+  }
+
+  return { rollingStyleIds, positions, windows };
+}
+
+function resolveRollingWindow(
+  attrs: Map<string, string>,
+  definitions: YoutubeTimedTextWindowDefinitions,
+): YoutubeRollingWindow | null {
+  const windowId = attrs.get('w');
+  if (windowId !== undefined) {
+    return definitions.windows.get(windowId) ?? null;
+  }
+
+  const styleId = attrs.get('ws');
+  const positionId = attrs.get('wp');
+  if (
+    styleId === undefined ||
+    positionId === undefined ||
+    !definitions.rollingStyleIds.has(styleId)
+  ) {
+    return null;
+  }
+  return definitions.positions.get(positionId) ?? null;
+}
+
+function extractYoutubeTimedTextDocument(xml: string): YoutubeTimedTextDocument {
   const rows: YoutubeTimedTextRow[] = [];
+  const eventStartsMs: number[] = [];
+  let hasRollingWindowEvents = false;
+  const windowDefinitions = extractYoutubeTimedTextWindowDefinitions(xml);
 
   for (const match of xml.matchAll(/<p\b([^>]*)>([\s\S]*?)<\/p>/g)) {
     const attrs = parseAttributeMap(match[1] ?? '');
     const startMs = Number(attrs.get('t'));
+    if (!Number.isFinite(startMs)) {
+      continue;
+    }
+    eventStartsMs.push(startMs);
+    if (attrs.get('a') === '1') {
+      hasRollingWindowEvents = true;
+    }
+
     const durationMs = Number(attrs.get('d'));
-    if (!Number.isFinite(startMs) || !Number.isFinite(durationMs)) {
+    if (!Number.isFinite(durationMs)) {
       continue;
     }
 
-    const inner = (match[2] ?? '').replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, '');
+    const rawInner = match[2] ?? '';
+    const inner = rawInner.replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, '');
     const text = decodeHtmlEntities(inner).trim();
     if (!text) {
       continue;
     }
 
-    rows.push({ startMs, durationMs, text });
+    rows.push({
+      startMs,
+      durationMs,
+      text,
+      isGenerated: /<s\b/.test(rawInner),
+      rollingWindow: resolveRollingWindow(attrs, windowDefinitions),
+    });
   }
 
-  return rows;
+  eventStartsMs.sort((a, b) => a - b);
+  return { rows, eventStartsMs, hasRollingWindowEvents };
+}
+
+function findNextEventStartMs(eventStartsMs: number[], afterMs: number): number | undefined {
+  for (const startMs of eventStartsMs) {
+    if (startMs > afterMs) {
+      return startMs;
+    }
+  }
+  return undefined;
+}
+
+function isGeneratedRollingCue(row: YoutubeTimedTextRow, hasRollingWindowEvents: boolean): boolean {
+  return row.isGenerated && (row.rollingWindow !== null || hasRollingWindowEvents);
 }
 
 function formatVttTimestamp(ms: number): string {
@@ -71,6 +195,79 @@ function formatVttTimestamp(ms: number): string {
   return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}.${String(millis).padStart(3, '0')}`;
 }
 
+const ROLLING_PAGE_BREAK_PATTERN = /[\s、。！？!?]/u;
+
+// VTT cannot carry SRV3's row and column limits. Page only roll-up windows so
+// the overlay keeps their bounded presentation without changing authored cues.
+function splitRollingCaptionIntoPages(text: string, rollingWindow: YoutubeRollingWindow): string[] {
+  const pageCapacity = rollingWindow.rowCount * rollingWindow.columnCount;
+  const characters = [...text];
+  if (
+    !Number.isSafeInteger(pageCapacity) ||
+    pageCapacity <= 0 ||
+    characters.length <= pageCapacity
+  ) {
+    return [text];
+  }
+
+  const pages: string[] = [];
+  let pageStart = 0;
+  while (pageStart < characters.length) {
+    let pageEnd = Math.min(pageStart + pageCapacity, characters.length);
+    if (pageEnd < characters.length) {
+      const earliestNaturalBreak = pageStart + Math.ceil(pageCapacity * 0.6);
+      for (let index = pageEnd - 1; index >= earliestNaturalBreak; index -= 1) {
+        if (ROLLING_PAGE_BREAK_PATTERN.test(characters[index]!)) {
+          pageEnd = index + 1;
+          break;
+        }
+      }
+    }
+    pages.push(characters.slice(pageStart, pageEnd).join(''));
+    pageStart = pageEnd;
+  }
+  return pages;
+}
+
+interface TimedCaptionPage {
+  startMs: number;
+  endMs: number;
+  text: string;
+}
+
+function timeCaptionPages(input: {
+  text: string;
+  pages: string[];
+  startMs: number;
+  endMs: number;
+}): TimedCaptionPage[] {
+  const durationMs = input.endMs - input.startMs;
+  if (input.pages.length === 1 || durationMs < input.pages.length) {
+    return [{ startMs: input.startMs, endMs: input.endMs, text: input.text }];
+  }
+
+  const totalCharacters = [...input.text].length;
+  const timedPages: TimedCaptionPage[] = [];
+  let consumedCharacters = 0;
+  let pageStartMs = input.startMs;
+  // Automatic captions often omit span offsets, so distribute the known cue
+  // duration by page length while guaranteeing every page at least one ms.
+  for (let index = 0; index < input.pages.length; index += 1) {
+    const page = input.pages[index]!;
+    consumedCharacters += [...page].length;
+    const remainingPages = input.pages.length - index - 1;
+    const proportionalEndMs =
+      input.startMs + Math.round((durationMs * consumedCharacters) / totalCharacters);
+    const pageEndMs =
+      remainingPages === 0
+        ? input.endMs
+        : Math.min(Math.max(proportionalEndMs, pageStartMs + 1), input.endMs - remainingPages);
+    timedPages.push({ startMs: pageStartMs, endMs: pageEndMs, text: page });
+    pageStartMs = pageEndMs;
+  }
+  return timedPages;
+}
+
 export function isYoutubeTimedTextExtension(value: string | undefined): boolean {
   if (!value) {
     return false;
@@ -79,7 +276,7 @@ export function isYoutubeTimedTextExtension(value: string | undefined): boolean
 }
 
 export function convertYoutubeTimedTextToVtt(xml: string): string {
-  const rows = extractYoutubeTimedTextRows(xml);
+  const { rows, eventStartsMs, hasRollingWindowEvents } = extractYoutubeTimedTextDocument(xml);
   if (rows.length === 0) {
     return 'WEBVTT\n';
   }
@@ -90,8 +287,17 @@ export function convertYoutubeTimedTextToVtt(xml: string): string {
     const row = rows[index]!;
     const nextRow = rows[index + 1];
     const unclampedEnd = row.startMs + row.durationMs;
+    // YouTube uses exactly 3000ms as a placeholder for generated rolling speech.
+    // Plain-text cues can explicitly use the same duration and must keep it.
+    const nextEventStart =
+      isGeneratedRollingCue(row, hasRollingWindowEvents) &&
+      row.durationMs === YOUTUBE_ROLLING_PLACEHOLDER_DURATION_MS
+        ? findNextEventStartMs(eventStartsMs, row.startMs)
+        : undefined;
     const clampedEnd =
-      nextRow && unclampedEnd > nextRow.startMs
+      nextEventStart !== undefined
+        ? nextEventStart
+        : nextRow && unclampedEnd > nextRow.startMs
           ? Math.max(row.startMs, nextRow.startMs - 1)
           : unclampedEnd;
     if (clampedEnd <= row.startMs) {
@@ -106,10 +312,20 @@ export function convertYoutubeTimedTextToVtt(xml: string): string {
     if (!text) {
       continue;
     }
+    const pages = row.rollingWindow
+      ? splitRollingCaptionIntoPages(text, row.rollingWindow)
+      : [text];
+    for (const page of timeCaptionPages({
+      text,
+      pages,
+      startMs: row.startMs,
+      endMs: clampedEnd,
+    })) {
       blocks.push(
-      `${formatVttTimestamp(row.startMs)} --> ${formatVttTimestamp(clampedEnd)}\n${text}`,
+        `${formatVttTimestamp(page.startMs)} --> ${formatVttTimestamp(page.endMs)}\n${page.text}`,
       );
     }
+  }
 
   return `WEBVTT\n\n${blocks.join('\n\n')}\n`;
 }

src/main.ts

@@ -235,7 +235,10 @@ import {
   createCycleSecondarySubModeRuntimeHandler,
 } from './main/runtime/domains/mpv';
 import { buildSubtitleTrackDiagnostics } from './main/runtime/mpv-track-diagnostics';
-import { resolveCanonicalPrimarySubtitle } from './main/runtime/primary-subtitle-text';
+import {
+  resolveCanonicalPrimarySubtitle,
+  resolvePrimarySubtitle,
+} from './main/runtime/primary-subtitle-text';
 import {
   createBuildCopyCurrentSubtitleMainDepsHandler,
   createBuildHandleMineSentenceDigitMainDepsHandler,
@@ -302,7 +305,6 @@ import {
   listJellyfinItemsRuntime,
   listJellyfinLibrariesRuntime,
   listJellyfinSubtitleTracksRuntime,
-  loadJellyfinSubtitleDelay,
   loadSubtitlePosition as loadSubtitlePositionCore,
   loadYomitanExtension as loadYomitanExtensionCore,
   markLastCardAsAudioCard as markLastCardAsAudioCardCore,
@@ -315,7 +317,6 @@ import {
   resolveSanitizedSubtitleSeekCommand,
   resolveJellyfinPlaybackPlanRuntime,
   runStartupBootstrapRuntime,
-  saveJellyfinSubtitleDelay,
   saveSubtitlePosition as saveSubtitlePositionCore,
   clearYomitanParserCachesForWindow,
   getYomitanCurrentAnkiDeckName as getYomitanCurrentAnkiDeckNameCore,
@@ -465,6 +466,15 @@ import { createMainBootServices, type MainBootServicesResult } from './main/boot
 import { handleCliCommandRuntimeServiceWithContext } from './main/cli-runtime';
 import { createOverlayModalRuntimeService } from './main/overlay-runtime';
 import { createOverlayModalInputState } from './main/runtime/overlay-modal-input-state';
+import { MediaTimingPreviewSession } from './core/services/media-timing-preview';
+import { getSharedRemoteMediaWindowCache } from './core/services/remote-media-window-cache';
+import { resolveMediaGenerationInput } from './anki-integration/media-source';
+import { generateSpeechWaveform } from './core/services/media-timing-waveform';
+import {
+  collectMediaTimingContextLines,
+  createMediaTimingReviewRuntime,
+} from './main/runtime/media-timing-review';
+import { openMediaTimingReviewModal } from './main/runtime/media-timing-review-open';
 import { openYoutubeTrackPicker } from './main/runtime/youtube-picker-open';
 import { openRuntimeOptionsModal as openRuntimeOptionsModalRuntime } from './main/runtime/runtime-options-open';
 import { openJimakuModal as openJimakuModalRuntime } from './main/runtime/jimaku-open';
@@ -677,7 +687,6 @@ function spawnManagedMpvProcess(args: string[]): ReturnType<typeof spawn> {
 }
 
 let activeJellyfinRemotePlayback: ActiveJellyfinRemotePlaybackState | null = null;
-let activeJellyfinSubtitleDelayKey: { itemId: string; streamIndex: number } | null = null;
 let jellyfinRemoteLastProgressAtMs = 0;
 let jellyfinMpvAutoLaunchInFlight: Promise<boolean> | null = null;
 let backgroundWarmupsStarted = false;
@@ -1823,28 +1832,31 @@ function withCurrentSubtitleTiming(payload: SubtitleData): SubtitleData {
 }
 
 function captureCurrentPrimarySubtitleMiningContext(): SubtitleMiningContext | null {
-  const canonical = resolveCanonicalPrimarySubtitle({
+  // Mine what the overlay shows, not raw mpv `sub-text`: the raw text lists every active
+  // event, so a finished caption row lingering beside a fresh line would end up on the
+  // card. The parsed view also carries the cue's own timings for the clip range.
+  const resolved = resolvePrimarySubtitle({
     liveText: appState.mpvClient?.currentSubText ?? '',
     currentTimeSec: Number(appState.mpvClient?.currentTimePos),
     cues: appState.activeParsedSubtitleCues,
   });
-  // Same validity bar as the live capture path: an unusable canonical span must fall
+  // Same validity bar as the live capture path: an unusable resolved span must fall
   // back rather than hand mining an empty line or an inverted range.
-  const canonicalText = canonical?.text.trim();
+  const resolvedText = resolved?.text.replace(/\n{2,}/g, '\n').trim();
   if (
-    !canonical ||
-    !canonicalText ||
-    !Number.isFinite(canonical.startTime) ||
-    !Number.isFinite(canonical.endTime) ||
-    canonical.endTime <= canonical.startTime
+    !resolved ||
+    !resolvedText ||
+    !Number.isFinite(resolved.startTime) ||
+    !Number.isFinite(resolved.endTime) ||
+    resolved.endTime <= resolved.startTime
   ) {
     return captureLiveSubtitleMiningContext(appState.mpvClient);
   }
   return {
     source: 'overlay',
-    text: canonicalText,
-    startTime: canonical.startTime,
-    endTime: canonical.endTime,
+    text: resolvedText,
+    startTime: resolved.startTime,
+    endTime: resolved.endTime,
     capturedAtMs: Date.now(),
   };
 }
@@ -2482,7 +2494,6 @@ const fieldGroupingOverlayRuntime = createFieldGroupingOverlayRuntime<OverlayHos
 const createFieldGroupingCallback = fieldGroupingOverlayRuntime.createFieldGroupingCallback;
 
 const SUBTITLE_POSITIONS_DIR = path.join(CONFIG_DIR, 'subtitle-positions');
-const JELLYFIN_SUBTITLE_DELAYS_PATH = path.join(CONFIG_DIR, 'jellyfin-subtitle-delays.json');
 
 const mediaRuntime = createMediaRuntimeService(
   createBuildMediaRuntimeMainDepsHandler({
@@ -2885,6 +2896,49 @@ function createOverlayHostedModalOpenDeps(): {
   };
 }
 
+const mediaTimingReviewRuntime = createMediaTimingReviewRuntime({
+  getMpvClient: () => appState.mpvClient,
+  getCurrentMediaPath: () =>
+    appState.currentMediaPath?.trim() || appState.mpvClient?.currentVideoPath?.trim() || null,
+  getMpvExecutablePath: () =>
+    configService.getConfig().mpv.executablePath || process.env.SUBMINER_MPV_PATH?.trim() || '',
+  createPreviewSession: () => new MediaTimingPreviewSession(),
+  generateWaveform: (options) => generateSpeechWaveform(options),
+  resolveMediaSource: async () => {
+    const resolved = await resolveMediaGenerationInput(appState.mpvClient, 'audio', {
+      getCachedMediaPath: (currentVideoPath, kind) =>
+        getCachedYoutubeMediaPathForCurrentPlayback(currentVideoPath, kind),
+      remoteCacheMode: shouldRequireYoutubeMediaCacheForCurrentPlayback() ? 'required' : 'optional',
+    });
+    return resolved
+      ? {
+          path: resolved.path,
+          ...(resolved.inputOptions ? { inputOptions: resolved.inputOptions } : {}),
+          singleResolvedStream: resolved.singleResolvedStream,
+        }
+      : null;
+  },
+  acquireMediaWindow: (source, range) => getSharedRemoteMediaWindowCache().acquire(source, range),
+  getSubtitleContextLines: (range) =>
+    collectMediaTimingContextLines({
+      cues: appState.activeParsedSubtitleCues,
+      fallbackPrevious: appState.subtitleTimingTracker?.getRecentEntries(40) ?? [],
+      startTime: range.startTime,
+      endTime: range.endTime,
+    }),
+  openModal: (payload) => openMediaTimingReviewModal(createOverlayHostedModalOpenDeps(), payload),
+  onPreviewEnded: (reviewId) => {
+    // The review may live in either overlay window; the renderer ignores foreign review ids.
+    for (const window of [overlayManager.getMainWindow(), overlayManager.getModalWindow()]) {
+      if (window && !window.isDestroyed()) {
+        window.webContents.send(IPC_CHANNELS.event.mediaTimingReviewPreviewEnded, reviewId);
+      }
+    }
+  },
+  showStatus: (message) =>
+    overlayNotificationsRuntime.showConfiguredStatusNotification(message, { variant: 'warning' }),
+});
+
 function openOverlayHostedModalWithOsd(
   openModal: (deps: ReturnType<typeof createOverlayHostedModalOpenDeps>) => Promise<boolean>,
   unavailableMessage: string,
@@ -3106,23 +3160,6 @@ const {
     wait: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
     cacheSubtitleTrack: (track) => jellyfinSubtitleCacheIo.cacheSubtitleTrack(track),
     cleanupCachedSubtitles: (dirs) => jellyfinSubtitleCacheIo.cleanupCachedSubtitles(dirs),
-    getSavedSubtitleDelay: (itemId, streamIndex) =>
-      loadJellyfinSubtitleDelay({
-        filePath: JELLYFIN_SUBTITLE_DELAYS_PATH,
-        itemId,
-        streamIndex,
-      }),
-    setActiveSubtitleDelayKey: (key) => {
-      activeJellyfinSubtitleDelayKey = key;
-    },
-    loadSubtitleSourceText,
-    saveSubtitleDelay: (itemId, streamIndex, delaySeconds) =>
-      saveJellyfinSubtitleDelay({
-        filePath: JELLYFIN_SUBTITLE_DELAYS_PATH,
-        itemId,
-        streamIndex,
-        delaySeconds,
-      }),
     initSubtitlePrefetch: (sourcePath) =>
       subtitlePrefetchRuntime.refreshSubtitleSidebarFromSource(sourcePath),
     logDebug: (message, error) => {
@@ -3188,7 +3225,6 @@ const {
     getActivePlayback: () => activeJellyfinRemotePlayback,
     clearActivePlayback: () => {
       activeJellyfinRemotePlayback = null;
-      activeJellyfinSubtitleDelayKey = null;
     },
     getSession: () => appState.jellyfinRemoteSession,
     getNow: () => Date.now(),
@@ -3968,6 +4004,7 @@ const {
     cleanupInternalSubtitleTrackCache: () => cachedInternalSubtitleTrackExtractor.clear(),
     cleanupYoutubeSubtitleTempDirs: () => youtubeFlowRuntime.cleanupSubtitleTempDirs(),
     cleanupYoutubeMediaCache: () => youtubeMediaCache.cleanup(),
+    cleanupRemoteMediaWindows: () => getSharedRemoteMediaWindowCache().cleanup(),
     cleanupJellyfinSubtitleCache: () => cleanupJellyfinSubtitleCache(),
     stopDiscordPresenceService: () => {
       void appState.discordPresenceService?.stop();
@@ -4545,7 +4582,6 @@ const {
           appState.activeParsedSubtitleSource = null;
           appState.activeParsedSubtitleMediaPath = null;
         }
-        activeJellyfinSubtitleDelayKey = null;
         overlayManager.broadcastToOverlayWindows('subtitle:set', resetSubtitlePayload);
         subtitleWsService.broadcast(resetSubtitlePayload, frequencyOptions);
         annotationSubtitleWsService.broadcast(resetSubtitlePayload, frequencyOptions);
@@ -5121,6 +5157,7 @@ function initializeOverlayRuntime(): void {
   appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
   appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(refreshCurrentSubtitleAnnotations);
   appState.ankiIntegration?.setSubtitleMiningContextConsumer(consumePendingSubtitleMiningContext);
+  appState.ankiIntegration?.setMediaTimingReviewCallback(mediaTimingReviewRuntime.requestReview);
   syncOverlayMpvSubtitleSuppression();
 }
 
@@ -5530,6 +5567,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       showMpvOsd: (text: string) => showConfiguredPlaybackFeedback(text),
     },
     mainDeps: {
+      previewMediaTimingReview: (request) => mediaTimingReviewRuntime.previewRange(request),
+      getMediaTimingReviewWaveform: (request) => mediaTimingReviewRuntime.getWaveform(request),
+      stopMediaTimingReviewPreview: (reviewId) => mediaTimingReviewRuntime.stopPreview(reviewId),
+      resolveMediaTimingReview: (request) => mediaTimingReviewRuntime.resolveReview(request),
       getMainWindow: () => overlayManager.getMainWindow(),
       getVisibleOverlayVisibility: () => overlayManager.getVisibleOverlayVisible(),
       focusMainWindow: () => {
@@ -5563,6 +5604,9 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         }
       },
       onOverlayModalClosed: (modal, senderWindow) => {
+        if (modal === 'media-timing-review') {
+          void mediaTimingReviewRuntime.dispose();
+        }
         if (modal === 'subtitle-sidebar' && senderWindow === overlayManager.getMainWindow()) {
           subtitleSidebarRequestedOpen = false;
         }
@@ -5916,6 +5960,9 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         appState.ankiIntegration?.setSubtitleMiningContextConsumer(
           consumePendingSubtitleMiningContext,
         );
+        appState.ankiIntegration?.setMediaTimingReviewCallback(
+          mediaTimingReviewRuntime.requestReview,
+        );
       },
       getKnownWordCacheStatePath: () => path.join(USER_DATA_PATH, 'known-words-cache.json'),
       getCachedMediaPath: (currentVideoPath, kind) =>
@@ -5925,6 +5972,8 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       showDesktopNotification,
       showOverlayNotification: (payload) =>
         overlayNotificationsRuntime.showOverlayNotification(payload),
+      dismissOverlayNotification: (id) =>
+        overlayNotificationsRuntime.dismissOverlayNotification(id),
       createFieldGroupingCallback: () => createFieldGroupingCallback(),
       broadcastRuntimeOptionsChanged: () =>
         overlayVisibilityComposer.broadcastRuntimeOptionsChanged(),
@@ -6238,6 +6287,7 @@ const { createMainWindow: createMainWindowHandler, createModalWindow: createModa
           if (overlayManager.getModalWindow() !== window) {
             return;
           }
+          void mediaTimingReviewRuntime.dispose();
           overlayManager.setModalWindow(null);
         }
       },
@@ -6415,6 +6465,8 @@ const { initializeOverlayRuntime: initializeOverlayRuntimeHandler } =
       showDesktopNotification,
       showOverlayNotification: (payload) =>
         overlayNotificationsRuntime.showOverlayNotification(payload),
+      dismissOverlayNotification: (id) =>
+        overlayNotificationsRuntime.dismissOverlayNotification(id),
       createFieldGroupingCallback: () => createFieldGroupingCallback(),
       getKnownWordCacheStatePath: () => path.join(USER_DATA_PATH, 'known-words-cache.json'),
       getCachedMediaPath: (currentVideoPath, kind) =>

src/main/dependencies.ts

@@ -62,6 +62,10 @@ export interface MainIpcRuntimeServiceDepsParams {
   onOverlayInteractiveHint?: IpcDepsRuntimeOptions['onOverlayInteractiveHint'];
   handleOverlayNotificationAction?: IpcDepsRuntimeOptions['handleOverlayNotificationAction'];
   onYoutubePickerResolve: IpcDepsRuntimeOptions['onYoutubePickerResolve'];
+  previewMediaTimingReview?: IpcDepsRuntimeOptions['previewMediaTimingReview'];
+  getMediaTimingReviewWaveform?: IpcDepsRuntimeOptions['getMediaTimingReviewWaveform'];
+  stopMediaTimingReviewPreview?: IpcDepsRuntimeOptions['stopMediaTimingReviewPreview'];
+  resolveMediaTimingReview?: IpcDepsRuntimeOptions['resolveMediaTimingReview'];
   openYomitanSettings: IpcDepsRuntimeOptions['openYomitanSettings'];
   quitApp: IpcDepsRuntimeOptions['quitApp'];
   toggleVisibleOverlay: IpcDepsRuntimeOptions['toggleVisibleOverlay'];
@@ -132,6 +136,7 @@ export interface AnkiJimakuIpcRuntimeServiceDepsParams {
   getYoutubeMediaSourceUrl?: AnkiJimakuIpcRuntimeOptions['getYoutubeMediaSourceUrl'];
   showDesktopNotification: AnkiJimakuIpcRuntimeOptions['showDesktopNotification'];
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: AnkiJimakuIpcRuntimeOptions['createFieldGroupingCallback'];
   broadcastRuntimeOptionsChanged: AnkiJimakuIpcRuntimeOptions['broadcastRuntimeOptionsChanged'];
   getFieldGroupingResolver: AnkiJimakuIpcRuntimeOptions['getFieldGroupingResolver'];
@@ -256,6 +261,10 @@ export function createMainIpcRuntimeServiceDeps(
     onOverlayInteractiveHint: params.onOverlayInteractiveHint,
     handleOverlayNotificationAction: params.handleOverlayNotificationAction,
     onYoutubePickerResolve: params.onYoutubePickerResolve,
+    previewMediaTimingReview: params.previewMediaTimingReview,
+    getMediaTimingReviewWaveform: params.getMediaTimingReviewWaveform,
+    stopMediaTimingReviewPreview: params.stopMediaTimingReviewPreview,
+    resolveMediaTimingReview: params.resolveMediaTimingReview,
     openYomitanSettings: params.openYomitanSettings,
     quitApp: params.quitApp,
     toggleVisibleOverlay: params.toggleVisibleOverlay,
@@ -334,6 +343,7 @@ export function createAnkiJimakuIpcRuntimeServiceDeps(
       : {}),
     showDesktopNotification: params.showDesktopNotification,
     showOverlayNotification: params.showOverlayNotification,
+    dismissOverlayNotification: params.dismissOverlayNotification,
     createFieldGroupingCallback: params.createFieldGroupingCallback,
     broadcastRuntimeOptionsChanged: params.broadcastRuntimeOptionsChanged,
     getFieldGroupingResolver: params.getFieldGroupingResolver,

src/main/overlay-runtime.test.ts

@@ -828,6 +828,7 @@ test('modal fallback reveal skips showing window when content is not ready', asy
       setModalWindowBounds: () => {},
     },
     {
+      platform: 'darwin',
       scheduleRevealFallback: (callback) => {
         scheduledReveal = callback;
         return { scheduled: true } as never;
@@ -1363,3 +1364,62 @@ test('modal placement reconcile cancels stale retry ladder after a newer visible
     globalThis.clearTimeout = originalClearTimeout;
   }
 });
+
+test('Linux keeps the dedicated modal window unmapped until the renderer opens the modal, then hides the overlay before revealing it', () => {
+  const mainWindow = createMockWindow();
+  mainWindow.visible = true;
+  const modalWindow = createMockWindow();
+  const order: string[] = [];
+  const hideMain = mainWindow.hide;
+  mainWindow.hide = () => {
+    order.push('main:hide');
+    hideMain();
+  };
+  const showModal = modalWindow.show;
+  modalWindow.show = () => {
+    order.push('modal:show');
+    showModal();
+  };
+  let revealScheduled = false;
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => mainWindow as never,
+      getModalWindow: () => modalWindow as never,
+      createModalWindow: () => modalWindow as never,
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    {
+      platform: 'linux',
+      scheduleRevealFallback: () => {
+        revealScheduled = true;
+        return { scheduled: true } as never;
+      },
+      clearRevealFallback: () => {},
+    },
+  );
+
+  const open = () =>
+    runtime.sendToActiveOverlayWindow(
+      'media-timing-review:open',
+      { reviewId: 'review' },
+      { restoreOnModalClose: 'media-timing-review', preferModalWindow: true },
+    );
+
+  assert.equal(open(), true);
+  assert.deepEqual(modalWindow.sent, [['media-timing-review:open', { reviewId: 'review' }]]);
+  assert.equal(revealScheduled, false);
+  assert.equal(modalWindow.getShowCount(), 0);
+  assert.equal(mainWindow.getHideCount(), 0);
+
+  // The open retry must not map the window before the renderer answers either.
+  assert.equal(open(), true);
+  assert.equal(modalWindow.getShowCount(), 0);
+
+  runtime.notifyOverlayModalOpened('media-timing-review');
+
+  assert.deepEqual(order, ['main:hide', 'modal:show']);
+  assert.equal(mainWindow.isVisible(), false);
+  assert.equal(modalWindow.isVisible(), true);
+  assert.equal(modalWindow.ignoreMouseEvents, false);
+});

src/main/overlay-runtime.ts

@@ -90,6 +90,12 @@ export function createOverlayModalRuntimeService(
   const platform = options.platform ?? process.platform;
   const shouldPrimeModalWindow = platform === 'darwin' || platform === 'win32';
   const reuseModalWindowAfterClose = platform === 'darwin';
+  // On Linux (Hyprland) every placement dispatch on a mapped window (resize, move, set_prop)
+  // blanks the still-visible overlay for a few frames while mpv is fullscreen. Revealing the
+  // dedicated modal window before its renderer has the modal open runs the placement ladder,
+  // and the open retry, against a visible overlay, which the user sees as flicker. Keep the
+  // window unmapped until the renderer acknowledges the open, then hide the overlay first.
+  const deferModalRevealUntilOpened = platform === 'linux';
   const focusApplication = options.focusApplication ?? requestOverlayApplicationFocus;
   const scheduleRevealFallback = (callback: () => void, delayMs: number): RevealFallbackHandle =>
     (options.scheduleRevealFallback ?? globalThis.setTimeout)(callback, delayMs);
@@ -457,7 +463,9 @@ export function createOverlayModalRuntimeService(
       deps.setModalWindowBounds(deps.getModalGeometry());
       const wasVisible = modalWindow.isVisible();
       if (!wasVisible) {
-        if (modalWindowPrimedForImmediateShow && isWindowReadyForIpc(modalWindow)) {
+        if (deferModalRevealUntilOpened) {
+          // notifyOverlayModalOpened reveals the window once the renderer has the modal open.
+        } else if (modalWindowPrimedForImmediateShow && isWindowReadyForIpc(modalWindow)) {
           showModalWindow(modalWindow);
         } else {
           scheduleModalWindowReveal(modalWindow);
@@ -560,15 +568,23 @@ export function createOverlayModalRuntimeService(
     }
 
     const modalWindow = deps.getModalWindow();
+    const targetIsModalWindow =
+      modalWindow !== null && !modalWindow.isDestroyed() && targetWindow === modalWindow;
+    const handOffMainWindowToModal = (): void => {
+      setMainWindowMousePassthroughForModal(true);
+      setMainWindowVisibilityForModal(true);
+    };
+
+    if (targetIsModalWindow && deferModalRevealUntilOpened) {
+      handOffMainWindowToModal();
+    }
     if (targetWindow.isVisible()) {
       ensureModalWindowInteractive(targetWindow);
     } else {
       showModalWindow(targetWindow);
     }
-
-    if (modalWindow && !modalWindow.isDestroyed() && targetWindow === modalWindow) {
-      setMainWindowMousePassthroughForModal(true);
-      setMainWindowVisibilityForModal(true);
+    if (targetIsModalWindow && !deferModalRevealUntilOpened) {
+      handOffMainWindowToModal();
     }
   };
 

src/main/runtime/app-lifecycle-actions.test.ts

@@ -46,12 +46,13 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
     cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });
 
   cleanup();
-  assert.equal(calls.length, 35);
+  assert.equal(calls.length, 36);
   assert.equal(calls[0], 'destroy-tray');
   assert.equal(calls[calls.length - 1], 'stop-discord-presence');
   assert.ok(calls.includes('cleanup-jellyfin-subtitles'));
@@ -60,6 +61,7 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
   assert.ok(calls.includes('clear-linux-mpv-fullscreen-overlay-refresh-timeouts'));
   assert.ok(calls.includes('cleanup-youtube-subtitles'));
   assert.ok(calls.includes('cleanup-youtube-media'));
+  assert.ok(calls.includes('cleanup-remote-media-windows'));
   assert.ok(calls.indexOf('flush-mpv-log') < calls.indexOf('destroy-socket'));
 });
 
@@ -102,6 +104,7 @@ test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping
     cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });

src/main/runtime/app-lifecycle-actions.ts

@@ -32,6 +32,7 @@ export function createOnWillQuitCleanupHandler(deps: {
   cleanupInternalSubtitleTrackCache: () => void;
   cleanupYoutubeSubtitleTempDirs: () => void;
   cleanupYoutubeMediaCache: () => void;
+  cleanupRemoteMediaWindows: () => void;
   cleanupJellyfinSubtitleCache: () => void;
   stopDiscordPresenceService: () => void;
 }) {
@@ -76,6 +77,7 @@ export function createOnWillQuitCleanupHandler(deps: {
     }
     deps.cleanupYoutubeSubtitleTempDirs();
     deps.cleanupYoutubeMediaCache();
+    deps.cleanupRemoteMediaWindows();
     deps.stopDiscordPresenceService();
     return Promise.resolve(stopSyncAutoScheduler);
   };

src/main/runtime/app-lifecycle-main-cleanup.test.ts

@@ -75,6 +75,7 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
     cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });
@@ -157,6 +158,7 @@ test('cleanup deps builder skips destroyed yomitan window', () => {
     cleanupInternalSubtitleTrackCache: () => {},
     cleanupYoutubeSubtitleTempDirs: () => {},
     cleanupYoutubeMediaCache: () => {},
+    cleanupRemoteMediaWindows: () => {},
     cleanupJellyfinSubtitleCache: () => {},
     stopDiscordPresenceService: () => {},
   });
@@ -210,6 +212,7 @@ test('cleanup deps builder skips global shortcut cleanup before app ready', () =
     cleanupInternalSubtitleTrackCache: () => {},
     cleanupYoutubeSubtitleTempDirs: () => {},
     cleanupYoutubeMediaCache: () => {},
+    cleanupRemoteMediaWindows: () => {},
     cleanupJellyfinSubtitleCache: () => {},
     stopDiscordPresenceService: () => {},
   });

src/main/runtime/app-lifecycle-main-cleanup.ts

@@ -61,6 +61,7 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
   cleanupInternalSubtitleTrackCache: () => void;
   cleanupYoutubeSubtitleTempDirs: () => void;
   cleanupYoutubeMediaCache: () => void;
+  cleanupRemoteMediaWindows: () => void;
   cleanupJellyfinSubtitleCache: () => void;
   stopDiscordPresenceService: () => void;
 }) {
@@ -148,6 +149,7 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
     cleanupInternalSubtitleTrackCache: () => deps.cleanupInternalSubtitleTrackCache(),
     cleanupYoutubeSubtitleTempDirs: () => deps.cleanupYoutubeSubtitleTempDirs(),
     cleanupYoutubeMediaCache: () => deps.cleanupYoutubeMediaCache(),
+    cleanupRemoteMediaWindows: () => deps.cleanupRemoteMediaWindows(),
     cleanupJellyfinSubtitleCache: () => deps.cleanupJellyfinSubtitleCache(),
     stopDiscordPresenceService: () => deps.stopDiscordPresenceService(),
   });

src/main/runtime/composers/startup-lifecycle-composer.test.ts

@@ -52,6 +52,7 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
       cleanupInternalSubtitleTrackCache: () => {},
       cleanupYoutubeSubtitleTempDirs: () => {},
       cleanupYoutubeMediaCache: () => {},
+      cleanupRemoteMediaWindows: () => {},
       cleanupJellyfinSubtitleCache: () => {},
       stopDiscordPresenceService: () => {},
     },

src/main/runtime/config-hot-reload-handlers.test.ts

@@ -156,6 +156,7 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
   const config = deepCloneConfig(DEFAULT_CONFIG);
   config.ankiConnect.media.normalizeAudio = false;
   config.ankiConnect.media.mirrorMpvVolume = false;
+  config.ankiConnect.media.reviewTiming = true;
   const ankiPatches: unknown[] = [];
 
   const applyHotReload = createConfigHotReloadAppliedHandler({
@@ -181,10 +182,18 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
     },
     config,
   );
+  applyHotReload(
+    {
+      hotReloadFields: ['ankiConnect.media.reviewTiming'],
+      restartRequiredFields: [],
+    },
+    config,
+  );
 
   assert.deepEqual(ankiPatches, [
     { media: { normalizeAudio: false } },
     { media: { mirrorMpvVolume: false } },
+    { media: { reviewTiming: true } },
   ]);
 });
 

src/main/runtime/config-hot-reload-handlers.ts

@@ -100,6 +100,9 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.media.mirrorMpvVolume')) {
     mediaPatch.mirrorMpvVolume = config.ankiConnect.media.mirrorMpvVolume;
   }
+  if (diff.hotReloadFields.includes('ankiConnect.media.reviewTiming')) {
+    mediaPatch.reviewTiming = config.ankiConnect.media.reviewTiming;
+  }
   if (Object.keys(mediaPatch).length > 0) {
     patch.media = mediaPatch;
   }
@@ -134,6 +137,9 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.isKiku.fieldGrouping')) {
     patch.isKiku = { fieldGrouping: config.ankiConnect.isKiku.fieldGrouping };
   }
+  if (diff.hotReloadFields.includes('ankiConnect.isSenren.fieldGrouping')) {
+    patch.isSenren = { fieldGrouping: config.ankiConnect.isSenren.fieldGrouping };
+  }
   if (diff.hotReloadFields.includes('ankiConnect.lapisKiku.wordCardKind')) {
     patch.lapisKiku = { wordCardKind: config.ankiConnect.lapisKiku.wordCardKind };
   }

src/main/runtime/jellyfin-subtitle-preload-main-deps.test.ts

@@ -19,19 +19,6 @@ test('preload jellyfin external subtitles main deps builder maps callbacks', asy
       return { path: '/tmp/sub.srt', cleanupDir: '/tmp/subs' };
     },
     cleanupCachedSubtitles: () => calls.push('cleanup'),
-    getSavedSubtitleDelay: (_itemId, streamIndex) => {
-      calls.push(`load-delay:${streamIndex}`);
-      return 1.25;
-    },
-    setActiveSubtitleDelayKey: (key) => calls.push(`active-delay:${key?.streamIndex ?? 'none'}`),
-    loadSubtitleSourceText: async (source) => {
-      calls.push(`load-source:${source}`);
-      return 'subtitle';
-    },
-    saveSubtitleDelay: (_itemId, streamIndex, delaySeconds) => {
-      calls.push(`save-delay:${streamIndex}:${delaySeconds}`);
-      return true;
-    },
     logDebug: (message) => calls.push(`debug:${message}`),
   })();
 
@@ -41,21 +28,6 @@ test('preload jellyfin external subtitles main deps builder maps callbacks', asy
   await deps.wait(1);
   await deps.cacheSubtitleTrack({ index: 1, deliveryUrl: 'https://example.test/sub.srt' });
   deps.cleanupCachedSubtitles(['/tmp/subs']);
-  assert.equal(deps.getSavedSubtitleDelay?.('item', 3), 1.25);
-  deps.setActiveSubtitleDelayKey?.({ itemId: 'item', streamIndex: 3 });
-  assert.equal(await deps.loadSubtitleSourceText?.('/tmp/sub.srt'), 'subtitle');
-  assert.equal(deps.saveSubtitleDelay?.('item', 3, -31.5), true);
   deps.logDebug('oops', null);
-  assert.deepEqual(calls, [
-    'list',
-    'send',
-    'wait',
-    'cache',
-    'cleanup',
-    'load-delay:3',
-    'active-delay:3',
-    'load-source:/tmp/sub.srt',
-    'save-delay:3:-31.5',
-    'debug:oops',
-  ]);
+  assert.deepEqual(calls, ['list', 'send', 'wait', 'cache', 'cleanup', 'debug:oops']);
 });

src/main/runtime/jellyfin-subtitle-preload-main-deps.ts

@@ -15,19 +15,6 @@ export function createBuildPreloadJellyfinExternalSubtitlesMainDepsHandler(
     wait: (ms: number) => deps.wait(ms),
     cacheSubtitleTrack: (track) => deps.cacheSubtitleTrack(track),
     cleanupCachedSubtitles: (dirs) => deps.cleanupCachedSubtitles(dirs),
-    getSavedSubtitleDelay: deps.getSavedSubtitleDelay
-      ? (itemId, streamIndex) => deps.getSavedSubtitleDelay!(itemId, streamIndex)
-      : undefined,
-    setActiveSubtitleDelayKey: deps.setActiveSubtitleDelayKey
-      ? (key) => deps.setActiveSubtitleDelayKey!(key)
-      : undefined,
-    loadSubtitleSourceText: deps.loadSubtitleSourceText
-      ? (source) => deps.loadSubtitleSourceText!(source)
-      : undefined,
-    saveSubtitleDelay: deps.saveSubtitleDelay
-      ? (itemId, streamIndex, delaySeconds) =>
-          deps.saveSubtitleDelay!(itemId, streamIndex, delaySeconds)
-      : undefined,
     initSubtitlePrefetch: deps.initSubtitlePrefetch
       ? (sourcePath) => deps.initSubtitlePrefetch!(sourcePath)
       : undefined,

src/main/runtime/jellyfin-subtitle-preload.test.ts

@@ -32,14 +32,6 @@ function makeDeps(overrides: {
   cleanupCachedSubtitles?: Parameters<
     typeof createPreloadJellyfinExternalSubtitlesHandler
   >[0]['cleanupCachedSubtitles'];
-  getSavedSubtitleDelay?: Parameters<
-    typeof createPreloadJellyfinExternalSubtitlesHandler
-  >[0]['getSavedSubtitleDelay'];
-  setActiveSubtitleDelayKey?: Parameters<
-    typeof createPreloadJellyfinExternalSubtitlesHandler
-  >[0]['setActiveSubtitleDelayKey'];
-  loadSubtitleSourceText?: (source: string) => Promise<string>;
-  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => void;
   initSubtitlePrefetch?: Parameters<
     typeof createPreloadJellyfinExternalSubtitlesHandler
   >[0]['initSubtitlePrefetch'];
@@ -57,10 +49,6 @@ function makeDeps(overrides: {
         cleanupDir: '/tmp/subminer-jellyfin-subtitles',
       })),
     cleanupCachedSubtitles: overrides.cleanupCachedSubtitles ?? (() => {}),
-    getSavedSubtitleDelay: overrides.getSavedSubtitleDelay,
-    setActiveSubtitleDelayKey: overrides.setActiveSubtitleDelayKey,
-    loadSubtitleSourceText: overrides.loadSubtitleSourceText,
-    saveSubtitleDelay: overrides.saveSubtitleDelay,
     initSubtitlePrefetch: overrides.initSubtitlePrefetch,
     logDebug: overrides.logDebug ?? (() => {}),
   };
@@ -377,20 +365,17 @@ test('preload jellyfin subtitles waits for delayed external japanese track inste
 
 test('preload jellyfin subtitles clears managed delay when no external tracks are available', async () => {
   const commands: Array<Array<string | number>> = [];
-  const activeDelayKeys: Array<unknown> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(
     makeDeps({
       listJellyfinSubtitleTracks: async () => [
         { index: 0, language: 'jpn', title: 'Embedded Japanese' },
       ],
       sendMpvCommand: (command) => commands.push(command),
-      setActiveSubtitleDelayKey: (key) => activeDelayKeys.push(key),
     }),
   );
 
   await preload({ session, clientInfo, itemId: 'item-1' });
 
-  assert.deepEqual(activeDelayKeys, [null]);
   assert.deepEqual(commands, [['set_property', 'sub-delay', 0]]);
 });
 
@@ -461,42 +446,7 @@ test('preload jellyfin subtitles prefers Jellyfin default and embedded japanese
   ]);
 });
 
-test('preload jellyfin subtitles applies saved delay for selected japanese stream', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const activeKeys: Array<{ itemId: string; streamIndex: number } | null> = [];
-  const preload = createPreloadJellyfinExternalSubtitlesHandler(
-    makeDeps({
-      listJellyfinSubtitleTracks: async () => [
-        { index: 3, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
-      ],
-      getMpvClient: () => ({
-        requestProperty: async () => [
-          {
-            type: 'sub',
-            id: 11,
-            lang: 'jpn',
-            title: 'Japanese',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/3.srt',
-          },
-        ],
-      }),
-      sendMpvCommand: (command) => commands.push(command),
-      getSavedSubtitleDelay: (_itemId, streamIndex) => (streamIndex === 3 ? 1.25 : null),
-      setActiveSubtitleDelayKey: (key) => activeKeys.push(key),
-    }),
-  );
-
-  await preload({ session, clientInfo, itemId: 'item-9' });
-
-  assert.deepEqual(setPropertyCommandsExceptTrackAutoSelection(commands), [
-    ['set_property', 'sub-delay', 1.25],
-    ['set_property', 'sid', 11],
-  ]);
-  assert.deepEqual(activeKeys, [{ itemId: 'item-9', streamIndex: 3 }]);
-});
-
-test('preload jellyfin subtitles applies saved delay before selecting japanese stream', async () => {
+test('preload jellyfin subtitles resets delay before selecting japanese stream', async () => {
   const commands: Array<Array<string | number>> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(
     makeDeps({
@@ -516,14 +466,13 @@ test('preload jellyfin subtitles applies saved delay before selecting japanese s
         ],
       }),
       sendMpvCommand: (command) => commands.push(command),
-      getSavedSubtitleDelay: () => 1.25,
     }),
   );
 
   await preload({ session, clientInfo, itemId: 'item-9' });
 
   const delayIndex = commands.findIndex(
-    (command) => command[0] === 'set_property' && command[1] === 'sub-delay' && command[2] === 1.25,
+    (command) => command[0] === 'set_property' && command[1] === 'sub-delay' && command[2] === 0,
   );
   const selectedSidIndex = commands.findIndex(
     (command) => command[0] === 'set_property' && command[1] === 'sid' && command[2] === 11,
@@ -533,143 +482,6 @@ test('preload jellyfin subtitles applies saved delay before selecting japanese s
   assert.ok(delayIndex < selectedSidIndex);
 });
 
-test('preload jellyfin subtitles auto-aligns late japanese track from english reference', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const savedDelays: Array<{ itemId: string; streamIndex: number; delaySeconds: number }> = [];
-  const primarySrt = `1
-00:00:34,935 --> 00:00:36,937
-Japanese 1
-
-2
-00:00:36,937 --> 00:00:41,441
-Japanese 2
-
-3
-00:00:41,441 --> 00:00:45,279
-Japanese 3
-
-4
-00:00:45,279 --> 00:00:48,115
-Japanese 4
-
-5
-00:00:48,115 --> 00:00:52,286
-Japanese 5
-
-6
-00:00:52,286 --> 00:00:54,955
-Japanese 6
-
-7
-00:00:54,955 --> 00:00:59,793
-Japanese 7
-
-8
-00:00:59,793 --> 00:01:03,630
-Japanese 8
-
-9
-00:01:03,630 --> 00:01:07,634
-Japanese 9
-
-10
-00:01:07,634 --> 00:01:13,040
-Japanese 10
-
-11
-00:01:16,643 --> 00:01:20,814
-Japanese 11
-
-12
-00:01:20,814 --> 00:01:23,116
-Japanese 12
-
-13
-00:01:27,988 --> 00:01:30,991
-Japanese 13
-
-14
-00:01:30,991 --> 00:01:34,094
-Japanese 14
-
-15
-00:01:34,094 --> 00:01:37,097
-Japanese 15
-
-16
-00:01:37,097 --> 00:01:39,100
-Japanese 16
-`;
-  const referenceAss = `[Events]
-Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
-Dialogue: 0,0:00:03.46,0:00:08.73,Default,,0,0,0,,English 1
-Dialogue: 0,0:00:09.48,0:00:13.61,Default,,0,0,0,,English 2
-Dialogue: 0,0:00:13.61,0:00:19.64,Default,,0,0,0,,English 3
-Dialogue: 0,0:00:21.40,0:00:27.32,Default,,0,0,0,,English 4
-Dialogue: 0,0:00:28.16,0:00:31.75,Default,,0,0,0,,English 5
-Dialogue: 0,0:00:32.06,0:00:34.52,Default,,0,0,0,,English 6
-Dialogue: 0,0:00:35.93,0:00:40.57,Default,,0,0,0,,English 7
-Dialogue: 0,0:00:45.10,0:00:51.01,Default,,0,0,0,,English 8
-Dialogue: 0,0:00:56.57,0:00:59.12,Default,,0,0,0,,English 9
-Dialogue: 0,0:00:59.68,0:01:02.44,Default,,0,0,0,,English 10
-Dialogue: 0,0:01:02.44,0:01:05.56,Default,,0,0,0,,English 11
-Dialogue: 0,0:01:05.56,0:01:06.87,Default,,0,0,0,,English 12
-`;
-  const preload = createPreloadJellyfinExternalSubtitlesHandler(
-    makeDeps({
-      listJellyfinSubtitleTracks: async () => [
-        { index: 0, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
-        { index: 4, language: 'eng', title: 'English', deliveryUrl: 'https://sub/eng.ass' },
-      ],
-      getMpvClient: () => ({
-        requestProperty: async () => [
-          {
-            type: 'sub',
-            id: 10,
-            lang: 'jpn',
-            title: 'Japanese',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
-          },
-          {
-            type: 'sub',
-            id: 12,
-            lang: 'eng',
-            title: 'English',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/4.ass',
-          },
-        ],
-      }),
-      sendMpvCommand: (command) => commands.push(command),
-      cacheSubtitleTrack: async (track) => ({
-        path: `/tmp/subminer-jellyfin-subtitles/${track.index}.${track.index === 4 ? 'ass' : 'srt'}`,
-        cleanupDir: '/tmp/subminer-jellyfin-subtitles',
-      }),
-      getSavedSubtitleDelay: () => null,
-      loadSubtitleSourceText: async (source) =>
-        source.endsWith('.ass') ? referenceAss : primarySrt,
-      saveSubtitleDelay: (itemId, streamIndex, delaySeconds) => {
-        savedDelays.push({ itemId, streamIndex, delaySeconds });
-      },
-    }),
-  );
-
-  await preload({ session, clientInfo, itemId: 'item-9' });
-
-  const delayCommand = commands.find(
-    (command) => command[0] === 'set_property' && command[1] === 'sub-delay',
-  );
-  assert.ok(delayCommand);
-  const delaySeconds = delayCommand[2];
-  if (typeof delaySeconds !== 'number') {
-    assert.fail('Expected numeric subtitle delay.');
-  }
-  assert.ok(delaySeconds > -32);
-  assert.ok(delaySeconds < -31);
-  assert.deepEqual(savedDelays, [{ itemId: 'item-9', streamIndex: 0, delaySeconds }]);
-});
-
 test('preload jellyfin subtitles accepts numeric string mpv track ids', async () => {
   const commands: Array<Array<string | number>> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(

src/main/runtime/jellyfin-subtitle-preload.ts

@@ -1,6 +1,3 @@
-import { parseSubtitleCues } from '../../core/services/subtitle-cue-parser';
-import { estimateSubtitleTimingOffset } from '../../core/services/subtitle-timing-offset';
-
 type JellyfinSession = {
   serverUrl: string;
   accessToken: string;
@@ -35,11 +32,6 @@ type CachedExternalSubtitleTrack = CachedSubtitleTrack & {
   source: JellyfinSubtitleTrack;
 };
 
-type JellyfinSubtitleDelayKey = {
-  itemId: string;
-  streamIndex: number;
-};
-
 type MpvSubtitleTrack = {
   id: number;
   lang: string;
@@ -257,54 +249,6 @@ async function waitForPreferredSubtitleTracks(
   return subtitleTracks;
 }
 
-async function estimateSubtitleDelayFromReference(
-  deps: {
-    loadSubtitleSourceText?: (source: string) => Promise<string>;
-    logDebug: (message: string, error: unknown) => void;
-  },
-  primaryTrack: CachedExternalSubtitleTrack | null,
-  referenceTrack: CachedExternalSubtitleTrack | null,
-): Promise<number | null> {
-  if (!deps.loadSubtitleSourceText || !primaryTrack || !referenceTrack) {
-    return null;
-  }
-
-  try {
-    const [primaryContent, referenceContent] = await Promise.all([
-      deps.loadSubtitleSourceText(primaryTrack.path),
-      deps.loadSubtitleSourceText(referenceTrack.path),
-    ]);
-    const primaryCues = parseSubtitleCues(primaryContent, primaryTrack.path);
-    const referenceCues = parseSubtitleCues(referenceContent, referenceTrack.path);
-    return estimateSubtitleTimingOffset(primaryCues, referenceCues)?.offsetSeconds ?? null;
-  } catch (error) {
-    deps.logDebug('Failed to auto-align Jellyfin subtitle timing', error);
-    return null;
-  }
-}
-
-function saveEstimatedSubtitleDelay(
-  deps: {
-    saveSubtitleDelay?: (
-      itemId: string,
-      streamIndex: number,
-      delaySeconds: number,
-    ) => boolean | void;
-    logDebug: (message: string, error: unknown) => void;
-  },
-  key: JellyfinSubtitleDelayKey,
-  delaySeconds: number,
-): void {
-  try {
-    const saved = deps.saveSubtitleDelay?.(key.itemId, key.streamIndex, delaySeconds);
-    if (saved === false) {
-      deps.logDebug('Failed to save Jellyfin auto subtitle delay', key);
-    }
-  } catch (error) {
-    deps.logDebug('Failed to save Jellyfin auto subtitle delay', error);
-  }
-}
-
 export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
   listJellyfinSubtitleTracks: (
     session: JellyfinSession,
@@ -316,10 +260,6 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
   wait: (ms: number) => Promise<void>;
   cacheSubtitleTrack: (track: JellyfinSubtitleTrack) => Promise<CachedSubtitleTrack>;
   cleanupCachedSubtitles: (dirs: string[]) => void;
-  getSavedSubtitleDelay?: (itemId: string, streamIndex: number) => number | null;
-  setActiveSubtitleDelayKey?: (key: JellyfinSubtitleDelayKey | null) => void;
-  loadSubtitleSourceText?: (source: string) => Promise<string>;
-  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => boolean | void;
   initSubtitlePrefetch?: (sourcePath: string) => void | Promise<void>;
   logDebug: (message: string, error: unknown) => void;
 }): PreloadJellyfinExternalSubtitlesHandler {
@@ -357,6 +297,7 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
     itemId: string;
   }): Promise<void> => {
     try {
+      resetManagedSubtitleDelay();
       try {
         cleanupActiveCache();
       } catch (error) {
@@ -369,8 +310,6 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
       );
       const externalTracks = tracks.filter((track) => Boolean(track.deliveryUrl));
       if (externalTracks.length === 0) {
-        deps.setActiveSubtitleDelayKey?.(null);
-        resetManagedSubtitleDelay();
         return;
       }
 
@@ -427,40 +366,13 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
           japanesePrimaryId,
         );
         if (selectedCachedTrack) {
-          const delayKey = { itemId: params.itemId, streamIndex: selectedCachedTrack.source.index };
-          deps.setActiveSubtitleDelayKey?.(delayKey);
-          const savedDelay = deps.getSavedSubtitleDelay?.(delayKey.itemId, delayKey.streamIndex);
-          if (typeof savedDelay === 'number' && Number.isFinite(savedDelay)) {
-            deps.sendMpvCommand(['set_property', 'sub-delay', savedDelay]);
-          } else {
-            const referenceCachedTrack = findCachedTrackForMpvTrackId(
-              resolvedSubtitleTracks,
-              cachedTracks,
-              englishSecondaryId,
-            );
-            const estimatedDelay = await estimateSubtitleDelayFromReference(
-              deps,
-              selectedCachedTrack,
-              referenceCachedTrack,
-            );
-            if (estimatedDelay !== null) {
-              deps.sendMpvCommand(['set_property', 'sub-delay', estimatedDelay]);
-              saveEstimatedSubtitleDelay(deps, delayKey, estimatedDelay);
-            } else {
-              resetManagedSubtitleDelay();
-            }
-          }
           deps.sendMpvCommand(['set_property', 'sid', japanesePrimaryId]);
           startSubtitlePrefetchForCachedTrack(selectedCachedTrack.path);
         } else {
-          deps.setActiveSubtitleDelayKey?.(null);
-          resetManagedSubtitleDelay();
           deps.sendMpvCommand(['set_property', 'sid', japanesePrimaryId]);
         }
       } else {
         deps.sendMpvCommand(['set_property', 'sid', 'no']);
-        deps.setActiveSubtitleDelayKey?.(null);
-        resetManagedSubtitleDelay();
       }
 
       if (englishSecondaryId !== null) {

src/main/runtime/media-timing-review-open.ts

@@ -0,0 +1,42 @@
+import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
+import type { MediaTimingReviewOpenPayload } from '../../types/anki';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+const MODAL: OverlayHostedModal = 'media-timing-review';
+
+export async function openMediaTimingReviewModal(
+  deps: {
+    ensureOverlayStartupPrereqs: () => void;
+    ensureOverlayWindowsReadyForVisibilityActions: () => void;
+    sendToActiveOverlayWindow: (
+      channel: string,
+      payload?: unknown,
+      runtimeOptions?: {
+        restoreOnModalClose?: OverlayHostedModal;
+        preferModalWindow?: boolean;
+      },
+    ) => boolean;
+    waitForModalOpen: (modal: OverlayHostedModal, timeoutMs: number) => Promise<boolean>;
+    logWarn: (message: string) => void;
+  },
+  payload: MediaTimingReviewOpenPayload,
+): Promise<boolean> {
+  return await retryOverlayModalOpen(
+    { waitForModalOpen: deps.waitForModalOpen, logWarn: deps.logWarn },
+    {
+      modal: MODAL,
+      // The review renderer regularly needs more than the 1.5 s the other modals allow; a
+      // premature retry re-sends the payload and reloads the waveform for nothing.
+      timeoutMs: 4_000,
+      retryWarning:
+        'Media timing review did not acknowledge modal open; retrying the dedicated modal window.',
+      sendOpen: () =>
+        openOverlayHostedModal(deps, {
+          channel: IPC_CHANNELS.event.mediaTimingReviewOpen,
+          modal: MODAL,
+          payload,
+          preferModalWindow: true,
+        }),
+    },
+  );
+}

src/main/runtime/media-timing-review.test.ts

@@ -0,0 +1,859 @@
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import type { MediaTimingReviewOpenPayload } from '../../types/anki';
+import type { SpeechWaveformOptions } from '../../core/services/media-timing-waveform';
+import type {
+  RemoteMediaWindow,
+  RemoteMediaWindowRange,
+  RemoteMediaWindowSource,
+} from '../../core/services/remote-media-window-cache';
+import type { MediaTimingPreviewSession } from '../../core/services/media-timing-preview';
+
+type MediaTimingPreviewSessionLike = Pick<MediaTimingPreviewSession, 'start'>;
+import {
+  buildMediaTimingReviewPayload,
+  collectMediaTimingContextLines,
+  createMediaTimingReviewRuntime,
+} from './media-timing-review';
+
+describe('buildMediaTimingReviewPayload', () => {
+  test('starts from the padded range and leaves two seconds to drag on each side', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'sentence',
+        text: '字幕',
+        startTime: 10,
+        endTime: 12,
+        audioPadding: 0.5,
+        maxMediaDuration: 30,
+      },
+      { reviewId: 'review-1', mediaDuration: 100 },
+    );
+
+    assert.equal(payload.selectionStartTime, 9.5);
+    assert.equal(payload.selectionEndTime, 12.5);
+    assert.equal(payload.timelineStartTime, 7.5);
+    assert.equal(payload.timelineEndTime, 14.5);
+  });
+
+  test('clamps the padded selection and timeline to media bounds', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'word',
+        text: '字幕',
+        startTime: 0.2,
+        endTime: 9.8,
+        audioPadding: 1,
+        maxMediaDuration: 30,
+      },
+      { reviewId: 'review-2', mediaDuration: 10 },
+    );
+
+    assert.equal(payload.selectionStartTime, 0);
+    assert.equal(payload.selectionEndTime, 10);
+    assert.equal(payload.timelineStartTime, 0);
+    assert.equal(payload.timelineEndTime, 10);
+  });
+
+  test('keeps an uncapped selection when max media duration is disabled', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'sentence',
+        text: '字幕',
+        startTime: 10,
+        endTime: 55,
+        audioPadding: 1,
+        maxMediaDuration: 0,
+      },
+      { reviewId: 'review-unlimited', mediaDuration: 100 },
+    );
+
+    assert.equal(payload.selectionStartTime, 9);
+    assert.equal(payload.selectionEndTime, 56);
+    assert.equal(payload.maxMediaDuration, 0);
+  });
+});
+
+async function startActiveMediaTimingReview(
+  options: {
+    maxMediaDuration?: number;
+    decisionTimeoutMs?: number;
+    generateWaveform?: () => Promise<number[]>;
+    play?: () => Promise<void>;
+  } = {},
+) {
+  const previewCalls: Array<[number, number]> = [];
+  let publishPayload!: (payload: MediaTimingReviewOpenPayload) => void;
+  const openedPayload = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
+    publishPayload = resolve;
+  });
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: options.generateWaveform ?? (async () => []),
+    decisionTimeoutMs: options.decisionTimeoutMs,
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async (startTime, endTime) => {
+        previewCalls.push([startTime, endTime]);
+        await options.play?.();
+      },
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      publishPayload(payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+  const pendingDecision = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: options.maxMediaDuration ?? 30,
+  });
+
+  return { runtime, payload: await openedPayload, pendingDecision, previewCalls };
+}
+
+test('media timing review pauses playback, resolves exact timing, and restores playing state', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const previewCalls: Array<[number, number]> = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) =>
+        ({ pause: false, duration: 100, aid: 2, volume: 60 })[
+          name as 'pause' | 'duration' | 'aid' | 'volume'
+        ],
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async (startTime, endTime) => {
+        previewCalls.push([startTime, endTime]);
+      },
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      queueMicrotask(() => {
+        void runtime
+          .previewRange({
+            reviewId: payload.reviewId,
+            startTime: 9.5,
+            endTime: 12.5,
+          })
+          .then(() => {
+            runtime.resolveReview({
+              reviewId: payload.reviewId,
+              decision: { action: 'confirm', startTime: 9.5, endTime: 12.5 },
+            });
+          });
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  const decision = await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    noteId: 42,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(decision, { action: 'confirm', startTime: 9.5, endTime: 12.5 });
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+  assert.deepEqual(previewCalls, [[9.5, 12.5]]);
+});
+
+test('media timing review analyzes the visible range on the selected audio stream', async () => {
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      currentAudioStreamIndex: 4,
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async (options) => {
+      waveformCalls.push(options);
+      return [0.1, 0.8, 0.2];
+    },
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      const waveform = await runtime.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      assert.deepEqual(waveform, { ok: true, peaks: [0.1, 0.8, 0.2] });
+      runtime.resolveReview({
+        reviewId: payload.reviewId,
+        decision: { action: 'use-original' },
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: '/video/show.mkv',
+      startTime: 7.5,
+      endTime: 14.5,
+      audioStreamIndex: 4,
+    },
+  ]);
+});
+
+const REMOTE_STREAM_URL = 'https://jellyfin.example/Videos/abc/stream?static=true';
+
+function createWindowStub(options: { fail?: boolean } = {}) {
+  const calls: Array<{ source: RemoteMediaWindowSource; range: RemoteMediaWindowRange }> = [];
+  const acquireMediaWindow = async (
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> => {
+    calls.push({ source, range });
+    if (options.fail) throw new Error('offline');
+    const windowPath = `/tmp/window-${range.startTime}-${range.endTime}.mkv`;
+    return {
+      path: windowPath,
+      startTime: range.startTime,
+      endTime: range.endTime,
+      sourcePath: source.path,
+      audioStreamIndex: source.audioStreamIndex ?? null,
+      media: {
+        path: windowPath,
+        source: 'remote-window',
+        singleResolvedStream: true,
+        absoluteTimestamps: true,
+      },
+    };
+  };
+  return { calls, acquireMediaWindow };
+}
+
+function createRemoteReviewRuntime(options: {
+  windowStub: ReturnType<typeof createWindowStub>;
+  waveformCalls: SpeechWaveformOptions[];
+  previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]>;
+  previewPlays: Array<[string, number, number]>;
+  disposed: string[];
+  openModal: (
+    runtime: ReturnType<typeof createMediaTimingReviewRuntime>,
+    payload: MediaTimingReviewOpenPayload,
+  ) => Promise<void>;
+}) {
+  let runtime!: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: REMOTE_STREAM_URL,
+      currentAudioStreamIndex: 2,
+      requestProperty: async (name) =>
+        ({ pause: true, duration: 100, aid: 3, volume: 60 })[
+          name as 'pause' | 'duration' | 'aid' | 'volume'
+        ] ?? null,
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => REMOTE_STREAM_URL,
+    getMpvExecutablePath: () => 'mpv',
+    resolveMediaSource: async () => ({
+      path: REMOTE_STREAM_URL,
+      inputOptions: { reconnect: true },
+    }),
+    acquireMediaWindow: options.windowStub.acquireMediaWindow,
+    generateWaveform: async (waveformOptions) => {
+      options.waveformCalls.push(waveformOptions);
+      return [0.1, 0.8, 0.2];
+    },
+    createPreviewSession: () => {
+      let mediaPath = '';
+      return {
+        start: async (startOptions) => {
+          mediaPath = startOptions.mediaPath;
+          options.previewStarts.push(startOptions);
+        },
+        play: async (startTime, endTime) => {
+          options.previewPlays.push([mediaPath, startTime, endTime]);
+        },
+        stop: async () => undefined,
+        onPlaybackEnded: () => undefined,
+        dispose: () => {
+          options.disposed.push(mediaPath);
+        },
+      };
+    },
+    openModal: async (payload) => {
+      await options.openModal(runtime, payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+  return runtime;
+}
+
+test('media timing review downloads one window of a remote stream for the waveform and preview', async () => {
+  const windowStub = createWindowStub();
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      const waveform = await active.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      assert.deepEqual(waveform, { ok: true, peaks: [0.1, 0.8, 0.2] });
+      assert.deepEqual(
+        await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 }),
+        { ok: true },
+      );
+      active.resolveReview({
+        reviewId: payload.reviewId,
+        decision: { action: 'confirm', startTime: 9.5, endTime: 12.5 },
+      });
+    },
+  });
+
+  const decision = await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(decision, { action: 'confirm', startTime: 9.5, endTime: 12.5 });
+  assert.deepEqual(windowStub.calls, [
+    {
+      source: { path: REMOTE_STREAM_URL, inputOptions: { reconnect: true }, audioStreamIndex: 2 },
+      range: { startTime: 7.5, endTime: 14.5 },
+    },
+  ]);
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: {
+        path: '/tmp/window-7.5-14.5.mkv',
+        source: 'remote-window',
+        singleResolvedStream: true,
+        absoluteTimestamps: true,
+      },
+      startTime: 7.5,
+      endTime: 14.5,
+    },
+  ]);
+  assert.deepEqual(previewStarts, [
+    {
+      mediaPath: '/tmp/window-7.5-14.5.mkv',
+      executablePath: 'mpv',
+      volume: 60,
+      absoluteTimestamps: true,
+    },
+  ]);
+  assert.deepEqual(previewPlays, [['/tmp/window-7.5-14.5.mkv', 9.5, 12.5]]);
+  assert.deepEqual(disposed, ['/tmp/window-7.5-14.5.mkv']);
+});
+
+test('media timing review restarts the preview on a wider window when the timeline grows', async () => {
+  const windowStub = createWindowStub();
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 });
+      // The user revealed two more seconds before the clip.
+      await active.getWaveform({ reviewId: payload.reviewId, startTime: 5.5, endTime: 14.5 });
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 6, endTime: 12.5 });
+      active.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+    },
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(
+    windowStub.calls.map((call) => call.range),
+    [
+      { startTime: 7.5, endTime: 14.5 },
+      { startTime: 5.5, endTime: 14.5 },
+    ],
+  );
+  assert.deepEqual(
+    previewStarts.map((start) => start.mediaPath),
+    ['/tmp/window-7.5-14.5.mkv', '/tmp/window-5.5-14.5.mkv'],
+  );
+  assert.deepEqual(previewPlays, [
+    ['/tmp/window-7.5-14.5.mkv', 9.5, 12.5],
+    ['/tmp/window-5.5-14.5.mkv', 6, 12.5],
+  ]);
+  assert.deepEqual(disposed, ['/tmp/window-7.5-14.5.mkv', '/tmp/window-5.5-14.5.mkv']);
+  assert.equal(waveformCalls[0]?.startTime, 5.5);
+});
+
+test('media timing review falls back to the remote stream after one failed window download', async () => {
+  const windowStub = createWindowStub({ fail: true });
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      await active.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 });
+      active.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+    },
+  });
+
+  await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.equal(windowStub.calls.length, 1);
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: { path: REMOTE_STREAM_URL, inputOptions: { reconnect: true } },
+      startTime: 7.5,
+      endTime: 14.5,
+      audioStreamIndex: 2,
+    },
+  ]);
+  assert.deepEqual(previewStarts, [
+    { mediaPath: REMOTE_STREAM_URL, executablePath: 'mpv', volume: 60, audioTrackId: 3 },
+  ]);
+  assert.deepEqual(previewPlays, [[REMOTE_STREAM_URL, 9.5, 12.5]]);
+});
+
+test('media timing review never downloads windows for local media', async () => {
+  const windowStub = createWindowStub();
+  let runtime!: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    resolveMediaSource: async () => ({ path: '/video/show.mkv' }),
+    acquireMediaWindow: windowStub.acquireMediaWindow,
+    generateWaveform: async () => [0.1, 0.8, 0.2],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      await runtime.getWaveform({ reviewId: payload.reviewId, startTime: 7.5, endTime: 14.5 });
+      runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.equal(windowStub.calls.length, 0);
+});
+
+test('media timing review rejects stale and out-of-range actions before allowing discard', async () => {
+  const { runtime, payload, pendingDecision, previewCalls } = await startActiveMediaTimingReview({
+    maxMediaDuration: 3,
+  });
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: 'stale-review', startTime: 10, endTime: 12 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: 'stale-review',
+      decision: { action: 'confirm', startTime: 10, endTime: 12 },
+    }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 10, endTime: 14 },
+    }),
+    { ok: false, message: 'The selected timing range is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 99, endTime: 100.5 },
+    }),
+    { ok: false, message: 'The selected timing range is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 10, endTime: 12, text: '   ' },
+    }),
+    { ok: false, message: 'The combined sentence text is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'discard' } }),
+    { ok: true },
+  );
+  assert.deepEqual(await pendingDecision, { action: 'discard' });
+  assert.deepEqual(previewCalls, []);
+});
+
+test('collectMediaTimingContextLines splits cues around the mined range', () => {
+  const cues = [
+    { text: '一行目', startTime: 0, endTime: 2 },
+    { text: '二行目', startTime: 2.5, endTime: 4 },
+    { text: '', startTime: 4.2, endTime: 4.4 },
+    { text: '採掘行', startTime: 5, endTime: 7 },
+    { text: '四行目', startTime: 7.5, endTime: 9 },
+    { text: '五行目', startTime: 9.5, endTime: 11 },
+  ];
+
+  const context = collectMediaTimingContextLines({ cues, startTime: 5, endTime: 7 });
+
+  assert.deepEqual(context.previous, [
+    { text: '一行目', startTime: 0, endTime: 2 },
+    { text: '二行目', startTime: 2.5, endTime: 4 },
+  ]);
+  assert.deepEqual(context.next, [
+    { text: '四行目', startTime: 7.5, endTime: 9 },
+    { text: '五行目', startTime: 9.5, endTime: 11 },
+  ]);
+});
+
+test('collectMediaTimingContextLines falls back to played history when no cues are loaded', () => {
+  const context = collectMediaTimingContextLines({
+    cues: [],
+    fallbackPrevious: [
+      { displayText: '前の行', startTime: 1, endTime: 2 },
+      { displayText: '採掘行', startTime: 5, endTime: 7 },
+    ],
+    startTime: 5,
+    endTime: 7,
+  });
+
+  assert.deepEqual(context.previous, [{ text: '前の行', startTime: 1, endTime: 2 }]);
+  assert.deepEqual(context.next, []);
+});
+
+test('media timing review watchdog falls back when the renderer stops responding', async () => {
+  const { pendingDecision } = await startActiveMediaTimingReview({ decisionTimeoutMs: 0 });
+
+  assert.deepEqual(await pendingDecision, { action: 'use-original' });
+});
+
+test('media timing review does not resume playback when the prior state is unavailable', async () => {
+  const commands: Array<Array<string | number>> = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async () => null,
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => '',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => {
+        throw new Error('preview unavailable');
+      },
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      queueMicrotask(() => {
+        runtime.resolveReview({
+          reviewId: payload.reviewId,
+          decision: { action: 'use-original' },
+        });
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  assert.deepEqual(
+    await runtime.requestReview({
+      kind: 'sentence',
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+    }),
+    { action: 'use-original' },
+  );
+  assert.deepEqual(commands, [['set_property', 'pause', 'yes']]);
+});
+
+test('media timing review restores playback when setup fails after pausing', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => {
+      throw new Error('preview setup failed');
+    },
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async () => true,
+    showStatus: () => undefined,
+  });
+
+  assert.deepEqual(
+    await runtime.requestReview({
+      kind: 'word',
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+    }),
+    { action: 'use-original' },
+  );
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+test('disposing an open review settles it with original timing and restores playback', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async () => true,
+    showStatus: () => undefined,
+  });
+
+  const pending = runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  await runtime.dispose();
+
+  assert.deepEqual(await pending, { action: 'use-original' });
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+test('media timing review forwards the hidden player finishing a preview to the modal', async () => {
+  const endedReviewIds: string[] = [];
+  const playback: { ended?: () => void } = {};
+  let publishPayload!: (payload: MediaTimingReviewOpenPayload) => void;
+  const openedPayload = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
+    publishPayload = resolve;
+  });
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: (listener) => {
+        playback.ended = listener;
+      },
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      publishPayload(payload);
+      return true;
+    },
+    onPreviewEnded: (reviewId) => {
+      endedReviewIds.push(reviewId);
+    },
+    showStatus: () => undefined,
+  });
+  const pendingDecision = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  const payload = await openedPayload;
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: payload.reviewId, startTime: 10, endTime: 12 }),
+    {
+      ok: true,
+    },
+  );
+  assert.ok(playback.ended);
+  playback.ended();
+  assert.deepEqual(endedReviewIds, [payload.reviewId]);
+
+  runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+  await pendingDecision;
+  playback.ended();
+  assert.deepEqual(endedReviewIds, [payload.reviewId]);
+});
+
+test('preview reports a stale review when the review ends during playback', async () => {
+  let endReview: (() => Promise<void>) | null = null;
+  const { runtime, payload, pendingDecision } = await startActiveMediaTimingReview({
+    play: async () => {
+      await endReview?.();
+    },
+  });
+  endReview = () => runtime.dispose();
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: payload.reviewId, startTime: 10, endTime: 12 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  await pendingDecision;
+});
+
+test('waveform reports a stale review when the review ends during analysis', async () => {
+  let endReview: (() => Promise<void>) | null = null;
+  const { runtime, payload, pendingDecision } = await startActiveMediaTimingReview({
+    generateWaveform: async () => {
+      await endReview?.();
+      return [0.1, 0.9, 0.2];
+    },
+  });
+  endReview = () => runtime.dispose();
+
+  assert.deepEqual(
+    await runtime.getWaveform({ reviewId: payload.reviewId, startTime: 8, endTime: 14 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  await pendingDecision;
+});

src/main/runtime/media-timing-review.ts

@@ -0,0 +1,589 @@
+import { randomUUID } from 'crypto';
+import type {
+  MediaTimingReviewActionResult,
+  MediaTimingReviewContextLine,
+  MediaTimingReviewDecision,
+  MediaTimingReviewOpenPayload,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewWaveformRequest,
+  MediaTimingReviewWaveformResult,
+} from '../../types/anki';
+import type { SpeechWaveformOptions } from '../../core/services/media-timing-waveform';
+import {
+  isRemoteMediaWindowSourcePath,
+  type RemoteMediaWindow,
+  type RemoteMediaWindowRange,
+  type RemoteMediaWindowSource,
+} from '../../core/services/remote-media-window-cache';
+import type { MediaInput, MediaInputOptions } from '../../media-input';
+
+const INITIAL_TIMELINE_MARGIN_SECONDS = 2;
+const REVIEW_DECISION_TIMEOUT_MS = 5 * 60_000;
+const CONTEXT_LINE_LIMIT = 12;
+const CONTEXT_LINE_EPSILON_SECONDS = 0.05;
+
+interface ReviewMpvClient {
+  connected: boolean;
+  currentVideoPath: string;
+  currentAudioStreamIndex?: number | null;
+  requestProperty?: (name: string) => Promise<unknown>;
+  send: (payload: { command: Array<string | number> }) => void;
+}
+
+interface PreviewSession {
+  start(options: {
+    mediaPath: string;
+    executablePath?: string;
+    audioTrackId?: number;
+    volume?: number;
+    absoluteTimestamps?: boolean;
+  }): Promise<void>;
+  play(startTime: number, endTime: number): Promise<void>;
+  stop(): Promise<void>;
+  /** Fires when the player reaches the end of the clip started by play(). */
+  onPlaybackEnded(listener: () => void): void;
+  dispose(): void;
+}
+
+interface ReviewMediaSource {
+  path: string;
+  inputOptions?: MediaInputOptions;
+  singleResolvedStream?: boolean;
+}
+
+interface ActiveReview {
+  payload: MediaTimingReviewOpenPayload;
+  /** What the hidden mpv preview plays when no cached window is available. */
+  mediaPath: string;
+  /** What the waveform reads when no cached window is available. */
+  waveformMedia: MediaInput;
+  audioStreamIndex?: number;
+  /** Remote source to download windows of; null for local media or without a cache. */
+  windowSource: RemoteMediaWindowSource | null;
+  /** Latest window returned for this review; reused while it still covers the request. */
+  window: RemoteMediaWindow | null;
+  windowRequest: (RemoteMediaWindowRange & { promise: Promise<RemoteMediaWindow | null> }) | null;
+  windowFailed: boolean;
+  previewOptions: { executablePath?: string; audioTrackId?: number; volume?: number };
+  preview: { path: string; session: Promise<PreviewSession> } | null;
+  mpvClient: ReviewMpvClient;
+  restorePlayback: boolean;
+  resolve: (decision: MediaTimingReviewDecision) => void;
+}
+
+export interface MediaTimingReviewRuntimeDeps {
+  getMpvClient: () => ReviewMpvClient | null;
+  getCurrentMediaPath: () => string | null;
+  getMpvExecutablePath: () => string;
+  createPreviewSession: () => PreviewSession;
+  generateWaveform: (options: SpeechWaveformOptions) => Promise<number[]>;
+  /** Resolves the FFmpeg-readable stream URL and headers behind the current media path. */
+  resolveMediaSource?: () => Promise<ReviewMediaSource | null>;
+  /** Downloads (or reuses) a local window of a remote source covering the range. */
+  acquireMediaWindow?: (
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ) => Promise<RemoteMediaWindow>;
+  getSubtitleContextLines?: (range: { startTime: number; endTime: number }) => {
+    previous: MediaTimingReviewContextLine[];
+    next: MediaTimingReviewContextLine[];
+  };
+  decisionTimeoutMs?: number;
+  openModal: (payload: MediaTimingReviewOpenPayload) => Promise<boolean>;
+  /** Tells the modal that the hidden player finished the previewed clip. */
+  onPreviewEnded?: (reviewId: string) => void;
+  showStatus: (message: string) => void;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function booleanProperty(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
+  if (value === 'yes' || value === 1) return true;
+  if (value === 'no' || value === 0) return false;
+  return null;
+}
+
+/**
+ * Picks the subtitle lines adjacent to the mined range that the review modal can pull
+ * onto the card. Parsed cues cover both directions; when none are loaded (e.g. the
+ * active track was never parsed) the timing tracker's history still provides the
+ * lines that already played, so only "next" is unavailable.
+ */
+export function collectMediaTimingContextLines(options: {
+  cues: readonly { text: string; startTime: number; endTime: number }[];
+  fallbackPrevious?: readonly { displayText: string; startTime: number; endTime: number }[];
+  startTime: number;
+  endTime: number;
+}): { previous: MediaTimingReviewContextLine[]; next: MediaTimingReviewContextLine[] } {
+  const usable = options.cues
+    .filter(
+      (cue) =>
+        cue.text.trim().length > 0 &&
+        Number.isFinite(cue.startTime) &&
+        Number.isFinite(cue.endTime) &&
+        cue.endTime > cue.startTime,
+    )
+    .sort((a, b) => a.startTime - b.startTime || a.endTime - b.endTime);
+
+  let previous = usable
+    .filter((cue) => cue.endTime <= options.startTime + CONTEXT_LINE_EPSILON_SECONDS)
+    .slice(-CONTEXT_LINE_LIMIT)
+    .map(({ text, startTime, endTime }) => ({ text: text.trim(), startTime, endTime }));
+  const next = usable
+    .filter((cue) => cue.startTime >= options.endTime - CONTEXT_LINE_EPSILON_SECONDS)
+    .slice(0, CONTEXT_LINE_LIMIT)
+    .map(({ text, startTime, endTime }) => ({ text: text.trim(), startTime, endTime }));
+
+  if (previous.length === 0 && options.fallbackPrevious) {
+    previous = options.fallbackPrevious
+      .filter(
+        (entry) =>
+          entry.displayText.trim().length > 0 &&
+          Number.isFinite(entry.startTime) &&
+          Number.isFinite(entry.endTime) &&
+          entry.endTime > entry.startTime &&
+          entry.endTime <= options.startTime + CONTEXT_LINE_EPSILON_SECONDS,
+      )
+      .slice(-CONTEXT_LINE_LIMIT)
+      .map((entry) => ({
+        text: entry.displayText.trim(),
+        startTime: entry.startTime,
+        endTime: entry.endTime,
+      }));
+  }
+  return { previous, next };
+}
+
+/**
+ * Result for requests that name a review main has already resolved or disposed (decision
+ * watchdog, overlay teardown, duplicate modal). The renderer closes on it instead of
+ * leaving the user with controls that can never succeed.
+ */
+function staleReviewResult(): MediaTimingReviewActionResult {
+  return { ok: false, stale: true, message: 'This timing review is no longer active.' };
+}
+
+function isValidMediaTimingRange(
+  payload: MediaTimingReviewOpenPayload,
+  startTime: number,
+  endTime: number,
+): boolean {
+  return (
+    Number.isFinite(startTime) &&
+    Number.isFinite(endTime) &&
+    startTime >= 0 &&
+    endTime > startTime &&
+    (payload.maxMediaDuration <= 0 || endTime - startTime <= payload.maxMediaDuration + 0.001) &&
+    (payload.mediaDuration === undefined || endTime <= payload.mediaDuration + 0.001)
+  );
+}
+
+export function buildMediaTimingReviewPayload(
+  request: MediaTimingReviewRequest,
+  options: {
+    reviewId: string;
+    mediaDuration?: number;
+    contextLines?: {
+      previous: MediaTimingReviewContextLine[];
+      next: MediaTimingReviewContextLine[];
+    };
+  },
+): MediaTimingReviewOpenPayload {
+  const duration = finiteNumber(options.mediaDuration);
+  const maxTime = duration !== null && duration > 0 ? duration : Number.POSITIVE_INFINITY;
+  const paddedStart = Math.max(0, request.startTime - request.audioPadding);
+  let paddedEnd = Math.min(maxTime, request.endTime + request.audioPadding);
+  const maxMediaDuration = Math.max(0, request.maxMediaDuration);
+  if (maxMediaDuration > 0 && paddedEnd - paddedStart > maxMediaDuration) {
+    paddedEnd = paddedStart + maxMediaDuration;
+  }
+  if (paddedEnd <= paddedStart) {
+    paddedEnd = Math.min(maxTime, paddedStart + 0.1);
+  }
+
+  const timelineStartTime = Math.max(0, paddedStart - INITIAL_TIMELINE_MARGIN_SECONDS);
+  const timelineEndTime = Math.max(
+    paddedEnd,
+    Math.min(maxTime, paddedEnd + INITIAL_TIMELINE_MARGIN_SECONDS),
+  );
+
+  return {
+    reviewId: options.reviewId,
+    kind: request.kind,
+    text: request.text,
+    previousLines: options.contextLines?.previous ?? [],
+    nextLines: options.contextLines?.next ?? [],
+    ...(request.noteId !== undefined ? { noteId: request.noteId } : {}),
+    originalStartTime: request.startTime,
+    originalEndTime: request.endTime,
+    selectionStartTime: paddedStart,
+    selectionEndTime: paddedEnd,
+    timelineStartTime,
+    timelineEndTime,
+    ...(duration !== null && duration > 0 ? { mediaDuration: duration } : {}),
+    maxMediaDuration,
+  };
+}
+
+export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDeps) {
+  let active: ActiveReview | null = null;
+  let reviewInProgress = false;
+  let pendingPauseRestore: ReviewMpvClient | null = null;
+
+  function restorePendingPlayback(): void {
+    const mpvClient = pendingPauseRestore;
+    pendingPauseRestore = null;
+    if (mpvClient?.connected) {
+      mpvClient.send({ command: ['set_property', 'pause', 'no'] });
+    }
+  }
+
+  function ensureWindow(
+    review: ActiveReview,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow | null> {
+    const { windowSource } = review;
+    if (!windowSource || review.windowFailed || !deps.acquireMediaWindow) {
+      return Promise.resolve(null);
+    }
+    const coversRange = (candidate: RemoteMediaWindowRange): boolean =>
+      candidate.startTime <= range.startTime && candidate.endTime >= range.endTime;
+    if (review.window && coversRange(review.window)) return Promise.resolve(review.window);
+    const inFlight = review.windowRequest;
+    if (inFlight && coversRange(inFlight)) return inFlight.promise;
+
+    const request = {
+      startTime: range.startTime,
+      endTime: range.endTime,
+      promise: Promise.resolve<RemoteMediaWindow | null>(null),
+    };
+    request.promise = deps
+      .acquireMediaWindow(windowSource, { startTime: range.startTime, endTime: range.endTime })
+      .then((window) => {
+        review.window = window;
+        return window;
+      })
+      .catch(() => {
+        // Fall back to the remote source for the rest of this review instead of retrying.
+        review.windowFailed = true;
+        return null;
+      })
+      .finally(() => {
+        if (review.windowRequest === request) review.windowRequest = null;
+      });
+    review.windowRequest = request;
+    return request.promise;
+  }
+
+  /**
+   * Returns the preview player for the range, restarting it when the range needs a
+   * different file (the first cached window, or a wider one after the timeline grew).
+   */
+  async function previewFor(
+    review: ActiveReview,
+    range: RemoteMediaWindowRange,
+  ): Promise<PreviewSession> {
+    const window = await ensureWindow(review, range);
+    if (active !== review) {
+      // The review ended during the download; do not start a player nobody will dispose.
+      throw new Error('This timing review is no longer active.');
+    }
+    const mediaPath = window?.path ?? review.mediaPath;
+    if (review.preview?.path === mediaPath) return review.preview.session;
+
+    const previous = review.preview;
+    const session = deps.createPreviewSession();
+    session.onPlaybackEnded(() => {
+      if (active === review && review.preview?.session === started) {
+        deps.onPreviewEnded?.(review.payload.reviewId);
+      }
+    });
+    const { audioTrackId, ...previewOptions } = review.previewOptions;
+    const started = session
+      .start({
+        mediaPath,
+        ...previewOptions,
+        // A cached window keeps one audio stream, so mpv's track id from the source no longer applies.
+        ...(window
+          ? { absoluteTimestamps: true }
+          : audioTrackId !== undefined
+            ? { audioTrackId }
+            : {}),
+      })
+      .then(() => session)
+      .catch((error) => {
+        session.dispose();
+        throw error;
+      });
+    review.preview = { path: mediaPath, session: started };
+    void started.catch(() => {});
+    if (previous) void previous.session.then((old) => old.dispose()).catch(() => {});
+    return started;
+  }
+
+  async function runReview(request: MediaTimingReviewRequest): Promise<MediaTimingReviewDecision> {
+    const mpvClient = deps.getMpvClient();
+    const mediaPath =
+      deps.getCurrentMediaPath()?.trim() || mpvClient?.currentVideoPath?.trim() || '';
+    if (!mpvClient?.connected || !mediaPath) {
+      deps.showStatus('Timing review unavailable. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    }
+
+    const [pauseRaw, durationRaw, audioTrackRaw, volumeRaw, resolvedSource] = await Promise.all([
+      mpvClient.requestProperty?.('pause').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('duration').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('aid').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('volume').catch(() => null) ?? null,
+      deps.resolveMediaSource?.().catch(() => null) ?? null,
+    ]);
+    const pauseState = booleanProperty(pauseRaw);
+    mpvClient.send({ command: ['set_property', 'pause', 'yes'] });
+    pendingPauseRestore = pauseState === false ? mpvClient : null;
+
+    let contextLines: ReturnType<NonNullable<typeof deps.getSubtitleContextLines>> | undefined;
+    try {
+      contextLines = deps.getSubtitleContextLines?.({
+        startTime: request.startTime,
+        endTime: request.endTime,
+      });
+    } catch {
+      contextLines = undefined;
+    }
+    const payload = buildMediaTimingReviewPayload(request, {
+      reviewId: randomUUID(),
+      mediaDuration: finiteNumber(durationRaw) ?? undefined,
+      ...(contextLines ? { contextLines } : {}),
+    });
+    const sourcePath = resolvedSource?.path.trim() || mediaPath;
+    const inputOptions = resolvedSource?.inputOptions;
+    const audioStreamIndex =
+      resolvedSource?.singleResolvedStream || mpvClient.currentAudioStreamIndex == null
+        ? undefined
+        : mpvClient.currentAudioStreamIndex;
+    const windowSource: RemoteMediaWindowSource | null =
+      deps.acquireMediaWindow && isRemoteMediaWindowSourcePath(sourcePath)
+        ? {
+            path: sourcePath,
+            ...(inputOptions ? { inputOptions } : {}),
+            audioStreamIndex: audioStreamIndex ?? null,
+          }
+        : null;
+
+    let resolveDecision!: (decision: MediaTimingReviewDecision) => void;
+    const decisionPromise = new Promise<MediaTimingReviewDecision>((resolve) => {
+      resolveDecision = resolve;
+    });
+    const review: ActiveReview = {
+      payload,
+      mediaPath,
+      waveformMedia: inputOptions ? { path: sourcePath, inputOptions } : sourcePath,
+      ...(audioStreamIndex !== undefined ? { audioStreamIndex } : {}),
+      windowSource,
+      window: null,
+      windowRequest: null,
+      windowFailed: false,
+      previewOptions: {
+        executablePath: deps.getMpvExecutablePath(),
+        audioTrackId: finiteNumber(audioTrackRaw) ?? undefined,
+        volume: finiteNumber(volumeRaw) ?? undefined,
+      },
+      preview: null,
+      mpvClient,
+      restorePlayback: pendingPauseRestore === mpvClient,
+      resolve: resolveDecision,
+    };
+    active = review;
+    pendingPauseRestore = null;
+    // Download the visible timeline once now; the waveform and preview both wait on it.
+    void previewFor(review, {
+      startTime: payload.timelineStartTime,
+      endTime: payload.timelineEndTime,
+    }).catch(() => {});
+
+    const opened = await deps.openModal(payload).catch(() => false);
+    if (!opened) {
+      await cleanupActiveReview();
+      deps.showStatus('Timing review could not open. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    }
+
+    const decisionWatchdog = setTimeout(
+      () => resolveDecision({ action: 'use-original' }),
+      Math.max(0, deps.decisionTimeoutMs ?? REVIEW_DECISION_TIMEOUT_MS),
+    );
+    let decision: MediaTimingReviewDecision;
+    try {
+      decision = await decisionPromise;
+    } finally {
+      clearTimeout(decisionWatchdog);
+    }
+    await cleanupActiveReview();
+    return decision;
+  }
+
+  async function requestReview(
+    request: MediaTimingReviewRequest,
+  ): Promise<MediaTimingReviewDecision> {
+    if (active || reviewInProgress) {
+      deps.showStatus('Finish the current timing review before mining another card.');
+      return { action: 'use-original' };
+    }
+    reviewInProgress = true;
+    try {
+      return await runReview(request);
+    } catch {
+      await cleanupActiveReview();
+      restorePendingPlayback();
+      deps.showStatus('Timing review failed. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    } finally {
+      reviewInProgress = false;
+    }
+  }
+
+  async function previewRange(
+    request: MediaTimingReviewPreviewRequest,
+  ): Promise<MediaTimingReviewActionResult> {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (!isValidMediaTimingRange(current.payload, request.startTime, request.endTime)) {
+      return { ok: false, message: 'The selected preview range is invalid.' };
+    }
+    try {
+      const previewSession = await previewFor(current, request);
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      await previewSession.play(request.startTime, request.endTime);
+      // Playback spans the whole clip, so the review can end (watchdog, teardown) while
+      // it runs; reporting success would leave the modal open on a dead review.
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return { ok: true };
+    } catch (error) {
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return {
+        ok: false,
+        message: `Audio preview unavailable: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  async function getWaveform(
+    request: MediaTimingReviewWaveformRequest,
+  ): Promise<MediaTimingReviewWaveformResult> {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (
+      !Number.isFinite(request.startTime) ||
+      !Number.isFinite(request.endTime) ||
+      request.startTime < 0 ||
+      request.endTime <= request.startTime ||
+      (current.payload.mediaDuration !== undefined &&
+        request.endTime > current.payload.mediaDuration + 0.001)
+    ) {
+      return { ok: false, message: 'The waveform range is invalid.' };
+    }
+
+    try {
+      const window = await ensureWindow(current, request);
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      const peaks = await deps.generateWaveform({
+        mediaPath: window?.media ?? current.waveformMedia,
+        startTime: request.startTime,
+        endTime: request.endTime,
+        ...(!window && current.audioStreamIndex !== undefined
+          ? { audioStreamIndex: current.audioStreamIndex }
+          : {}),
+      });
+      // ffmpeg decoding runs long enough for the review to end underneath it.
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      if (peaks.length < 2 || peaks.some((peak) => !Number.isFinite(peak))) {
+        return { ok: false, message: 'Timing waveform is unavailable.' };
+      }
+      return { ok: true, peaks };
+    } catch {
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return { ok: false, message: 'Timing waveform is unavailable.' };
+    }
+  }
+
+  async function stopPreview(reviewId: string): Promise<MediaTimingReviewActionResult> {
+    const current = active;
+    if (!current || reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    try {
+      const previewSession = current.preview ? await current.preview.session : null;
+      await previewSession?.stop();
+      return { ok: true };
+    } catch (error) {
+      return {
+        ok: false,
+        message: `Could not stop preview: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  function resolveReview(request: MediaTimingReviewResolveRequest): MediaTimingReviewActionResult {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (request.decision.action === 'confirm') {
+      const { startTime, endTime, text } = request.decision;
+      if (!isValidMediaTimingRange(current.payload, startTime, endTime)) {
+        return { ok: false, message: 'The selected timing range is invalid.' };
+      }
+      if (text !== undefined && (typeof text !== 'string' || text.trim().length === 0)) {
+        return { ok: false, message: 'The combined sentence text is invalid.' };
+      }
+    }
+    current.resolve(request.decision);
+    return { ok: true };
+  }
+
+  async function cleanupActiveReview(): Promise<void> {
+    const current = active;
+    active = null;
+    if (!current) return;
+    void current.preview?.session.then((session) => session.dispose()).catch(() => {});
+    if (current.restorePlayback && current.mpvClient.connected) {
+      current.mpvClient.send({ command: ['set_property', 'pause', 'no'] });
+    }
+  }
+
+  async function dispose(): Promise<void> {
+    active?.resolve({ action: 'use-original' });
+    await cleanupActiveReview();
+    restorePendingPlayback();
+  }
+
+  return {
+    requestReview,
+    previewRange,
+    getWaveform,
+    stopPreview,
+    resolveReview,
+    dispose,
+  };
+}

src/main/runtime/mpv-main-event-main-deps.test.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { parseAssCues } from '../../core/services/subtitle-cue-parser';
 import { createBuildBindMpvMainEventHandlersMainDepsHandler } from './mpv-main-event-main-deps';
 
 test('mpv main event main deps map app state updates and delegate callbacks', async () => {
@@ -503,14 +504,21 @@ test('canonical ASS cues replace live glyph spam for display, history, and immer
   assert.deepEqual(timing.slice(3), [{ text: '今　手にある物差しでは', start: 1.2, end: 3.8 }]);
   assert.equal(immersion.length, 3);
 
-  // A jump of exactly the seek threshold counts as a seek, matching the time-pos
-  // handler's own `>=` boundary.
-  handlers.onTimePosUpdate?.(4.5);
-  handlers.onTimePosUpdate?.(2);
+  // Jumping back to a brief previous line moves time-pos by less than the general
+  // seek threshold. It is still a backward seek, so the revisited line records
+  // again; otherwise multi-line copy would keep treating the later line as current.
+  handlers.onTimePosUpdate?.(3.9);
+  handlers.onTimePosUpdate?.(2.9);
   handlers.recordSubtitleTiming('今', 0.8, 1.5);
 
   assert.deepEqual(timing.slice(4), [{ text: '今　手にある物差しでは', start: 1.2, end: 3.8 }]);
 
+  // Tiny time-pos jitter is not a seek and must not re-record the line.
+  handlers.onTimePosUpdate?.(3.0);
+  handlers.onTimePosUpdate?.(2.9);
+  handlers.recordSubtitleTiming('今', 0.8, 1.5);
+  assert.equal(timing.length, 5);
+
   handlers.recordImmersionSubtitleLine('Maid\nCafe', 10, 12);
   handlers.recordSubtitleTiming('Maid\nCafe', 10, 12);
   assert.equal(immersion.length, 3);
@@ -575,3 +583,156 @@ test('subtitle-track changes stop stale canonical cues from substituting immedia
   assert.equal(appState.activeParsedSubtitleSource, null);
   assert.equal(handlers.resolveSubtitleText?.('今\n手にある'), '今\n手にある');
 });
+
+test('subtitle recorders drop ASS furigana events the same way the display does', () => {
+  // Broadcast-caption ASS (Caption2Ass style): furigana are separate half-scale events
+  // positioned above their base line, and mpv lists them as their own live lines.
+  const cues = parseAssCues(
+    [
+      '[Script Info]',
+      'PlayResX: 960',
+      'PlayResY: 540',
+      '',
+      '[V4+ Styles]',
+      'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding',
+      'Style: Default,Yu Gothic,46,&H00FFFFFF,&H000000FF,&H00000000,&H7F000000,1,0,0,0,100,100,4,0,1,2,2,1,0,0,0,1',
+      '',
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      'Dialogue: 0,0:04:56.26,0:04:59.63,Default,,0000,0000,0000,,{\\pos(472,443)\\fscx50\\fscy50}あくむ',
+      'Dialogue: 0,0:04:56.26,0:04:59.63,Default,,0000,0000,0000,,{\\pos(172,497)}こんな短時間で{\\fscx50}　{\\fscx100}悪夢{\\fscx50}　{\\fscx100}見んなよ{\\fscx50}。',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(172,407)\\fscx50}（{\\fscx100}平{\\fscx50}）{\\fscx100}暗記教科は{\\fscx50}　{\\fscx100}もう',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(332,443)\\fscx50\\fscy50}かた',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(412,443)\\fscx50\\fscy50}ぱし',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(172,497)}とにかく片っ端から覚えるんだよ{\\fscx50}。',
+    ].join('\n'),
+  );
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'こんな短時間で　悪夢　見んなよ。',
+      '（平）暗記教科は　もう',
+      'とにかく片っ端から覚えるんだよ。',
+    ],
+  );
+
+  const immersion: string[] = [];
+  const timing: string[] = [];
+  const handlers = createBuildBindMpvMainEventHandlersMainDepsHandler({
+    appState: {
+      initialArgs: null,
+      overlayRuntimeInitialized: true,
+      mpvClient: { currentTimePos: 299.7 },
+      immersionTracker: { recordSubtitleLine: (text: string) => immersion.push(text) },
+      subtitleTimingTracker: { recordSubtitle: (text: string) => timing.push(text) },
+      activeParsedSubtitleCues: cues,
+      currentSubText: '',
+      currentSubAssText: '',
+      playbackPaused: null,
+      previousSecondarySubVisibility: false,
+    },
+    getQuitOnDisconnectArmed: () => false,
+    scheduleQuitCheck: () => {},
+    quitApp: () => {},
+    reportJellyfinRemoteStopped: () => {},
+    syncOverlayMpvSubtitleSuppression: () => {},
+    maybeRunAnilistPostWatchUpdate: async () => {},
+    logSubtitleTimingError: () => {},
+    broadcastToOverlayWindows: () => {},
+    onSubtitleChange: () => {},
+    ensureImmersionTrackerInitialized: () => {},
+    updateCurrentMediaPath: () => {},
+    restoreMpvSubVisibility: () => {},
+    getCurrentAnilistMediaKey: () => null,
+    resetAnilistMediaTracking: () => {},
+    maybeProbeAnilistDuration: () => {},
+    ensureAnilistMediaGuess: () => {},
+    syncImmersionMediaState: () => {},
+    updateCurrentMediaTitle: () => {},
+    resetAnilistMediaGuessState: () => {},
+    reportJellyfinRemoteProgress: () => {},
+    updateSubtitleRenderMetrics: () => {},
+    refreshDiscordPresence: () => {},
+  })();
+
+  const liveText = '（平）暗記教科は　もう\nかた\nぱし\nとにかく片っ端から覚えるんだよ。';
+  const expected = '（平）暗記教科は　もう\n\nとにかく片っ端から覚えるんだよ。';
+  assert.equal(handlers.resolveSubtitleText?.(liveText), expected);
+  handlers.recordImmersionSubtitleLine(liveText, 299.63, 303.54);
+  handlers.recordSubtitleTiming(liveText, 299.63, 303.54);
+
+  assert.deepEqual(immersion, [expected]);
+  assert.deepEqual(timing, [expected]);
+});
+
+test('a resolved line survives recording while a fragment grid is on screen', () => {
+  // Fragment stripping drops every line it can trace back to a cue, and returns nothing
+  // at all when a fragment grid is nearby. Text the parsed cues already resolved is a
+  // complete line, not raw mpv output, so it must not be fed through that path.
+  const immersion: string[] = [];
+  const timing: string[] = [];
+  const handlers = createBuildBindMpvMainEventHandlersMainDepsHandler({
+    appState: {
+      initialArgs: null,
+      overlayRuntimeInitialized: true,
+      mpvClient: { currentTimePos: 3.2 },
+      immersionTracker: { recordSubtitleLine: (text: string) => immersion.push(text) },
+      subtitleTimingTracker: { recordSubtitle: (text: string) => timing.push(text) },
+      activeParsedSubtitleCues: [
+        { startTime: 3, endTime: 6, text: '飛び越えてみたくて', source: 'canonical-ass' },
+        {
+          startTime: 3,
+          endTime: 6,
+          text: 'MaidCafeMaidCafe',
+          source: 'reconstructed-ass',
+          assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+        },
+      ],
+      currentSubText: '',
+      currentSubAssText: '',
+      playbackPaused: null,
+      previousSecondarySubVisibility: false,
+    },
+    getQuitOnDisconnectArmed: () => false,
+    scheduleQuitCheck: () => {},
+    quitApp: () => {},
+    reportJellyfinRemoteStopped: () => {},
+    syncOverlayMpvSubtitleSuppression: () => {},
+    maybeRunAnilistPostWatchUpdate: async () => {},
+    logSubtitleTimingError: () => {},
+    broadcastToOverlayWindows: () => {},
+    onSubtitleChange: () => {},
+    ensureImmersionTrackerInitialized: () => {},
+    updateCurrentMediaPath: () => {},
+    restoreMpvSubVisibility: () => {},
+    getCurrentAnilistMediaKey: () => null,
+    resetAnilistMediaTracking: () => {},
+    maybeProbeAnilistDuration: () => {},
+    ensureAnilistMediaGuess: () => {},
+    syncImmersionMediaState: () => {},
+    updateCurrentMediaTitle: () => {},
+    resetAnilistMediaGuessState: () => {},
+    reportJellyfinRemoteProgress: () => {},
+    updateSubtitleRenderMetrics: () => {},
+    refreshDiscordPresence: () => {},
+  })();
+
+  // The grid fragment beside the lyric keeps canonical substitution from applying, so
+  // recording falls to the parsed view -- which is where the whole line is recovered.
+  const liveText = '飛び越え\nMaid';
+  assert.equal(handlers.resolveSubtitleText?.(liveText), '飛び越えてみたくて');
+  handlers.recordImmersionSubtitleLine(liveText, 3, 6);
+  handlers.recordSubtitleTiming(liveText, 3, 6);
+
+  assert.deepEqual(immersion, ['飛び越えてみたくて']);
+  assert.deepEqual(timing, ['飛び越えてみたくて']);
+
+  // A spacer event left as literal control debris is not a subtitle line. The display
+  // drops it, so no recorder may keep it either.
+  assert.equal(handlers.resolveSubtitleText?.('\\'), '');
+  handlers.recordImmersionSubtitleLine('\\', 3, 6);
+  handlers.recordSubtitleTiming('\\', 3, 6);
+
+  assert.equal(immersion.length, 1);
+  assert.equal(timing.length, 1);
+});