feat(plugin): add AniSkip intro skip flow with launcher metadata hints

2026-02-27 18:22:41 -08:00 · 2026-02-22 02:14:37 -08:00
parent b3b55de4b9
commit f6e7dd496a
10 changed files with 1056 additions and 1 deletions
--- a/docs/mpv-plugin.md
+++ b/docs/mpv-plugin.md
@@ -38,6 +38,7 @@ All keybindings use a `y` chord prefix — press `y`, then the second key:
 | `y-o` | Open settings window     |
 | `y-r` | Restart overlay          |
 | `y-c` | Check status             |
+| `y-k` | Skip intro (AniSkip)     |

 ## Menu

@@ -91,6 +92,29 @@ osd_messages=yes

 # Logging level: debug, info, warn, error.
 log_level=info
+
+# Enable AniSkip intro detection/markers.
+aniskip_enabled=yes
+
+# Optional title override (launcher fills from guessit when available).
+aniskip_title=
+
+# Optional season override (launcher fills from guessit when available).
+aniskip_season=
+
+# Optional MAL ID override. Leave blank to resolve from media title.
+aniskip_mal_id=
+
+# Optional episode override. Leave blank to detect from filename/title.
+aniskip_episode=
+
+# Show OSD skip button while inside intro range.
+aniskip_show_button=yes
+
+# OSD label + keybinding for intro skip action.
+aniskip_button_text=You can skip by pressing %s
+aniskip_button_key=y-k
+aniskip_button_duration=3
 ```

 ### Option Reference
@@ -107,6 +131,15 @@ log_level=info
 | `auto_start_invisible_overlay` | `platform-default`     | `platform-default`, `visible`, `hidden`    | Invisible layer on auto-start    |
 | `osd_messages`                 | `yes`                  | `yes` / `no`                               | Show OSD status messages         |
 | `log_level`                    | `info`                 | `debug`, `info`, `warn`, `error`           | Log verbosity                    |
+| `aniskip_enabled`              | `yes`                  | `yes` / `no`                               | Enable AniSkip intro detection   |
+| `aniskip_title`                | `""`                   | string                                     | Override title used for lookup   |
+| `aniskip_season`               | `""`                   | numeric season                             | Optional season hint             |
+| `aniskip_mal_id`               | `""`                   | numeric MAL id                             | Skip title lookup; use fixed id  |
+| `aniskip_episode`              | `""`                   | numeric episode                            | Skip episode parsing; use fixed  |
+| `aniskip_show_button`          | `yes`                  | `yes` / `no`                               | Show in-range intro skip prompt  |
+| `aniskip_button_text`          | `You can skip by pressing %s` | string                              | OSD prompt format (`%s`=key)     |
+| `aniskip_button_key`           | `y-k`                  | mpv key chord                              | Primary key for intro skip action (`y-k` always works as fallback) |
+| `aniskip_button_duration`      | `3`                    | float seconds                              | OSD hint duration                |

 ## Binary Auto-Detection

@@ -155,6 +188,8 @@ script-message subminer-menu
 script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
+script-message subminer-aniskip-refresh
+script-message subminer-skip-intro
 ```

 The `subminer-start` message accepts overrides:
@@ -166,6 +201,15 @@ script-message subminer-start backend=hyprland socket=/custom/path texthooker=no
 `log-level` here controls only logging verbosity passed to SubMiner.
 `--debug` is a separate app/dev-mode flag in the main CLI and should not be used here for logging.

+## AniSkip Intro Skip
+
+- On file load, plugin resolves title + episode, resolves MAL id, then calls AniSkip API.
+- When launched via `subminer`, launcher runs `guessit` first (file targets) and passes title/season/episode to the plugin; fallback is filename-derived title.
+- Install `guessit` for best detection quality (`python3 -m pip install --user guessit`).
+- If OP interval exists, plugin adds `AniSkip Intro Start` and `AniSkip Intro End` chapters.
+- At intro start, plugin shows an OSD hint for the first 3 seconds (`You can skip by pressing y-k` by default).
+- Use `script-message subminer-aniskip-refresh` after changing media metadata/options to retry lookup.
+
 ## Lifecycle

 - **File loaded**: If `auto_start=yes`, the plugin starts the overlay and applies visibility preferences after a short delay.
