From 0e64b630d0507fbb742a4f0fccf46b847b7aceb6 Mon Sep 17 00:00:00 2001 From: sudacode Date: Sat, 28 Feb 2026 22:55:00 -0800 Subject: [PATCH] update backlog, docs, and readme --- README.md | 4 +- ...-auto-pause-config-and-runtime-behavior.md | 45 ++++++++++++++++ ...ause-until-ready-and-single-start-guard.md | 53 +++++++++++++++++++ docs/configuration.md | 5 ++ docs/installation.md | 5 +- docs/launcher-script.md | 30 ++++++----- docs/mining-workflow.md | 1 + docs/mpv-plugin.md | 2 + docs/shortcuts.md | 2 + docs/usage.md | 11 ++-- 10 files changed, 139 insertions(+), 19 deletions(-) create mode 100644 backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md create mode 100644 backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md diff --git a/README.md b/README.md index 7035b50..7970f43 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ SubMiner is an Electron overlay that sits on top of mpv. It turns your video pla - **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation - **Instant auto-enrichment** — Optional local AnkiConnect proxy enriches new Yomitan cards immediately - **Reading annotations** — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read +- **Hover-aware playback** — By default, hovering subtitle text pauses mpv and resumes on mouse leave (`subtitleStyle.autoPauseVideoOnHover`) - **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync - **Immersion tracking** — SQLite-powered stats on your watch time and mining activity - **Custom texthooker page** — Built-in custom texthooker page and websocket, no extra setup @@ -75,7 +76,8 @@ subminer app --start --yomitan ```bash subminer app --start --background -subminer video.mkv # y-t toggles overlay visibility +subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready +subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no ``` ## Requirements diff --git a/backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md b/backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md new file mode 100644 index 0000000..44ee291 --- /dev/null +++ b/backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md @@ -0,0 +1,45 @@ +--- +id: TASK-77 +title: 'Subtitle hover: auto-pause playback with config toggle' +status: Done +assignee: [] +created_date: '2026-02-28 22:43' +updated_date: '2026-02-28 22:43' +labels: [] +dependencies: [] +priority: medium +ordinal: 8000 +--- + +## Description + + + +Add a user-facing subtitle config option to pause mpv playback when the cursor hovers subtitle text and resume playback when the cursor leaves. + +Scope: +- New config key: `subtitleStyle.autoPauseVideoOnHover`. +- Default should be enabled. +- Hover pause/resume must not unpause if playback was already paused before hover. +- Docs/examples/tests updated. + + + +## Acceptance Criteria + + + +- [x] #1 `subtitleStyle.autoPauseVideoOnHover` exists and defaults to `true`. +- [x] #2 Overlay pauses playback on subtitle hover and resumes on leave only when hover-triggered pause occurred. +- [x] #3 Main/renderer IPC exposes pause-state query for safe hover behavior. +- [x] #4 Config docs/examples and user docs/readme mention the new behavior and toggle. +- [x] #5 Regression tests cover config parsing/validation and hover behavior edge cases. + + +## Final Summary + + + +Implemented `subtitleStyle.autoPauseVideoOnHover` with default `true`, wired through config defaults/resolution/types, renderer state/style, and mouse hover handlers. Added playback pause-state IPC (`getPlaybackPaused`) to avoid false resume when media was already paused. Added renderer hover behavior tests (including race/cancel case) and config/resolve tests. Updated config examples and docs (`README`, usage, shortcuts, mining workflow, configuration) to document default hover pause/resume behavior and disable path. + + diff --git a/backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md b/backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md new file mode 100644 index 0000000..ffbf98a --- /dev/null +++ b/backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md @@ -0,0 +1,53 @@ +--- +id: TASK-78 +title: 'Launcher + mpv plugin: auto-start visible overlay pause-until-ready and single-start guard' +status: Done +assignee: [] +created_date: '2026-02-28 22:45' +updated_date: '2026-02-28 22:45' +labels: [] +dependencies: [] +priority: medium +ordinal: 9000 +--- + +## Description + + + +Add startup gating behavior for wrapper + mpv plugin flow so playback starts paused when visible overlay auto-start is enabled, then auto-resumes only after subtitle tokenization is ready. + +Scope: +- Plugin option `auto_start_pause_until_ready` (default `yes`). +- Launcher reads plugin runtime config and starts mpv paused when `auto_start=yes`, `auto_start_visible_overlay=yes`, and `auto_start_pause_until_ready=yes`. +- Main process signals readiness via mpv script message after tokenized subtitle delivery. +- Prevent duplicate auto-start attempts from showing `SubMiner already running` OSD. +- Keep startup/loading OSD messaging visible and update docs/tests. + + + +## Acceptance Criteria + + + +- [x] #1 Launcher reads `auto_start`, `auto_start_visible_overlay`, and `auto_start_pause_until_ready` from `subminer.conf` and starts mpv with `--pause=yes` when all are enabled. +- [x] #2 Plugin pauses on eligible auto-start and resumes only on readiness signal or timeout fallback. +- [x] #3 Main process emits `script-message subminer-autoplay-ready` after subtitle tokenization is ready. +- [x] #4 Auto-start duplicate triggers are idempotent (no duplicate `--start` behavior and no spurious `Already running` OSD for auto-start path). +- [x] #5 Docs and regression tests cover defaults, startup gating behavior, and duplicate-start suppression. + + + +## Final Summary + + + +Implemented startup pause gate across launcher/plugin/main runtime: +- Added plugin runtime config parsing in launcher (`auto_start`, `auto_start_visible_overlay`, `auto_start_pause_until_ready`) and mpv start-paused behavior for eligible runs. +- Added plugin auto-play gate state, timeout fallback, and readiness release via `subminer-autoplay-ready` script message. +- Added main-process readiness signaling after tokenization delivery, including unpause fallback command path. +- Split auto-start visibility control into separate control commands and added duplicate auto-start idempotency guard to suppress repeated auto-start `Already running` noise. +- Updated plugin defaults to enabled (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`) and refreshed docs (`README`, usage, launcher, installation, plugin/config docs). +- Added/updated regression coverage (`scripts/test-plugin-start-gate.lua`, launcher smoke/unit tests) validating paused startup, readiness resume, and duplicate-start suppression. + + diff --git a/docs/configuration.md b/docs/configuration.md index be16493..be3eb71 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -354,6 +354,11 @@ Control whether the overlay automatically becomes visible when it connects to mp The mpv plugin controls startup overlay visibility via `auto_start_visible_overlay` in `subminer.conf`. For wrapper-driven playback, `subminer.conf` can also enable startup pause gating with `auto_start_pause_until_ready` (requires `auto_start=yes` + `auto_start_visible_overlay=yes`). +Current plugin defaults in `subminer.conf` are: + +- `auto_start=yes` +- `auto_start_visible_overlay=yes` +- `auto_start_pause_until_ready=yes` ### Auto Subtitle Sync diff --git a/docs/installation.md b/docs/installation.md index 48b7a8b..17a44fe 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -194,7 +194,10 @@ See [MPV Plugin](/mpv-plugin) for the full configuration reference, script messa After installing, confirm SubMiner is working: ```bash -# Start the overlay (connects to mpv IPC) +# Play a file (default plugin config auto-starts visible overlay and waits for annotation readiness) +subminer video.mkv + +# Optional explicit overlay start for setups with plugin auto_start=no subminer --start video.mkv # Useful launch modes for troubleshooting diff --git a/docs/launcher-script.md b/docs/launcher-script.md index 4c92535..c68f30b 100644 --- a/docs/launcher-script.md +++ b/docs/launcher-script.md @@ -53,8 +53,9 @@ SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R ## Common Commands ```bash -subminer video.mkv # play a specific file -subminer --start video.mkv # play + explicitly start overlay +subminer video.mkv # play a specific file (default plugin config auto-starts visible overlay) +subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no +subminer -S video.mkv # same as above via --start-overlay subminer https://youtu.be/... # YouTube playback (requires yt-dlp) subminer ytsearch:"jp news" # YouTube search ``` @@ -78,17 +79,20 @@ Use `subminer -h` for command-specific help. ## Options -| Flag | Description | -| --------------------- | --------------------------------------------------- | -| `-d, --directory` | Video search directory (default: cwd) | -| `-r, --recursive` | Search directories recursively | -| `-R, --rofi` | Use rofi instead of fzf | -| `-S, --start` | Start overlay after mpv launches | -| `-T, --no-texthooker` | Disable texthooker server | -| `-p, --profile` | mpv profile name (default: `subminer`) | -| `-b, --backend` | Force window backend (`hyprland`, `sway`, `x11`) | -| `--log-level` | Logger verbosity (`debug`, `info`, `warn`, `error`) | -| `--dev`, `--debug` | Enable app dev-mode (not tied to log level) | +| Flag | Description | +| ----------------------- | --------------------------------------------------- | +| `-d, --directory` | Video search directory (default: cwd) | +| `-r, --recursive` | Search directories recursively | +| `-R, --rofi` | Use rofi instead of fzf | +| `--start` | Explicitly start overlay after mpv launches | +| `-S, --start-overlay` | Explicitly start overlay after mpv launches | +| `-T, --no-texthooker` | Disable texthooker server | +| `-p, --profile` | mpv profile name (default: `subminer`) | +| `-b, --backend` | Force window backend (`hyprland`, `sway`, `x11`) | +| `--log-level` | Logger verbosity (`debug`, `info`, `warn`, `error`) | +| `--dev`, `--debug` | Enable app dev-mode (not tied to log level) | + +With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`), explicit start flags are usually unnecessary. ## Logging diff --git a/docs/mining-workflow.md b/docs/mining-workflow.md index f3af336..90ca1d7 100644 --- a/docs/mining-workflow.md +++ b/docs/mining-workflow.md @@ -33,6 +33,7 @@ SubMiner uses one overlay window with modal surfaces. The visible overlay renders subtitles as tokenized, clickable word spans. Each word is a separate element with reading and headword data attached. This plane is styled independently from mpv subtitles and supports: - Word-level click targets for Yomitan lookup +- Auto pause/resume on subtitle hover (enabled by default via `subtitleStyle.autoPauseVideoOnHover`) - Right-click to pause/resume - Right-click + drag to reposition subtitles - Modal dialogs for Jimaku search, field grouping, subsync, and runtime options diff --git a/docs/mpv-plugin.md b/docs/mpv-plugin.md index 1d178a4..2ccf270 100644 --- a/docs/mpv-plugin.md +++ b/docs/mpv-plugin.md @@ -186,6 +186,7 @@ script-message subminer-menu script-message subminer-options script-message subminer-restart script-message subminer-status +script-message subminer-autoplay-ready script-message subminer-aniskip-refresh script-message subminer-skip-intro ``` @@ -217,6 +218,7 @@ script-message subminer-start backend=hyprland socket=/custom/path texthooker=no - **File loaded**: If `auto_start=yes`, the plugin starts the overlay, then defers AniSkip lookup until after startup delay. - **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused and the plugin resumes playback after SubMiner reports tokenization-ready (with timeout fallback). +- **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts). - **MPV shutdown**: The plugin sends a stop command to gracefully shut down both the overlay and the texthooker server. - **Texthooker**: Starts as a separate subprocess before the overlay to ensure the app lock is acquired first. diff --git a/docs/shortcuts.md b/docs/shortcuts.md index 088e1fd..5c4de0f 100644 --- a/docs/shortcuts.md +++ b/docs/shortcuts.md @@ -56,6 +56,8 @@ These control playback and subtitle display. They require overlay window focus. These keybindings can be overridden or disabled via the `keybindings` config array. +Mouse-hover playback behavior is configured separately from shortcuts: `subtitleStyle.autoPauseVideoOnHover` defaults to `true` (pause on subtitle hover, resume on leave). + ## Subtitle & Feature Shortcuts | Shortcut | Action | Config key | diff --git a/docs/usage.md b/docs/usage.md index 2d0a8d6..7b91b8b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,12 +4,12 @@ There are two ways to use SubMiner — the `subminer` wrapper script or the mpv | Approach | Best For | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **subminer script** | All-in-one solution. Handles video selection, launches MPV with the correct socket, and manages app commands. Overlay start is explicit (`--start`, `-S`, or `y-s`). | +| **subminer script** | All-in-one solution. Handles video selection, launches MPV with the correct socket, and manages app commands. With default plugin settings, overlay auto-starts visible and playback resumes after annotation readiness. | | **MPV plugin** | When you launch MPV yourself or from other tools. Provides in-MPV chord keybindings (e.g. `y-y` for menu) to control overlay visibility. Requires `--input-ipc-server=/tmp/subminer-socket`. | You can use both together—install the plugin for on-demand control, but use `subminer` when you want the streamlined workflow. -`subminer` is implemented as a Bun script and runs directly via shebang (no `bun run` needed), for example: `subminer --start video.mkv`. +`subminer` is implemented as a Bun script and runs directly via shebang (no `bun run` needed), for example: `subminer video.mkv`. ## Live Config Reload @@ -34,8 +34,9 @@ subminer # Current directory (uses fzf) subminer -R # Use rofi instead of fzf subminer -d ~/Videos # Specific directory subminer -r -d ~/Anime # Recursive search -subminer video.mkv # Play specific file -subminer --start video.mkv # Play + explicitly start overlay +subminer video.mkv # Play specific file (default plugin config auto-starts visible overlay) +subminer --start video.mkv # Optional explicit overlay start (use when plugin auto_start=no) +subminer -S video.mkv # Same as above via --start-overlay subminer https://youtu.be/... # Play a YouTube URL subminer ytsearch:"jp news" # Play first YouTube search result subminer --log-level debug video.mkv # Enable verbose logs for launch/debugging @@ -199,6 +200,8 @@ Notes: These keybindings only work when the overlay window has focus. See [Configuration](/configuration) for customization. +By default, hovering over subtitle text pauses mpv playback and leaving the subtitle area resumes playback. Set `subtitleStyle.autoPauseVideoOnHover` to `false` to disable this behavior. + ### Drag-and-drop Queueing - Drag and drop one or more video files onto the overlay to replace current playback (`loadfile ... replace` for first file, then append remainder).