feat(subtitles): optimize anime stream audio extraction

- Prefer matching audio and lower-resolution sources with HLS sampling - Reuse verified audio within sessions and clean temporary files on shutdown - Allow character dictionary sync without loaded subtitles
feat(subtitles): generate subtitles from anime streams
2026-11-14 04:46:07 -08:00 · 2026-09-22 00:20:54 -07:00 · 2026-09-21 21:28:15 -07:00 · 2026-09-21 00:18:32 -07:00 · 2026-09-21 00:10:00 -07:00 · 2026-09-21 00:09:48 -07:00
541 changed files with 41400 additions and 2020 deletions
@@ -13,6 +13,9 @@ on:
        required: true
      APPLE_TEAM_ID:
        required: true
+      # Project TMDB key baked into release artifacts; builds stay valid without it.
+      SUBMINER_TMDB_API_KEY:
+        required: false

 permissions:
  contents: read
@@ -69,6 +72,8 @@ jobs:

      - name: Build AppImage
        run: bun run build:appimage
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}

      - name: Build unversioned AppImage
        run: |
@@ -168,6 +173,7 @@ jobs:
      - name: Build signed + notarized macOS artifacts
        run: bun run build:mac
        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
@@ -248,6 +254,8 @@ jobs:

      - name: Build unsigned Windows artifacts
        run: bun run build:win:unsigned
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}

      - name: Smoke packaged runtime assets
        shell: bash
@@ -27,6 +27,7 @@ jobs:
      APPLE_ID: ${{ secrets.APPLE_ID }}
      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}

  release:
    needs: [package]
@@ -93,12 +93,20 @@ jobs:
          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
          lua -v

-      - name: Test suite (source)
-        run: bun run test:fast
+      - name: Launcher unit and script suites
+        run: bun run test:launcher:unit:src && bun run test:scripts

      - name: Environment suite
        run: bun run test:env

+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
      - name: Coverage suite (maintained source lane)
        run: bun run test:coverage:src

@@ -112,17 +120,6 @@ jobs:
      - name: Stats UI tests
        run: bun run test:stats

-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
      - name: Build (bundle)
        run: bun run build

@@ -28,6 +28,7 @@ jobs:
      APPLE_ID: ${{ secrets.APPLE_ID }}
      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}

  release:
    needs: [package]
@@ -86,10 +86,18 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
    <td><b>Jellyfin</b></td>
    <td>Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray</td>
  </tr>
+  <tr>
+    <td><b>Anime Browser</b></td>
+    <td>Search anime sources you supply as <a href="https://github.com/aniyomiorg/aniyomi">Aniyomi</a> extension APKs and play an episode in mpv with the overlay attached (<code>subminer anime</code>); SubMiner ships no repositories and bundles no sources</td>
+  </tr>
  <tr>
    <td><b>Jimaku</b></td>
    <td>Search and download Japanese subtitles</td>
  </tr>
+  <tr>
+    <td><b>Japanese Subtitle Generation</b></td>
+    <td>Generate Japanese subtitles from local files or finite anime streams in a standalone modal (<code>Ctrl+Shift+G</code>) or the sidebar button. The launcher supports local files. Transcription runs locally with whisper.cpp and FFmpeg, with progress and optional managed model downloads. Stream subtitles are saved in the application cache. Optional Silero speech detection prioritizes dialogue in separately timed passages. <a href="https://docs.subminer.moe/main/subtitle-generation">Setup guide</a></td>
+  </tr>
  <tr>
    <td><b>TsukiHime</b></td>
    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>) — no API key, requires <code>xz</code> on your <code>PATH</code></td>