--- a/docs/subagents/INDEX.md
+++ b/docs/subagents/INDEX.md
@@ -4,6 +4,7 @@ Read first. Keep concise.

 | agent_id                                                      | alias                                   | mission                                                                                                              | status        | file                                                                                   | last_update_utc        |
 | ------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- | ---------------------- |
+| `codex-aniskip-intro-skip-20260222T080257Z-51fx` | `codex-aniskip-intro-skip` | `Port intro skip to AniSkip API in mpv plugin with OSD skip button` | `handoff` | `docs/subagents/agents/codex-aniskip-intro-skip-20260222T080257Z-51fx.md` | `2026-02-22T10:04:20Z` |
 | `codex-generate-minecard-image-20260220T112900Z-vsxr`         | `codex-generate-minecard-image`         | `Generate media fallbacks (GIF) from assets/minecard.webm and wire README/docs fallback markup`                      | `done`        | `docs/subagents/agents/codex-generate-minecard-image-20260220T112900Z-vsxr.md`         | `2026-02-20T11:35:30Z` |
 | `codex-main`                                                  | `planner-exec`                          | `Fix frequency/N+1 regression in plugin --start flow`                                                                | `in_progress` | `docs/subagents/agents/codex-main.md`                                                  | `2026-02-19T19:36:46Z` |
 | `codex-task85-20260219T233711Z-46hc`                          | `codex-task85`                          | `Resume TASK-85 maintainability refactor from latest handoff point`                                                  | `in_progress` | `docs/subagents/agents/codex-task85-20260219T233711Z-46hc.md`                          | `2026-02-20T11:42:39Z` |
@@ -69,3 +70,4 @@ Read first. Keep concise.
 | `codex-review-cleanup-20260222T065718Z-9p4m` | `codex-review-cleanup` | `Review post-refactor codebase quality and create cleanup tickets with concrete scope and completion criteria` | `done` | `docs/subagents/agents/codex-review-cleanup-20260222T065718Z-9p4m.md` | `2026-02-22T07:04:48Z` |
 | `codex-jellyfin-ts-fix-20260222T071530Z-5e50` | `codex-jellyfin-ts-fix` | `Fix Jellyfin token/session type drift causing TS compile failures in config+main.` | `done` | `docs/subagents/agents/codex-jellyfin-ts-fix-20260222T071530Z-5e50.md` | `2026-02-22T07:23:47Z` |
 | `codex-overlay-toggle-regression-20260222T073450Z-q7m4` | `codex-overlay-toggle-regression` | `Fix post-rebase overlay toggle regression causing transparent non-interactable windows and broken keybinds (TASK-107).` | `testing` | `docs/subagents/agents/codex-overlay-toggle-regression-20260222T073450Z-q7m4.md` | `2026-02-22T07:45:58Z` |
+| `codex-docs-review-20260222T094009Z-g8p2` | `codex-docs-review` | `Review README/docs for drift vs current code/scripts; patch stale or missing documentation.` | `done` | `docs/subagents/agents/codex-docs-review-20260222T094009Z-g8p2.md` | `2026-02-22T09:43:52Z` |
--- a/docs/subagents/agents/codex-aniskip-intro-skip-20260222T080257Z-51fx.md
+++ b/docs/subagents/agents/codex-aniskip-intro-skip-20260222T080257Z-51fx.md
@@ -0,0 +1,48 @@
+# Agent: `codex-aniskip-intro-skip-20260222T080257Z-51fx`
+
+- alias: `codex-aniskip-intro-skip`
+- mission: `Port intro skip to AniSkip API in mpv plugin with OSD skip button`
+- status: `handoff`
+- branch: `main`
+- started_at: `2026-02-22T08:02:57Z`
+- heartbeat_minutes: `5`
+
+## Current Work (newest first)
+- [2026-02-22T08:03:20Z] intent: inspect plugin flow + ani-skip script behavior; design direct API integration.
+- [2026-02-22T08:13:40Z] progress: added launcher guessit metadata extraction + script-opts passthrough (`aniskip_title`, `aniskip_season`, `aniskip_episode`) for file playback.
+- [2026-02-22T08:13:40Z] progress: updated plugin intro hint behavior to show `You can skip by pressing y-k` for first 3 seconds from intro start.
+- [2026-02-22T08:13:40Z] test: `bun test launcher/aniskip-metadata.test.ts`, `bun test launcher/mpv.test.ts`, `luac -p plugin/subminer.lua`, `bun run tsc --noEmit`.
+
+## Files Touched
+- `plugin/subminer.lua`
+- `plugin/subminer.conf`
+- `docs/mpv-plugin.md`
+- `launcher/aniskip-metadata.ts`
+- `launcher/aniskip-metadata.test.ts`
+- `launcher/mpv.ts`
+
+## Assumptions
+- mpv build supports `subprocess` curl fallback for HTTP.
+- intro skip should be OP-only by default.
+
+## Open Questions / Blockers
+- none
+
+## Next Step
+- manual mpv runtime validation still needed (network + real media metadata).
+- [2026-02-22T09:25:57Z] progress: fixed intro skip keypath reliability by always binding fallback `y-k` alias; added explicit OSD feedback when skip not available/outside intro window.
+- [2026-02-22T09:25:57Z] test: `luac -p plugin/subminer.lua`; `bun run tsc --noEmit`.
+- [2026-02-22T09:30:27Z] progress: added explicit AniSkip query logging in plugin (`title/season/episode` context, MAL lookup query, resolved MAL id, AniSkip URL) for season mismatch diagnosis.
+- [2026-02-22T09:30:27Z] test: `luac -p plugin/subminer.lua`.
+- [2026-02-22T09:33:22Z] progress: improved MAL resolution heuristic for AniSkip (title overlap + season-aware ranking) to avoid sequel mis-selection; logs chosen MAL candidate title/id/score.
+- [2026-02-22T09:33:22Z] test: `luac -p plugin/subminer.lua`.
+- [2026-02-22T09:36:05Z] progress: hardened MAL candidate scoring (token overlap + stopword filtering + coverage + low-confidence rejection threshold) to prevent unrelated anime selection; syntax check passed.
+- [2026-02-22T09:42:00Z] progress: added MAL lookup fallback attempts across multiple title sources (`aniskip_title`, `media-title`, filename, path) with per-attempt logs; keeps season/episode fixed.
+- [2026-02-22T09:57:40Z] progress: tightened title overlap scoring for MAL candidate selection (strong penalty for partial multi-token matches) to prevent wrong-ID picks like "Shadow Skill" from "The Eminence in Shadow".
+- [2026-02-22T09:57:40Z] test: `luac -p plugin/subminer.lua`.
+- [2026-02-22T10:04:20Z] progress: launcher AniSkip metadata now prioritizes guessit `series` over episode `title`; fallback title extraction now prefers anime directory name before season dir (`.../<Show>/Season-1/<file>`).
+- [2026-02-22T10:04:20Z] test: `bun test launcher/aniskip-metadata.test.ts`, `bun test launcher/mpv.test.ts`, `bun run tsc --noEmit`, `luac -p plugin/subminer.lua`.
+- [2026-02-22T10:10:30Z] progress: plugin now extracts show title from media path (`.../<Show>/Season-*`) and prioritizes it over `aniskip_title`, preventing episode-title queries when launcher metadata is stale/wrong.
+- [2026-02-22T10:10:30Z] test: `luac -p plugin/subminer.lua`.
+- [2026-02-22T10:14:40Z] progress: per user request removed MAL scoring/rejection; resolver now selects first MAL search result with an id and logs selected first result.
+- [2026-02-22T10:14:40Z] test: `luac -p plugin/subminer.lua`.
--- a/docs/subagents/collaboration.md
+++ b/docs/subagents/collaboration.md
@@ -101,3 +101,18 @@ Shared notes. Append-only.
 - [2026-02-22T07:34:50Z] [codex-overlay-toggle-regression-20260222T073450Z-q7m4|codex-overlay-toggle-regression] starting TASK-107 bugfix for post-rebase overlay regression: toggling visible/invisible opens transparent non-interactable window; keybinds + subtitle rendering fail in both modes.
 - [2026-02-22T07:44:40Z] [codex-overlay-toggle-regression-20260222T073450Z-q7m4|codex-overlay-toggle-regression] identified renderer layer-resolution bug risk under shared renderer process (`process.argv` preload arg drift); fixed `resolvePlatformInfo` to prioritize per-window `?layer=` query, added regression test, verified `bun test src/renderer/error-recovery.test.ts` + `bun run build`.
 - [2026-02-22T07:45:58Z] [codex-overlay-toggle-regression-20260222T073450Z-q7m4|codex-overlay-toggle-regression] added explicit overlay BrowserWindow sandbox guard (`webPreferences.sandbox=false`) to avoid preload API break on newer Electron defaults; added regression test `src/core/services/overlay-window-config.test.ts`; verified focused tests + build green.