@@ -178,6 +186,8 @@ See the [full requirements list](https://docs.subminer.moe/installation#_1-insta

 ```bash
 paru -S subminer-bin
+# optional: the anime browser bridge, shared with Mangatan and updated by pacman
+paru -S mangatan-extension-server
 ```

 </details>
@@ -260,22 +270,40 @@ Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more

 SubMiner builds on the work of these open-source projects:

-| Project                                                                                     | Role                                                                    |
-| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [ani-skip](https://github.com/synacktraa/ani-skip)                                          | AniSkip API client for anime intro/outro skip timestamps                |
-| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
-| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
-| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
-| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                |
-| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
-| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
-| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
-| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
-| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser     |
-| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
+| Project                                                                                     | Role                                                                         |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [ani-skip](https://github.com/synacktraa/ani-skip)                                          | AniSkip API client for anime intro/outro skip timestamps                     |
+| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                          |
+| [Aniyomi](https://github.com/aniyomiorg/aniyomi)                                            | Anime extension API and data model the anime browser targets                 |
+| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing      |
+| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                      |
+| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                     |
+| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration                    |
+| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                         |
+| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                       |
+| [M-Extension-Server](https://github.com/1Selxo/M-Extension-Server)                          | Runs Aniyomi extension APKs off Android; the bridge the anime browser drives |
+| [Mangatan](https://github.com/1Selxo/Mangatan)                                              | Reference client for the bridge protocol the anime browser speaks            |
+| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                                |
+| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser          |
+| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                               |
+
+## Disclaimer
+
+SubMiner is a media player and language-learning tool. The project does not
+host, supply, or link to anime, video streams, or subtitle libraries. The anime
+browser runs Aniyomi extensions that you install yourself from repositories you
+choose; SubMiner bundles none and recommends none. The SubMiner developers are
+not affiliated with any content provider and have no control over what those
+sources offer, whether they stay available, or the quality of what they serve.

 ## License

-SubMiner is released under the [GNU General Public License v3.0](LICENSE).
+[GNU General Public License v3.0](LICENSE)
+
+The anime browser drives [M-Extension-Server](https://github.com/1Selxo/M-Extension-Server),
+downloaded from its upstream releases at runtime rather than
+bundled or redistributed here; its bundles carry their own dependencies, including a JRE and
+GPL-3.0 NewPipe Extractor. SubMiner includes none of them and talks to the bridge
+over its own HTTP protocol. It ships no extensions or repositories by default.

 Release packages also bundle an unmodified copy of [Bun](https://github.com/oven-sh/bun), which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under `resources/bun/licenses`, and each release publishes `bun-v1.3.5-source.tar.gz` with the corresponding source. See [Bundled Bun runtime](https://docs.subminer.moe/installation#bundled-bun-runtime).
@@ -0,0 +1,7 @@
+type: fixed
+area: anilist
+
+- Resolving "season N" against AniList no longer lands one season short for franchises whose broadcast seasons are listed as several entries. AniList records the back half of a split cour ("… Season 2 Part 2", "… Cour 2", "第2クール") as its own sequel, and the resolver counted each as a season — so Mushoku Tensei season 3 resolved to the season 2 entry and Re:ZERO season 4 to season 3, which then drove the character dictionary and AniList progress updates to the wrong series. A sequel carrying a part or cour marker that matches the season it continues is now followed without advancing the season count, in both the relation walk and the air-order fallback. Titles are compared ignoring punctuation, and the marker is looked for in every title and synonym rather than just the display title. A wrong match cached before this fix is remembered in `character-dictionaries/anilist-resolution-cache.json` and needs removing (or overriding from the character dictionary picker) for the affected series.
+- A special or OVA sitting in a franchise's sequel chain is walked through without counting as a season. Dr. STONE links STONE WARS to New World through a one-episode special, which made New World resolve as season 4 and every later season shift with it.
+- An AniList rate limit or network failure while walking sequel relations is reported so the caller can retry, instead of falling through to the air-date fallback. That fallback is for a franchise with missing relation edges; running it after a failed lookup turned a transient 429 into a confidently wrong season.
+- The shared title parser recognizes spelled-out episode labels (`Episode 4`, `第4話`) and a season named at the end of the title (`… Season 3`, `… 3rd Season`, `… S3`), which now fill the Season field instead of being searched for as part of the series name. The TsukiHime modal gained a Season field to match Jimaku, and seasons after the first are included in its search query so a later season's releases are actually found.
@@ -0,0 +1,4 @@
+type: docs
+area: anime
+
+- Added a README disclaimer stating that SubMiner hosts no content, ships no anime sources or repositories, is not affiliated with any content provider, and that users are responsible for the content they access. The anime browser docs no longer describe SubMiner as a "host" of extensions.
@@ -0,0 +1,36 @@
+type: added
+area: anime
+
+- Added an anime browser window that searches Aniyomi extension sources, shows cover art and episode lists, and plays an episode in mpv so the overlay and mining tools attach as usual.
+- Browser failures show a dismissible explanation with next steps and expandable technical details, including the bridge's error response instead of only its HTTP status.
+- Added `subminer anime` and the `--anime` flag to open the browser, plus a "Browse Anime" tray entry.
+- Anime extensions are read from `<userData>/anime-extensions`; drop Aniyomi `.apk` files there to add sources.
+- Added a source settings tab so extensions that need configuration (server address, credentials, quality) can be set up from the browser; values persist per extension and source, and updated extension schemas replace stale saved field definitions without losing values. Older unscoped preferences are discarded once because their package ownership cannot be proven safely.
+- Added an Extensions tab for adding repository URLs and installing, updating, or removing extensions in place; extensions that fail to load are listed with the reason. Repository requests time out instead of hanging, APK updates are staged before replacing the installed copy, and removing an extension refreshes the runtime even when saved credential cleanup fails while still reporting that failure.
+- Browse, Extensions, and Source settings are tabs, so each one gets the full window instead of sharing it with the search results.
+- Repository URLs only need to be an https URL to a `.json` index; the file name is not restricted to `index.min.json`.
+- The source picker offers "All sources", which searches every installed source at once. Results stream in as each source answers, with per-source progress in the status bar. Results are tagged with their source, failures do not blank the grid, and **Load more** appends later pages without duplicating streamed entries.
+- The Extensions tab opens with an Installed section listing every extension on disk with Remove, including ones added by hand or whose repository has since been removed. It compares APK and repository version codes, enables Update only for newer builds, marks current extensions as Up to date, and offers Update all when multiple updates are waiting.
+- Added `anime.repos`, `anime.extensionsDir`, `anime.preferredQuality`, and `anime.defaultSource` config keys; **Set default** on an Installed row in the Extensions tab makes that source (or All sources) the one the browser opens on, and the current default carries a tag. SubMiner ships no extension repositories and performs no discovery.
+- The settings app now groups Anime Browser config under an **Aniyomi** section in Integrations. A new `anime.autoOpenJimaku` option pauses newly loaded Anime Browser episodes, waits for mpv's video window to appear, closes the in-player browser, hides the standalone browser window so it is not pulled in front of mpv when the modals close, opens Jimaku with the episode details filled in, and resumes after a subtitle loads or the modal closes without overriding playback that was already paused.
+- Anime playback targets Japanese audio: dub-labelled entries are skipped when the source offers an alternative, `alang` prefers Japanese, and the source's own audio and subtitle tracks are loaded into mpv (Japanese selected) instead of being discarded, so all of them can be switched from mpv's track menu.
+- The primary subtitle slot stays reserved for Japanese: a source that only has, say, English subtitles gets them added with a normalized language tag (`English` → `en`) but not selected, so the regular `secondarySub` auto-load can route them to the secondary slot instead.
+- HLS streams pass through a local strip proxy that removes fake image headers some hosts glue onto their video segments and gives disguised segment URLs (`.image`, `.jpg`, `.css`, and other rotating fake extensions) a media-safe local alias, so those streams play in mpv and support Anki audio and image extraction with current ffmpeg releases. Upstream responses use identity encoding so playlists remain readable for URL rewriting.
+- The strip proxy retries a failed segment fetch once after a short pause and logs upstream error statuses; a host that errors on the very first fetches right after an episode resolves no longer kills the whole playback, disconnecting clients release their active upstream fetch instead of consuming the socket and bandwidth in the background, stalled response bodies retain the upstream inactivity timeout, and only origin-form requests can reach the configured local bridge.
+- The strip proxy no longer forwards `Range` headers to the bridge: ffmpeg opens every HLS segment with `Range: bytes=0-`, the bridge answers some of those with 206, and a partial response bypassed the disguise strip, so whether an episode played depended on the bridge's cache state.
+- A bridge that dies out from under the app (killed, crashed, or stopped mid-operation) no longer leaves the browser failing every request until an app restart: the exit is detected, surfaced in the status bar, and the bridge restarts on the next request.
+- "Playing" is only reported once mpv actually configures a video output; slow streams remain loading while mpv opens them, and failed streams show mpv's error.
+- The bridge bundle is downloaded from the newest upstream release that ships a bundle for the platform (skipping releases older than the oldest server SubMiner is known to work with), the same way Mangatan fetches it, so all four published bundles (macOS arm64 and x64, Linux x64, Windows x64) work without a maintainer hashing each one first.
+- The Extensions tab's available list has a language chip row: pick one or more languages to narrow a repository index that otherwise lists every language it knows, or "All" to clear the filter. Rows name the language ("Japanese" instead of `ja`) and the Available heading counts what the filter leaves.
+- A stream's subtitle tracks are downloaded to a temp directory and loaded into mpv as files rather than streamed from the source URL, so they can serve as the alass reference in Subsync the way Jellyfin subtitles do. The format is detected from the file's own content, a track that fails to download falls back to its URL so the episode still plays, and the directory is removed when the next episode starts or the app exits.
+- An episode launched from the browser carries its series, season and episode number through the app instead of a single joined string: stats group by series (every stream previously landed in one entry named `m3u8`), rewatching reuses the existing entry, the Jimaku and TsukiHime modals prefill Title/Season/Episode from the source's own listing, AniList updates use those fields directly, and the mpv title reads `Series S03E04 - Episode Name`.
+- Opening the browser shows a tray icon on every platform and — on macOS — puts the app in the Cmd+Tab switcher and Dock, so you can switch between it and mpv; the Dock icon is released again when the window closes during playback. Launching a video starts a regular SubMiner session, and in `subminer anime` standalone mode closing the window during playback no longer quits the app and kills the stream.
+- The episode list has a filter box: type an episode number (`12`), a range (`12-18`), or part of an episode name to narrow a long list, with a `6 of 25` counter while it is applied. Escape inside the box clears the filter instead of leaving the detail page.
+- Episodes already watched are dimmed and marked in the episode list, with a watched count in the header. The marks come from the stats history playback already writes (an episode is marked once a session passes the completion threshold), so they match the stats window and survive the stream URL changing between playbacks. They refresh when the browser window comes back to the front, and stay empty when immersion tracking is disabled.
+- Right-clicking an episode opens a menu for marking it watched or unwatched by hand, plus "Mark this and N below watched/unwatched" for the episode and every episode listed under it. Sources list newest first, so a span covers the back catalogue, which is how a series watched elsewhere gets caught up. A filter never narrows what a span covers, and the status bar reports how many episodes were touched.
+- Marking an episode that was never played creates its stats row, carrying the same series, season and episode fields playback would have recorded. Both stats library views join the lifetime tables, so a manual mark does not show up there as watch time nobody spent, and clearing a mark creates nothing.
+- Episodes can be queued instead of replacing what is playing. Every episode row has **Play** and **Queue** buttons (clicking the row still plays now), the right-click menu offers the same two, and a queued episode shows its place in line ("next up", "#2 in queue") with a queue count and **Clear queue** in the episode header. The queue spans anime, resolves and appends each episode to mpv's real playlist as soon as it is queued while subtitle tracks cache in the background, so next/previous navigation works immediately and the next episode starts without a resolution pause when the current one ends. Queueing with nothing playing just plays.
+- Added an in-player Anime Browser modal on `Ctrl+Alt+A`. The shortcut toggles it without losing its page or scroll position. It stays within the player bounds and shares the active episode, playback queue, source configuration, and watch history with the standalone browser, while each surface keeps independent search and navigation state. The modal validates its embedded page before changing overlay state, so a load setup failure leaves it closed rather than revealing a broken modal. The SubMiner logo identifies the Anime Browser in both the modal and standalone window.
+- The bridge is reused from a package-manager install when one exists: on Arch the AUR `mangatan-extension-server` package (shared with Mangatan) is picked up from `/usr/share/mangatan/extension_server`, so nothing is downloaded and pacman keeps it current. `anime.bridgeDir` points SubMiner at a bundle anywhere else. `subminer-bin` lists the package as an optional dependency.
+- Once the bridge is running, SubMiner checks GitHub for a newer release, including for AUR and custom installations. AUR update notices direct users to their AUR helper; custom installs get manual-update guidance. Only SubMiner-managed copies offer an **Update to vX** button. The new release is downloaded beside the running bridge, then the bridge restarts on it. The updater waits for a bridge still starting to stop and keeps the previous bundle until the replacement is active. The Extensions tab shows the bridge version, where it lives, and who updates it without describing an unchecked install as current.
+- The detail page keeps its episode list when only the details call fails: the episodes render with a "Details unavailable" note and the error in the status bar, instead of an empty page.
@@ -0,0 +1,4 @@
+type: docs
+area: anime
+
+- Document how the anime browser waits for slow streams to start without reporting a premature playback failure.
@@ -0,0 +1,5 @@
+type: docs
+area: subtitles
+
+- Document anime stream generation, audio-only and lower-resolution extraction candidates, concurrent HLS downloads, temporary disk usage, audio cache reuse and limits, full-episode processing, supported audio tracks, and stream access limitations.
+- Explain HLS source-check diagnostics and session-only audio cleanup on quit and after crashes.
@@ -0,0 +1,6 @@
+type: added
+area: subtitles
+
+- Generate Japanese subtitles from finite HTTP/HTTPS anime episode streams in the existing generation modal. Reuse mpv's supported request headers and the anime proxy, transcribe downloaded audio locally, retain generated SRT files in the application cache, and load them only into the matching stream. Local-file generation and the launcher keep their existing behavior.
+- Prepare plain HLS episodes with up to four concurrent segment downloads, preserving audio order and timing. Show download progress, cancel active requests together, and retain FFmpeg extraction for complex playlists.
+- Reduce anime-stream extraction downloads by preferring separate Japanese audio or lower-resolution video when duration and sampled audio match playback. Sample HLS through short local segment windows, account for timestamp origins, retry empty original samples, and report why candidates are rejected. Selected external HTTP audio tracks are extracted directly with their playback delay preserved. Reuse verified completed audio across transcription retries and model changes within the current app session. Remove downloaded audio and working files on quit, recover abandoned sessions on startup, and preserve saved subtitles.
@@ -0,0 +1,4 @@
+type: docs
+area: subtitles
+
+- Clarify that character dictionary sync works without a subtitle track and explain readiness and import timeouts.
@@ -0,0 +1,4 @@
+type: fixed
+area: subtitles
+
+- Let character dictionaries finish syncing when no Japanese subtitles are loaded. Wait for Yomitan extension readiness instead of the first processed subtitle, and report readiness failures instead of leaving the notification stuck on Checking.
@@ -0,0 +1,4 @@
+type: internal
+area: ci
+
+- Removed duplicate source and launcher smoke executions from the reusable quality gate while preserving every distinct test lane and failure artifact.
@@ -0,0 +1,4 @@
+type: internal
+area: verification
+
+- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check for compiled stats startup, HTTP service, native SQLite, port conflicts, and cleanup.
@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Added `ankiConnect.fields.wordAudio` to read word audio separately from the generated sentence-audio destination, fixing animated images that start moving immediately when `fields.audio` points to `SentenceAudio`.
@@ -0,0 +1,4 @@
+type: fixed
+area: config
+
+- Validate direct AnkiConnect, Kiku, and Senren settings before admitting them to runtime config, with warnings and defaults for invalid values.
@@ -0,0 +1,5 @@
+type: fixed
+area: runtime
+
+- Shutdown finishes independent media and Discord cleanup and waits for sync shutdown even when Jellyfin cleanup fails, then reports the first cleanup error.
+- Tsukihime ignores delayed media-info results and errors from a closed modal session.
@@ -0,0 +1,7 @@
+type: fixed
+area: jellyfin
+
+- Set the mpv title before loading Jellyfin streams and reject URL-derived titles from metadata lookups, Anki source fields, Discord presence, and stats.
+- Keep authenticated stream URLs out of stats identities even when playback metadata has not arrived.
+- Remove previously cached credential-bearing Jellyfin stream parser metadata without changing unrelated anime metadata, watch history, or library assignments.
+- Use safe media identities for persisted AniList retry keys, discard URL-derived queued searches, and skip updates and retries whose media identity is empty.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Clicking a subtitle sidebar cue releases row focus, and Space no longer seeks back to a focused cue. Enter still seeks the focused cue, and Space keeps its configured playback action.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Reject malformed resource IDs and partly invalid ID lists before stats library mutations or cover backfills run.
@@ -0,0 +1,5 @@
+type: fixed
+area: stats
+
+- Stats server startup reports port conflicts without crashing SubMiner, shares concurrent startup requests, and shows in-app startup errors through configured status notifications.
+- Background stop cancels pending background startup without disconnecting foreground-only dashboards. Shutdown bounds the wait for active HTTP requests and awaits tracker finalization before exit, with a deadline for forced application exit.
@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Closing the overlay while media timing review is still loading now cancels setup and modal retries, restores playback if the review paused it, and cleans up the hidden preview player.
@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Treat `ankiConnect.media.maxMediaDuration: 0` as unlimited for stats dashboard mining, matching overlay mining and configuration.
@@ -0,0 +1,5 @@
+type: docs
+area: subtitles
+
+- Explain how dialogue generation retains uncertain audible sections, why songs may also be transcribed, how detected speech starts guide long-passage cuts to reduce early subtitles, and why each passage uses a fresh Whisper process.
+- Document automatic loaded subtitle references, English dialogue preference, signs/songs filtering, fallback behavior, and the limits of reference-guided timing.
@@ -0,0 +1,8 @@
+type: added
+area: subtitles
+
+- Generate local Japanese SRT subtitles with whisper.cpp from a standalone modal opened with Ctrl+Shift+G, the empty subtitle sidebar's generation button, or `subminer generate-subs`, with shared progress reporting, cancellation, safe output files, and automatic loading into the matching mpv video. The sidebar button hides while subtitle lines are loaded.
+- Configure an existing multilingual model in Settings or choose an official multilingual model, including quantized variants, in the modal or launcher. The modal shows download sizes, speed and accuracy guidance, and a recommended starting model before explicitly downloading a verified SubMiner-managed model. Executable paths are optional overrides; empty fields find whisper-cli, ffmpeg, and ffprobe on PATH. The modal's Local tools check and the launcher name any missing executable and its setting before downloading a model or extracting audio, and generation confirms the destination directory grants write and search permissions up front.
+- Optionally select Focus on spoken dialogue in the modal and use Download speech detection model to install the separate Silero model with progress and cancellation. The choice lasts for the session; a configured VAD model path sets the default. Retain uncertain audible sections so VAD rejection does not discard dialogue under music, accepting that songs may also be transcribed. Keep passages intact within Whisper's audio window, split longer passages near detected speech starts or quiet pauses with overlapping context to reduce early subtitle timing, and combine overlapping duplicate cues even when punctuation differs. Run each passage in a fresh Whisper process to prevent repeated-character output caused by state carried between files, at the cost of reloading the model per passage. Preserve original media timing and separate repeated dialogue.
+- Recommend large-v3-turbo in the model picker when NVIDIA hardware and CUDA device support in the selected Whisper executable are confirmed; recommend small otherwise. Preserve configured and session model selections. Use a wider generation modal to reduce text wrapping and scrolling, while keeping it within smaller player windows.
+- Automatically use an eligible embedded or external subtitle track loaded in mpv to guide long-passage cuts, preferring English dialogue and excluding tracks marked signs, songs, forced, or generated. Honor active subtitle delays, retain unreferenced audio, and fall back to audio timing when references cannot be read. Available in the overlay and launcher, with or without VAD. The launcher captures audio selection, reference tracks, and delays before model setup so playback changes during a download do not mix inputs from different times, and rejects an unverified media snapshot before using mpv's selected audio stream.
@@ -0,0 +1,5 @@
+type: docs
+area: jellyfin
+
+- Explain how Jellyfin media titles, unknown-title fallbacks, and stats identities keep stream credentials out of metadata.
+- Document AniList rejection of empty media identities and the conditions for clearing cached Jellyfin parser metadata.
@@ -0,0 +1,4 @@
+type: added
+area: jimaku
+
+- Jimaku modal gains Anime / Live action tabs so searches can pull from Jimaku's live action catalogue instead of only anime entries (Arrow Left / Right switch tabs).
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed the overlay never loading (stuck on the "Overlay loading" OSD spinner) when the Yomitan content-script reload raced overlay window creation at startup, most visible when playing from the anime browser on Linux/Wayland: a hidden window stops painting after that reload, so the ready-to-show signal that gates showing the overlay never fired. Content-ready now falls back to did-finish-load after a short grace period.
@@ -0,0 +1,4 @@
+type: fixed
+area: macos
+
+- `subminer anime` (and `--settings` / `--sync`) now bring their window to the front on macOS. `show()`/`focus()` only reorder windows inside the app that is already active, so the window opened behind the terminal that launched it; SubMiner now activates itself when opening one. The anime browser also restores its Dock icon before showing rather than after, because the overlay's fullscreen transform leaves the app as an accessory process that macOS refuses to bring forward at all.
@@ -0,0 +1,4 @@
+type: docs
+area: mining
+
+- Document independent screenshot selection in media timing review.
@@ -0,0 +1,4 @@
+type: added
+area: mining
+
+- Choose a still screenshot independently of the audio in media timing review, with a live preview, a separate time slider, and decoded-frame stepping. Local video and seekable remote streams such as Jellyfin are supported.
@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- The overlay discovers non-conflicting keyboard bindings from mpv defaults, input.conf, and loaded scripts in the background. SubMiner controls and explicitly disabled bindings take precedence. Discovered bindings stay session-only and do not appear in SubMiner's help menu.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Cancel pending Linux overlay window replacements during teardown so a delayed close callback cannot reopen the overlay.
@@ -0,0 +1,4 @@
+type: docs
+area: config
+
+- Clarified live-setting save feedback, mixed restart warnings, and subtitle-generation reload behavior.
@@ -0,0 +1,5 @@
+type: fixed
+area: config
+
+- Settings marked LIVE now use the same reload policy as save results, fixing false restart warnings for notifications and subtitle generation.
+- Mixed saves apply live changes and list only sections with changed fields that require a restart.
@@ -0,0 +1,6 @@
+type: changed
+breaking: true
+area: stats
+
+- Reject requests from untrusted browser origins and hosts before stats data, media, or Anki operations run, and require JSON for mutation bodies.
+- Load the in-app stats overlay from the local server so it uses the same origin protection as the browser dashboard.
@@ -0,0 +1,4 @@
+type: fixed
+area: subsync
+
+- Subsync no longer fails with `Protocol "file:" not supported` on a subtitle that was dropped onto mpv. mpv reports such a track as a percent-encoded `file://` URL, which subsync read as a stream and tried to fetch over HTTP; the URL is now decoded back to its path, so both the retimed target and an alass reference work. A `file://` video path is treated as local too, which restores the video reference and ffsubsync for a dropped file.
@@ -0,0 +1,7 @@
+type: fixed
+area: subsync
+
+- Subsync now works when mpv loaded a subtitle track from a URL, which is how Aniyomi extension streams and Jellyfin add theirs. The track is downloaded to a temporary file first — reusing mpv's own request headers, so authenticated and referer-gated hosts stay reachable — instead of being rejected with "Subtitle file not found: https://…". This applies to both the sync target and the alass reference, so a Jimaku or TsukiHime download can be retimed against a stream's own subtitles. Internal tracks of a stream also pass mpv's headers through to `ffmpeg`.
+- Alass now works on tracks that arrive as WebVTT, which is what Aniyomi extension streams serve. Alass picks its parser from the file extension and has no WebVTT support, so it treated a `.vtt` reference as a video file and failed with "no audio stream in file". Both the target and the reference are rewritten as SRT for alass, keeping the cue text as-is, and the originals are left untouched.
+- Leaving `subsync.alass_path`, `ffsubsync_path`, or `ffmpeg_path` empty now actually auto-discovers the binary, as the config help has always claimed. Previously it fell back to a hard-coded `/usr/bin/<tool>`, which does not exist on macOS and broke subsync for every default-config install there. Discovery searches `PATH` plus the usual install prefixes (a GUI launch inherits a minimal `PATH`) and accepts `alass-cli` as well as `alass`. An explicitly configured path is still used verbatim and never silently substituted.
+- Subsync failures are written to the application log. Previously the only trace was an OSD toast that vanished after a few seconds, leaving nothing to diagnose from.
@@ -0,0 +1,4 @@
+type: fixed
+area: subtitles
+
+- Keep the subtitle sidebar near playback during gaps when the subtitle file has a cue starting at zero.
@@ -0,0 +1,4 @@
+type: docs
+area: stats
+
+- Documented provider reassignment, merge compatibility, and TMDB credential command caching and retry cooldown.
@@ -0,0 +1,8 @@
+type: added
+area: stats
+
+- Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB. Release builds include a project key, so it works out of the box; `tmdb.apiKey` (or `tmdb.apiKeyCommand`) overrides it, and is required when running from source.
+- Unlinked titles that AniList cannot match are looked up on TMDB automatically when the parsed filename matches a Japanese live-action title exactly; otherwise use the new **Link to TMDB** action on a title to pick it by hand.
+- Entries linked to the same TMDB title are merged into one card even when they came from different season folders, and the Library kind selector gained a Live Action option alongside Anime and YouTube.
+- Provider reassignment preserves the previous link and artwork if the replacement download fails, and refreshes completion totals when the episode count changes. Merges and sync keep conflicting AniList and TMDB identities separate, and the merge dialog explains when a selection mixes the two instead of failing.
+- TMDB credential commands cache successful output and wait 30 seconds before retrying failed or empty output, using the bundled key in the meantime when available.
@@ -0,0 +1,4 @@
+type: docs
+area: anki
+
+- Documented the separate word-audio mapping for animated-image synchronization and that existing images need regeneration to pick up the corrected freeze.
@@ -0,0 +1,4 @@
+type: changed
+area: yomitan
+
+- Updated bundled Yomitan with upstream 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
@@ -0,0 +1,4 @@
+type: docs
+area: stats
+
+- Document YouTube channel filtering and video statistics in the Library.
@@ -0,0 +1,7 @@
+type: added
+area: stats
+
+- Store YouTube channels as a separate media kind and migrate existing channel entries without changing viewing history or manual video assignments, including channels created after temporarily returning to an older build.
+- Add All Titles, Anime, and YouTube Library filters, identify channel pages, and keep channels out of AniList matching, season repair, and duplicate recommendations.
+- Keep same-title anime and YouTube records separate in storage and sync while repairing legacy channel classification.
+- Refuse merges and video moves that would mix an anime entry with a YouTube channel; the move picker and merge selection only combine entries of the same kind.
@@ -6,6 +6,23 @@
 */
 {

+  // ==========================================
+  // Japanese Subtitle Generation
+  // Generate timed Japanese subtitles from local audio using whisper.cpp.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
  // ==========================================
  // Visible Overlay Auto-Start
  // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -206,6 +223,7 @@
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
+    "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -341,6 +359,12 @@
        "__playlist-browser-open"
      ] // Command setting.
    },
+    {
+      "key": "Ctrl+Alt+KeyA", // Key setting.
+      "command": [
+        "__anime-browser-open"
+      ] // Command setting.
+    },
    {
      "key": "Ctrl+Shift+KeyH", // Key setting.
      "command": [
@@ -523,7 +547,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // 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.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/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.
  // ==========================================
@@ -544,6 +568,7 @@
    "fields": {
      "word": "Expression", // Card field for the mined word or expression text.
      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
      "image": "Picture", // Card field that receives the captured screenshot or animated image.
      "sentence": "Sentence", // Card field that receives the source sentence text.
      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -572,7 +597,7 @@
      "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.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
    }, // Media setting.
    "knownWords": {
      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -617,6 +642,21 @@
    } // Lapis kiku setting.
  }, // Automatic Anki updates and media generation options.

+  // ==========================================
+  // Anime Browser
+  // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+  // add a repository index URL here (or drop .apk files in the extensions directory) to have any.
+  // Hot-reload: autoOpenJimaku applies to the next episode; other anime changes apply the next time the anime browser opens.
+  // ==========================================
+  "anime": {
+    "autoOpenJimaku": false, // Pause Anime Browser playback and open Jimaku when an episode loads. Playback resumes after a subtitle loads or the modal closes only when auto-open initiated the pause. Values: true | false
+    "extensionsDir": "", // Directory holding Aniyomi extension .apk files. Empty uses <userData>/anime-extensions.
+    "repos": [], // Extension repository index URLs (any https .json index, e.g. https://.../index.min.json). Empty by default; SubMiner ships no repositories.
+    "preferredQuality": "", // Preferred stream quality label, matched as a substring (for example: 1080). Empty uses the source order.
+    "defaultSource": "", // Source the Anime Browser selects when it opens: a source id (<package>:<source>) or "all" for every installed source. Empty selects the first installed source. "Set default" in the Extensions tab writes this value.
+    "bridgeDir": "" // Directory holding an M-Extension-Server bundle (java runtime plus server jar) to run instead of the copy SubMiner downloads. Empty checks the package-manager install (Arch: mangatan-extension-server), then <userData>/anime-bridge.
+  }, // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+
  // ==========================================
  // Jimaku
  // Jimaku API configuration and defaults.
@@ -640,6 +680,16 @@
    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.

+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
  // ==========================================
  // YouTube Playback Settings
  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
@@ -368,7 +368,9 @@ const sidebar: DefaultTheme.SidebarItem[] = [
      { text: 'Anki', link: '/anki-integration' },
      { text: 'Jellyfin', link: '/jellyfin-integration' },
      { text: 'YouTube', link: '/youtube-integration' },
+      { text: 'Anime Browser', link: '/anime-browser' },
      { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'Subtitle Generation', link: '/subtitle-generation' },
      { text: 'TsukiHime', link: '/tsukihime-integration' },
      { text: 'AniList', link: '/anilist-integration' },
      { text: 'AniSkip', link: '/aniskip-integration' },
@@ -47,6 +47,8 @@ The update flow:

 Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.

+Updates are skipped if the media path cannot produce a safe, nonempty identity. Invalid entries are discarded when loading or adding to the retry queue.
+
 | Parameter        | Value      |
 | ---------------- | ---------- |
 | Initial backoff  | 30 seconds |
@@ -69,6 +71,8 @@ SubMiner fetches cover art from AniList for display in the stats dashboard. When

 A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.

+When AniList has no match, SubMiner tries [TMDB](/configuration#tmdb) next so live-action dramas and movies get a poster and synopsis too. See [Immersion tracking](/immersion-tracking#library) for how live-action entries are grouped.
+
 If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.

 ## Rate limiting
@@ -0,0 +1,419 @@
+# Anime Browser
+
+Search anime sources, pick an episode, and play it in mpv with SubMiner's overlay
+and mining tools attached — the same way a local file or a Jellyfin stream works.
+
+Open it with `subminer anime`, with `SubMiner.AppImage --anime`, or from
+**Browse Anime** in the tray menu. The window stays open while you watch, so you
+can queue the next episode without reopening it.
+
+During playback, `Ctrl+Alt+A` toggles the same browser as a modal inside the mpv
+player bounds. It uses a dedicated modal surface, so it stays above fullscreen
+playback and closes like the other in-player tools. Toggling it off keeps its
+current page and scroll position ready for the next toggle. The standalone
+window and the modal keep their own search, selected source, tab, and scroll
+state, so using one does not replace or cancel what you were doing in the other.
+
+Both surfaces use the same playback queue, source configuration, and stats
+history. Queue changes and the currently playing episode appear in both
+immediately, and watched marks come from the same history that playback and the
+stats window update. Closing and reopening the modal therefore picks up progress
+made from either browser surface.
+
+While the window is open, SubMiner shows a tray icon and — on macOS — appears
+in the Cmd+Tab switcher and the Dock (macOS ties the two together), so you can
+flip between the browser and mpv. SubMiner normally hides itself from the Dock
+because the subtitle overlay needs that to float above fullscreen video; it
+hides again when the window closes during playback.
+
+Launching an episode starts a full SubMiner playback session, the same as
+playing a local file: the overlay and mining tools attach, and the tray icon
+stays available. In standalone `subminer anime` mode, closing the window while
+a video is playing leaves playback running — reopen the browser from the tray
+(**Browse Anime**). The app only exits with the window when nothing is playing.
+
+## How it works
+
+SubMiner does not implement any anime source itself. It runs **Aniyomi extension
+APKs** through a bundled JVM sidecar ([M-Extension-Server][mes]), asks the
+selected extension to resolve an episode, and hands the resulting URL to mpv.
+
+```
+extension APK  →  bridge (JVM)  →  { url, headers }  →  mpv  →  SubMiner overlay
+```
+
+Because the extension resolves the stream, whichever sources you install decide
+what is available. SubMiner runs the installed extensions locally and nothing
+more.
+
+## Installing extensions
+
+**SubMiner ships no extension repositories and bundles no sources.** There is no
+default repository, no suggested list, and no discovery. Until you add one, the
+browser has nothing to search — that is deliberate. Every repository and
+extension comes from you, and SubMiner is not affiliated with any of the sites
+they connect to.
+
+There are two ways to add extensions.
+
+### From a repository
+
+The window has three tabs — **Browse**, **Extensions**, and **Source settings** —
+and each one fills the window, so a long extension list is not squeezed in above
+the search results.
+
+Open the **Extensions** tab, paste a repository index URL, and choose
+**Add repository**. The URL must be `https` and point at a `.json` index file —
+`index.min.json` is the common Aniyomi name, but repositories are free to publish
+under another one (for example `video.min.json`). Anything else is rejected
+immediately rather than failing later. Everything before the file name is treated
+as the repository root, so `.apk` and icon URLs are resolved relative to it.
+
+Extensions your repositories offer but you do not have appear under
+**Available**, each with **Install**. Repositories are stored in config under
+`anime.repos`, so you can also manage them there and keep them in a dotfile.
+
+Every row carries the extension's icon, as the repository publishes it, so a
+site is recognisable before you read the name. A repository row shows its host's
+favicon instead. Icons are the only part of a row that is fetched from the
+network, and a row whose icon is missing falls back to the first letter of its
+name rather than an empty box.
+
+A repository index lists every language it knows about, which is far more than
+any one person reads, so the **Available** list has a language chip row above
+it. Pick one or more languages to narrow it, or **All** to clear the filter;
+picking a language replaces **All** rather than sitting beside it. Rows name the
+language in full ("Japanese" rather than `ja`), extensions whose sources span
+languages are grouped under **Multi-language**, and the Available heading counts
+how many of the offered extensions the filter leaves.
+
+### Managing what is installed
+
+The Extensions tab opens with an **Installed** section listing everything in the
+extensions directory, with the sources each one provides and a **Remove**
+button. It is built from the directory rather than from a repository, so an
+extension you dropped in by hand — or one whose repository you have since
+removed — is still listed and still removable. An installed extension borrows
+its icon from the catalogue, so one no repository carries shows its monogram.
+
+SubMiner compares the APK's Android version code with the newest build in the
+configured repositories. **Update** is clickable only when the repository has a
+newer build. A current extension says **Up to date**. If an unusual APK has no
+readable version code, its disabled button says **Version unknown**. **Update
+all** installs every newer build in one pass and disables itself when there is
+nothing to update.
+
+### From a file
+
+Drop Aniyomi `.apk` files into the extensions directory, shown at the top of the
+Extensions tab. It defaults to `<userData>/anime-extensions` — on macOS,
+`~/Library/Application Support/SubMiner/anime-extensions` — and can be moved with
+`anime.extensionsDir`.
+
+A single APK may provide several sources; each appears separately in the
+**Source** picker. Extensions that fail to load are listed in the Installed
+section with the reason, so a broken APK is visible rather than silently
+missing.
+
+An extension that fails to load is skipped rather than blocking the others, so
+one bad APK will not hide the rest.
+
+### Default source
+
+The browser opens on the first installed source. To open on a different one,
+press **Set default** on its row in the Installed list; the row then carries a
+**default** tag, and only one source can carry it. The choice is written to
+`anime.defaultSource` and applies the next time a browser window or the
+in-player modal opens. With more than one source installed, an **All sources**
+row at the top of the list can be the default too. A default that is no longer
+installed falls back to the first source.
+
+## Searching every source at once
+
+With more than one source installed, the **Source** picker gains an
+**All sources** entry. Searching with it selected runs the query against every
+installed source at once, and each source's results appear the moment that
+source answers — a fast source is on screen while a slow one is still
+resolving. The status bar counts sources as they finish
+(`Searching… 3/5 sources · 42 results`).
+
+Each cover is labelled with the source it came from, and opening one always
+queries that source, whatever the picker says afterwards.
+
+A source that errors is named in the status bar and the rest still show their
+results; one extension that needs a login cannot blank the grid. If every
+source fails, the first error is shown in full.
+
+Typing a new search while one is still running simply starts over: results
+from the superseded search are discarded, even if its sources answer late.
+
+When a source reports another page, **Load more** appears below the covers.
+It appends the next page without duplicating entries that already arrived in
+the live result stream. A failed next-page request remains available to retry.
+
+Source settings belong to a single extension, so the **Source settings** tab
+asks you to pick one while **All sources** is selected.
+
+## Finding an episode, and what you have watched
+
+An episode list can run to hundreds of entries, so the episode header carries a
+filter box:
+
+- A number, `12`, keeps that episode. Sources that report no numbers at all
+  are still searched by name, so `12` also matches `Episode 12` in a title.
+- A range, `12-18`, keeps the episodes between the two, in either order
+  (`18-12` reads the same). Episodes the source gave no number are left out of
+  a range.
+- Anything else is a case-insensitive substring of the episode name, so `beach`
+  finds `OVA: Beach Special`.
+
+The counter next to **Episodes** reads `6 of 25` while a filter is applied.
+Pressing Escape in the filter box clears it; pressing it anywhere else goes back
+to the results grid.
+
+Episodes you have already watched are dimmed and marked `✓ watched`, with a
+count in the header. This is not a separate list the browser keeps: it reads the
+same stats history the rest of SubMiner writes to, where an episode is marked
+watched once a session runs past the completion threshold. Streams are recorded
+under a stable per-episode identity, so the mark survives the stream URL
+changing between playbacks, and it is the same mark the stats window and
+`--mark-watched` use.
+
+Because playback marks an episode partway through the session, the marks
+refresh when the browser window comes back to the front: finish an episode in
+mpv, switch back, and it is marked. With
+[immersion tracking](configuration.md) disabled there is no history to read, so
+no episode is marked.
+
+### Marking by hand, and catching up
+
+Right-click an episode for:
+
+- **Mark watched** / **Mark unwatched**: the single episode, whichever way it
+  is not already.
+- **Mark this and N below watched** / **... unwatched**: that episode and every
+  episode listed below it. Sources list newest first, so "below" is the back
+  catalogue: right-click the last episode you saw and mark everything down to
+  the start, which is how you catch up a series you watched somewhere else.
+
+A filter narrows what you are looking at, not what you mark: a span always
+covers the full episode list, and the status bar says how many episodes it
+touched. The oldest episode has nothing below it, so it only offers the single
+entry. Escape closes the menu.
+
+Marking an episode you have never played creates its stats row so the mark has
+somewhere to live. That row carries the same series, season and episode fields
+playback would have recorded, and both stats library views join the lifetime
+tables, so a manually marked episode does not appear there as watch time you
+never spent. Clearing a mark never creates anything.
+
+Marks are written to the stats history, so with immersion tracking disabled
+there is nowhere to write them and the status bar says so.
+
+## Settings
+
+| Key                      | Purpose                                                                  |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `anime.autoOpenJimaku`   | Pause new episodes and open Jimaku for Japanese subtitles.               |
+| `anime.repos`            | Repository index URLs. Empty by default.                                 |
+| `anime.extensionsDir`    | Where APKs are read from. Empty uses `<userData>/anime-extensions`.      |
+| `anime.preferredQuality` | Preferred stream label, matched as a substring (for example `1080`).     |
+| `anime.defaultSource`    | Source the browser opens on: a source id or `all`. Empty uses the first. |
+| `anime.bridgeDir`        | A bridge bundle to run instead of the downloaded one. Empty by default.  |
+
+Enable `anime.autoOpenJimaku` to hand each newly loaded Anime Browser episode
+to Jimaku. SubMiner pauses playback on its first frame, waits for mpv's video
+window to appear, closes the in-player browser if it is open, hides the
+standalone browser window, and opens Jimaku with the source title, season, and
+episode already filled in. Playback resumes after the selected subtitle loads.
+Closing Jimaku also releases the automatic pause, while playback that was
+already paused stays paused. A stream that never shows a window resumes without
+opening Jimaku. Reopen the browser window with `subminer anime`, the tray
+entry, or the shortcut to keep browsing.
+
+## Source settings
+
+Most extensions need configuration before they return anything — a server
+address and credentials, a preferred quality, a language filter. Open the
+**Source settings** tab to edit them. Changes save as you make them and
+persist across restarts in `<userData>/anime-source-preferences.json`.
+
+Each save is handed back to the extension, so it can react: the Jellyfin source
+logs in when the address and password land, then fills in its media-library
+picker. Password-like fields are masked. Because that file can hold
+credentials, it is written with owner-only permissions. Values are scoped to
+the exact extension package and source, so two extensions that reuse the same
+internal source ID cannot read each other's settings. Preferences saved by an
+older build without package ownership are discarded; re-enter those source
+settings once after upgrading.
+
+## The bridge
+
+SubMiner looks for the server in three places, in order, and runs the first
+one it finds:
+
+1. `anime.bridgeDir`, if set. It must hold a Java runtime and the
+   `MExtensionServer-*.jar`, laid out as upstream ships them. A directory that
+   holds neither is an error rather than a silent fallback.
+2. A package-manager install. On Arch that is the AUR
+   [`mangatan-extension-server`](https://aur.archlinux.org/packages/mangatan-extension-server)
+   package, which Mangatan also uses, at `/usr/share/mangatan/extension_server`.
+   Installing it means no download, and pacman keeps the bridge current. The
+   `subminer-bin` package lists it as an optional dependency.
+3. SubMiner's own copy in `<userData>/anime-bridge`. The first launch downloads
+   the newest upstream release that ships a bundle for your platform (~130 MB,
+   containing the server and a matching Java runtime, so no system JDK is
+   required), the same way Mangatan does. Releases older than the oldest server
+   SubMiner is known to work with are skipped. Progress appears in the banner
+   at the top of the window.
+
+The **Bridge** note at the bottom of the Extensions tab says which one is in
+use, its version, and who updates it.
+
+### Updating the bridge
+
+Only the copy SubMiner downloaded is ever updated by SubMiner. A package-manager
+install or an `anime.bridgeDir` belongs to whoever put it there.
+
+Once the bridge is running, SubMiner asks GitHub for the newest release and
+compares it with the installed version, including package-manager installs and
+custom bridge directories. When upstream has published a newer release, the
+banner reads "Extension bridge v… is installed; v… is available".
+
+For an AUR bridge, the banner directs you to update `mangatan-extension-server`
+through your AUR helper, for example `paru -S mangatan-extension-server`, then
+restart SubMiner. Custom installations get a reminder to use their package
+manager or original installation method. These notices have no in-app update
+button. The check uses upstream releases, so AUR packaging may lag behind the
+notice. External installations with an unreadable version do not show a notice.
+
+For SubMiner's own copy, the banner includes an **Update to v…** button.
+Clicking it downloads the new release beside the
+running bridge, so a failed download changes nothing, then stops the bridge,
+swaps the directories, and starts it again. The restart takes a few seconds
+and kills the stream of an episode that is playing, the same as when the
+bridge exits for any other reason; the queue and browser state survive. The
+check is one unauthenticated GitHub API call per bridge start; if it fails
+(offline, rate limited) it is logged and no update is offered until the next
+start.
+
+Upstream publishes no checksums, so the download is trusted the way Mangatan
+and the AUR package trust it: TLS to GitHub and the maintainer's account. That
+is the same trust running the server implies in the first place.
+
+The bridge stays running while the window is open. Resolved video URLs point at
+its own loopback proxy so the extension's cookies and headers apply, which means
+those URLs stop working once it exits — the window keeps it alive for the whole
+session.
+
+If the bridge dies anyway (killed by hand, crashed, or stopped mid-operation),
+the exit is detected and named in the status bar, and the next request starts a
+new one. Playback already in flight still ends when its stream URL dies, but the
+browser recovers without an app restart.
+
+Two known limits:
+
+- There is no Android WebView, so extensions that need one (typically for
+  Cloudflare challenges) will fail with an error from the source.
+- Bundles are published for macOS (arm64, x64), Linux (x64), and Windows (x64).
+  Other platforms are unsupported outright.
+
+## Playback
+
+Selecting an episode resolves the best available stream, applies the source's
+required headers as mpv `http-header-fields`, and loads it. The headers are
+readable back off mpv, so Anki card audio and screenshots fetch correctly too.
+
+HLS streams are routed through a small local proxy before mpv sees them. Some
+hosts disguise their video segments by prepending a fake image header (a real
+1x1 PNG) so scrapers back off; Aniyomi's own player strips this, but ffmpeg
+probes the segment as a picture and playback dies with "no audio or video data
+played". The proxy scans each segment for the first genuine MPEG-TS packet run
+and drops whatever junk sits in front of it. Segments that are not TS (fMP4,
+subtitles, encryption keys) pass through untouched, and direct-file streams
+skip the proxy entirely. Segment URLs disguised behind fake extensions
+(`.image`, `.jpg`, `.css`, and friends) are exposed locally with a `.ts`
+suffix so current ffmpeg releases accept them when Anki extracts audio,
+screenshots, or animated images from the playing stream.
+
+"Playing" in the status bar means playing: after handing mpv the stream,
+SubMiner waits until mpv actually configures a video output before reporting
+success. If mpv gives up instead — a dead host, an undecodable stream — the
+browser shows mpv's error rather than pretending playback started (a failed
+load leaves no mpv window, because the player idles windowless).
+Slow streams stay in the loading state while mpv is still opening them, even
+after the initial playback confirmation deadline. Loading ends when video
+appears, mpv reports an error or returns to idle, or another episode replaces
+the request.
+
+Failed requests appear in a dismissible panel at the bottom of the browser.
+It explains the failed action and suggests a next step. Expand **Technical
+details** to read the bridge or mpv error when reporting a problem. Missing
+bridge APIs and incomplete extension data have distinct explanations; an
+update may be needed, but a compatible release may not yet be available.
+
+Choosing **Queue** resolves the episode and appends the playable stream to mpv's
+own playlist immediately, while its subtitle tracks cache in the background.
+That makes mpv's next command available at once and lets the next episode begin
+automatically when the current one ends, without waiting for another source
+request. Resolved stream URLs can be short-lived, so a very long queue can still
+outlive what its source issued; dequeue and queue that episode again to refresh
+it.
+
+### Japanese audio, and switching tracks
+
+Sources often return a dub and the original audio as two separate entries — or
+as two audio tracks of one stream — and the dub is frequently listed first.
+SubMiner always aims at the Japanese audio:
+
+- Entries labelled as a dub are skipped as long as another entry exists. This
+  outranks `anime.preferredQuality`: a 1080p dub is the wrong file, not a better
+  one. If every entry is a dub, it still plays.
+- mpv's `alang` is set to `ja,jpn,jp,japanese` before the file loads, so a
+  stream carrying several audio tracks starts on the Japanese one. With no
+  Japanese track, mpv falls back to the first one as usual.
+- Any audio or subtitle tracks the extension supplies separately are added to
+  mpv with `audio-add` / `sub-add`, tagged with their language, and the
+  Japanese one is selected.
+
+The primary subtitle slot is reserved for Japanese — it is what the overlay
+mines. A source that only carries, say, English subtitles does not get them
+promoted to primary; instead the track is added with a normalized language tag
+(`English` → `en`), and the regular [dual-subtitle settings](configuration.md)
+apply: with `secondarySub.autoLoadSecondarySub` enabled and the language listed
+in `secondarySub.secondarySubLanguages`, it is picked up as the secondary
+subtitle, exactly as it would be for a local file.
+
+Every track is added, including the ones that are not selected, so all of them
+appear in mpv's track menu and can be switched by hand while watching
+(`#` cycles audio, `j` cycles subtitles by default).
+
+The extension hands over subtitle tracks as URLs, but SubMiner downloads each
+one to a temporary directory and gives mpv the local file. mpv is happy either
+way; [Subsync](/troubleshooting#subtitle-sync-subsync) is not, because alass
+needs a file on disk to use as the timing reference. A track that fails to
+download falls back to its URL so the episode still plays, the format is
+detected from the file's own content rather than its URL, and the directory is
+removed when the next episode starts or the app exits.
+
+### Generating Japanese subtitles
+
+While an episode is playing, press **Ctrl+Shift+G** to [generate Japanese subtitles](/subtitle-generation#generating-for-anime-streams) from its audio. SubMiner fetches the complete episode audio, transcribes it locally with whisper.cpp, and loads the resulting SRT if the same stream is still playing. Generated subtitles stay in the application cache. This requires a finite HTTP/HTTPS stream with an internal audio track; live streams and separately attached audio tracks are not supported.
+
+### Series, season, and episode
+
+The episode's identity travels with it instead of being guessed back out of the
+stream URL, which carries nothing but a proxy path and a file extension. The
+title and episode label from the source's own listing are split into series,
+season, and episode number once, at launch, and everything downstream reads
+those fields:
+
+- mpv's title reads `Series S03E04 - Episode Name`.
+- Stats group by series, and rewatching an episode reuses its entry instead of
+  creating a new one.
+- The [Jimaku](/jimaku-integration) and [TsukiHime](/tsukihime-integration)
+  modals open with Title, Season, and Episode already filled in, so a subtitle
+  search is one keypress rather than a retype.
+- [AniList](/anilist-integration) progress updates use those fields directly.
+
+[mes]: https://github.com/1Selxo/M-Extension-Server
@@ -19,6 +19,8 @@ This project is built primarily for [Kiku](https://kiku.youyoumu.my.id/) and [La

 AnkiConnect listens on `http://127.0.0.1:8765` by default. If you changed the port in AnkiConnect's settings, update `ankiConnect.url` in your SubMiner config.

+AnkiConnect and Kiku/Senren settings follow the [configuration validation rules](/configuration#configuration-file): invalid values produce a warning and fall back to the option's default. Use JSON booleans such as `true`, not strings such as `"true"`, and a positive number for `ankiConnect.pollingRate`.
+
 ## Auto-enrichment transport

 When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, and image fields automatically. Two detection methods are available:
@@ -125,6 +127,7 @@ SubMiner maps its data to your Anki note fields. Configure these under `ankiConn
  "fields": {
    "word": "Expression",        // mined word / expression text
    "audio": "SentenceAudio",    // sentence audio clip cut from the video
+    "wordAudio": "ExpressionAudio", // existing Yomitan word audio, read for animation sync
    "image": "Picture",          // screenshot or animated clip
    "sentence": "Sentence",      // subtitle text
    "miscInfo": "MiscInfo"       // metadata (filename, timestamp)
@@ -136,6 +139,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.

+`fields.wordAudio` selects the existing dictionary-audio field used to calculate the animated image's opening freeze. This mapping only reads audio; `fields.audio` still controls where generated sentence audio is written. See [config.example.jsonc](/config.example.jsonc) for defaults.
+
 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).
@@ -183,12 +188,18 @@ 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]`.

+Overlay and stats-dashboard mining use the same `media.maxMediaDuration` limit. See the [configuration example](/config.example.jsonc) for its default and how to disable the cap.
+
 Set `media.reviewTiming` to `true` to pause playback and check the clip before its media is generated. It applies to word, sentence, and audio cards.

 The review opens on the subtitle range plus your configured audio padding. Subtitles usually hang around after the dialogue has stopped, so once the waveform loads, an untouched clip end pulls back to just after the last speech in the line. The Line end rail still marks the original subtitle timing, Reset puts it back, and a line whose speech runs right through its end is left alone.

 **Adjusting the clip.** Drag either edge to trim, drag the middle to slide the whole clip without changing its length, or click anywhere on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys: 100 ms per press, or 500 ms with Shift. The 100 ms buttons do the same thing. Earlier and Later each reveal two more seconds of timeline without moving the selection.

+**Choosing the screenshot.** With still images enabled, drag the screenshot slider or use the Frame buttons to choose a video frame independently of the audio. Earlier and Later reveal more time for both sliders. The image follows the audio midpoint until you pick a frame, then stays fixed while you trim audio. Reset below the image restores automatic selection; the audio Reset affects only the audio. The screenshot slider also supports arrow keys, Home, and End.
+
+The picker supports local video and seekable remote streams, including Jellyfin, without seeking the main player. A selected frame must load before you can confirm; if it fails, choose another frame or Reset. The picker is hidden when image generation is disabled or animated AVIF is selected. Animated images continue to use the reviewed audio range.
+
 **Keys.** Space previews the selection with a playhead sweeping the clip. The preview ends when the hidden player has actually played the last sample, so Bluetooth output latency does not clip the tail. Enter confirms and Escape cancels.

 **The waveform.** SubMiner reads a center channel when one carries dialogue and falls back to a mono mix otherwise, keeps only the 250 to 3500 Hz speech band, and draws each slice's loudness against the clip's own noise floor. Steady background music flattens out and dialogue stands up, which makes it much easier to tell adjacent lines apart. The mined subtitle appears as a tinted band with labeled line-start and line-end rails. If waveform analysis fails, the timing controls still work.
@@ -203,6 +214,8 @@ Confirming writes the combined lines to the sentence field. Reset drops the adde

 Clipboard updates and stats-dashboard mining never open timing review. The option is off by default and hot-reloads. **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`) toggles it for the current session.

+If SubMiner closes the overlay while a timing review is still loading, it cancels pending setup and modal retries and restores playback if the review paused it. A new timing review can start after the overlay reopens.
+
 ### Screenshots (static)

 A single frame is captured at the current playback position.
@@ -237,7 +250,7 @@ SubMiner can produce an animated AVIF spanning the subtitle duration instead of
 }
 ```

-Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing word-audio duration, so the motion starts together with the sentence audio.
+Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing audio duration in `fields.wordAudio`, so the motion starts together with the sentence audio. The freeze is baked into the image when mined; changing the mapping does not repair previously generated images.

 ### Behavior options

@@ -73,8 +73,8 @@ src/
  shared/ipc/              # Cross-process IPC channel constants + payload validators
  renderer/                # Overlay renderer (modularized UI/runtime)
    handlers/              # Keyboard/mouse/gamepad interaction modules
-    modals/                # Modal flows (Jimaku, Kiku, subsync, runtime options, session help,
-                           #   changelog, character dictionary, playlist browser, subtitle
+    modals/                # Modal flows (Anime Browser, Jimaku, Kiku, subsync, runtime options,
+                           #   session help, changelog, character dictionary, playlist browser, subtitle
                           #   sidebar, YouTube track picker, controller config/debug/select)
    positioning/           # Subtitle position controller (drag-to-reposition)
  settings/                # Settings window UI (model, controls, markup)
@@ -35,6 +35,8 @@ Character dictionary sync is disabled by default. To turn it on:

 ::: tip
 The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
+
+Dictionary sync does not require a loaded Japanese subtitle track. Once Yomitan is ready, SubMiner can reuse an installed character dictionary even before the first subtitle is processed. If Yomitan readiness times out, the status reports a failure instead of staying on **Checking**.
 :::

 ::: info
@@ -168,7 +170,7 @@ These phases are emitted through the configured notification surface. Some phase
 2. **generating** - No cache hit: fetch characters from AniList GraphQL, download portraits (250ms throttle between image requests), save snapshot JSON.
 3. MRU update (no notification) - add the media ID to the most-recently-used list and evict old entries beyond `maxLoaded`.
 4. **building** - Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set - if it matches the previously imported revision, the import is skipped.
-5. **importing** - Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
+5. **importing** - Push the ZIP into Yomitan when the installed revision differs. Dictionary checks and settings updates wait for the extension to be ready, independently of subtitle processing. Readiness and quick operations have bounded timeouts; imports have a separate budget that grows with the ZIP size.
 6. **ready** - Dictionary is live. Character names will match on the next subtitle line.

 **State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.
@@ -61,7 +61,7 @@ The Settings window preserves existing JSONC comments, trailing commas, and unre

 Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `jimaku.apiKeyCommand` when available.

-Saving validates the candidate config before writing. Live-reloadable changes are applied immediately; other changes return a restart-required banner in the window.
+Saving validates the candidate config before writing. Saving only fields marked **LIVE** shows "Saved. Live settings applied." If a save also changes fields that need a restart, the banner lists only the sections containing those changed fields. Live changes still apply in the same save.

 ## Configuration file

@@ -103,7 +103,7 @@ SubMiner watches the active config file (`config.jsonc` or `config.json`) while

 Hot-reloadable settings include subtitle appearance, sidebar controls, keybindings,
 shortcuts, notifications, logging level, selected source-language preferences,
-Jimaku/Subsync settings, AniSkip settings (`mpv.aniskipEnabled`, `mpv.aniskipButtonKey`),
+Jimaku/Subsync and subtitle-generation settings, AniSkip settings (`mpv.aniskipEnabled`, `mpv.aniskipButtonKey`),
 stats keys (`stats.toggleKey`, `stats.markWatchedKey`), the secondary-subtitle default
 mode, and the Anki deck, known-word, N+1, field, sentence-card, and Kiku options
 listed in the reference tables below.
@@ -154,8 +154,10 @@ The configuration file includes several main sections:

 **External Integrations**

+- [**Anime Browser**](#anime-browser) - Extension repositories and stream preferences for the anime browser
 - [**Jimaku**](#jimaku) - Jimaku API configuration and defaults
 - [**TsukiHime**](#tsukihime) - Multi-language subtitle search and download
+- [**TMDB**](#tmdb) - Posters and synopses for live-action dramas and movies in the stats Library
 - [**Subtitle Sync**](#subtitle-sync) - Sync current subtitle with `alass`/`ffsubsync`
 - [**AniList**](#anilist) - Optional post-watch progress updates
 - [**Yomitan**](#yomitan) - Reuse an external read-only Yomitan profile
@@ -590,6 +592,7 @@ See `config.example.jsonc` for detailed configuration options and more examples.
 | `KeyJ`                  | `["cycle", "sid"]`            | Cycle primary subtitle track            |
 | `Shift+KeyJ`            | `["cycle", "secondary-sid"]`  | Cycle secondary subtitle track          |
 | `Ctrl+Alt+KeyP`         | `["__playlist-browser-open"]` | Open playlist browser                   |
+| `Ctrl+Alt+KeyA`         | `["__anime-browser-open"]`    | Toggle Anime Browser in the player      |
 | `Ctrl+Alt+KeyC`         | `["__youtube-picker-open"]`   | Open the manual YouTube subtitle picker |
 | `ArrowRight`            | `["seek", 5]`                 | Seek forward 5 seconds                  |
 | `ArrowLeft`             | `["seek", -5]`                | Seek backward 5 seconds                 |
@@ -631,10 +634,15 @@ See `config.example.jsonc` for detailed configuration options and more examples.
 { "key": "Space", "command": null }
 ```

-**Special commands:** Commands prefixed with `__` are handled internally by the overlay rather than sent to mpv. `__playlist-browser-open` opens the split-pane playlist browser for the current file's parent directory and the live mpv queue. `__replay-subtitle` replays the current subtitle and pauses at its end. `__play-next-subtitle` seeks to the next subtitle, plays it, and pauses at its end. `__runtime-options-open` opens the runtime options palette. `__runtime-option-cycle:<id>[:next|prev]` cycles a runtime option value.
+**Special commands:** Commands prefixed with `__` are handled internally by the overlay rather than sent to mpv. `__playlist-browser-open` opens the split-pane playlist browser for the current file's parent directory and the live mpv queue. `__anime-browser-open` opens the Anime Browser inside the player bounds. `__replay-subtitle` replays the current subtitle and pauses at its end. `__play-next-subtitle` seeks to the next subtitle, plays it, and pauses at its end. `__runtime-options-open` opens the runtime options palette. `__runtime-option-cycle:<id>[:next|prev]` cycles a runtime option value.

 **Supported commands:** Any valid mpv JSON IPC command array (`["cycle", "pause"]`, `["seek", 5]`, `["script-binding", "..."]`, etc.)

+Supported, unclaimed single-key keyboard bindings from the connected mpv session are also available
+in the overlay automatically. Configured SubMiner bindings, including `null` entries,
+take precedence. See [mpv binding discovery](/shortcuts#automatic-mpv-bindings) for session refresh
+behavior and limitations.
+
 Subtitle delay commands (`sub-delay`, `sub-step`) show a native mpv OSD notification after the command runs. Subtitle-position and subtitle-track proxy commands (`sub-pos`, `sid`, `secondary-sid`) show playback feedback through the configured notification surface.

 **See `config.example.jsonc`** for more keybinding examples and configuration options.
@@ -971,6 +979,7 @@ This example is intentionally compact. The option table below documents availabl
 | `ankiConnect.deck`                                | string                                      | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available. In Settings, this dropdown auto-fills and persists Yomitan's current mining deck when available. |
 | `fields.word`                                     | string                                      | Card field for mined word / expression text (default: `Expression`)                                                                                                                                                             |
 | `fields.audio`                                    | string                                      | Card field for the generated sentence audio clip (default: `ExpressionAudio`). Set this to a dedicated field such as `SentenceAudio` so it does not collide with the word audio Yomitan writes.                                  |
+| `fields.wordAudio`                                | string                                      | Existing word-audio field read for the animated image's opening freeze. Independent of the sentence-audio destination in `fields.audio`; this mapping does not write audio. See [config.example.jsonc](/config.example.jsonc) for defaults. |
 | `fields.image`                                    | string                                      | Card field for images (default: `Picture`)                                                                                                                                                                                      |
 | `fields.sentence`                                 | string                                      | Card field for sentences (default: `Sentence`)                                                                                                                                                                                  |
 | `fields.miscInfo`                                 | string                                      | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                                       |
@@ -991,7 +1000,7 @@ This example is intentionally compact. The option table below documents availabl
 | `media.syncAnimatedImageToWordAudio`              | `true`, `false`                             | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                                                         |
 | `media.audioPadding`                              | number (seconds)                            | Optional padding around generated sentence media timing (default: `0`). Animated AVIF clips include the same padded source range as sentence audio.                                                                             |
 | `media.fallbackDuration`                          | number (seconds)                            | Default duration if timing unavailable (default: `3.0`)                                                                                                                                                                         |
-| `media.maxMediaDuration`                          | number (seconds)                            | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                                                           |
+| `media.maxMediaDuration`                          | number (seconds)                            | Maximum generated clip duration for overlay and stats-dashboard mining. See the [configuration example](/config.example.jsonc) for the default and disabling the cap.                                                           |
 | `behavior.overwriteAudio`                         | `true`, `false`                             | Replace existing audio on updates; when `false`, new audio is appended/prepended using the configured media insert mode; manual clipboard updates always replace generated sentence audio (default: `true`)                     |
 | `behavior.overwriteImage`                         | `true`, `false`                             | Replace existing images on updates; when `false`, new images are appended/prepended using the configured media insert mode (default: `true`)                                                                                    |
 | `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                     | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                                                           |
@@ -1010,7 +1019,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`.                                                      |
+| `isSenren`                                        | object                                      | Senren-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }`. Merges duplicates using Senren's scene-switching markup. Mutually exclusive with `isKiku.enabled`.                                                     |

 ### Kiku/Lapis integration

@@ -1112,6 +1121,35 @@ When the manual merge popup opens, SubMiner pauses playback and closes any open

 ## External integrations

+### Anime Browser
+
+Sources for the [anime browser](/anime-browser). SubMiner ships no extension repositories and bundles no sources, so these are empty until you add one:
+
+```json
+{
+  "anime": {
+    "autoOpenJimaku": false,
+    "extensionsDir": "",
+    "repos": [],
+    "preferredQuality": "",
+    "defaultSource": ""
+  }
+}
+```
+
+| Option                   | Type       | Default | Description                                                                                                                                                                                                                                         |
+| ------------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anime.autoOpenJimaku`   | `boolean`  | `false` | Pause Anime Browser playback and open Jimaku when an episode loads. Playback resumes after a subtitle loads or the modal closes. Playback that was already paused stays paused.                                                                     |
+| `anime.extensionsDir`    | `string`   | `""`    | Directory holding Aniyomi extension `.apk` files. Empty uses `<userData>/anime-extensions`.                                                                                                                                                         |
+| `anime.repos`            | `string[]` | `[]`    | Extension repository index URLs. Any `https` URL ending in `.json` works; `index.min.json` is only the common name.                                                                                                                                 |
+| `anime.preferredQuality` | `string`   | `""`    | Preferred stream quality label, matched as a substring (for example `1080`). Empty keeps the source's own order. A Japanese-audio entry always outranks a higher-quality dub.                                                                       |
+| `anime.defaultSource`    | `string`   | `""`    | Source the Anime Browser selects when it opens: a source id (`<package>:<source>`) or `all` for every installed source. Empty selects the first installed source. **Set default** in the Extensions tab writes this value.                          |
+| `anime.bridgeDir`        | `string`   | `""`    | Directory holding an M-Extension-Server bundle (Java runtime plus server jar) to run instead of the downloaded copy. Empty checks the package-manager install first, then `<userData>/anime-bridge`. See [the bridge](anime-browser.md#the-bridge). |
+
+Repositories added from the browser's Extensions tab are written back to `anime.repos`, so the list can also be kept in a dotfile. Changes apply the next time the anime browser opens.
+
+Per-source settings (server addresses, credentials, per-extension quality or language options) are not part of `config.jsonc`. They belong to the extension, are edited in the browser's **Source settings** tab, and persist in `<userData>/anime-source-preferences.json` with owner-only permissions.
+
 ### Jimaku

 Configure Jimaku API access and defaults:
@@ -1152,6 +1190,40 @@ The keyboard shortcut lives under `shortcuts.openTsukihime` (default `Ctrl+Shift

 See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, language tabs, and troubleshooting.

+### TMDB
+
+TMDB (The Movie Database) supplies posters, synopses, and show grouping for live-action dramas and movies in the stats [Library](/immersion-tracking#library). AniList only covers anime, so TMDB is what gives live-action titles a cover and a description.
+
+Release builds ship with a project TMDB key, so nothing needs to be configured. Set your own key to use your own quota, or when running SubMiner from source, where no key is bundled. Create one for free under **Settings > API** on [themoviedb.org](https://www.themoviedb.org/settings/api); either the short API key or the long "API Read Access Token" works.
+
+```json
+{
+  "tmdb": {
+    "apiKey": "",
+    "apiKeyCommand": "cat ~/.tmdb_key"
+  }
+}
+```
+
+| Option               | Values | Description                                                                                        |
+| -------------------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `tmdb.apiKey`        | string | Your own TMDB API key or read access token; overrides the bundled key (default: empty)             |
+| `tmdb.apiKeyCommand` | string | Shell command that prints the key to stdout, used instead of `apiKey` to keep it out of the config |
+
+Successful `apiKeyCommand` output is cached for the running client until `tmdb.apiKey` or `tmdb.apiKeyCommand` changes. Failed or empty command output uses the bundled key when available and waits 30 seconds before the next request can retry the command. Changing either credential setting resets this cooldown.
+
+Changes apply to the next TMDB request without a restart.
+
+This product uses the TMDB API but is not endorsed or certified by TMDB.
+
+### Japanese subtitle generation
+
+Open the standalone modal with `Ctrl+Shift+G`, configurable through `shortcuts.openSubtitleGeneration`, or use the subtitle sidebar button. See [shortcuts](/shortcuts) for the shared mpv and overlay keybindings.
+
+`subtitleGeneration` configures local Japanese transcription for both the launcher and overlay. In **Settings → Integrations → Japanese Subtitle Generation**, set `modelPath` to an existing multilingual whisper.cpp GGML model, or leave it empty and choose a `managedModel` as the default. The generation modal lets you select another model for the current session, with download sizes and accuracy versus speed guidance. Downloads are explicit. Leave `whisperPath`, `ffmpegPath`, and `ffprobePath` empty to find the executables on `PATH`, or set them to override the executable paths. `threads` controls the CPU thread count. Settings apply to the next operation. See [subtitle generation](/subtitle-generation) for setup and behavior, and the [generated configuration example](/config.example.jsonc) for defaults.
+
+The generation modal offers an optional **Focus on spoken dialogue** checkbox and a separate Silero model download. Set `subtitleGeneration.vadModelPath` to a Silero GGML VAD model to make dialogue mode the default. `vadPath` overrides the speech detector executable. See [dialogue generation setup](/subtitle-generation#prioritizing-spoken-dialogue) for session behavior, the additional tool, and limitations.
+
 ### Subtitle sync

 Sync a subtitle track from the overlay picker using `alass` or `ffsubsync`. The picker lets you choose which track gets retimed (the active primary track by default) and, for alass, which reference it is aligned against (the secondary subtitle track by default). Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).
@@ -1172,11 +1244,17 @@ Sync a subtitle track from the overlay picker using `alass` or `ffsubsync`. The

 | Option           | Values          | Description                                                                                                               |
 | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `alass_path`     | string path     | Path to `alass` executable. Empty falls back to `/usr/bin/alass`. `alass` must be installed separately.                   |
-| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty falls back to `/usr/bin/ffsubsync`. `ffsubsync` must be installed separately.       |
-| `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
+| `alass_path`     | string path     | Path to `alass` executable. Empty auto-discovers `alass` or `alass-cli`. `alass` must be installed separately.            |
+| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty auto-discovers `ffsubsync`. `ffsubsync` must be installed separately.               |
+| `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` auto-discovers `ffmpeg`.                        |
 | `replace`        | `true`, `false` | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |

+Auto-discovery searches `PATH`, then the usual install prefixes (`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/usr/bin`, `/bin`) — a GUI launch inherits a minimal `PATH` that often omits the first two. Set the option explicitly if your binary lives elsewhere.
+
+Subtitle tracks that mpv loaded from a URL (Aniyomi extension streams, Jellyfin) are downloaded to a temporary file first, reusing mpv's own request headers, so they can be used as either the sync target or the alass reference.
+
+Stats dashboard sentence mining also uses `alass_path` when available to align a local English sidecar against the local Japanese sidecar before filling the card translation field. This stats-only retime writes a temporary cached copy and never edits the original subtitle files.
+
 Default trigger is `Ctrl+Alt+S` via `shortcuts.triggerSubsync`.
 Customize it there, or set it to `null` to disable.

@@ -31,12 +31,42 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_

 The same immersion data powers the stats dashboard.

+The browser dashboard and in-app stats overlay both load from the local HTTP server.
+The server accepts loopback hosts only and rejects requests from other browser origins,
+including opaque origins such as `file://`. API clients without a browser origin can
+still use the local API. Mutation requests with a body must use `application/json`;
+bodyless deletion and Anki browse requests remain supported. Requests rejected by the
+host or origin checks receive `403`; mutation bodies without a JSON content type
+receive `415`.
+
+Use the loopback dashboard URL directly. Reverse-proxied dashboards and Tailscale
+Serve URLs are unsupported because their host or browser origin is not the local
+server's origin. SSH stats synchronization is unchanged.
+
+Scripts sending a JSON body must include the content type. For example, this
+requests a duplicate-line cleanup preview without changing the database. Replace
+the port if you configured a different `stats.serverPort`:
+
+```bash
+curl http://127.0.0.1:6969/api/stats/maintenance/duplicate-lines \
+  -H 'Content-Type: application/json' \
+  -d '{"dryRun":true}'
+```
+
 - In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
 - Launcher command: run `subminer stats` to start the local stats server on demand (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
 - Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables non-destructively (recomputed from per-episode history, so lifetime totals older than the session retention window are kept); `subminer stats cleanup --duplicate-lines` collapses repeated lines left behind by typeset subtitles (see [Repeated Line Cleanup](#repeated-line-cleanup)). `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
 - Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.

+SubMiner waits for the local server to bind before reporting that the dashboard is available. If another process already uses the configured port, the command reports the startup error and the desktop app stays open. Opening the in-app dashboard also reports startup failures through your configured status notifications.
+
+`subminer stats -s` stops a background stats server or cancels a pending background start. It leaves a foreground-only server running, so an open in-app dashboard stays connected. Shutdown gives active HTTP requests one second to finish before closing their connections and finalizing stats.
+
+### Stats API resource IDs
+
+Resource IDs in URLs must be positive safe integers written as decimal digits without leading zeros, fractions, or exponent notation. ID lists in JSON bodies must contain positive safe integer numbers. Invalid IDs or list entries return `400` before any mutation; bulk requests do not apply just the valid subset. Pagination limits keep their existing rounding and bounds.
+
 ### Dashboard tabs

 #### Overview
@@ -53,14 +83,16 @@ Local files and Jellyfin items with detected season numbers are split into seaso

 When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.

+**Live-action dramas and movies.** Anime covers come from AniList, which has no live-action titles. A title that AniList cannot match is looked up on [TMDB](/configuration#tmdb) instead (release builds bundle a key; source builds need your own): only a Japanese-language, non-animated result whose known titles match the parsed filename exactly is accepted, and it supplies the poster, synopsis, English and Japanese titles, and episode count. If nothing matches automatically, open the title and use **Link to TMDB** to search and pick it by hand. A TMDB show spans all of its seasons, so entries that resolve to the same TMDB title are merged into one card regardless of the season folder they came from, and the merged season titles are remembered so later episodes land on the same card. The **All Titles** / **Anime** / **Live Action** / **YouTube** selector above the grid narrows the Library to one kind, and a title's detail view shows whether it is a drama or a movie. Linking a title to AniList again turns it back into an anime entry. Changing providers downloads the replacement cover before saving the new link; a failed download leaves the previous link and artwork intact. A title without a cover clears the previous artwork. Automatic TMDB matching leaves existing AniList links unchanged.
+
 Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.

-When YouTube channel metadata is available, the Library tab groups videos by creator/channel and treats each tracked video as an episode-like entry inside that channel section.
+When YouTube channel metadata is available, the Library tab groups videos by creator/channel. Use the kind selector above the grid (**All Titles**, **Anime**, **Live Action**, **YouTube**) to filter the library. Channel pages show tracked videos and their stats without AniList controls. Existing channel entries are classified as YouTube automatically on startup, preserving viewing history and manual video assignments. Anime and YouTube entries with the same normalized title remain separate, including during stats sync. Channels are excluded from anime metadata matching, season repair, and duplicate recommendations.

 A library entry is identified by its parsed title plus any detected season, so the same show can end up on several cards when releases disagree about the title or omit the season tag. Two fixes are available:

- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
+- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. AniList-linked and TMDB-linked entries cannot be merged together, and YouTube channels cannot be merged with anime or live-action entries. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
+- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. Anime and live-action entries are interchangeable here, but a YouTube video can only move between channels. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.

 Once cover art resolves a series to an AniList entry, cards with compatible seasons are folded together automatically only when the searched title exactly matches an AniList title or synonym. A fuzzy result that points at an AniList entry already used by another card appears as a **Possible duplicate** review above the Library grid instead. Choose **Review merge** to compare the cards and pick which one to keep, or **Not duplicates** to dismiss that suggestion permanently. Entries with conflicting explicit season numbers are left alone rather than merged or suggested.

@@ -327,14 +359,14 @@ LIMIT ?;
 - Large-table reads are index-backed for `sample_ms`, session time windows, frequency-ranked words/kanji, and cover-art identity lookups.
 - Workload-dependent tuning knobs remain at defaults unless you change them: `cache_size`, `mmap_size`, `temp_store`, `auto_vacuum`.

-### Schema (v23)
+### Schema (v24)

 The exact schema version lives in `SCHEMA_VERSION` (`src/core/services/immersion-tracker/types.ts`) and is recorded in the `imm_schema_version` table.

 Core tables:

 - `imm_videos` - video key/title/source metadata
- `imm_anime` - anime/series metadata referenced by videos and lifetime tables
+- `imm_anime` - series or YouTube channel metadata referenced by videos and lifetime tables, including the media kind (`anime`, `live_action` or `youtube`) and the AniList or TMDB link
 - `imm_anime_title_aliases` - alternate titles that resolve to the same anime row
 - `imm_anime_merge_recommendations` - candidate duplicate-series merges surfaced in the dashboard
 - `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals
@@ -16,6 +16,10 @@ Only **mpv** is strictly required. Everything else is optional, though you will

 Some rows below matter only for the `subminer` command-line launcher's picker features. On Windows, the **SubMiner mpv** shortcut remains the recommended playback entry point.

+[Local Japanese subtitle generation](/subtitle-generation) additionally requires whisper.cpp's `whisper-cli`, FFmpeg, and `ffprobe`. Configure their executable paths in Settings if needed. SubMiner can download a speech model explicitly, or use your existing multilingual GGML model.
+
+Optional [dialogue-focused generation](/subtitle-generation#prioritizing-spoken-dialogue) also uses whisper.cpp's speech segment detector and a separate Silero GGML VAD model.
+
 | Dependency           | Status      | Platforms    | What it does                                                                                                                                                   |
 | -------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | mpv                  | Required    | All          | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                                                                      |
@@ -217,6 +221,10 @@ Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from t
 paru -S subminer-bin
 ```

+For the [anime browser](anime-browser.md#the-bridge), optionally add
+`mangatan-extension-server`. SubMiner picks the package up instead of
+downloading its own copy of the bridge, and pacman keeps it updated.
+
 Or manually:

 ```bash
@@ -52,10 +52,13 @@ From then on, pause / resume / seek / stop and audio or subtitle track changes y
 - **mpv launches automatically.** If mpv isn't already running when you cast, SubMiner starts it with SubMiner defaults and the bundled mpv plugin, so keybindings work right away.
 - **The overlay is managed by SubMiner,** so your configured `subtitleStyle` controls how subtitles look. Use the [overlay-toggle shortcut](/shortcuts) to hide it for a session.
 - **Resume works.** If Jellyfin has a saved position for the item, SubMiner seeks there on load.
+- **Titles and credentials stay separate.** AniList, character dictionaries, Anki source fields, and Discord presence use media titles, never authenticated stream URLs. If a usable title is unavailable, lookups are skipped and source fields show an unknown-media label. Stats identifies Jellyfin videos by server and item ID without the stream URL or API key.
 - **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.
 - **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.

+On startup, SubMiner clears cached anime parser metadata containing both API-key text and Jellyfin stream markers. Metadata containing only one of these is preserved.
+
 ## Settings

 All Jellyfin options live under **Settings → Integrations → Jellyfin** (open settings from the tray's **Open SubMiner Settings**). The ones that matter for casting:
@@ -1,6 +1,6 @@
 # Jimaku integration

-[Jimaku](https://jimaku.cc) is a community subtitle repository for anime, built from files other learners uploaded. SubMiner talks to the Jimaku API, so you search, browse, and download Japanese subtitle files from inside the overlay. No alt-tabbing, no moving files around. A downloaded track loads into mpv right away.
+[Jimaku](https://jimaku.cc) is a community subtitle repository for anime and Japanese live action, built from files other learners uploaded. SubMiner talks to the Jimaku API, so you search, browse, and download Japanese subtitle files from inside the overlay. No alt-tabbing, no moving files around. A downloaded track loads into mpv right away.

 ::: tip Prerequisite: a free API key
 You need a Jimaku account and an API key (a personal access string) before this feature works. Create an account at [jimaku.cc](https://jimaku.cc), copy your key, and add it to your config as shown under [Configuration](#configuration) below. Without a key, the search modal will report "Jimaku API key not set."
@@ -14,21 +14,23 @@ When you open the modal, SubMiner parses the current video filename to extract a

 From there:

-1. **Search** - SubMiner queries the Jimaku API with the parsed title. Results appear as a list of anime entries (Japanese and English names).
-2. **Browse entries** - Select an entry to load its available subtitle files, filtered by episode if one was detected.
-3. **Browse files** - Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
-4. **Download** - Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.
+1. **Pick a catalogue** - The **Anime** and **Live action** tabs at the top of the modal choose which Jimaku catalogue to search. Switching tabs re-runs the current search. The choice persists until SubMiner restarts.
+2. **Search** - SubMiner queries the Jimaku API with the parsed title. Results appear as a list of entries (Japanese and English names).
+3. **Browse entries** - Select an entry to load its available subtitle files, filtered by episode if one was detected.
+4. **Browse files** - Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
+5. **Download** - Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.

 If no files match the current episode filter, a "Show all files" button lets you broaden the search to all episodes for that entry.

 ### Modal keyboard shortcuts

-| Key | Action |
-| --- | --- |
-| `Enter` (in text field) | Search |
-| `Enter` (in list) | Select entry / download file |
-| `Arrow Up` / `Arrow Down` | Navigate entries or files |
-| `Escape` | Close modal |
+| Key                          | Action                                        |
+| ---------------------------- | --------------------------------------------- |
+| `Enter` (in text field)      | Search                                        |
+| `Enter` (in list)            | Select entry / download file                  |
+| `Arrow Up` / `Arrow Down`    | Navigate entries or files                     |
+| `Arrow Left` / `Arrow Right` | Switch between the Anime and Live action tabs |
+| `Escape`                     | Close modal                                   |

 ## Configuration

@@ -41,26 +43,26 @@ Add a `jimaku` section to your `config.jsonc`:
    "apiKeyCommand": "cat ~/.jimaku_key",
    "apiBaseUrl": "https://jimaku.cc",
    "languagePreference": "ja",
-    "maxEntryResults": 10
-  }
+    "maxEntryResults": 10,
+  },
 }
 ```

-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `jimaku.apiKey` | `string` | - | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`. |
-| `jimaku.apiKeyCommand` | `string` | - | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`). |
-| `jimaku.apiBaseUrl` | `string` | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance. |
-| `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"` | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
-| `jimaku.maxEntryResults` | `number` | `10` | Maximum number of anime entries returned per search. |
+| Option                      | Type                         | Default               | Description                                                                                                                                              |
+| --------------------------- | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jimaku.apiKey`             | `string`                     | -                     | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`.                                                                                     |
+| `jimaku.apiKeyCommand`      | `string`                     | -                     | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`).                                               |
+| `jimaku.apiBaseUrl`         | `string`                     | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance.                                                                       |
+| `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"`                | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
+| `jimaku.maxEntryResults`    | `number`                     | `10`                  | Maximum number of entries returned per search.                                                                                                           |

 The keyboard shortcut is configured separately under `shortcuts`:

 ```jsonc
 {
  "shortcuts": {
-    "openJimaku": "Ctrl+Shift+J"
-  }
+    "openJimaku": "Ctrl+Shift+J",
+  },
 }
 ```

@@ -79,6 +81,8 @@ SubMiner extracts media info from the current video path to pre-fill the search

 - **Season + episode patterns:** `S01E03`, `1x03`
 - **Episode-only patterns:** `E03`, `EP03`, or dash-separated numbers like `Title - 03 -`
+- **Spelled-out episode labels:** `Episode 4`, `第4話`
+- **Season named at the end of the title:** `… Season 3`, `… 3rd Season`, `… S3`, `… 第3期` - the season goes in the Season field instead of being searched for as part of the series name
 - **Season folders:** a parent directory named `Season 2` or `S2` fills in the season when the filename lacks one
 - **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` - stripped before title extraction
 - **Year tags:** `(2024)` - stripped
@@ -87,6 +91,8 @@ SubMiner extracts media info from the current video path to pre-fill the search

 If the parser produces a high-confidence result (title + episode both detected), the search runs automatically when the modal opens. Otherwise, you can adjust the fields manually before searching.

+Episodes launched from the [anime browser](/anime-browser) skip parsing entirely: Title, Season, and Episode come from the source's own listing, which is why the search runs immediately even though the stream URL says nothing about the episode.
+
 ## Troubleshooting

 **"Jimaku API key not set"**
@@ -173,6 +173,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats rebuild` / `backfill`      | Rebuild or backfill rollup data                                                                   |
 | `subminer doctor`                          | Dependency + config + socket diagnostics (`--refresh-known-words` refreshes the known-word cache) |
 | `subminer settings`                        | Open the SubMiner settings window                                                                 |
+| `subminer generate-subs [video]`           | Generate [Japanese subtitles](/usage#generate-japanese-subtitles-locally) locally                 |
 | `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path                                          |
 | `subminer config path`                     | Print active config file path                                                                     |
 | `subminer config show`                     | Print active config contents                                                                      |
@@ -6,6 +6,23 @@
 */
 {

+  // ==========================================
+  // Japanese Subtitle Generation
+  // Generate timed Japanese subtitles from local audio using whisper.cpp.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
  // ==========================================
  // Visible Overlay Auto-Start
  // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -206,6 +223,7 @@
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
+    "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -341,6 +359,12 @@
        "__playlist-browser-open"
      ] // Command setting.
    },
+    {
+      "key": "Ctrl+Alt+KeyA", // Key setting.
+      "command": [
+        "__anime-browser-open"
+      ] // Command setting.
+    },
    {
      "key": "Ctrl+Shift+KeyH", // Key setting.
      "command": [
@@ -523,7 +547,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // 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.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/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.
  // ==========================================
@@ -544,6 +568,7 @@
    "fields": {
      "word": "Expression", // Card field for the mined word or expression text.
      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
      "image": "Picture", // Card field that receives the captured screenshot or animated image.
      "sentence": "Sentence", // Card field that receives the source sentence text.
      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -572,7 +597,7 @@
      "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.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
    }, // Media setting.
    "knownWords": {
      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -617,6 +642,21 @@
    } // Lapis kiku setting.
  }, // Automatic Anki updates and media generation options.

+  // ==========================================
+  // Anime Browser
+  // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+  // add a repository index URL here (or drop .apk files in the extensions directory) to have any.
+  // Hot-reload: autoOpenJimaku applies to the next episode; other anime changes apply the next time the anime browser opens.
+  // ==========================================
+  "anime": {
+    "autoOpenJimaku": false, // Pause Anime Browser playback and open Jimaku when an episode loads. Playback resumes after a subtitle loads or the modal closes only when auto-open initiated the pause. Values: true | false
+    "extensionsDir": "", // Directory holding Aniyomi extension .apk files. Empty uses <userData>/anime-extensions.
+    "repos": [], // Extension repository index URLs (any https .json index, e.g. https://.../index.min.json). Empty by default; SubMiner ships no repositories.
+    "preferredQuality": "", // Preferred stream quality label, matched as a substring (for example: 1080). Empty uses the source order.
+    "defaultSource": "", // Source the Anime Browser selects when it opens: a source id (<package>:<source>) or "all" for every installed source. Empty selects the first installed source. "Set default" in the Extensions tab writes this value.
+    "bridgeDir": "" // Directory holding an M-Extension-Server bundle (java runtime plus server jar) to run instead of the copy SubMiner downloads. Empty checks the package-manager install (Arch: mangatan-extension-server), then <userData>/anime-bridge.
+  }, // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+
  // ==========================================
  // Jimaku
  // Jimaku API configuration and defaults.
@@ -640,6 +680,16 @@
    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.

+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
  // ==========================================
  // YouTube Playback Settings
  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
@@ -51,6 +51,7 @@ These control playback and subtitle display. They require overlay window focus.
 | `J`                  | Cycle primary subtitle track                               |
 | `Shift+J`            | Cycle secondary subtitle track                             |
 | `Ctrl+Alt+P`         | Open playlist browser for current directory + queue        |
+| `Ctrl+Alt+A`         | Toggle Anime Browser inside the player                      |
 | `ArrowRight`         | Seek forward 5 seconds                                     |
 | `ArrowLeft`          | Seek backward 5 seconds                                    |
 | `ArrowUp`            | Seek forward 60 seconds                                    |
@@ -69,7 +70,7 @@ These control playback and subtitle display. They require overlay window focus.
 | `Right-click`        | Toggle pause (outside subtitle area)                       |
 | `Right-click + drag` | Reposition subtitles (on subtitle area)                    |

-The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V` and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V` and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right. The Anime Browser shortcut toggles a dedicated overlay modal bounded to the player; the standalone Anime Browser window remains independent, while active playback is shared.

 On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.

@@ -84,6 +85,7 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 | `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`             |
 | `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                |
 | `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                     |
+| `Ctrl+Shift+G`     | Open Japanese subtitle generation modal                 | `shortcuts.openSubtitleGeneration`         |
 | `Ctrl+Shift+T`     | Open TsukiHime subtitle search modal (EN/JA tabs)       | `shortcuts.openTsukihime`                 |
 | `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`      |
 | `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                              |
@@ -99,6 +101,8 @@ The stats toggle is handled inside the focused visible overlay window. It is con

 The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.

+In the sidebar, `Enter` seeks the keyboard-focused cue. `Space` keeps its configured playback action, normally pause/resume, even when a cue has focus.
+
 ## Controller shortcuts

 These overlay-local shortcuts open controller utilities for the Chrome Gamepad API integration.
@@ -169,3 +173,20 @@ The `keybindings` array overrides or extends the overlay's built-in key handling
 Mouse keybinding names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`.

 Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) - changes take effect without restarting SubMiner.
+
+### Automatic mpv bindings
+
+The overlay also discovers supported single-key keyboard bindings from the connected mpv session,
+including `input.conf`, mpv defaults, and loaded scripts. When SubMiner does not handle a
+key, it forwards the key to mpv to run the current binding. SubMiner shortcuts and
+configured bindings take precedence, including entries explicitly disabled with
+`"command": null`. Text entry, overlay menus, and Yomitan popups do not forward these
+fallback keys.
+
+Discovery runs in the background at startup, again after a short delay for scripts,
+when the overlay regains focus, and when SubMiner's binding configuration reloads.
+Bindings added later may require refocusing the overlay. Imported bindings stay in
+memory for the session and do not appear in SubMiner's help menu or modify its config.
+Supported keys include characters, common navigation keys, and F1 through F24, with
+modifiers. Mouse bindings, keypad-specific and media keys, key sequences, and full
+navigation of interactive mpv script menus are not imported. If discovery is unavailable, SubMiner's configured controls keep working.
@@ -0,0 +1,98 @@
+# Japanese subtitle generation
+
+Generate Japanese SRT subtitles from a local video's audio or an anime stream using [whisper.cpp](https://github.com/ggml-org/whisper.cpp). The launcher and overlay use the same local generation service. Transcription runs on your computer without uploading audio. Model downloads and stream audio extraction require an internet connection; local-file generation with an installed model does not.
+
+## Setup
+
+Install whisper.cpp's `whisper-cli` executable and FFmpeg, including `ffprobe`. SubMiner downloads models, not these executables. Leave `whisperPath`, `ffmpegPath`, and `ffprobePath` empty to find the executables on `PATH`. To use a specific installation, set a path override under **Settings → Integrations → Japanese Subtitle Generation**.
+
+The generation modal checks for these executables under **Local tools** and keeps **Generate subtitles** disabled until every required one is found, naming the missing executable and its setting. Model downloads stay available in the meantime. After installing a tool or changing a path, click **Check again**. The launcher runs the same check before any model download. Generation also confirms the destination directory grants write and search permissions before extracting audio.
+
+Choose one model source:
+
+- Set `subtitleGeneration.modelPath` to an existing **multilingual whisper.cpp GGML `.bin` model**. Python Whisper checkpoints and English-only models are not suitable for Japanese transcription.
+- Leave that path empty and choose a model directly in the generation modal. Each option shows its download size; the selected model has speed and accuracy guidance. The modal offers **Download model** when that model is missing. Your choice lasts for the current SubMiner session, including closing and reopening the modal. Set `subtitleGeneration.managedModel` in Settings to change the default for future sessions.
+
+Managed models are stored in `models/whisper/` beside your SubMiner configuration file. Downloads show progress, verify the expected file size and SHA256, and publish the model only after verification. Cancelling or failing a download removes its temporary files. A configured external path always takes precedence; an unreadable path displays an error instead of silently downloading another model.
+
+See the [generated configuration example](/config.example.jsonc) for current defaults. Changes apply to the next operation.
+
+## Prioritizing spoken dialogue
+
+To focus on dialogue, check the optional **Focus on spoken dialogue** box in the generation modal. If the speech detection model is missing, click **Download speech detection model** to install it. This separate download uses the same progress, cancellation, and integrity checks as Whisper downloads. Checking the box never downloads automatically, and leaving it unchecked lets you generate without the Silero model.
+
+You also need whisper.cpp's [speech segment detector](https://github.com/ggml-org/whisper.cpp/tree/master/examples/vad-speech-segments). SubMiner downloads the model, not this executable. The detector is found as `whisper-vad-speech-segments` or, for builds from the upstream source, `vad-speech-segments` on `PATH`. Set `vadPath` in **Settings → Integrations → Japanese Subtitle Generation** for any other location. With **Focus on spoken dialogue** checked, the modal's **Local tools** check requires the detector too.
+
+The checkbox choice lasts for the current SubMiner session, including closing and reopening the modal. To make dialogue mode your default, set `vadModelPath` in Settings to a [Silero GGML VAD model](https://huggingface.co/ggml-org/whisper-vad/tree/main). The modal downloads `ggml-silero-v6.2.0.bin` into the same `models/whisper/` directory as managed Whisper models. An existing configured VAD path takes precedence and checks the box initially. Unchecking it temporarily disables dialogue mode without changing that path. Downloading the model alone does not enable dialogue mode.
+
+With speech detection configured, SubMiner keeps detected speech and other audible sections for Whisper to evaluate. A low speech score alone does not discard audio, which helps retain dialogue mixed with music. Only confidently silent gaps outside detected speech are omitted, with extra audio retained around each passage to reduce clipped syllables.
+
+Passages that fit within Whisper's 30-second audio window stay intact. Longer passages prefer nearby detected speech starts when choosing cuts, falling back to quiet pauses, with a small overlap to provide context. This reduces early subtitles caused by starting a clip well before its dialogue, while keeping all retained audio covered. Matching overlapping cues are combined even when punctuation differs; repeated dialogue at separate times remains separate. SubMiner runs each passage in a fresh Whisper process so decoder state from earlier audio cannot affect later passages. This reloads the model for each passage and can increase generation time. Subtitle cues stay within the supplied audio and retain each passage's position on the original timeline. Progress reports the current passage.
+
+This mode favors retaining dialogue over excluding music, so songs and background sounds may also produce subtitles. It can take longer than transcribing only VAD-approved speech. Whisper can still miss or misrecognize dialogue, and its timestamps remain estimates. Uncheck **Focus on spoken dialogue** to disable VAD for the session, or clear `vadModelPath` to change the default. Without a usable subtitle reference, disabling VAD returns to full-audio transcription. A selected detector or model that fails stops generation with an error. Existing subtitles are preserved.
+
+## Using loaded subtitles as timing references
+
+When generating for the video currently open in mpv, SubMiner automatically looks for a dialogue subtitle track among its embedded subtitles and loaded external SRT, ASS/SSA, or WebVTT files. It prefers English, then tracks labeled full or dialogue. Forced tracks, image subtitles, generated subtitles, and tracks whose titles or filenames identify signs, songs, lyrics, karaoke, or opening/ending subtitles are skipped. These checks rely on metadata; an unlabeled signs-only file cannot always be identified.
+
+The selected reference appears in generation progress. SubMiner reads its timestamps, including the active primary or secondary track's subtitle delay, and uses nearby cue starts to guide cuts in long audio passages. Short passages stay intact. The reference works with or without **Focus on spoken dialogue**. With that option enabled, reference starts take priority over VAD starts when choosing a nearby cut; VAD still helps identify speech. Audio outside reference cues remains eligible for transcription, and Whisper still supplies the Japanese text and final timestamps. The reference is assumed to be timed for the playing video; this does not automatically sync a mistimed reference.
+
+Unreadable or empty references are skipped in favor of another eligible loaded track. If none can be read, generation uses its normal audio timing. The launcher uses loaded references only when its input matches the video currently open in mpv; standalone generation keeps its existing behavior. It captures reference tracks and delays together with the initial audio selection, before checking or downloading a model. When relying on mpv's selected audio, it stops and asks you to retry if the media changes or cannot be verified during capture.
+
+## Choosing a model
+
+The modal recommends **large-v3-turbo** when it detects an NVIDIA GPU through `nvidia-smi` and the selected `whisper-cli` discovers an available CUDA device. Otherwise it recommends **small** for a balance of Japanese recognition quality and CPU time. The check works before downloading a model and falls back to small if a tool is missing, fails, times out, or reports an unrecognized result. Vulkan, AMD, and Apple GPU support do not qualify for the turbo recommendation. Checks are cached for up to 30 seconds; changing the Whisper executable path triggers a new check.
+
+The recommendation labels the model picker and explains the detected support. It does not change your configured model, current selection, external model path, or launcher's model choice. It also does not force a GPU backend during transcription. These are starting recommendations, not hardware benchmarks or guarantees that every model fits in available GPU memory. Tiny and base need less memory and usually finish sooner, with more recognition errors. Medium and large models favor accuracy but need more resources. Large-v3-turbo is optimized for speed compared with large-v3, with some accuracy tradeoff; actual performance depends on your CPU, GPU, whisper.cpp build, and audio.
+
+The picker includes whisper.cpp's official multilingual tiny, base, small, medium, large-v1, large-v2, large-v3, and large-v3-turbo downloads, including their available quantized variants. Quantized models use less disk space and memory, with possible accuracy loss. English-only `.en` models are excluded. See the [upstream model list](https://github.com/ggml-org/whisper.cpp/blob/master/models/download-ggml-model.sh) and [Whisper's model guidance](https://github.com/openai/whisper#available-models-and-languages).
+
+A configured external Model Path takes precedence and hides the managed model picker. Clear it in Settings to choose a managed model. Changing the picker never downloads automatically, and it cannot change the model during an active download or generation.
+
+## From the overlay
+
+1. Open a local video or an anime episode stream in mpv and select its Japanese audio track.
+2. Press **Ctrl+Shift+G** to open the standalone generation modal. When the subtitle sidebar has no subtitle lines loaded, it also offers a **Generate Japanese subtitles** button. Neither an open sidebar nor an existing subtitle track is required for the shortcut.
+3. Choose a model and download it if prompted, or configure your existing model path in Settings and click **Check again**.
+4. Optionally check **Focus on spoken dialogue** and click **Download speech detection model** if prompted.
+5. Click **Generate subtitles**.
+
+The modal adapts to the player window, using a wider layout when space allows and scrolling in smaller windows. It shows audio preparation, transcription, and saving progress. Percentages appear when the underlying tool reports them. **Cancel** stops the current operation. Closing the modal lets the job continue; reopening it shows the current progress or result.
+
+**Escape** or **Close** closes the modal using the same focus and overlay restoration as other SubMiner modals. Change or disable its shortcut with `shortcuts.openSubtitleGeneration` in Settings. Ctrl+G remains assigned to field grouping.
+
+SubMiner saves `<video>.ja.generated.srt` beside the media, adding a numeric suffix if that name already exists. It selects the generated Japanese subtitle track and resets the subtitle delay when mpv is still playing the same file. If playback changes, the subtitles remain saved and are not attached to the new video. The result includes the saved path even if mpv cannot load it.
+
+### Generating for anime streams
+
+Start the episode from the [anime browser](/anime-browser), then open the generation modal as usual. HTTP and HTTPS episode streams, including HLS through the anime browser's proxy, can use the same models and dialogue options as local files. The selected audio may be inside the stream or a separately attached HTTP/HTTPS audio track. For a selected external audio stream, SubMiner downloads that track directly and includes mpv's current audio delay in the subtitle timing. Local external audio files remain unsupported.
+
+SubMiner fetches the episode's audio into a temporary WAV before transcription. It reuses mpv's supported request headers, referrer, and user agent. The existing media-fetch policy excludes Cookie and Authorization headers, so sources requiring those directly may fail unless the anime bridge handles authentication. Expired URLs or a stopped bridge can also interrupt extraction; reopen the episode and retry.
+
+For anime-browser episodes, extraction first considers separate Japanese audio tracks returned by the source, then video streams with lower resolution than playback. It checks duration, starting offset, and short audio samples at three points against the selected playback audio. Different dialogue, shifted timing, silence, or failed checks keep the original stream. Checking alternatives has a 20-second budget. For plain HLS, it downloads only the segments covering each sample and aligns their timestamps to playback before comparing audio. Empty original samples are retried once and never reused. Failed checks log the candidate number, phase, reason, and elapsed time without exposing stream URLs or request headers. Progress names the source used for extraction; playback keeps its selected quality. Sources that expose only one combined stream still require downloading its video bytes.
+
+For plain HLS episodes with MPEG-TS segments, SubMiner downloads up to four segments at once, then extracts audio in playback order. Progress shows segment downloading followed by audio extraction. The temporary segments require space for the episode's combined video and audio and are removed after extraction, or when generation fails or is cancelled. Encrypted playlists, variant playlists, byte ranges, and other complex stream formats use the existing FFmpeg extraction path. Download speed still depends on the source and proxy.
+
+Generated SRT files are retained under `cache/generated-subtitles` in SubMiner's application data directory, using a URL hash for the filename and a numeric suffix for repeated generation. The result shows the saved path. Playback can continue during generation; the completed SRT is selected only if the same stream is still playing. Cached SRT results are not automatically loaded on a later visit.
+
+Completed audio extracts can be reused for retries and model changes during the current app session. They live with temporary job files under `cache/generated-subtitles/sessions`, separate from saved SRT files. The cache distinguishes the stream URL, selected audio track, and request headers, verifies contents before reuse, and evicts older audio above 512 MiB. Partial downloads are not cached.
+
+Quitting cancels the active job, waits for its cleanup, and removes the session's downloaded audio and working files. On startup, SubMiner removes abandoned session directories from processes that have exited, plus audio retained by the older persistent cache. Audio is never reused across app restarts. Generated SRT files and installed speech models remain available.
+
+This processes the complete episode, so subtitles appear after extraction and transcription finish. Streams must report a finite duration; live streams are not supported. A stream with combined video and audio segments may require downloading those segments even though only audio is retained.
+
+## From the launcher
+
+```bash
+subminer generate-subs episode.mkv --download-model
+subminer generate-subs episode.mkv --model-path /path/to/ggml-small.bin
+subminer generate-subs
+```
+
+With no file argument, the command uses the current local mpv media and its selected audio track. With an explicit file, it prefers an audio stream tagged Japanese, otherwise the first audio stream. Use `--audio-stream` to choose an absolute FFmpeg stream index. `--output` specifies a new destination SRT; existing output files are never overwritten. See [launcher usage](/usage) for all flags. Ctrl+C cancels the operation.
+
+## Timing and limitations
+
+The SRT includes whisper.cpp's timestamps, adjusted for the audio stream's position on the media timeline and, when speech detection is configured, each passage's original start time. No alass step is required to load it. This version uses native Whisper timing; it does not run WhisperX or another forced aligner. Recognition can repeat or invent lines, and timing can be imperfect, especially with music or overlapping speech. Review generated text and audio boundaries when mining.
+
+The overlay supports local files and finite HTTP/HTTPS streams with internal or selected external HTTP audio tracks. The launcher remains local-file only. Subtitle translation and separately attached local audio files are not supported by the modal. Pass a separate local audio file to the launcher if needed. The destination directory needs writable space for subtitles; temporary storage needs enough space for the extracted mono audio. Cached local subtitle tracks and embedded text subtitles can guide stream transcription; unreadable references fall back to audio timing.
@@ -6,10 +6,14 @@ The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if y

 ## How it works

+When the sidebar has no subtitle lines loaded, the **Generate Japanese subtitles** button opens [local subtitle generation](/subtitle-generation). The button hides once subtitle lines are loaded and stays hidden between lines. Press **Ctrl+Shift+G** to open generation at any time.
+
 When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open:

 - The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
+- Between subtitle lines, the sidebar follows playback to the next cue without jumping back to a cue at the start of the file.
 - Clicking any cue seeks mpv into that line. For overlapping ASS karaoke, SubMiner moves past the previous line's exit animation when the selected cue has enough time remaining.
+- Clicking to seek releases row focus. `Enter` seeks a keyboard-focused cue; `Space` keeps its configured playback action, normally pause/resume, without seeking back to a row.
 - The sidebar and the overlay share one cue list, so a media change or subtitle source switch updates both at once.

 For typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.
@@ -211,21 +211,26 @@ Resume playback and wait for the next subtitle to appear, then try mining again.

 Both **alass** and **ffsubsync** are optional external dependencies. Subtitle syncing requires at least one of them to be installed.

-**"Configured alass executable not found"**
+Subsync writes to the application log under the `subsync` scope, so the full command failure — exit code, stderr, resolved file paths — is recorded there as well as on the OSD.
+
+**"Could not find alass" / "Configured alass executable not found"**

 Install alass or configure the path:

+- **Homebrew**: `brew install alass`
 - **Arch Linux (AUR)**: `paru -S alass`
 - **Cargo**: `cargo install alass-cli`
 - Set the path: `subsync.alass_path` in your config.

-**"Configured ffsubsync executable not found"**
+Leaving the option empty searches `PATH` plus the usual install prefixes, and accepts either `alass` or `alass-cli`. Set the option explicitly when the binary lives somewhere else. The second message means the configured path itself does not exist — SubMiner never silently substitutes a different binary for one you named.
+
+**"Could not find ffsubsync" / "Configured ffsubsync executable not found"**

 Install ffsubsync or configure the path:

 - **Arch Linux (AUR)**: `paru -S python-ffsubsync`
 - **pip**: `pip install ffsubsync`
- Must be on `PATH` or configured via `subsync.ffsubsync_path` in your config.
+- Must be discoverable, or configured via `subsync.ffsubsync_path` in your config.

 **"alass synchronization failed" / "ffsubsync synchronization failed"**

@@ -236,6 +241,38 @@ If subtitle sync fails (the error message is prefixed with the engine name):
 - Try running the sync tool manually to see detailed error output.
 - ffsubsync requires local files and cannot handle remote media streams (e.g., streaming URLs).

+**Syncing subtitles on a stream (Aniyomi extensions, Jellyfin)**
+
+Subtitle tracks mpv loaded from a URL are downloaded to a temporary file first, reusing mpv's own request headers, so they work as either the sync target or the alass reference. Downloading a Japanese track from Jimaku or TsukiHime while a stream is playing also works — it becomes the primary track and therefore the sync target.
+
+Internal subtitle tracks of a stream still go through `ffmpeg`, which has to reach the origin itself. If that fails, prefer an external track or a Jimaku download as the reference.
+
+Streams usually serve WebVTT, which alass cannot parse — it picks its parser from the file extension and treats a `.vtt` file as a video, failing with "no audio stream in file". SubMiner rewrites both the target and the reference as SRT for alass, so this is handled automatically; the retimed track mpv loads is that SRT.
+
+## Anime Browser
+
+See the [anime browser guide](/anime-browser) for how sources and the bridge work.
+
+**Nothing to search**
+
+SubMiner ships no extension repositories and bundles no sources. Until you add a repository index URL in the **Extensions** tab (or drop Aniyomi `.apk` files into the extensions directory) the browser has nothing to query.
+
+**"No pinned checksum for …"**
+
+The bridge bundle is verified against a SHA-256 that a maintainer has checked by hand. Bundles exist for macOS (arm64, x64), Linux (x64), and Windows (x64), but only macOS arm64 and Linux x64 are pinned so far; the rest stop with this message rather than running an unverified download. Other platforms are unsupported outright.
+
+**A source returns nothing, or asks for a login**
+
+Most extensions need configuration first - a server address, credentials, a preferred quality. Open the **Source settings** tab and fill them in; each save is handed straight back to the extension. Sources that need an Android WebView (typically for Cloudflare challenges) cannot work here, because the bridge has none.
+
+**"Playback failed" with an mpv error**
+
+"Playing" is only reported once mpv actually configures a video output, so this is a real failure rather than a silent one: a dead host, an expired stream URL, or an undecodable stream. Resolve the episode again; if it keeps failing, try another source or quality entry.
+
+**The browser starts failing every request**
+
+A bridge that dies (killed, crashed, stopped mid-operation) is named in the status bar and restarted on the next request. Anything already playing ends with it, since stream URLs point at its loopback proxy.
+
 ## TsukiHime

 **"xz binary not found"**
@@ -16,11 +16,11 @@ Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is th

 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.
+When you open the modal, SubMiner parses the current video filename to extract a title, season, 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. Episodes launched from the [anime browser](/anime-browser) fill all three fields from the source's own listing instead of from a filename.

 From there:

-1. **Search** - SubMiner queries TsukiHime with `<title> <episode>`. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), each showing size, file count, and the subtitle languages the release carries.
+1. **Search** - SubMiner queries TsukiHime with `<title> <season> <episode>`. Season 1 is left out on purpose: releases of a first season almost never carry `S01` in their name, so including it would match nothing. Later seasons are included, which is what makes their releases findable at all. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), each showing size, file count, and the subtitle languages the release carries.
 2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
 3. **Download** - Selecting a track downloads the xz-compressed subtitle from TsukiHime's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as mpv's **primary** subtitle. Tracks from the configured secondary tab are assigned to mpv's **secondary** subtitle slot without replacing the primary. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.

@@ -72,6 +72,8 @@ subminer https://youtu.be/...     # Play a YouTube URL
 subminer stats                    # Open the immersion stats dashboard
 subminer doctor                   # Check dependencies, config, and the mpv socket
 subminer settings                 # Open the SubMiner settings window
+subminer anime                    # Open the anime browser window
+subminer generate-subs video.mkv   # Generate Japanese subtitles from local audio
 subminer app --setup              # Re-open first-run setup
 subminer -u                       # Check for updates
 ```
@@ -83,6 +85,44 @@ Two flags are worth knowing early:
 - `-a/--args` passes extra arguments straight to mpv, for example `subminer --args "--ao=alsa --volume=80" video.mkv`.
 - `--log-level debug` turns on verbose logging when something is not working.

+### Generate Japanese subtitles locally
+
+`generate-subs` transcribes local audio with whisper.cpp, saves a timed Japanese SRT file,
+and loads it into mpv if that same media file is still playing, clearing the previous subtitle
+delay. It also works with no running
+SubMiner app or mpv instance when you provide a file path. Omit the path to use the current
+mpv file and selected audio track.
+
+When the input matches the current mpv file, generation automatically uses an eligible embedded
+or loaded external subtitle track as a timing reference, preferring English dialogue and skipping
+tracks marked as signs, songs, or forced. See [timing references](/subtitle-generation#using-loaded-subtitles-as-timing-references).
+
+```bash
+subminer generate-subs video.mkv --download-model
+subminer generate-subs video.mkv --model-path ~/models/ggml-medium.bin
+subminer generate-subs --model medium --download-model
+subminer generate-subs video.mkv --audio-stream 2 --output ~/Subs/video.ja.srt
+```
+
+Install `whisper-cli` from whisper.cpp, `ffmpeg`, and `ffprobe`, or configure their paths in
+`subtitleGeneration.whisperPath`, `subtitleGeneration.ffmpegPath`, and `subtitleGeneration.ffprobePath`.
+Set `subtitleGeneration.modelPath` in settings to reuse an existing whisper.cpp model.
+With no external path, SubMiner uses `subtitleGeneration.managedModel` and stores downloaded
+models under `models/whisper` beside its config file. `--model` selects an official multilingual model, including available quantized variants, for
+this invocation and overrides a configured external model path. Run `subminer generate-subs --help`
+for accepted names. See [model selection](/subtitle-generation#choosing-a-model) for accuracy and speed guidance.
+
+Downloads only happen when you pass `--download-model` or choose the download action in the
+generation modal. The launcher reports each stage and percentages when available. Press Ctrl+C
+to cancel. `--audio-stream` takes an absolute ffprobe stream index. When you provide a file
+path without that flag, generation uses a Japanese audio track when tagged, falling back
+to the first audio track. With no file path, mpv must have an identifiable selected audio
+track, or you must provide `--audio-stream`.
+
+Generated files include Whisper's native timing. Speech recognition can make mistakes,
+especially over music or overlapping dialogue, so check the wording before mining. Existing
+output files are preserved. See [configuration](/configuration) for the generation settings.
+
 <details>
 <summary><b>Less common launcher commands</b></summary>

@@ -137,6 +177,7 @@ SubMiner.AppImage --open-tsukihime        # Open TsukiHime subtitle search
 SubMiner.AppImage --yomitan               # Open Yomitan settings
 SubMiner.AppImage --settings              # Open the SubMiner settings window
 SubMiner.AppImage --jellyfin              # Open the Jellyfin setup window
+SubMiner.AppImage --anime                 # Open the anime browser window
 SubMiner.AppImage --dictionary            # Generate a character dictionary ZIP
 SubMiner.AppImage --start --dev           # Enable app/dev mode
 SubMiner.AppImage --start --log-level debug  # Verbose logging without dev mode
@@ -149,6 +149,10 @@ These settings come from `config.jsonc` (or built-in defaults); there are no CLI
 - **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.
 - **Native mpv secondary rendering**: Stays hidden during YouTube flows so the SubMiner overlay remains the visible secondary subtitle surface.

+## Viewing stats
+
+The stats Library groups tracked YouTube videos by channel when channel metadata is available. Select **YouTube** in the Library filter to see those channels separately from anime. Each channel page lists its videos, watch time, vocabulary, and mined cards. See [Immersion Tracking](/immersion-tracking#library).
+
 ## Related pages

 - [Usage - YouTube Playback](/usage#youtube-playback)
@@ -15,7 +15,10 @@

 Stable and prerelease workflows share `.github/workflows/package-release.yml`.
 Both callers explicitly pass the five required macOS signing/notarization
-secrets; `GITHUB_TOKEN` remains automatically available to the reusable workflow.
+secrets plus the optional `SUBMINER_TMDB_API_KEY` (the project TMDB key that
+`scripts/prepare-build-assets.mjs` stages into `dist/bundled-integration-keys.json`;
+artifacts built without it simply require users to set `tmdb.apiKey`).
+`GITHUB_TOKEN` remains automatically available to the reusable workflow.
 Each platform verifies its ASAR and external resources before signing, then
 measures the signed app and installers before upload. Missing runtime assets,
 foreign SQLite/Koffi binaries, duplicate UI fonts, demo media, source maps,
@@ -64,7 +64,6 @@ External subtitle files only (SRT, VTT, ASS). Embedded subtitle tracks are out o
 A cue parser extracts both timing and text content from subtitle files for prefetching.

 **Parsed cue structure:**
-
 ```typescript
 interface SubtitleCue {
  startTime: number; // seconds
@@ -77,7 +76,6 @@ interface SubtitleCue {
 ```

 **Supported formats:**
-
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
 - ASS: Parse the `[Events]` section, read the field order from the `Format:` row, and extract timed `Dialogue:` lines. Timed `Comment:` lines are normally ignored, but can supply canonical authored text when they match a nearby generated animation from the same style and actor. Text can itself contain commas.

@@ -167,7 +165,6 @@ tokens (already have frequencyRank values from parser-level applyFrequencyRanks)
 ### Dependency Analysis

 All annotations either depend on MeCab POS data or benefit from running after it:
-
 - **Known word marking:** Needs base tokens (surface/headword). No POS dependency, but no reason to run separately.
 - **Frequency filtering:** Uses `pos1Exclusions` and `pos2Exclusions` to clear frequency ranks on excluded tokens (particles, noise). Depends on MeCab POS data.
 - **JLPT marking:** Uses `shouldIgnoreJlptForMecabPos1` to filter. Depends on MeCab POS data.
@@ -184,14 +181,18 @@ function annotateTokens(tokens, deps, options): MergedToken[] {

  // Single pass: known word + frequency filtering + JLPT computed together
  const annotated = tokens.map((token) => {
-    const isKnown = nPlusOneEnabled ? token.isKnown || computeIsKnown(token, deps) : false;
+    const isKnown = nPlusOneEnabled
+      ? token.isKnown || computeIsKnown(token, deps)
+      : false;

    // Filter frequency rank using POS exclusions (rank values already set at parser level)
    const frequencyRank = frequencyEnabled
      ? filterFrequencyRank(token, pos1Exclusions, pos2Exclusions)
      : undefined;

-    const jlptLevel = jlptEnabled ? computeJlptLevel(token, deps.getJlptLevel) : undefined;
+    const jlptLevel = jlptEnabled
+      ? computeJlptLevel(token, deps.getJlptLevel)
+      : undefined;

    return { ...token, isKnown, frequencyRank, jlptLevel };
  });
@@ -232,7 +233,6 @@ Replace `document.createElement('span')` calls in the renderer with `templateSpa
 ### Current Behavior

 In `renderWithTokens` (`subtitle-render.ts`), each render cycle:
-
 1. Clears DOM with `innerHTML = ''`
 2. Creates a `DocumentFragment`
 3. Calls `document.createElement('span')` for each token (~10-15 per subtitle)
@@ -268,30 +268,27 @@ Full recycling (collecting old nodes, clearing attributes, reusing them) require

 ## Combined Impact Summary

-| Scenario                          | Before     | After      | Improvement |
-| --------------------------------- | ---------- | ---------- | ----------- |
-| Normal playback (prefetch-warmed) | ~200-320ms | ~30-50ms   | ~80-85%     |
-| Cache hit (repeated subtitle)     | ~72ms      | ~55-65ms   | ~10-20%     |
-| Cache miss (immediate seek)       | ~200-320ms | ~150-260ms | ~20-25%     |
+| Scenario | Before | After | Improvement |
+|----------|--------|-------|-------------|
+| Normal playback (prefetch-warmed) | ~200-320ms | ~30-50ms | ~80-85% |
+| Cache hit (repeated subtitle) | ~72ms | ~55-65ms | ~10-20% |
+| Cache miss (immediate seek) | ~200-320ms | ~150-260ms | ~20-25% |

 ---

 ## Files Summary

 ### New Files
-
 - `src/core/services/subtitle-prefetch.ts`
 - `src/core/services/subtitle-cue-parser.ts`

 ### Modified Files
-
 - `src/core/services/subtitle-processing-controller.ts` (expose `preCacheTokenization`)
 - `src/core/services/tokenizer/annotation-stage.ts` (batched single-pass)
 - `src/renderer/subtitle-render.ts` (template cloneNode)
 - `src/main.ts` (wire up prefetch service)

 ### Test Files
-
 - New tests for subtitle cue parser (SRT, VTT, ASS formats)
 - New tests for subtitle prefetch service (priority window, seek, pause/resume)
 - Updated tests for annotation stage (same behavior, new implementation)
@@ -30,7 +30,11 @@ Update checks and startup launcher migration share a serialized update-state sto

 - `src/main/` owns composition, runtime setup, IPC wiring, and app lifecycle adapters.
 - `src/main/boot/` owns boot-phase assembly seams so `src/main.ts` can stay focused on lifecycle coordination and startup-path selection.
+- `src/main/runtime/linux-overlay-mode-runtime.ts` owns Linux fullscreen mode state and window replacement. App cleanup cancels pending replacements; `main.ts` supplies window creation and subtitle refresh hooks.
 - `src/core/services/` owns focused runtime services plus pure or side-effect-bounded logic.
+- `src/core/services/subtitle-generation*.ts` shares local whisper.cpp transcription, safe model downloads, and progress between the launcher and Electron. The overlay also accepts finite HTTP/HTTPS episode streams, snapshots mpv's supported HTTP headers, and extracts audio through FFmpeg with bounded network reads. Network reference extraction uses the same headers. Generated stream subtitles persist under the injected application cache directory with hashed filenames. `subtitle-generation-audio.ts` owns probing, extraction, and completed-audio reuse. Anime playback retains bounded per-URL alternative-source metadata; generation checks candidate duration, offset, and decoded audio samples before selecting separate Japanese audio or lower-resolution video. Verified extracts are reused only within the current app session, keyed by playback URL, audio stream index, and request headers. `subtitle-generation-session.ts` owns temporary audio and job directories, removes abandoned process directories on startup, and drains cancellation before shutdown cleanup. Saved SRT files remain separate. Plain HLS samples use short segment windows and container timestamps to avoid empty remote seeks; source rejection diagnostics omit URLs and headers. The launcher remains local-file only. Optional dialogue mode retains both Silero-detected speech and other audible sections, omits confidently silent gaps, decodes passages independently, and restores original media timing. `src/main/runtime/subtitle-generation-runtime.ts` owns the overlay job lifecycle and only loads completed subtitles into the same media; `src/shared/subtitle-generation*.ts` owns configuration, the multilingual model catalog, and IPC contracts. The overlay runtime retains a session model selection, validates picker requests through IPC, and keeps external model paths authoritative.
+- Subtitle model recommendations use bounded `nvidia-smi` and Whisper CUDA discovery probes in `subtitle-generation-acceleration.ts`. The overlay runtime caches results by executable path for 30 seconds and exposes acceleration status through the existing status IPC. Recommendations do not alter model selection or transcription arguments.
+- `subtitle-generation-reference.ts` ranks mpv's loaded text subtitle tracks, excludes signs/songs and forced references, and extracts timing hints with FFmpeg. The overlay and launcher snapshot references only for matching media, including active subtitle delays. Hints guide long-passage cuts with or without VAD; they never limit audio coverage or replace Whisper timestamps.
 - `src/renderer/` owns overlay rendering and input behavior.
 - `src/config/` owns config definitions, defaults, loading, and resolution.
 - `src/types/` owns shared cross-runtime contracts via domain entrypoints; `src/types.ts` stays a compatibility barrel.
@@ -3,7 +3,7 @@
 # Domain Ownership

 Status: active
-Last verified: 2026-07-15
+Last verified: 2026-08-02
 Owner: Kyle Yasuda
 Read when: you need to find the owner module for a behavior or test surface

@@ -30,7 +30,18 @@ Read when: you need to find the owner module for a behavior or test surface
 - Immersion sync: `src/core/services/stats-sync/`, bound by `src/main/sync-cli.ts`.
  `snapshot-transfer.ts` selects compressed rsync or scp. `transfer-cache.ts` atomically retains the last successfully received snapshot per hashed peer/database identity under the config directory's `sync-transfer-cache/`. Cache copies seed isolated transfer directories; rsync verifies reconstructed files before the existing merge engine runs. The `--make-temp` / `--remove-temp` helpers accept an internal `--transfer-cache` key, with a fallback for older peers that do not recognize it.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
+- TMDB live-action metadata: `src/core/services/tmdb/` (client + exact-title resolver), `src/core/services/immersion-tracker/live-action-link.ts` (links an entry to a TMDB title and merges other holders of the same title). The AniList cover-art fetcher calls the resolver as its fallback; `imm_anime.media_kind` marks the result and keeps the entry out of AniList season repair.
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
+- Anime browser: extension bridge client, sidecar, and stream handling in `src/anime-bridge/`;
+  the loopback stream proxy separates request transport/retry from response transformation in
+  `stream-strip-transport.ts` and `stream-strip-response.ts`;
+  browser window UI in `src/animeui/` (preload `src/preload-animeui.ts`); runtime wiring in
+  `src/main/runtime/anime-browser-application-runtime.ts`, `src/main/runtime/anime-browser-runtime.ts`,
+  `src/main/runtime/anime-browser-ipc-handlers.ts`, `src/main/runtime/anime-browser-sessions.ts`,
+  `src/main/runtime/anime-bridge-installer.ts`, and `src/main/runtime/stream-playback-metadata.ts`.
+  The play queue resolves episodes on click and appends them to mpv's real playlist
+  (`src/main/runtime/anime-browser-queue.ts`), then observes media-path changes to
+  attach prepared external tracks and update the browser queue state.
 - Window trackers: `src/window-trackers/`
 - Stats HTTP app: `src/core/services/stats-server.ts`, with route groups and shared route support
  in `src/core/services/stats-server/`
@@ -39,6 +50,17 @@ Read when: you need to find the owner module for a behavior or test surface

 ## Shared Contract Entry Points

+Automatic mpv keyboard discovery uses the `get-mpv-input-bindings` IPC request and
+`MpvInputBindingsSnapshot` in `src/types/session-bindings.ts`.
+`src/main/runtime/mpv-input-bindings.ts` queries the connected player and preserves
+configured keys, including disabled entries. `src/shared/mpv-input-bindings.ts`
+validates discovered keys and translates browser input. The renderer's
+`handlers/mpv-input-forwarding.ts` keeps the session lookup, coalesces asynchronous
+refreshes, and releases held keys on blur or disposal. `handlers/keyboard.ts` runs
+this fallback after SubMiner controls and refreshes on startup, a delayed startup
+pass, focus, and binding reload. Discovery does not enter compiled session bindings,
+the plugin artifact, persistent config, or session help.
+
 The subtitle sidebar consumes parsed cues through `SubtitleSidebarSnapshot`. Its `sourceKey`
 identifies the media and subtitle source so renderer selections are invalidated on source changes,
 including changes whose cue text and timings are identical. Native selection and clean clipboard
@@ -56,6 +78,7 @@ on Chromium document focus or require activating the overlay window.
 - Settings UI contracts: `src/types/settings.ts`
 - Session-binding contracts: `src/types/session-bindings.ts`
 - Stats HTTP wire contracts: `src/types/stats-wire.ts`, `src/types/stats-http-contract.ts`
+- Anime browser contracts: `src/types/anime-browser.ts`, bridge wire types in `src/anime-bridge/types.ts`
 - Compatibility-only barrel: `src/types.ts`

 ## Ownership Heuristics
@@ -11,7 +11,7 @@ Read when: finding internal docs or checking verification status
 | --- | --- | --- | --- | --- |
 | KB home | `docs/README.md` | active | 2026-05-23 | internal entrypoint |
 | Architecture index | `docs/architecture/README.md` | active | 2026-05-23 | top-level runtime map |
-| Domain ownership | `docs/architecture/domains.md` | active | 2026-05-23 | runtime and feature ownership |
+| Domain ownership | `docs/architecture/domains.md` | active | 2026-08-02 | runtime and feature ownership |
 | Layering rules | `docs/architecture/layering.md` | active | 2026-05-23 | dependency direction and smells |
 | Subtitle overlay priming | `docs/architecture/subtitle-overlay-priming.md` | active | 2026-06-01 | visible-overlay subtitle startup flow |
 | KB rules | `docs/knowledge-base/README.md` | active | 2026-05-23 | maintenance policy |
@@ -22,9 +22,15 @@ Read when: selecting the right verification lane for a change
  pull requests, stable tags, and prerelease tags. Keep common quality steps
  there instead of copying them into caller workflows.
 - The reusable gate installs Lua and runs `bun run test:env`, so the shipped mpv
-  plugin tests run for every pull request and tagged release.
+  plugin tests and launcher smoke run for every pull request and tagged release.
  Lua installation uses only the runner's Ubuntu package sources so unrelated
  third-party repository failures do not block the gate.
+- In the reusable gate, `test:coverage:src` is also the blocking execution of the
+  discovered `src/**` test lane. The coverage runner returns the failing test's
+  status, so CI does not rerun that lane through `test:fast`. Launcher unit and
+  script tests still run separately because they are outside the coverage lane.
+- Launcher smoke artifacts are uploaded after `test:env` fails. CI does not rerun
+  launcher smoke solely to collect the same artifacts.

 ## Default Handoff Gate

@@ -49,7 +55,7 @@ bun run docs:build
 - Internal KB, `AGENTS.md`, or `.agents/skills/**` changes: `bun run test:docs:kb`
 - Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
- Runtime-compat / compiled behavior: `bun run test:runtime:compat`
+- Runtime-compat / compiled behavior after `bun run build`: `bun run test:runtime:compat`
 - Stats dashboard UI: `bun run test:stats`
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Packaging: build the platform package, then run `bun run test:package <resources-directory>`.
@@ -62,11 +68,30 @@ bun run docs:build

 ## Coverage Reporting

- `bun run test:coverage:src` runs the maintained `test:src` lane through a sharded coverage runner: one Bun coverage process per test file, then merged LCOV output.
+- `bun run test:coverage:src` runs the same discovered `bun-src-full` membership as
+  `test:src` through a sharded coverage runner: one Bun coverage process per test
+  file, then merged LCOV output.
+- A failing coverage shard stops the runner with a nonzero status. Coverage is a
+  source test gate, not a report-only step.
 - Machine-readable output lands at `coverage/test-src/lcov.info`.
 - Every reusable quality-gate run uploads that LCOV file as the
  `coverage-test-src` artifact.

+## Compiled Runtime Smoke
+
+- `bun run test:smoke:dist` and its `test:runtime:compat` alias require an existing
+  full build and fail with the missing artifact paths when `dist/` or the stats UI
+  bundle is absent.
+- The check runs the emitted stats daemon under Electron's Node runtime. It opens
+  the production HTTP server, queries the overview endpoint through native
+  libsql-backed storage, and leaves an HTTP request body unfinished before
+  shutting the daemon down. It verifies a clean exit and that the port and
+  ownership state are released despite the unfinished request.
+- The check also occupies the configured port, requires startup to fail without
+  stale ownership state, releases the conflict, and verifies a clean retry.
+- This is not a full Electron UI startup check. It does not require a display and
+  makes no claims about renderer, window, tray, or mpv behavior.
+
 ## Dependency Audit Policy

 - `bun audit --audit-level high` blocks the reusable quality gate.
@@ -16,6 +16,10 @@ type AppCommandDeps = {
    appPath: string,
    logLevel: LauncherCommandContext['args']['logLevel'],
  ) => void;
+  launchAnimeBrowserDetached: (
+    appPath: string,
+    logLevel: LauncherCommandContext['args']['logLevel'],
+  ) => void;
 };

 const defaultAppCommandDeps: AppCommandDeps = {
@@ -23,6 +27,8 @@ const defaultAppCommandDeps: AppCommandDeps = {
  launchSyncUiDetached: (appPath, logLevel) =>
    launchAppCommandDetached(appPath, ['--sync-window'], logLevel, 'sync-ui'),
  launchAppBackgroundDetached,
+  launchAnimeBrowserDetached: (appPath, logLevel) =>
+    launchAppCommandDetached(appPath, ['--anime'], logLevel, 'anime'),
 };

 export function runAppPassthroughCommand(
@@ -37,6 +43,11 @@ export function runAppPassthroughCommand(
    deps.runAppCommandWithInherit(appPath, ['--settings']);
    return true;
  }
+  if (args.animeBrowser) {
+    // Detached: the browser window is long-lived and owns the bridge process.
+    deps.launchAnimeBrowserDetached(appPath, args.logLevel);
+    return true;
+  }
  if (args.syncUi) {
    deps.launchSyncUiDetached(appPath, args.logLevel);
    return true;
@@ -207,6 +207,7 @@ test('app command starts default macOS background app detached from launcher', (
      calls.push('attached');
    },
    launchSyncUiDetached: () => calls.push('sync-ui'),
+    launchAnimeBrowserDetached: () => {},
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -227,6 +228,7 @@ test('app command starts default Linux background app detached from launcher', (
      calls.push('attached');
    },
    launchSyncUiDetached: () => calls.push('sync-ui'),
+    launchAnimeBrowserDetached: () => {},
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -248,6 +250,7 @@ test('app command keeps explicit passthrough args attached', () => {
      forwarded.push(appArgs);
    },
    launchSyncUiDetached: () => detached.push('sync-ui'),
+    launchAnimeBrowserDetached: () => {},
    launchAppBackgroundDetached: () => {
      detached.push('detached');
    },
@@ -266,6 +269,7 @@ test('sync UI command launches the app detached from the terminal', () => {
  const handled = runAppPassthroughCommand(context, {
    runAppCommandWithInherit: () => calls.push('piped'),
    launchSyncUiDetached: (appPath, logLevel) => calls.push(`sync-ui:${appPath}:${logLevel}`),
+    launchAnimeBrowserDetached: () => calls.push('anime'),
    launchAppBackgroundDetached: () => calls.push('detached'),
  });

@@ -0,0 +1,413 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import path from 'node:path';
+import { parseArgs } from '../config.js';
+import {
+  createGenerationProgressReporter,
+  runGenerateSubtitlesCommand,
+} from './generate-subtitles-command.js';
+
+type Deps = NonNullable<Parameters<typeof runGenerateSubtitlesCommand>[1]>;
+
+function fixture(argv: string[] = ['generate-subs', '/media/episode.mkv']) {
+  const output: string[] = [];
+  const commands: unknown[][] = [];
+  const generations: Parameters<NonNullable<Deps['generate']>>[0][] = [];
+  let exitCode: number | undefined;
+  let interrupted: (() => void) | undefined;
+  let detached = false;
+  const context = {
+    args: parseArgs(argv, 'subminer', {}),
+    mpvSocketPath: '/tmp/test-subminer-socket',
+    processAdapter: {
+      writeStdout: (text: string) => {
+        output.push(text);
+      },
+      setExitCode: (code: number) => {
+        exitCode = code;
+      },
+    },
+  };
+  const deps: Deps = {
+    readConfig: () => ({ subtitleGeneration: { modelPath: '/models/external.bin' } }),
+    configPath: () => '/settings/SubMiner/config.jsonc',
+    resolveModel: async () => ({ kind: 'external', path: '/models/external.bin' }),
+    resolveTools: async () => ({
+      ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+      ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+      whisper: { kind: 'found', path: '/usr/bin/whisper-cli' },
+      vad: null,
+    }),
+    downloadModel: async () => {
+      throw new Error('Unexpected model download');
+    },
+    generate: async (input) => {
+      generations.push(input);
+      input.onProgress?.({
+        stage: 'transcribe',
+        percent: 50,
+        message: 'Transcribing Japanese audio',
+      });
+      return '/media/episode.ja.srt';
+    },
+    mpvCommand: async (_socket, command) => {
+      commands.push(command);
+      if (command[1] === 'path') return '/media/episode.mkv';
+      if (command[1] === 'track-list') return [{ type: 'audio', selected: true, 'ff-index': 2 }];
+      return undefined;
+    },
+    onInterrupt: (handler) => {
+      interrupted = handler;
+      return () => {
+        detached = true;
+      };
+    },
+  };
+  return {
+    context,
+    deps,
+    output,
+    commands,
+    generations,
+    exitCode: () => exitCode,
+    interrupt: () => interrupted?.(),
+    detached: () => detached,
+  };
+}
+
+test('launcher uses the shared core and selected mpv audio then loads the generated file', async () => {
+  const f = fixture(['generate-subs']);
+  assert.equal(await runGenerateSubtitlesCommand(f.context, f.deps), true);
+  assert.equal(f.generations[0]?.mediaPath, '/media/episode.mkv');
+  assert.equal(f.generations[0]?.audioStreamIndex, 2);
+  assert.equal(
+    f.generations[0]?.modelDirectory,
+    path.join('/settings/SubMiner', 'models', 'whisper'),
+  );
+  assert.equal(f.generations[0]?.config.modelPath, '/models/external.bin');
+  assert.deepEqual(f.commands.at(-2), [
+    'sub-add',
+    '/media/episode.ja.srt',
+    'select',
+    'Japanese (generated)',
+    'ja',
+  ]);
+  assert.deepEqual(f.commands.at(-1), ['set_property', 'sub-delay', 0]);
+  assert.match(f.output.join(''), /50%/);
+  assert.match(f.output.join(''), /Saved Japanese subtitles/);
+  assert.equal(f.detached(), true);
+});
+
+test('launcher reports a missing executable before downloading a model', async () => {
+  const f = fixture(['generate-subs', '/media/episode.mkv', '--download-model']);
+  f.deps.resolveModel = async () => ({ kind: 'missing', path: '/models/missing.bin' });
+  f.deps.resolveTools = async () => ({
+    ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+    ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+    whisper: { kind: 'missing', message: 'whisper-cli was not found on PATH.' },
+    vad: null,
+  });
+  await assert.rejects(
+    runGenerateSubtitlesCommand(f.context, f.deps),
+    /whisper-cli was not found on PATH/,
+  );
+  assert.equal(f.generations.length, 0);
+});
+
+test('launcher never downloads a model without the explicit option', async () => {
+  const f = fixture();
+  f.deps.resolveModel = async () => ({ kind: 'missing', path: '/models/missing.bin' });
+  await assert.rejects(runGenerateSubtitlesCommand(f.context, f.deps), /--download-model/);
+  assert.equal(f.generations.length, 0);
+  assert.equal(f.detached(), true);
+});
+
+test('current mpv generation requires an identifiable selected audio track', async () => {
+  for (const tracks of [
+    [],
+    [{ type: 'audio', selected: true }],
+    [{ type: 'audio', selected: true, external: true, 'ff-index': 0 }],
+  ]) {
+    const f = fixture(['generate-subs']);
+    f.deps.mpvCommand = async (_socket, command) =>
+      command[1] === 'path' ? '/media/episode.mkv' : tracks;
+    await assert.rejects(runGenerateSubtitlesCommand(f.context, f.deps), /audio track/);
+    assert.equal(f.generations.length, 0);
+  }
+});
+
+test('explicit playing file leaves audio selection to the generator but inspects subtitle references', async () => {
+  const f = fixture();
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations[0]?.audioStreamIndex, undefined);
+  assert.equal(
+    f.commands.some((command) => command[1] === 'track-list'),
+    true,
+  );
+});
+
+test('launcher does not load generated subtitles after mpv switches files', async () => {
+  const f = fixture(['generate-subs']);
+  let changed = false;
+  f.deps.mpvCommand = async (_socket, command) => {
+    f.commands.push(command);
+    if (command[1] === 'path') return changed ? '/media/next.mkv' : '/media/episode.mkv';
+    return [{ type: 'audio', selected: true, 'ff-index': 2 }];
+  };
+  f.deps.generate = async () => {
+    changed = true;
+    return '/media/episode.ja.srt';
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(
+    f.commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
+  assert.match(f.output.join(''), /Saved Japanese subtitles/);
+});
+
+test('current mpv generation rejects tracks when playback changes during capture', async () => {
+  for (const nextMedia of ['/media/next.mkv', null]) {
+    const f = fixture(['generate-subs']);
+    let media: string | null = '/media/episode.mkv';
+    let modelChecks = 0;
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return media;
+      if (command[1] === 'track-list') {
+        media = nextMedia;
+        return [{ type: 'audio', selected: true, 'ff-index': 99 }];
+      }
+      return undefined;
+    };
+    f.deps.resolveModel = async () => {
+      modelChecks += 1;
+      return { kind: 'external', path: '/models/model.bin' };
+    };
+    await assert.rejects(
+      runGenerateSubtitlesCommand(f.context, f.deps),
+      /mpv media.*Run generate-subs again/,
+    );
+    assert.equal(f.generations.length, 0);
+    assert.equal(modelChecks, 0);
+  }
+});
+
+test('explicit media or audio stream remains usable when the mpv snapshot changes', async () => {
+  for (const options of [['/media/episode.mkv'], ['--audio-stream', '7']]) {
+    const f = fixture(['generate-subs', ...options]);
+    let media = '/media/episode.mkv';
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return media;
+      if (command[1] === 'track-list') {
+        media = '/media/next.mkv';
+        return [
+          { type: 'audio', selected: true, 'ff-index': 99 },
+          { type: 'sub', lang: 'eng', 'ff-index': 100 },
+        ];
+      }
+      return undefined;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations[0]?.mediaPath, '/media/episode.mkv');
+    assert.equal(
+      f.generations[0]?.audioStreamIndex,
+      options[0] === '--audio-stream' ? 7 : undefined,
+    );
+    assert.deepEqual(f.generations[0]?.references, []);
+  }
+});
+
+test('launcher captures loaded external references only for the matching media', async () => {
+  for (const matching of [true, false]) {
+    const f = fixture();
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return matching ? '/media/episode.mkv' : '/media/other.mkv';
+      if (command[1] === 'working-directory') return '/mpv';
+      if (command[1] === 'track-list')
+        return [
+          { type: 'sub', external: true, 'external-filename': 'episode.en.signs.ass' },
+          { type: 'sub', external: true, 'external-filename': 'episode.en.srt' },
+        ];
+      return undefined;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.deepEqual(
+      f.generations[0]?.references,
+      matching
+        ? [
+            {
+              label: 'episode.en.srt',
+              delaySeconds: 0,
+              source: { kind: 'external', path: '/mpv/episode.en.srt' },
+            },
+          ]
+        : [],
+    );
+  }
+});
+
+test('explicit managed model overrides external config and downloads before generation', async () => {
+  const f = fixture([
+    'generate-subs',
+    '/media/episode.mkv',
+    '--model',
+    'medium',
+    '--download-model',
+  ]);
+  f.deps.resolveModel = async (config) => {
+    assert.equal(config.modelPath, '');
+    assert.equal(config.managedModel, 'medium');
+    return { kind: 'missing', path: '/models/medium.bin' };
+  };
+  let downloaded = false;
+  f.deps.downloadModel = async () => {
+    downloaded = true;
+    return '/models/medium.bin';
+  };
+  const generate = f.deps.generate;
+  f.deps.generate = async (input) => {
+    assert.equal(downloaded, true);
+    if (!generate) throw new Error('Missing fixture generator');
+    return generate(input);
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations.length, 1);
+});
+
+test('audio and subtitle timing use the initial mpv snapshot across model setup', async () => {
+  for (const changeDuring of ['resolve', 'download']) {
+    const f = fixture(['generate-subs', '--download-model']);
+    let changed = false;
+    let trackReads = 0;
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return '/media/episode.mkv';
+      if (command[1] === 'track-list') {
+        trackReads += 1;
+        return [
+          { type: 'audio', selected: true, 'ff-index': changed ? 3 : 2 },
+          { type: 'sub', id: 1, title: 'English Full', lang: 'eng', 'ff-index': changed ? 5 : 4 },
+        ];
+      }
+      if (command[1] === 'sid') return 1;
+      if (command[1] === 'sub-delay') return changed ? 9 : 1.5;
+      return undefined;
+    };
+    f.deps.resolveModel = async () => {
+      if (changeDuring === 'resolve') changed = true;
+      return { kind: 'missing', path: '/models/model.bin' };
+    };
+    f.deps.downloadModel = async () => {
+      changed = true;
+      return '/models/model.bin';
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations[0]?.audioStreamIndex, 2);
+    assert.deepEqual(f.generations[0]?.references, [
+      {
+        label: 'English Full',
+        delaySeconds: 1.5,
+        source: { kind: 'embedded', streamIndex: 4 },
+      },
+    ]);
+    assert.equal(trackReads, 1);
+  }
+});
+
+test('explicit audio stream bypasses mpv audio selection while retaining subtitle references', async () => {
+  const f = fixture(['generate-subs', '--audio-stream', '7']);
+  f.deps.mpvCommand = async (_socket, command) => {
+    if (command[1] === 'path') return '/media/episode.mkv';
+    if (command[1] === 'track-list')
+      return [
+        { type: 'audio', selected: true, external: true, 'ff-index': 0 },
+        { type: 'sub', id: 2, title: 'English Full', lang: 'eng', 'ff-index': 4 },
+      ];
+    if (command[1] === 'secondary-sid') return 2;
+    if (command[1] === 'secondary-sub-delay') return -0.5;
+    return undefined;
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations[0]?.audioStreamIndex, 7);
+  assert.deepEqual(f.generations[0]?.references, [
+    {
+      label: 'English Full',
+      delaySeconds: -0.5,
+      source: { kind: 'embedded', streamIndex: 4 },
+    },
+  ]);
+});
+
+test('generation can run standalone and never loads subtitles into another video', async () => {
+  for (const playing of [null, '/media/different.mkv']) {
+    const f = fixture();
+    f.deps.mpvCommand = async (_socket, command) => {
+      f.commands.push(command);
+      if (playing === null) throw new Error('mpv is not running');
+      return playing;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations.length, 1);
+    assert.equal(
+      f.commands.some((command) => command[0] === 'sub-add'),
+      false,
+    );
+  }
+});
+
+test('launcher preserves the saved path when loading into mpv fails', async () => {
+  const f = fixture();
+  const mpv = f.deps.mpvCommand;
+  f.deps.mpvCommand = async (socket, command, timeout) => {
+    if (command[0] === 'sub-add') throw new Error('load failed');
+    return mpv?.(socket, command, timeout);
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.match(f.output.join(''), /Saved Japanese subtitles: \/media\/episode.ja.srt/);
+  assert.match(f.output.join(''), /mpv could not load them: load failed/);
+  assert.equal(f.exitCode(), 1);
+});
+
+test('SIGINT cancels shared generation and unregisters its handler', async () => {
+  const f = fixture();
+  f.deps.generate = async (input) => {
+    f.interrupt();
+    assert.equal(input.signal?.aborted, true);
+    throw new Error('Aborted');
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.exitCode(), 130);
+  assert.equal(f.detached(), true);
+  assert.match(f.output.join(''), /cancelled/);
+});
+
+test('cancellation after generation preserves the saved path and skips mpv loading', async () => {
+  const f = fixture();
+  f.deps.generate = async () => {
+    f.interrupt();
+    return '/media/episode.ja.srt';
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(
+    f.commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
+  assert.match(f.output.join(''), /Saved Japanese subtitles: \/media\/episode.ja.srt/);
+  assert.equal(f.exitCode(), 130);
+  assert.equal(f.detached(), true);
+});
+
+test('progress throttles repeated updates but always reports stage changes and completion', () => {
+  const output: string[] = [];
+  let time = 0;
+  const progress = createGenerationProgressReporter(
+    (text) => output.push(text),
+    () => time,
+  );
+  progress({ stage: 'download', percent: 0, message: 'Downloading' });
+  progress({ stage: 'download', percent: 1, message: 'Downloading' });
+  time = 1000;
+  progress({ stage: 'download', percent: 50, message: 'Downloading' });
+  progress({ stage: 'download', percent: 100, message: 'Downloading' });
+  progress({ stage: 'extract', message: 'Extracting audio' });
+  assert.equal(output.length, 4);
+});
@@ -0,0 +1,245 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  downloadSubtitleGenerationModel,
+  generateJapaneseSubtitles,
+  resolveSubtitleGenerationModel,
+  resolveSubtitleGenerationTools,
+} from '../../src/core/services/subtitle-generation.js';
+import { requireSubtitleGenerationTools } from '../../src/core/services/subtitle-generation-tools.js';
+import {
+  readSubtitleGenerationReferences,
+  type SubtitleGenerationReference,
+} from '../../src/core/services/subtitle-generation-reference.js';
+import {
+  resolveSubtitleGenerationConfig,
+  type SubtitleGenerationProgress,
+} from '../../src/shared/subtitle-generation.js';
+import {
+  readLauncherMainConfigObject,
+  resolveLauncherMainConfigPath,
+} from '../config/shared-config-reader.js';
+import { sendMpvCommandWithResponse } from '../mpv.js';
+import { resolvePathMaybe } from '../util.js';
+import type { LauncherCommandContext } from './context.js';
+
+type GenerationCommandContext = Pick<LauncherCommandContext, 'args' | 'mpvSocketPath'> & {
+  processAdapter: Pick<LauncherCommandContext['processAdapter'], 'writeStdout' | 'setExitCode'>;
+};
+
+interface GenerationCommandDeps {
+  readConfig: typeof readLauncherMainConfigObject;
+  configPath: typeof resolveLauncherMainConfigPath;
+  resolveModel: typeof resolveSubtitleGenerationModel;
+  resolveTools: typeof resolveSubtitleGenerationTools;
+  downloadModel: typeof downloadSubtitleGenerationModel;
+  generate: typeof generateJapaneseSubtitles;
+  mpvCommand: typeof sendMpvCommandWithResponse;
+  onInterrupt: (handler: () => void) => () => void;
+}
+
+const defaultDeps: GenerationCommandDeps = {
+  readConfig: readLauncherMainConfigObject,
+  configPath: resolveLauncherMainConfigPath,
+  resolveModel: resolveSubtitleGenerationModel,
+  resolveTools: resolveSubtitleGenerationTools,
+  downloadModel: downloadSubtitleGenerationModel,
+  generate: generateJapaneseSubtitles,
+  mpvCommand: sendMpvCommandWithResponse,
+  onInterrupt: (handler) => {
+    process.on('SIGINT', handler);
+    return () => process.off('SIGINT', handler);
+  },
+};
+
+function localMediaPath(value: string, workingDirectory = process.cwd()): string {
+  if (value.startsWith('file://')) return fileURLToPath(value);
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(value)) {
+    throw new Error('Japanese subtitle generation requires a local media file.');
+  }
+  return path.resolve(workingDirectory, resolvePathMaybe(value));
+}
+
+async function readMpvMedia(socketPath: string, command: GenerationCommandDeps['mpvCommand']) {
+  const media = await command(socketPath, ['get_property', 'path'], 1000);
+  if (typeof media !== 'string' || !media.trim()) return null;
+  let workingDirectory: string | undefined;
+  if (!path.isAbsolute(media) && !media.startsWith('file://')) {
+    const directory = await command(socketPath, ['get_property', 'working-directory'], 1000);
+    if (typeof directory !== 'string') return null;
+    workingDirectory = directory;
+  }
+  return localMediaPath(media, workingDirectory);
+}
+
+function selectedMpvAudioStream(value: unknown) {
+  const tracks: unknown[] = Array.isArray(value) ? value : [];
+  for (const track of tracks) {
+    if (
+      typeof track === 'object' &&
+      track !== null &&
+      'type' in track &&
+      track.type === 'audio' &&
+      'selected' in track &&
+      track.selected === true
+    ) {
+      if ('external' in track && track.external === true) {
+        throw new Error(
+          'The selected mpv audio track is external. Pass its local file to generate-subs.',
+        );
+      }
+      if (
+        'ff-index' in track &&
+        typeof track['ff-index'] === 'number' &&
+        Number.isSafeInteger(track['ff-index']) &&
+        track['ff-index'] >= 0
+      ) {
+        return track['ff-index'];
+      }
+    }
+  }
+  throw new Error(
+    'Select an audio track in mpv, or pass --audio-stream with its absolute stream index.',
+  );
+}
+
+function sameFile(left: string, right: string): boolean {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+/** Keep progress readable in terminals and redirected logs, even for large model downloads. */
+export function createGenerationProgressReporter(write: (text: string) => void, now = Date.now) {
+  let previousStage: SubtitleGenerationProgress['stage'] | undefined;
+  let previousTime = -Infinity;
+  let previousLine = '';
+  return (progress: SubtitleGenerationProgress): void => {
+    const percent =
+      typeof progress.percent === 'number' && Number.isFinite(progress.percent)
+        ? Math.floor(Math.max(0, Math.min(100, progress.percent)))
+        : undefined;
+    const line = `[${progress.stage}] ${percent === undefined ? '' : `${percent}% `}${progress.message}\n`;
+    const timestamp = now();
+    if (
+      line === previousLine ||
+      (progress.stage === previousStage && timestamp - previousTime < 1000 && percent !== 100)
+    )
+      return;
+    write(line);
+    previousStage = progress.stage;
+    previousTime = timestamp;
+    previousLine = line;
+  };
+}
+
+export async function runGenerateSubtitlesCommand(
+  context: GenerationCommandContext,
+  overrides: Partial<GenerationCommandDeps> = {},
+): Promise<boolean> {
+  const options = context.args.generateSubtitles;
+  if (!options) return false;
+  const deps = { ...defaultDeps, ...overrides };
+  const write = (text: string) => context.processAdapter.writeStdout(text);
+  const controller = new AbortController();
+  const removeInterrupt = deps.onInterrupt(() => controller.abort());
+  try {
+    const config = resolveSubtitleGenerationConfig(deps.readConfig()?.subtitleGeneration);
+    if (options.managedModel) {
+      config.managedModel = options.managedModel;
+      config.modelPath = '';
+    }
+    if (options.modelPath !== undefined)
+      config.modelPath = path.resolve(resolvePathMaybe(options.modelPath));
+    const modelDirectory = path.join(path.dirname(deps.configPath()), 'models', 'whisper');
+    const currentMedia = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+      () => null,
+    );
+    const mediaPath = options.mediaPath ? localMediaPath(options.mediaPath) : currentMedia;
+    if (!mediaPath)
+      throw new Error('Pass a local video file or open one in mpv before running generate-subs.');
+    // Capture audio and subtitle timing together before model setup can yield to playback changes.
+    const matchesCurrentMedia = currentMedia !== null && sameFile(currentMedia, mediaPath);
+    const tracks = matchesCurrentMedia
+      ? await deps
+          .mpvCommand(context.mpvSocketPath, ['get_property', 'track-list'], 1000)
+          .catch(() => null)
+      : null;
+    let references: SubtitleGenerationReference[] = [];
+    if (matchesCurrentMedia) {
+      const candidates = await readSubtitleGenerationReferences(tracks, (name) =>
+        deps.mpvCommand(context.mpvSocketPath, ['get_property', name], 1000),
+      );
+      const stillPlaying = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+        () => null,
+      );
+      if (stillPlaying && sameFile(stillPlaying, mediaPath)) references = candidates;
+      else if (!options.mediaPath && options.audioStreamIndex === undefined)
+        throw new Error(
+          'The current mpv media changed or could not be verified while reading tracks. Run generate-subs again.',
+        );
+    }
+    const audioStreamIndex =
+      options.audioStreamIndex ?? (!options.mediaPath ? selectedMpvAudioStream(tracks) : undefined);
+    const onProgress = createGenerationProgressReporter(write);
+    // Missing executables fail here, before any model download starts.
+    requireSubtitleGenerationTools(await deps.resolveTools(config));
+    const model = await deps.resolveModel(config, modelDirectory);
+    if (model.kind === 'invalid') throw new Error(model.message);
+    if (model.kind === 'missing') {
+      if (!options.downloadModel) {
+        throw new Error(
+          'No Whisper model found. Run again with --download-model, or set subtitleGeneration.modelPath / --model-path.',
+        );
+      }
+      await deps.downloadModel({ config, modelDirectory, onProgress, signal: controller.signal });
+    }
+    const outputPath = await deps.generate({
+      config,
+      modelDirectory,
+      mediaPath,
+      audioStreamIndex,
+      references,
+      outputPath: options.outputPath
+        ? path.resolve(resolvePathMaybe(options.outputPath))
+        : undefined,
+      onProgress,
+      signal: controller.signal,
+    });
+    write(`Saved Japanese subtitles: ${outputPath}\n`);
+    controller.signal.throwIfAborted();
+    const playingMedia = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+      () => null,
+    );
+    controller.signal.throwIfAborted();
+    if (playingMedia && sameFile(playingMedia, mediaPath)) {
+      try {
+        await deps.mpvCommand(context.mpvSocketPath, [
+          'sub-add',
+          outputPath,
+          'select',
+          'Japanese (generated)',
+          'ja',
+        ]);
+        await deps.mpvCommand(context.mpvSocketPath, ['set_property', 'sub-delay', 0]);
+        write('Loaded Japanese subtitles into mpv.\n');
+      } catch (error) {
+        write(
+          `Subtitles are saved, but mpv could not load them: ${error instanceof Error ? error.message : String(error)}\n`,
+        );
+        context.processAdapter.setExitCode(1);
+      }
+    }
+    return true;
+  } catch (error) {
+    if (!controller.signal.aborted) throw error;
+    write('Subtitle generation cancelled.\n');
+    context.processAdapter.setExitCode(130);
+    return true;
+  } finally {
+    removeInterrupt();
+  }
+}
@@ -63,6 +63,7 @@ function createContext(): LauncherCommandContext {
      logsExport: false,
      version: false,
      settings: false,
+      animeBrowser: false,
      configPath: false,
      configShow: false,
      mpvIdle: false,
@@ -120,6 +120,7 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
      logLevel: 'warn',
    },
    settingsInvocation: null,
+    animeInvocation: null,
    mpvInvocation: null,
    appInvocation: null,
    dictionaryTriggered: false,
@@ -174,6 +175,7 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
    settingsInvocation: {
      logLevel: undefined,
    },
+    animeInvocation: null,
    mpvInvocation: null,
    appInvocation: null,
    dictionaryTriggered: false,
@@ -221,6 +223,7 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
        action: undefined,
      },
      settingsInvocation: null,
+      animeInvocation: null,
      mpvInvocation: null,
      appInvocation: null,
      dictionaryTriggered: false,
@@ -266,6 +269,7 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
    jellyfinInvocation: null,
    configInvocation: null,
    settingsInvocation: null,
+    animeInvocation: null,
    mpvInvocation: null,
    appInvocation: null,
    dictionaryTriggered: false,
@@ -170,6 +170,7 @@ export function createDefaultArgs(
    version: false,
    update: false,
    settings: false,
+    animeBrowser: false,
    configPath: false,
    configShow: false,
    mpvIdle: false,
@@ -248,6 +249,7 @@ export function applyRootOptionsToArgs(
 }

 export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations): void {
+  if (invocations.generateSubtitles) parsed.generateSubtitles = invocations.generateSubtitles;
  if (invocations.dictionaryTriggered) parsed.dictionary = true;
  if (invocations.dictionaryCandidates) parsed.dictionaryCandidates = true;
  if (invocations.dictionarySelect) parsed.dictionarySelect = true;
@@ -355,6 +357,12 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
      );
  }

+  if (invocations.animeInvocation) {
+    if (invocations.animeInvocation.logLevel) {
+      parsed.logLevel = parseLogLevel(invocations.animeInvocation.logLevel);
+    }
+    parsed.animeBrowser = true;
+  }
  if (invocations.settingsInvocation) {
    if (invocations.settingsInvocation.logLevel) {
      parsed.logLevel = parseLogLevel(invocations.settingsInvocation.logLevel);
@@ -1,6 +1,61 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { parseCliPrograms, resolveTopLevelCommand } from './cli-parser-builder.js';
+import { SUBTITLE_GENERATION_MODELS } from '../../src/shared/subtitle-generation-model-catalog.js';
+
+test('generate-subs accepts all downloadable multilingual model variants', () => {
+  for (const { id } of SUBTITLE_GENERATION_MODELS) {
+    const { invocations } = parseCliPrograms(['generate-subs', '--model', id], 'subminer');
+    assert.equal(invocations.generateSubtitles?.managedModel, id);
+  }
+});
+
+test('generate-subs parses local generation options separately from YouTube options', () => {
+  const result = parseCliPrograms(
+    [
+      'generate-subs',
+      'episode.mkv',
+      '--download-model',
+      '--model',
+      'medium',
+      '--output',
+      'episode.ja.srt',
+      '--audio-stream',
+      '2',
+    ],
+    'subminer',
+  );
+  assert.deepEqual(result.invocations.generateSubtitles, {
+    mediaPath: 'episode.mkv',
+    downloadModel: true,
+    managedModel: 'medium',
+    modelPath: undefined,
+    outputPath: 'episode.ja.srt',
+    audioStreamIndex: 2,
+  });
+  assert.equal(
+    parseCliPrograms(['generate-subs'], 'subminer').invocations.generateSubtitles?.mediaPath,
+    undefined,
+  );
+  assert.equal(
+    parseCliPrograms(['generate-subs', '--model-path', '/models/ggml.bin'], 'subminer').invocations
+      .generateSubtitles?.modelPath,
+    '/models/ggml.bin',
+  );
+});
+
+test('generate-subs rejects conflicting models and malformed audio stream indices', () => {
+  for (const flags of [
+    ['--model', 'tiny.en'],
+    ['--model', 'small.en-q5_1'],
+    ['--model', 'toString'],
+    ['--audio-stream', '-1'],
+    ['--audio-stream', '1.5'],
+    ['--model-path', '/model.bin', '--download-model'],
+    ['--model-path', '/model.bin', '--model', 'small'],
+  ])
+    assert.throws(() => parseCliPrograms(['generate-subs', ...flags], 'subminer'), /Generation/);
+});

 test('resolveTopLevelCommand skips root options and finds the first command', () => {
  assert.deepEqual(resolveTopLevelCommand(['--backend', 'macos', 'config', 'show']), {
@@ -1,4 +1,9 @@
 import { Command } from 'commander';
+import type { Args } from '../types.js';
+import {
+  isSubtitleGenerationModelId,
+  SUBTITLE_GENERATION_MODELS,
+} from '../../src/shared/subtitle-generation-model-catalog.js';

 export interface JellyfinInvocation {
  action?: string;
@@ -20,9 +25,11 @@ export interface CommandActionInvocation {
 }

 export interface CliInvocations {
+  generateSubtitles?: Args['generateSubtitles'];
  jellyfinInvocation: JellyfinInvocation | null;
  configInvocation: CommandActionInvocation | null;
  settingsInvocation: CommandActionInvocation | null;
+  animeInvocation: CommandActionInvocation | null;
  mpvInvocation: CommandActionInvocation | null;
  appInvocation: { appArgs: string[] } | null;
  dictionaryTriggered: boolean;
@@ -115,9 +122,11 @@ function getTopLevelCommand(argv: string[]): { name: string; index: number } | n
    'doctor',
    'config',
    'settings',
+    'anime',
    'mpv',
    'logs',
    'dictionary',
+    'generate-subs',
    'dict',
    'stats',
    'sync',
@@ -168,6 +177,7 @@ export function parseCliPrograms(
  let jellyfinInvocation: JellyfinInvocation | null = null;
  let configInvocation: CommandActionInvocation | null = null;
  let settingsInvocation: CommandActionInvocation | null = null;
+  let animeInvocation: CommandActionInvocation | null = null;
  let mpvInvocation: CommandActionInvocation | null = null;
  let appInvocation: { appArgs: string[] } | null = null;
  let dictionaryTriggered = false;
@@ -199,6 +209,7 @@ export function parseCliPrograms(
  let texthookerOpenBrowser = false;
  let doctorTriggered = false;
  let texthookerTriggered = false;
+  let generateSubtitles: Args['generateSubtitles'];

  const commandProgram = new Command();
  commandProgram
@@ -223,6 +234,50 @@ export function parseCliPrograms(
    .argument('[target]', 'file, directory, or URL');
  applyRootOptions(rootProgram);

+  commandProgram
+    .command('generate-subs')
+    .description('Generate Japanese subtitles locally with whisper.cpp')
+    .argument('[video]', 'Local media file, or the current mpv file if omitted')
+    .option('--download-model', 'Download the selected managed model if missing')
+    .option('--model-path <path>', 'Use an existing whisper.cpp model file')
+    .option(
+      '--model <name>',
+      `Managed model: ${SUBTITLE_GENERATION_MODELS.map((model) => model.id).join(', ')}`,
+    )
+    .option('--output <path>', 'Save subtitles to this SRT path')
+    .option('--audio-stream <index>', 'Absolute audio stream index from ffprobe')
+    .action((mediaPath: string | undefined, options: Record<string, unknown>) => {
+      const model = options.model;
+      if (model !== undefined && !isSubtitleGenerationModelId(model)) {
+        throw new Error(
+          `Generation --model must be one of: ${SUBTITLE_GENERATION_MODELS.map((entry) => entry.id).join(', ')}.`,
+        );
+      }
+      if (
+        options.modelPath !== undefined &&
+        (model !== undefined || options.downloadModel === true)
+      ) {
+        throw new Error(
+          'Generation --model-path cannot be combined with --model or --download-model.',
+        );
+      }
+      let audioStreamIndex: number | undefined;
+      if (typeof options.audioStream === 'string') {
+        audioStreamIndex = Number(options.audioStream);
+        if (!/^\d+$/.test(options.audioStream) || !Number.isSafeInteger(audioStreamIndex)) {
+          throw new Error('Generation --audio-stream must be a non-negative integer stream index.');
+        }
+      }
+      generateSubtitles = {
+        mediaPath,
+        downloadModel: options.downloadModel === true,
+        modelPath: typeof options.modelPath === 'string' ? options.modelPath : undefined,
+        managedModel: model,
+        outputPath: typeof options.output === 'string' ? options.output : undefined,
+        audioStreamIndex,
+      };
+    });
+
  commandProgram
    .command('jellyfin')
    .alias('jf')
@@ -460,6 +515,16 @@ export function parseCliPrograms(
      };
    });

+  commandProgram
+    .command('anime')
+    .description('Open the anime browser window')
+    .option('--log-level <level>', 'Log level')
+    .action((options: Record<string, unknown>) => {
+      animeInvocation = {
+        logLevel: typeof options.logLevel === 'string' ? options.logLevel : undefined,
+      };
+    });
+
  commandProgram
    .command('mpv')
    .description('MPV helpers')
@@ -511,9 +576,11 @@ export function parseCliPrograms(
    options: selectedProgram.opts<Record<string, unknown>>(),
    rootTarget: rootProgram.processedArgs[0],
    invocations: {
+      generateSubtitles,
      jellyfinInvocation,
      configInvocation,
      settingsInvocation,
+      animeInvocation,
      mpvInvocation,
      appInvocation,
      dictionaryTriggered,
@@ -57,6 +57,7 @@ function createArgs(): Args {
    logsExport: false,
    version: false,
    settings: false,
+    animeBrowser: false,
    configPath: false,
    configShow: false,
    mpvIdle: false,
@@ -25,6 +25,7 @@ import { runHistorySession } from './commands/history-command.js';
 import { runSyncCommand } from './commands/sync-command.js';
 import { runPlaybackCommand } from './commands/playback-command.js';
 import { runUpdateCommand } from './commands/update-command.js';
+import { runGenerateSubtitlesCommand } from './commands/generate-subtitles-command.js';

 const APP_VERSION =
  typeof packageJson.version === 'string' && packageJson.version.trim()
@@ -112,6 +113,10 @@ async function main(): Promise<void> {
    return;
  }

+  if (await runGenerateSubtitlesCommand(context)) {
+    return;
+  }
+
  const resolvedAppPath = ensureAppPath(context);
  state.appPath = resolvedAppPath;
  log('debug', args.logLevel, `Using SubMiner app binary: ${resolvedAppPath}`);
@@ -627,6 +627,7 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
    logsExport: false,
    version: false,
    settings: false,
+    animeBrowser: false,
    configPath: false,
    configShow: false,
    mpvIdle: false,
@@ -31,6 +31,7 @@ const SYNC_SCHEMA_OBJECTS = [
  'imm_lifetime_applied_sessions',
  'imm_stats_excluded_words',
  'idx_anime_normalized_title',
+  'idx_anime_namespace_title',
  'idx_anime_anilist_id',
  'idx_videos_anime_id',
  'idx_sessions_video_started',
@@ -12,7 +12,7 @@ export const IMMERSION_DB_FIXTURE_DDL = `
  );
  CREATE TABLE imm_anime(
    anime_id INTEGER PRIMARY KEY AUTOINCREMENT,
-    normalized_title_key TEXT NOT NULL UNIQUE,
+    normalized_title_key TEXT NOT NULL,
    canonical_title TEXT NOT NULL,
    anilist_id INTEGER UNIQUE,
    title_romaji TEXT,
@@ -20,10 +20,14 @@ export const IMMERSION_DB_FIXTURE_DDL = `
    title_native TEXT,
    episodes_total INTEGER,
    description TEXT,
+    media_kind TEXT NOT NULL DEFAULT 'anime',
+    tmdb_id INTEGER,
+    tmdb_type TEXT,
    metadata_json TEXT,
    CREATED_DATE TEXT,
    LAST_UPDATE_DATE TEXT
  );
+  CREATE UNIQUE INDEX idx_anime_namespace_title ON imm_anime((media_kind = 'youtube'), normalized_title_key);
  CREATE TABLE imm_videos(
    video_id INTEGER PRIMARY KEY AUTOINCREMENT,
    video_key TEXT NOT NULL UNIQUE,
@@ -1,6 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import type { MpvBackend, MpvLaunchMode } from '../src/types/config.js';
+import type { SubtitleGenerationConfig } from '../src/shared/subtitle-generation.js';
 import {
  resolveDefaultLogFilePath,
  type LogFileToggles,
@@ -88,6 +89,14 @@ export interface LauncherAiConfig {
 }

 export interface Args {
+  generateSubtitles?: {
+    mediaPath?: string;
+    downloadModel: boolean;
+    modelPath?: string;
+    managedModel?: SubtitleGenerationConfig['managedModel'];
+    outputPath?: string;
+    audioStreamIndex?: number;
+  };
  backend: Backend;
  directory: string;
  recursive: boolean;
@@ -152,6 +161,7 @@ export interface Args {
  version: boolean;
  update?: boolean;
  settings: boolean;
+  animeBrowser: boolean;
  configPath: boolean;
  configShow: boolean;
  mpvIdle: boolean;
@@ -21,10 +21,11 @@
    "build:launcher": "bun run scripts/build-launcher.ts",
    "build:stats": "cd stats && bun run build",
    "dev:stats": "cd stats && bun run dev",
-    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:syncui && bun run build:launcher && bun run build:assets",
+    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:syncui && bun run build:animeui && bun run build:launcher && bun run build:assets",
    "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
    "build:settings": "esbuild src/settings/settings.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/settings/settings.js --sourcemap",
    "build:syncui": "esbuild src/syncui/syncui.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/syncui/syncui.js --sourcemap && esbuild src/preload-syncui.ts --bundle --platform=node --format=cjs --target=node20 --external:electron --outfile=dist/preload-syncui.js --sourcemap",
+    "build:animeui": "esbuild src/animeui/animeui.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/animeui/animeui.js --sourcemap && esbuild src/preload-animeui.ts --bundle --platform=node --format=cjs --target=node20 --external:electron --outfile=dist/preload-animeui.js --sourcemap",
    "changelog:build": "bun run scripts/build-changelog.ts build-release",
    "changelog:check": "bun run scripts/build-changelog.ts check",
    "changelog:docs": "bun run scripts/build-changelog.ts docs",
@@ -51,7 +52,7 @@
    "test:docs:kb": "bun test scripts/docs-knowledge-base.test.ts",
    "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-process-start-retries.lua && lua scripts/test-plugin-restart-feedback.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
    "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
-    "test:smoke:dist": "bun scripts/run-test-lane.mjs bun-src-full",
+    "test:smoke:dist": "env ELECTRON_RUN_AS_NODE=1 electron scripts/compiled-runtime-smoke.mjs",
    "test:subtitle:src": "bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts",
    "test:immersion:sqlite:src": "bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts",
    "test:immersion:sqlite:dist": "bun test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js",
@@ -63,7 +64,7 @@
    "test:scripts": "bun scripts/run-test-lane.mjs scripts",
    "test:stats": "bun scripts/run-test-lane.mjs stats",
    "test:env": "bun run test:launcher:smoke:src && bun run test:plugin:src && bun run test:immersion:sqlite:src",
-    "test:runtime:compat": "bun run tsc && bun scripts/run-test-lane.mjs bun-src-full",
+    "test:runtime:compat": "bun run test:smoke:dist",
    "test": "bun run test:fast",
    "test:config": "bun scripts/run-test-lane.mjs config",
    "test:launcher": "bun scripts/run-test-lane.mjs launcher && bun run test:plugin:src",
@@ -1,7 +1,7 @@
 pkgbase = subminer-bin
 	pkgdesc = All-in-one sentence mining overlay with AnkiConnect and dictionary integration
-	pkgver = 0.6.2
-	pkgrel = 1
+	pkgver = 0.19.5
+	pkgrel = 2
 	url = https://github.com/ksyasuda/SubMiner
 	arch = x86_64
 	license = GPL-3.0-or-later
@@ -25,16 +25,17 @@ pkgbase = subminer-bin
 	optdepends = python-guessit: improved AniSkip title and episode inference
 	optdepends = alass-git: preferred subtitle synchronization engine
 	optdepends = python-ffsubsync: fallback subtitle synchronization engine
-	provides = subminer=0.6.2
+	optdepends = mangatan-extension-server: anime browser bridge shared with Mangatan; skips the bundle download and is updated by pacman
+	provides = subminer=0.19.5
 	conflicts = subminer
-	noextract = SubMiner-0.6.2.AppImage
+	noextract = SubMiner-0.19.5.AppImage
 	options = !strip
 	options = !debug
-	source = SubMiner-0.6.2.AppImage::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/SubMiner-0.6.2.AppImage
-	source = subminer-0.6.2::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer
-	source = subminer-assets-0.6.2.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer-assets.tar.gz
-	sha256sums = c91667adbbc47a0fba34855358233454a9ea442ab57510546b2219abd1f2461e
-	sha256sums = 85050918e14cb2512fcd34be83387a2383fa5c206dc1bdc11e8d98f7d37817e5
-	sha256sums = 210113be64a06840f4dfaebc22a8e6fc802392f1308413aa00d9348c804ab2a1
+	source = SubMiner-0.19.5.AppImage::https://github.com/ksyasuda/SubMiner/releases/download/v0.19.5/SubMiner-0.19.5.AppImage
+	source = subminer-0.19.5::https://github.com/ksyasuda/SubMiner/releases/download/v0.19.5/subminer
+	source = subminer-assets-0.19.5.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v0.19.5/subminer-assets.tar.gz
+	sha256sums = bd683d949956ff847927f23acfede49efad6320cf7ec4cdc3cbd586a5287884e
+	sha256sums = 2fa292f672df715461765aef8d5c6bf3612004c8b8070b1b1f0afa10d4b74c1e
+	sha256sums = 591468a1fc68a13de315acaf1154df9da41fe3bcbc0e5522a04ba21e939ed1ae

 pkgname = subminer-bin
@@ -1,8 +1,8 @@
 # Maintainer: Kyle Yasuda <suda@sudacode.com>

 pkgname=subminer-bin
-pkgver=0.6.2
-pkgrel=1
+pkgver=0.19.5
+pkgrel=2
 pkgdesc='All-in-one sentence mining overlay with AnkiConnect and dictionary integration'
 arch=('x86_64')
 url='https://github.com/ksyasuda/SubMiner'
@@ -26,6 +26,7 @@ optdepends=(
 	'python-guessit: improved AniSkip title and episode inference'
 	'alass-git: preferred subtitle synchronization engine'
 	'python-ffsubsync: fallback subtitle synchronization engine'
+	'mangatan-extension-server: anime browser bridge shared with Mangatan; skips the bundle download and is updated by pacman'
 )
 provides=("subminer=${pkgver}")
 conflicts=('subminer')
@@ -35,9 +36,9 @@ source=(
 	"subminer-assets-${pkgver}.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/subminer-assets.tar.gz"
 )
 sha256sums=(
-	'c91667adbbc47a0fba34855358233454a9ea442ab57510546b2219abd1f2461e'
-	'85050918e14cb2512fcd34be83387a2383fa5c206dc1bdc11e8d98f7d37817e5'
-	'210113be64a06840f4dfaebc22a8e6fc802392f1308413aa00d9348c804ab2a1'
+	'bd683d949956ff847927f23acfede49efad6320cf7ec4cdc3cbd586a5287884e'
+	'2fa292f672df715461765aef8d5c6bf3612004c8b8070b1b1f0afa10d4b74c1e'
+	'591468a1fc68a13de315acaf1154df9da41fe3bcbc0e5522a04ba21e939ed1ae'
 )
 noextract=("SubMiner-${pkgver}.AppImage")

@@ -268,6 +268,8 @@ function M.create(ctx)
 			return { "--open-controller-debug" }
 		elseif action_id == "openPlaylistBrowser" then
 			return { "--open-playlist-browser" }
+		elseif action_id == "openAnimeBrowser" then
+			return { "--session-action", '{"actionId":"openAnimeBrowser"}' }
 		elseif action_id == "replayCurrentSubtitle" then
 			return { "--replay-current-subtitle" }
 		elseif action_id == "playNextSubtitle" then
@@ -1,54 +0,0 @@
-## Highlights
-### Added
- **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
- **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
- **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(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
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
- Linux: `SubMiner.AppImage`
- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
- Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher
- Bun corresponding source: `bun-v1.3.5-source.tar.gz` and its `.sha256` file
-
-Both launcher downloads use Bun included with the SubMiner app. Download `subminer` on Linux or macOS and `subminer.cmd` on Windows.
-
-The app bundles an unmodified Bun 1.3.5 runtime. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and third-party notices ship inside the app under `resources/bun/licenses`, and the source archive above contains the matching Bun, WebKit, and dependency sources for relinking.
@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Release builds carry a project-owned TMDB key so live-action lookups work
+ * without user setup. The key is injected from the SUBMINER_TMDB_API_KEY
+ * environment variable at build time (a GitHub Actions secret in CI) and never
+ * lives in the repository. The runtime reader is
+ * src/core/services/tmdb/bundled-api-key.ts; keep the file name in sync.
+ */
+export const BUNDLED_INTEGRATION_KEYS_FILENAME = 'bundled-integration-keys.json';
+export const TMDB_API_KEY_ENV = 'SUBMINER_TMDB_API_KEY';
+
+/**
+ * Write the bundled keys file into `distDir`, or remove a stale one when no
+ * key is present so a keyless build never ships an older key by accident.
+ * Returns the names of the keys staged.
+ */
+export function stageBundledIntegrationKeys(distDir, env = process.env) {
+  const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+  const tmdbApiKey = env[TMDB_API_KEY_ENV]?.trim() ?? '';
+  if (!tmdbApiKey) {
+    fs.rmSync(outputPath, { force: true });
+    return [];
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify({ tmdbApiKey })}\n`, { mode: 0o644 });
+  return ['tmdb'];
+}
@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  BUNDLED_INTEGRATION_KEYS_FILENAME,
+  stageBundledIntegrationKeys,
+} from './bundled-integration-keys.mjs';
+
+function withDistDir(work: (distDir: string) => void): void {
+  const distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-bundled-keys-'));
+  try {
+    work(distDir);
+  } finally {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+}
+
+test('stageBundledIntegrationKeys writes the TMDB key from the environment', () => {
+  withDistDir((distDir) => {
+    const staged = stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: ' abc123 ' });
+    assert.deepEqual(staged, ['tmdb']);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME), 'utf8'),
+    );
+    assert.deepEqual(written, { tmdbApiKey: 'abc123' });
+  });
+});
+
+test('stageBundledIntegrationKeys removes a stale file when the variable is unset', () => {
+  withDistDir((distDir) => {
+    const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+    fs.writeFileSync(outputPath, '{"tmdbApiKey":"old"}');
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, {}), []);
+    assert.equal(fs.existsSync(outputPath), false);
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: '  ' }), []);
+  });
+});
@@ -0,0 +1,345 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const START_TIMEOUT_MS = 15_000;
+const STOP_TIMEOUT_MS = 5_000;
+const POLL_INTERVAL_MS = 25;
+const MAX_CHILD_OUTPUT_BYTES = 64 * 1024;
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRootArgIndex = process.argv.indexOf('--repo-root');
+const repoRoot = resolve(
+  repoRootArgIndex === -1 ? join(scriptDir, '..') : (process.argv[repoRootArgIndex + 1] ?? ''),
+);
+const paths = {
+  mainEntry: join(repoRoot, 'dist', 'main-entry.js'),
+  daemonEntry: join(repoRoot, 'dist', 'stats-daemon-runner.js'),
+  statsServer: join(repoRoot, 'dist', 'core', 'services', 'stats-server.js'),
+  tracker: join(repoRoot, 'dist', 'core', 'services', 'immersion-tracker-service.js'),
+  statsIndex: join(repoRoot, 'stats', 'dist', 'index.html'),
+};
+
+function requireCompiledArtifacts() {
+  const missing = Object.values(paths).filter((artifactPath) => !existsSync(artifactPath));
+  if (missing.length > 0) {
+    throw new Error(
+      `Compiled runtime artifacts are missing. Run \`bun run build\` before this check:\n${missing
+        .map((artifactPath) => `  - ${artifactPath}`)
+        .join('\n')}`,
+    );
+  }
+}
+
+function requireElectronNodeRuntime() {
+  if (!process.versions.electron || process.env.ELECTRON_RUN_AS_NODE !== '1') {
+    throw new Error(
+      'This check must run with Electron in Node mode. Use `bun run test:smoke:dist`.',
+    );
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+function listen(server, port = 0) {
+  return new Promise((resolvePromise, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('Could not resolve the stats smoke port.'));
+        return;
+      }
+      resolvePromise(address.port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolvePromise, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+async function findAvailablePort() {
+  const reservation = createServer();
+  const port = await listen(reservation);
+  await closeServer(reservation);
+  return port;
+}
+
+function writeSmokeConfig(userDataPath, port) {
+  writeFileSync(
+    join(userDataPath, 'config.json'),
+    `${JSON.stringify({ stats: { serverPort: port } })}\n`,
+  );
+}
+
+function spawnDaemon(userDataPath, responsePath) {
+  const child = spawn(
+    process.execPath,
+    [
+      paths.daemonEntry,
+      '--stats-user-data-path',
+      userDataPath,
+      '--stats-response-path',
+      responsePath,
+    ],
+    {
+      cwd: repoRoot,
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  let output = '';
+  const appendOutput = (chunk) => {
+    if (output.length >= MAX_CHILD_OUTPUT_BYTES) return;
+    output += String(chunk);
+    if (output.length > MAX_CHILD_OUTPUT_BYTES) {
+      output = `${output.slice(0, MAX_CHILD_OUTPUT_BYTES)}\n[child output truncated]\n`;
+    }
+  };
+  child.stdout.on('data', appendOutput);
+  child.stderr.on('data', appendOutput);
+  let exited = false;
+  const exit = new Promise((resolvePromise) => {
+    child.once('error', (error) => {
+      exited = true;
+      resolvePromise({ code: null, signal: null, error });
+    });
+    child.once('exit', (code, signal) => {
+      exited = true;
+      resolvePromise({ code, signal, error: null });
+    });
+  });
+  return { child, exit, hasExited: () => exited, getOutput: () => output };
+}
+
+async function waitForResponse(responsePath, daemon) {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (existsSync(responsePath)) {
+      try {
+        return JSON.parse(readFileSync(responsePath, 'utf8'));
+      } catch {
+        // The daemon may still be finishing the response file write.
+      }
+    }
+    if (daemon.hasExited()) {
+      const result = await daemon.exit;
+      throw new Error(
+        `Stats daemon exited before writing a startup response (${formatExit(result)}).\n${daemon.getOutput()}`,
+      );
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for stats daemon startup.\n${daemon.getOutput()}`);
+}
+
+function formatExit(result) {
+  if (result.error) return result.error.message;
+  if (result.signal) return `signal ${result.signal}`;
+  return `exit code ${result.code}`;
+}
+
+async function waitForExit(daemon, timeoutMs) {
+  return await Promise.race([daemon.exit, delay(timeoutMs).then(() => null)]);
+}
+
+async function stopDaemon(daemon) {
+  if (daemon.hasExited()) {
+    return await daemon.exit;
+  }
+  daemon.child.kill('SIGTERM');
+  const result = await waitForExit(daemon, STOP_TIMEOUT_MS);
+  if (result) return result;
+  daemon.child.kill('SIGKILL');
+  await daemon.exit;
+  throw new Error(`Stats daemon did not stop after SIGTERM.\n${daemon.getOutput()}`);
+}
+
+async function assertPortCanBind(port) {
+  const server = createServer();
+  try {
+    await listen(server, port);
+  } finally {
+    if (server.listening) await closeServer(server);
+  }
+}
+
+async function fetchOverview(url, daemon) {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await fetch(`${url}/api/stats/overview`, {
+        signal: AbortSignal.timeout(START_TIMEOUT_MS),
+      });
+    } catch (error) {
+      lastError = error;
+    }
+    if (daemon.hasExited()) {
+      const result = await daemon.exit;
+      throw new Error(
+        `Stats daemon exited before accepting HTTP requests (${formatExit(result)}).\n${daemon.getOutput()}`,
+      );
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+  throw new Error(
+    `Timed out waiting for the stats HTTP server: ${lastError instanceof Error ? lastError.message : String(lastError)}\n${daemon.getOutput()}`,
+  );
+}
+
+async function runHealthyStartup(userDataPath, port, responseName) {
+  writeSmokeConfig(userDataPath, port);
+  const responsePath = join(userDataPath, responseName);
+  const statePath = join(userDataPath, 'stats-daemon.json');
+  const databasePath = join(userDataPath, 'immersion.sqlite');
+  const daemon = spawnDaemon(userDataPath, responsePath);
+  let shutdownResult;
+  let unfinishedRequest;
+
+  try {
+    const startup = await waitForResponse(responsePath, daemon);
+    assert.deepEqual(startup, { ok: true, url: `http://127.0.0.1:${port}` });
+
+    const response = await fetchOverview(startup.url, daemon);
+    assert.equal(response.status, 200);
+    assert.match(response.headers.get('content-type') ?? '', /^application\/json\b/);
+    const overview = await response.json();
+    assert.equal(typeof overview, 'object');
+    assert.ok(overview !== null);
+    assert.ok(Array.isArray(overview.sessions));
+    assert.ok(Array.isArray(overview.rollups));
+    assert.equal(typeof overview.hints, 'object');
+
+    const dashboard = await fetch(`${startup.url}/?overlay=1`, {
+      signal: AbortSignal.timeout(START_TIMEOUT_MS),
+    });
+    assert.equal(dashboard.status, 200);
+    assert.match(dashboard.headers.get('content-type') ?? '', /^text\/html\b/);
+    assert.match(await dashboard.text(), /id="root"/);
+
+    assert.ok(existsSync(databasePath), 'The compiled tracker did not create its SQLite database.');
+    assert.ok(
+      statSync(databasePath).size > 0,
+      'The compiled tracker created an empty SQLite file.',
+    );
+
+    // Leave a real request body unfinished so shutdown must bound its drain wait.
+    unfinishedRequest = httpRequest(new URL('/api/stats/anki/notesInfo', startup.url), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': '1000',
+        Expect: '100-continue',
+      },
+      signal: AbortSignal.timeout(START_TIMEOUT_MS),
+    });
+    await new Promise((resolvePromise, reject) => {
+      unfinishedRequest.on('error', reject);
+      unfinishedRequest.once('continue', () => {
+        unfinishedRequest.write('{');
+        resolvePromise();
+      });
+      unfinishedRequest.flushHeaders();
+    });
+  } finally {
+    try {
+      shutdownResult = await stopDaemon(daemon);
+    } finally {
+      unfinishedRequest?.destroy();
+    }
+  }
+
+  assert.equal(shutdownResult.code, 0, `Stats daemon shutdown failed.\n${daemon.getOutput()}`);
+  assert.equal(existsSync(statePath), false, 'Stats daemon state remained after shutdown.');
+  await assertPortCanBind(port);
+}
+
+async function runConflictRecovery() {
+  const userDataPath = mkdtempSync(join(tmpdir(), 'subminer-compiled-conflict-'));
+  const reservation = createServer();
+  const port = await listen(reservation);
+  const responsePath = join(userDataPath, 'conflict-response.json');
+  const statePath = join(userDataPath, 'stats-daemon.json');
+  writeSmokeConfig(userDataPath, port);
+  const daemon = spawnDaemon(userDataPath, responsePath);
+  const failures = [];
+
+  try {
+    const response = await waitForResponse(responsePath, daemon);
+    if (response.ok !== false) {
+      failures.push('The stats daemon reported success while its configured port was occupied.');
+    }
+    const result = await waitForExit(daemon, STOP_TIMEOUT_MS);
+    if (!result) {
+      failures.push('The stats daemon did not exit after its configured port failed to bind.');
+    } else if (result.code === 0) {
+      failures.push(
+        'The stats daemon exited successfully after its configured port failed to bind.',
+      );
+    }
+    if (existsSync(statePath)) {
+      failures.push(
+        'The stats daemon left ownership state behind after its configured port failed to bind.',
+      );
+    }
+  } finally {
+    await closeServer(reservation);
+    if (!daemon.hasExited()) {
+      await stopDaemon(daemon);
+    }
+  }
+
+  try {
+    await runHealthyStartup(userDataPath, port, 'recovery-response.json');
+  } finally {
+    rmSync(userDataPath, { recursive: true, force: true });
+  }
+
+  assert.deepEqual(failures, []);
+}
+
+async function main() {
+  requireCompiledArtifacts();
+  requireElectronNodeRuntime();
+
+  const userDataPath = mkdtempSync(join(tmpdir(), 'subminer-compiled-runtime-'));
+  try {
+    await runHealthyStartup(userDataPath, await findAvailablePort(), 'startup-response.json');
+  } finally {
+    rmSync(userDataPath, { recursive: true, force: true });
+  }
+  await runConflictRecovery();
+
+  process.stdout.write(
+    `Compiled runtime smoke passed with Electron ${process.versions.electron}, Node ${process.versions.node}, HTTP, and native SQLite.\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+  process.exitCode = 1;
+});
@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+test('compiled runtime smoke fails clearly when build artifacts are missing', () => {
+  const emptyRepo = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-compiled-missing-'));
+  try {
+    const result = spawnSync(
+      process.execPath,
+      ['scripts/compiled-runtime-smoke.mjs', '--repo-root', emptyRepo],
+      {
+        cwd: path.resolve(import.meta.dir, '..'),
+        encoding: 'utf8',
+      },
+    );
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /Compiled runtime artifacts are missing/);
+    assert.match(result.stderr, /dist\/main-entry\.js/);
+    assert.match(result.stderr, /dist\/stats-daemon-runner\.js/);
+    assert.doesNotMatch(result.stderr, /must run with Electron/);
+  } finally {
+    fs.rmSync(emptyRepo, { recursive: true, force: true });
+  }
+});
@@ -3,14 +3,40 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';

-test('build:syncui bundles the sandboxed preload and keeps Electron external', () => {
+function buildScript(name: string): string {
  const packageJson = JSON.parse(
    fs.readFileSync(path.join(import.meta.dir, '..', 'package.json'), 'utf8'),
  ) as { scripts: Record<string, string> };
-  const command = packageJson.scripts['build:syncui'] ?? '';
+  return packageJson.scripts[name] ?? '';
+}
+
+test('build:syncui bundles the sandboxed preload and keeps Electron external', () => {
+  const command = buildScript('build:syncui');

  assert.match(command, /src\/preload-syncui\.ts/);
  assert.match(command, /--bundle/);
  assert.match(command, /--external:electron/);
  assert.match(command, /--outfile=dist\/preload-syncui\.js/);
 });
+
+test('build:animeui bundles the sandboxed preload and keeps Electron external', () => {
+  const command = buildScript('build:animeui');
+  const sharedPreloadSource = fs.readFileSync(
+    path.join(import.meta.dir, '..', 'src', 'preload-anime-browser-api.ts'),
+    'utf8',
+  );
+
+  // The preload imports IPC_CHANNELS, so it must be bundled rather than
+  // emitted by plain tsc with a relative runtime require.
+  assert.match(command, /src\/preload-animeui\.ts/);
+  assert.match(command, /--bundle/);
+  assert.match(command, /--external:electron/);
+  assert.match(command, /--outfile=dist\/preload-animeui\.js/);
+  // The standalone Anime window uses Electron's sandboxed preload runtime,
+  // which exposes `electron` but cannot require arbitrary Node built-ins.
+  assert.doesNotMatch(sharedPreloadSource, /from ['"]node:/);
+});
+
+test('build:animeui runs as part of the top-level build', () => {
+  assert.match(buildScript('build'), /bun run build:animeui/);
+});
@@ -3,15 +3,19 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { stageBundledIntegrationKeys, TMDB_API_KEY_ENV } from './bundled-integration-keys.mjs';

 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, '..');
+const assetsSourceDir = path.join(repoRoot, 'assets');
 const rendererSourceDir = path.join(repoRoot, 'src', 'renderer');
 const rendererOutputDir = path.join(repoRoot, 'dist', 'renderer');
 const settingsSourceDir = path.join(repoRoot, 'src', 'settings');
 const settingsOutputDir = path.join(repoRoot, 'dist', 'settings');
 const syncUiSourceDir = path.join(repoRoot, 'src', 'syncui');
 const syncUiOutputDir = path.join(repoRoot, 'dist', 'syncui');
+const animeUiSourceDir = path.join(repoRoot, 'src', 'animeui');
+const animeUiOutputDir = path.join(repoRoot, 'dist', 'animeui');
 const scriptsOutputDir = path.join(repoRoot, 'dist', 'scripts');
 const macosHelperSourcePath = path.join(scriptDir, 'get-mpv-window-macos.swift');
 const macosHelperBinaryPath = path.join(scriptsOutputDir, 'get-mpv-window-macos');
@@ -26,9 +30,11 @@ function copyFile(sourcePath, outputPath) {
  fs.copyFileSync(sourcePath, outputPath);
 }

-function copyAssets(sourceDir, outputDir, label) {
+function copyAssets(sourceDir, outputDir, label, stylesheets = ['style.css']) {
  copyFile(path.join(sourceDir, 'index.html'), path.join(outputDir, 'index.html'));
-  copyFile(path.join(sourceDir, 'style.css'), path.join(outputDir, 'style.css'));
+  for (const stylesheet of stylesheets) {
+    copyFile(path.join(sourceDir, stylesheet), path.join(outputDir, stylesheet));
+  }
  process.stdout.write(`Staged ${label} assets in ${outputDir}\n`);
 }

@@ -44,6 +50,15 @@ function copySyncUiAssets() {
  copyAssets(syncUiSourceDir, syncUiOutputDir, 'syncui');
 }

+function copyAnimeUiAssets() {
+  copyAssets(animeUiSourceDir, animeUiOutputDir, 'animeui', [
+    'style.css',
+    'detail.css',
+    'panels.css',
+  ]);
+  copyFile(path.join(assetsSourceDir, 'SubMiner.png'), path.join(animeUiOutputDir, 'SubMiner.png'));
+}
+
 function fallbackToMacosSource() {
  copyFile(macosHelperSourcePath, macosHelperSourceCopyPath);
  process.stdout.write(`Staged macOS helper source fallback: ${macosHelperSourceCopyPath}\n`);
@@ -97,6 +112,17 @@ function buildMacosHelper() {
  }
 }

+// Only the key names are logged, never the values: CI masks secrets, but a
+// stray echo would still leak them into local build logs.
+function stageIntegrationKeys() {
+  const staged = stageBundledIntegrationKeys(path.join(repoRoot, 'dist'));
+  process.stdout.write(
+    staged.length > 0
+      ? `Staged bundled integration keys: ${staged.join(', ')}\n`
+      : `No bundled integration keys (${TMDB_API_KEY_ENV} unset)\n`,
+  );
+}
+
 function main() {
  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(repoRoot, 'dist', 'fonts'), {
    recursive: true,
@@ -105,7 +131,9 @@ function main() {
  copyRendererAssets();
  copySettingsAssets();
  copySyncUiAssets();
+  copyAnimeUiAssets();
  buildMacosHelper();
+  stageIntegrationKeys();
 }

 main();
@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import test from 'node:test';

 const source = readFileSync('scripts/prepare-build-assets.mjs', 'utf8');
@@ -19,6 +19,26 @@ test('macOS helper build creates dist scripts directory before swiftc output', (
  );
 });

+test('anime UI stylesheet files exist and are all staged', () => {
+  const html = readFileSync('src/animeui/index.html', 'utf8');
+  const stylesheets = [...html.matchAll(/<link rel="stylesheet" href="\.\/(.+?\.css)"/g)].map(
+    (match) => match[1],
+  );
+
+  assert.deepEqual(stylesheets, ['style.css', 'detail.css', 'panels.css']);
+  for (const stylesheet of stylesheets) {
+    assert.equal(existsSync(`src/animeui/${stylesheet}`), true, `${stylesheet} must exist`);
+  }
+  assert.match(
+    source,
+    /copyAssets\(animeUiSourceDir, animeUiOutputDir, 'animeui', \[\s*'style\.css',\s*'detail\.css',\s*'panels\.css',?\s*\]\)/,
+  );
+  assert.match(
+    source,
+    /copyFile\(\s*path\.join\(assetsSourceDir, 'SubMiner\.png'\),\s*path\.join\(animeUiOutputDir, 'SubMiner\.png'\),?\s*\)/,
+  );
+});
+
 // Regression guard for #213: an untargeted swiftc stamps the build machine's OS
 // version as the helper's minimum, so released builds refuse to load on older macOS.
 test('macOS helper is compiled with an explicit deployment target', () => {