+
+## 2026-02-22
+- [2026-02-22T08:04:10Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] starting feature: port intro skip to AniSkip API in `plugin/subminer.lua` with chapter markers + in-range OSD skip button; scoped to mpv plugin/docs only.
+- [2026-02-22T08:05:38Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] implemented AniSkip OP lookup + chapter markers + in-range OSD skip prompt/key in `plugin/subminer.lua`; updated plugin conf/docs; syntax check `luac -p plugin/subminer.lua` passed.
+- [2026-02-22T08:13:40Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] follow-up applied: launcher now runs `guessit` for file playback and passes AniSkip title/season/episode script-opts (fallback title from filename), and intro hint now displays for first 3s from intro start (`You can skip by pressing y-k`).
+- [2026-02-22T09:25:57Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] bugfix follow-up: `y-k` now always bound as fallback intro-skip key regardless custom key config; skip handler now emits OSD reason when unavailable/outside intro window to aid diagnosis.
+- [2026-02-22T09:30:27Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] diagnostics follow-up: plugin now logs AniSkip query context + MAL lookup query + resolved MAL id + AniSkip URL to help debug wrong-season resolution.
+- [2026-02-22T09:33:22Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] season-mismatch mitigation: MAL lookup now ranks prefix-search candidates by title overlap + season signal, logs selected candidate name/id/score before AniSkip query.
+- [2026-02-22T09:36:05Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] tightened MAL resolver scoring and added low-confidence rejection (<35) so unrelated matches are skipped instead of used.
+- [2026-02-22T09:40:09Z] [codex-docs-review-20260222T094009Z-g8p2|codex-docs-review] starting docs review/update pass for README + docs pages; scope docs-only consistency fixes against current scripts/config/features.
+- [2026-02-22T09:43:52Z] [codex-docs-review-20260222T094009Z-g8p2|codex-docs-review] completed docs review/update pass: removed stale guardrail docs, fixed DevTools shortcut docs, added guessit guidance for AniSkip metadata quality, verified `bun run docs:build` passes.
+- [2026-02-22T09:42:00Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] added AniSkip MAL fallback title attempts to recover from guessit title mismatches while preserving season/episode hints.
+- [2026-02-22T10:04:20Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] launcher metadata fix: prefer guessit `series` for AniSkip title and fallback to show-directory extraction (`.../<Show>/Season-*`) instead of episode filename title.
+- [2026-02-22T10:10:30Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] plugin hardening: path-derived show title now prioritized over script-opt title for AniSkip lookups, reducing dependence on launcher metadata correctness.
+- [2026-02-22T10:14:40Z] [codex-aniskip-intro-skip-20260222T080257Z-51fx|codex-aniskip-intro-skip] simplified MAL resolution policy to first-result selection (no score/reject) per user preference.