diff --git a/README.md b/README.md
index 1a677593..267677f9 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,10 @@ A stats dashboard tracks watch time, vocabulary growth, mining throughput, sessi
| WebSocket |
Plain subtitle feed plus a dedicated annotated feed for texthooker pages and custom tools |
+
+ | Plugins |
+ Load your own JavaScript at startup to react to playback, run timers, add key-bound actions, and show results in an overlay panel. The bundled example explains the current line with Codex. Plugin guide |
+
@@ -267,7 +271,7 @@ SubMiner builds on the work of these open-source projects:
| [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) | Default dictionary engine and morphological parser |
+| [Yomitan](https://github.com/yomidevs/yomitan) | Default dictionary engine and morphological parser |
| [Hachidori](https://github.com/bee-san/hachidori) | Alternative dictionary backend, powered by HoshiDicts |
| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab) | JLPT level tags for vocabulary |
diff --git a/assets/plugins/ai-explain/main.js b/assets/plugins/ai-explain/main.js
new file mode 100644
index 00000000..84a4649e
--- /dev/null
+++ b/assets/plugins/ai-explain/main.js
@@ -0,0 +1,134 @@
+// Sends the current subtitle line, with a few lines of context, to `codex exec` and shows the
+// answer in the SubMiner plugin panel. Registers two actions: `explain` and `translate`.
+const { mkdtemp, readFile, rm } = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_SETTINGS = {
+ codexPath: 'codex',
+ model: '',
+ // Passed as -c model_reasoning_effort; low keeps answers to a few seconds. Empty uses your Codex config.
+ reasoningEffort: 'low',
+ before: 2,
+ after: 1,
+ timeoutMs: 120_000,
+ pause: true,
+ prompts: {},
+};
+
+const ACTIONS = {
+ explain: {
+ title: 'Grammar',
+ prompt:
+ 'You are a Japanese tutor. Explain the line marked >>> for an intermediate learner. ' +
+ 'Use the other lines only as context. Reply in English markdown: a natural translation, ' +
+ 'then a bullet list of the grammar points and notable vocabulary. Be concise.',
+ },
+ translate: {
+ title: 'Translation',
+ prompt:
+ 'Translate the line marked >>> into natural English. Use the other lines only as context. ' +
+ 'Reply with the translation, then one short note only if the line is ambiguous.',
+ },
+};
+
+function activate(ctx) {
+ const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+ for (const [name, action] of Object.entries(ACTIONS)) {
+ const prompt = settings.prompts?.[name] ?? action.prompt;
+ ctx.actions.register(name, () => ask(ctx, settings, action.title, prompt));
+ }
+}
+
+function quote(text) {
+ return text
+ .split('\n')
+ .map((line) => `> ${line}`)
+ .join('\n');
+}
+
+// Subtitles wrap across lines; flatten each cue so the >>> marker covers all of it.
+function oneLine(text) {
+ return text
+ .split('\n')
+ .map((part) => part.trim())
+ .filter(Boolean)
+ .join(' ');
+}
+
+function tail(text, lineCount) {
+ return text.trim().split('\n').slice(-lineCount).join('\n');
+}
+
+async function ask(ctx, settings, title, instructions) {
+ const { before, current, after } = ctx.subtitles.context({
+ before: settings.before,
+ after: settings.after,
+ });
+ if (!current) {
+ ctx.notify('No subtitle line to send.', { variant: 'warning' });
+ return;
+ }
+ if (settings.pause) ctx.mpv.command(['set', 'pause', 'yes']);
+
+ const header = quote(current.text);
+ const panel = ctx.ui.panel({ title, markdown: `${header}\n\n_Asking Codex..._` });
+ const prompt = [
+ instructions,
+ '',
+ 'Subtitles:',
+ ...before.map((line) => oneLine(line.text)),
+ `>>> ${oneLine(current.text)}`,
+ ...after.map((line) => oneLine(line.text)),
+ ].join('\n');
+
+ // Codex runs in an empty read-only directory so any command it tries cannot touch real files.
+ const workDir = await mkdtemp(path.join(os.tmpdir(), 'subminer-ai-explain-'));
+ const answerPath = path.join(workDir, 'answer.md');
+ const args = [
+ 'exec',
+ '--ephemeral',
+ '--skip-git-repo-check',
+ '--sandbox',
+ 'read-only',
+ '--color',
+ 'never',
+ '-C',
+ workDir,
+ '-o',
+ answerPath,
+ ];
+ if (settings.model) args.push('-m', settings.model);
+ if (settings.reasoningEffort) {
+ args.push('-c', `model_reasoning_effort=${JSON.stringify(settings.reasoningEffort)}`);
+ }
+ args.push('-');
+
+ try {
+ const result = await ctx.exec(settings.codexPath, args, {
+ stdin: prompt,
+ timeoutMs: settings.timeoutMs,
+ signal: panel.signal,
+ });
+ if (result.exitCode !== 0) {
+ throw new Error(tail(result.stderr, 6) || `codex exited with code ${result.exitCode}`);
+ }
+ const answer = (await readFile(answerPath, 'utf8')).trim();
+ panel.update({ markdown: `${header}\n\n${answer || '_Codex returned an empty answer._'}` });
+ } catch (error) {
+ // Closing the panel aborts the request; there is nobody left to show the error to.
+ if (panel.signal.aborted) return;
+ const message =
+ error?.code === 'ENOENT'
+ ? `Cannot find \`${settings.codexPath}\`. Set \`plugins.ai-explain.settings.codexPath\` to its full path.`
+ : String(error?.message ?? error);
+ ctx.log.warn(`Codex request failed: ${message}`);
+ panel.update({
+ markdown: `${header}\n\n**Codex request failed.**\n\n\`\`\`\n${message}\n\`\`\``,
+ });
+ } finally {
+ await rm(workDir, { recursive: true, force: true });
+ }
+}
+
+module.exports = { activate };
diff --git a/assets/plugins/ai-explain/plugin.json b/assets/plugins/ai-explain/plugin.json
new file mode 100644
index 00000000..2dec6dd7
--- /dev/null
+++ b/assets/plugins/ai-explain/plugin.json
@@ -0,0 +1,6 @@
+{
+ "name": "AI Explain",
+ "version": "1.0.0",
+ "apiVersion": 1,
+ "main": "main.js"
+}
diff --git a/assets/plugins/anki-sync/main.js b/assets/plugins/anki-sync/main.js
new file mode 100644
index 00000000..b39ab397
--- /dev/null
+++ b/assets/plugins/anki-sync/main.js
@@ -0,0 +1,61 @@
+// Runs AnkiConnect's `sync` (AnkiWeb) after you mine cards. A burst of mining becomes one sync:
+// it waits until no card has been mined for `delayMs`, and syncs right away when playback ends.
+// Also registers a `sync` action for a manual sync.
+
+const DEFAULT_SETTINGS = {
+ delayMs: 30_000,
+ syncOnEnd: true,
+ timeoutMs: 60_000,
+ notify: true,
+};
+
+const END_REASONS = new Set(['eof', 'stop', 'quit']);
+
+function activate(ctx) {
+ const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+ // Cards mined since the last sync started.
+ let dirty = false;
+ let syncing = false;
+ let cancelTimer = null;
+
+ function schedule() {
+ cancelTimer?.();
+ cancelTimer = ctx.after(settings.delayMs, flush);
+ }
+
+ async function flush() {
+ cancelTimer?.();
+ cancelTimer = null;
+ // A sync already running picks up new cards when it finishes.
+ if (!dirty || syncing) return;
+ dirty = false;
+ syncing = true;
+ try {
+ await ctx.anki.invoke('sync', {}, { timeoutMs: settings.timeoutMs });
+ ctx.log.info('Synced Anki.');
+ if (settings.notify) ctx.notify('Anki synced');
+ } catch (error) {
+ ctx.log.warn(`Anki sync failed: ${error.message}`);
+ ctx.notify(`Anki sync failed: ${error.message}`, { variant: 'error' });
+ } finally {
+ syncing = false;
+ if (dirty) schedule();
+ }
+ }
+
+ ctx.anki.on('card-mined', () => {
+ dirty = true;
+ schedule();
+ });
+
+ ctx.mpv.on('end-file', ({ reason }) => {
+ if (settings.syncOnEnd && END_REASONS.has(reason)) return flush();
+ });
+
+ ctx.actions.register('sync', () => {
+ dirty = true;
+ return flush();
+ });
+}
+
+module.exports = { activate };
diff --git a/assets/plugins/anki-sync/plugin.json b/assets/plugins/anki-sync/plugin.json
new file mode 100644
index 00000000..565b4533
--- /dev/null
+++ b/assets/plugins/anki-sync/plugin.json
@@ -0,0 +1,6 @@
+{
+ "name": "Anki Sync",
+ "version": "1.0.0",
+ "apiVersion": 1,
+ "main": "main.js"
+}
diff --git a/assets/plugins/auto-jimaku/main.js b/assets/plugins/auto-jimaku/main.js
new file mode 100644
index 00000000..1744e621
--- /dev/null
+++ b/assets/plugins/auto-jimaku/main.js
@@ -0,0 +1,51 @@
+// Opens the Jimaku subtitle search when a file starts without a Japanese subtitle track.
+// It waits a few seconds after the file loads so external subtitles mpv or SubMiner add count.
+
+const DEFAULT_SETTINGS = {
+ // Built-in action to run, e.g. `openTsukihime` or `openSubtitleSelection`.
+ action: 'openJimaku',
+ // Track `lang` codes that count as Japanese. Track titles with "Japanese" or 日本語 count too.
+ languages: ['ja', 'jp', 'jpn'],
+ delayMs: 3_000,
+ // Also check http(s) streams; Jimaku can only search by name, which streams rarely have.
+ streams: false,
+};
+
+const JAPANESE_TITLE = /japanese|日本語/i;
+
+function activate(ctx) {
+ const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+ const languages = new Set(settings.languages.map((lang) => lang.toLowerCase()));
+ let cancelCheck = null;
+ let playbackId = null;
+
+ function hasJapaneseSubtitle(trackList) {
+ return trackList.some(
+ (track) =>
+ track?.type === 'sub' &&
+ (languages.has(String(track.lang ?? '').toLowerCase()) ||
+ JAPANESE_TITLE.test(String(track.title ?? ''))),
+ );
+ }
+
+ async function check(media) {
+ cancelCheck = null;
+ const trackList = await ctx.mpv.getProperty('track-list');
+ if (ctx.media.current()?.playbackId !== media.playbackId || !Array.isArray(trackList)) return;
+ if (hasJapaneseSubtitle(trackList)) return;
+ ctx.log.info(`No Japanese subtitles for ${media.path}; running ${settings.action}.`);
+ await ctx.actions.run(settings.action);
+ }
+
+ ctx.media.on('change', (media) => {
+ if (media?.playbackId === playbackId) return;
+ playbackId = media?.playbackId ?? null;
+ cancelCheck?.();
+ cancelCheck = null;
+ if (!media) return;
+ if (!settings.streams && /^[a-z]+:\/\//i.test(media.path)) return;
+ cancelCheck = ctx.after(settings.delayMs, () => check(media));
+ });
+}
+
+module.exports = { activate };
diff --git a/assets/plugins/auto-jimaku/plugin.json b/assets/plugins/auto-jimaku/plugin.json
new file mode 100644
index 00000000..2b720859
--- /dev/null
+++ b/assets/plugins/auto-jimaku/plugin.json
@@ -0,0 +1,6 @@
+{
+ "name": "Auto Jimaku",
+ "version": "1.0.0",
+ "apiVersion": 1,
+ "main": "main.js"
+}
diff --git a/assets/plugins/episode-tags/main.js b/assets/plugins/episode-tags/main.js
new file mode 100644
index 00000000..74151a6b
--- /dev/null
+++ b/assets/plugins/episode-tags/main.js
@@ -0,0 +1,110 @@
+// Tags each mined card with the show and episode it came from, e.g. `show::Frieren::S01E07`.
+// The show and episode are parsed from the file name, or from mpv's media title for streams.
+const path = require('node:path');
+
+const DEFAULT_SETTINGS = {
+ // Placeholders: {show}, {season}, {episode}, and {ep} (S01E07, or E07 without a season).
+ // A tag stops before the first `::` level whose placeholder has no value.
+ tags: ['show::{show}::{ep}'],
+ notify: false,
+};
+
+// Tried in order; the first match wins. Runs on names with brackets and dots already removed.
+const EPISODE_PATTERNS = [
+ /^(?.*?)\s*S(?\d{1,2})\s?E(?\d{1,4})\b/i,
+ /^(?.*?)\s*(?:Season\s?(?\d{1,2})\s*)?(?:Episode|Ep)\s?(?\d{1,4})\b/i,
+ /^(?.*?)\s+-\s+(?\d{1,4})(?:v\d)?\b/,
+ /^(?.*?)\s+(?\d{1,4})(?:v\d)?$/,
+ /^(?.*?)\s*第(?\d{1,4})話/,
+];
+
+// `[Group] Show Name - 07 (1080p).mkv` -> { show: 'Show Name', season: null, episode: '07' }
+function parseMediaName(name) {
+ const cleaned = name
+ .replace(/\.[a-z0-9]{2,4}$/i, '')
+ .replace(/\[[^\]]*\]|\([^)]*\)|【[^】]*】/g, ' ')
+ .replace(/[._]/g, ' ')
+ .replace(/\s+/g, ' ')
+ .trim();
+ for (const pattern of EPISODE_PATTERNS) {
+ const groups = cleaned.match(pattern)?.groups;
+ const show = groups?.show.replace(/[\s-]+$/, '');
+ if (!show) continue;
+ return { show, season: pad(groups.season), episode: pad(groups.episode) };
+ }
+ return { show: cleaned || null, season: null, episode: null };
+}
+
+function pad(number) {
+ return number ? String(Number(number)).padStart(2, '0') : null;
+}
+
+// Anki tags can't hold spaces, and a `::` in a value would add a hierarchy level.
+function tagValue(value) {
+ return value.replace(/::?/g, ' ').trim().replace(/\s+/g, '_').replace(/"/g, '');
+}
+
+function renderTag(template, values) {
+ const levels = [];
+ for (const level of template.split('::')) {
+ let missing = false;
+ const rendered = level.replace(/\{(\w+)\}/g, (_, key) => {
+ const value = values[key];
+ if (!value) missing = true;
+ return value ? tagValue(value) : '';
+ });
+ if (missing) break;
+ levels.push(rendered);
+ }
+ return levels.join('::');
+}
+
+function mediaName(mediaPath, title) {
+ // A stream URL's last segment is usually an id, so streams use the title mpv shows.
+ if (typeof mediaPath === 'string' && mediaPath && !/^[a-z]+:\/\//i.test(mediaPath)) {
+ return path.basename(mediaPath);
+ }
+ return typeof title === 'string' && title ? title : null;
+}
+
+function renderTags(templates, name) {
+ const { show, season, episode } = parseMediaName(name);
+ const ep = episode ? `${season ? `S${season}` : ''}E${episode}` : null;
+ const values = { show, season, episode, ep };
+ return [...new Set(templates.map((template) => renderTag(template, values)))].filter(Boolean);
+}
+
+function activate(ctx) {
+ const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
+ ctx.anki.on('card-mined', async ({ notes }) => {
+ // Notes from the same file share one addTags call.
+ const notesByName = new Map();
+ for (const { noteId, provenance } of notes) {
+ const name = mediaName(provenance?.media?.path, provenance?.media?.title);
+ if (!name) {
+ ctx.log.debug(`Note ${noteId} has no known media source; not tagging it.`);
+ continue;
+ }
+ if (!notesByName.has(name)) notesByName.set(name, new Set());
+ notesByName.get(name).add(noteId);
+ }
+
+ for (const [name, notes] of notesByName) {
+ const tags = renderTags(settings.tags, name);
+ if (tags.length === 0) {
+ ctx.log.debug(`No tags for "${name}".`);
+ continue;
+ }
+ try {
+ await ctx.anki.invoke('addTags', { notes: [...notes], tags: tags.join(' ') });
+ ctx.log.info(`Tagged ${notes.size} note(s): ${tags.join(' ')}`);
+ if (settings.notify) ctx.notify(`Tagged ${tags.join(' ')}`);
+ } catch (error) {
+ ctx.log.warn(`Tagging failed: ${error.message}`);
+ ctx.notify(`Episode tagging failed: ${error.message}`, { variant: 'error' });
+ }
+ }
+ });
+}
+
+module.exports = { activate };
diff --git a/assets/plugins/episode-tags/plugin.json b/assets/plugins/episode-tags/plugin.json
new file mode 100644
index 00000000..6b83a66c
--- /dev/null
+++ b/assets/plugins/episode-tags/plugin.json
@@ -0,0 +1,6 @@
+{
+ "name": "Episode Tags",
+ "version": "1.0.0",
+ "apiVersion": 1,
+ "main": "main.js"
+}
diff --git a/changes/plugin-system.md b/changes/plugin-system.md
new file mode 100644
index 00000000..43e860ef
--- /dev/null
+++ b/changes/plugin-system.md
@@ -0,0 +1,10 @@
+type: added
+area: plugins
+
+- Added JavaScript plugins loaded at startup from `/plugins//` and enabled under `plugins` in the config. Plugins can listen to mpv events, run timers, register actions bound with `__plugin-action:/` keybindings or run with `--plugin-action`, run built-in actions, react to mined Anki cards and call AnkiConnect, start mpv, run programs, keep state in a per-plugin data folder, and show results in an overlay panel or their own window.
+- Added an example `ai-explain` plugin that sends the current line and its neighbors to `codex exec` and shows a translation or grammar explanation.
+- Added an example `anki-sync` plugin that syncs Anki to AnkiWeb after you mine cards, once mining goes quiet or playback ends.
+- Added an example `episode-tags` plugin that tags mined cards with the show and episode, such as `show::Frieren::S01E07`.
+- Added an example `auto-jimaku` plugin that opens the Jimaku search when a file starts without a Japanese subtitle track.
+- Added a versioned plugin API with standalone authoring types, cached playback snapshots, lifecycle cancellation and cleanup, and awaitable mpv commands. Async activation is bounded and actions wait only for their own plugin. Shutdown skips pending loads, runs each deactivation once, and blocks calls from disposed plugins.
+- Mining events preserve original and kept note ids with the media and subtitle captured when mining starts, so delayed enrichment and merges into older notes keep the source episode. Stats-dashboard cards do not trigger plugin events. Plugin subtitle lookups and mining provenance account for subtitle delay and return timing on the subtitle file's timeline.
diff --git a/config.example.jsonc b/config.example.jsonc
index 1dba331f..cf2a4e8c 100644
--- a/config.example.jsonc
+++ b/config.example.jsonc
@@ -218,6 +218,14 @@
"overlayPosition": "top-right" // Position for in-overlay notification cards. Values: top-left | top | top-right
}, // Overlay notification display behavior.
+ // ==========================================
+ // Plugins
+ // JavaScript plugins loaded from /plugins// at startup.
+ // Plugins run inside SubMiner with full access to your system. Only enable code you trust.
+ // Restart SubMiner after changing plugins.
+ // ==========================================
+ "plugins": {}, // Plugins to load at startup, keyed by directory name under /plugins/. Each entry is { "enabled": true, "settings": { ... } }; settings are passed to the plugin as ctx.settings.
+
// ==========================================
// Keyboard Shortcuts
// Overlay keyboard shortcuts. Set a shortcut to null to disable.
diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts
index 42795fd1..84d0200b 100644
--- a/docs-site/.vitepress/config.ts
+++ b/docs-site/.vitepress/config.ts
@@ -221,6 +221,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
{ text: 'AniList', link: '/anilist-integration' },
{ text: 'AniSkip', link: '/aniskip-integration' },
{ text: 'Character Dictionary', link: '/character-dictionary' },
+ { text: 'Plugins', link: '/plugins' },
],
},
{
diff --git a/docs-site/configuration.md b/docs-site/configuration.md
index 84be8109..ddbdb91a 100644
--- a/docs-site/configuration.md
+++ b/docs-site/configuration.md
@@ -106,6 +106,15 @@ Overlay notifications are also kept in a session-only history panel. Toggle it w
Mining and startup status notifications use `ankiConnect.behavior.notificationType` (see [AnkiConnect](#ankiconnect)).
+### Plugins
+
+`plugins` enables [plugins](/plugins) from the `plugins/` folder next to this config file. Each key is a plugin folder name. Changes apply after a restart.
+
+| Key | Default | What it does |
+| ----------------------- | ------- | -------------------------------------- |
+| `plugins..enabled` | `false` | Load the plugin at startup |
+| `plugins..settings` | `{}` | Passed to the plugin as `ctx.settings` |
+
### Auto-start overlay
When mpv is started by SubMiner or the `subminer` launcher, the launcher passes these settings to the bundled mpv plugin. There is no separate plugin config file. `mpv.autoStartSubMiner` and `mpv.pauseUntilOverlayReady` (see [MPV launcher](#mpv-launcher)) control the background start and the initial pause.
@@ -268,7 +277,7 @@ Adds a modal for choosing mpv's primary and secondary subtitle tracks. Open it w
- `key` uses `KeyboardEvent.code` names (`Space`, `KeyR`, `ArrowRight`) with optional `Ctrl+`, `Alt+`, `Shift+`, `Meta+`. Mouse buttons are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, `MBTN_FORWARD`. Scroll wheel keys are `WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, `WHEEL_RIGHT`.
- `command` is any mpv JSON IPC command array. Set it to `null` to disable a default.
-- Commands starting with `__` run inside SubMiner: `__playlist-browser-open`, `__youtube-picker-open`, `__replay-subtitle`, `__play-next-subtitle`, `__runtime-options-open`, and `__runtime-option-cycle:[:next|prev]`.
+- Commands starting with `__` run inside SubMiner: `__playlist-browser-open`, `__youtube-picker-open`, `__replay-subtitle`, `__play-next-subtitle`, `__runtime-options-open`, `__runtime-option-cycle:[:next|prev]`, and `__plugin-action:/` (see [Plugins](/plugins)).
- Unused single-key, mouse button, and scroll wheel bindings from your mpv config also work in the overlay. Your SubMiner bindings win on conflicts.
### Shortcuts configuration
diff --git a/docs-site/plugins.md b/docs-site/plugins.md
new file mode 100644
index 00000000..a0e6a6c9
--- /dev/null
+++ b/docs-site/plugins.md
@@ -0,0 +1,199 @@
+# Plugins
+
+Plugins are JavaScript files that SubMiner loads at startup. A plugin can react to playback, run code on a timer, add actions you bind to keys, run programs, and show results in an overlay panel, all without rebuilding SubMiner.
+
+::: warning Only run plugins you trust
+Plugins run inside SubMiner with the same access to your files and system as SubMiner itself. There is no sandbox.
+:::
+
+These are SubMiner app plugins. The Lua script that runs inside mpv is the separate [mpv plugin](/mpv-plugin).
+
+## Install a plugin
+
+1. Put the plugin in its own folder in `plugins/` next to your [config file](/configuration#configuration-file), for example `~/.config/SubMiner/plugins/ai-explain/`. The folder name is the plugin id.
+2. Enable it in `config.jsonc`. `settings` is passed to the plugin as-is:
+
+ ```jsonc
+ {
+ "plugins": {
+ "ai-explain": { "enabled": true, "settings": { "reasoningEffort": "medium" } },
+ },
+ }
+ ```
+
+3. Bind its actions to keys with the `__plugin-action:/` command:
+
+ ```jsonc
+ {
+ "keybindings": [
+ { "key": "Ctrl+KeyE", "command": ["__plugin-action:ai-explain/explain"] },
+ { "key": "Ctrl+KeyT", "command": ["__plugin-action:ai-explain/translate"] },
+ ],
+ }
+ ```
+
+ To run an action from a script or a window-manager shortcut, use `subminer app --plugin-action ai-explain/explain`. It goes to the running SubMiner, or starts one if none is running.
+
+4. Restart SubMiner. Plugin changes apply on the next start; keybinding changes apply immediately.
+
+Load errors and plugin log output go to the app log with a `plugin:` scope.
+
+## Example: explain the current line with Codex
+
+The repository ships [`assets/plugins/ai-explain`](https://github.com/ksyasuda/SubMiner/tree/main/assets/plugins/ai-explain). It sends the current line, plus the lines around it, to [`codex exec`](https://github.com/openai/codex) and shows the answer in a panel. It needs a logged-in Codex CLI.
+
+| Action | What it does |
+| ----------- | --------------------------------------------------------------- |
+| `explain` | Translation plus a breakdown of the grammar and vocabulary |
+| `translate` | Natural English translation, with a note only when it's unclear |
+
+| Setting | Default | What it does |
+| ----------------- | --------- | ----------------------------------------------------------------- |
+| `codexPath` | `"codex"` | Codex binary. Use a full path if SubMiner can't find it on `PATH` |
+| `model` | `""` | Model passed to `codex exec -m`; empty uses your Codex config |
+| `reasoningEffort` | `"low"` | Codex reasoning effort; empty uses your Codex config |
+| `before`, `after` | `2`, `1` | Lines of context sent before and after the current line |
+| `pause` | `true` | Pause playback when the panel opens |
+| `timeoutMs` | `120000` | Give up after this long |
+| `prompts` | `{}` | Replace an action's instructions, e.g. `{ "translate": "..." }` |
+
+Press `Esc` to close the panel. Closing it, or starting another request, stops the running Codex process.
+
+## Example: sync Anki after mining
+
+[`assets/plugins/anki-sync`](https://github.com/ksyasuda/SubMiner/tree/main/assets/plugins/anki-sync) runs AnkiConnect's `sync` after you mine cards, so they reach AnkiWeb without opening Anki. It waits until you stop mining for a while, so a burst of cards becomes one sync. It also adds a `sync` action you can bind to a key.
+
+| Setting | Default | What it does |
+| ----------- | ------- | ------------------------------------------------------- |
+| `delayMs` | `30000` | Sync after no card has been mined for this long |
+| `syncOnEnd` | `true` | Sync right away when playback ends or mpv quits |
+| `timeoutMs` | `60000` | Give up on a sync after this long |
+| `notify` | `true` | Show a notification after each sync. Failures always do |
+
+Anki must be running and logged in to AnkiWeb. Cards mined from the stats dashboard don't trigger a sync.
+
+## Example: tag cards with the episode
+
+[`assets/plugins/episode-tags`](https://github.com/ksyasuda/SubMiner/tree/main/assets/plugins/episode-tags) tags each mined card with the show and episode it came from, such as `show::Sousou_no_Frieren::E07`. It reads them from the file name (`[Group] Show - 07 (1080p).mkv`, `Show.S01E07.mkv`, `Show 第7話.mkv`), or from the title mpv shows for streams. It uses the source captured when mining started, so delayed media and field grouping into an older note keep the correct episode. Notes with unknown provenance, including cards discovered by polling, are left alone. Spaces become `_`.
+
+| Setting | Default | What it does |
+| -------- | ------------------------ | ----------------------------------------------- |
+| `tags` | `["show::{show}::{ep}"]` | Tags to add, one template each |
+| `notify` | `false` | Show a notification with the tags for each card |
+
+Templates can use `{show}`, `{season}`, `{episode}`, and `{ep}` (`S01E07`, or `E07` when there is no season). When a placeholder has no value, the tag stops before that `::` level, so a movie gets `show::`. The parsing is a guess from the name: a title ending in a number, like `Mob Psycho 100`, reads that number as the episode.
+
+## Example: open Jimaku when a file has no Japanese subtitles
+
+[`assets/plugins/auto-jimaku`](https://github.com/ksyasuda/SubMiner/tree/main/assets/plugins/auto-jimaku) opens the Jimaku search a few seconds after a file starts if none of its subtitle tracks is Japanese. A track counts as Japanese when its language code is in `languages`, or its title contains "Japanese" or 日本語.
+
+| Setting | Default | What it does |
+| ----------- | --------------------- | --------------------------------------------------------------- |
+| `action` | `"openJimaku"` | Built-in action to run, e.g. `openTsukihime` |
+| `languages` | `["ja", "jp", "jpn"]` | Track language codes that count as Japanese |
+| `delayMs` | `3000` | Wait this long after the file starts, so external subs load |
+| `streams` | `false` | Also check `http(s)` streams, which Jimaku usually can't search |
+
+## Write a plugin
+
+A plugin folder needs a `plugin.json`:
+
+```json
+{ "name": "My Plugin", "version": "1.0.0", "apiVersion": 1, "main": "main.js" }
+```
+
+`apiVersion` declares the required SubMiner plugin API version. The current version is `1`; omitted values also mean v1 for existing plugins. An unsupported version is rejected before the plugin's entry module runs. `version` is the plugin's own version and does not control compatibility.
+
+`main` points to a CommonJS module (`.js`) or an ES module (`.mjs`) that exports `activate(ctx)`. Activation may be asynchronous and has a 10-second timeout. A plugin's actions wait for its own activation, so a slow plugin does not hold up other plugins. If activation fails or times out, its registrations are removed and its signal aborts. Synchronous code still shares the app's main thread.
+
+Activation may return a cleanup function, or the module can export `deactivate()`. On quit, SubMiner aborts `ctx.signal` first and waits up to 2 seconds in total for loading and deactivation. A plugin still reading its files is skipped. Everything a plugin registers through `ctx` is cleaned up automatically. A late activation cannot leave new listeners, timers, or actions behind, and its returned cleanup still runs once. Deactivation can call Anki, mpv, built-in actions, and notifications until disposal. After disposal, those calls throw or reject, including work that resumes after an activation or deactivation timeout.
+
+```js
+function activate(ctx) {
+ ctx.media.on('change', (media) => {
+ if (media) ctx.log.info(`Now playing ${media.path}`);
+ });
+ ctx.every(60_000, () => ctx.log.info('Still watching'));
+ ctx.actions.register('hello', () => {
+ const line = ctx.subtitles.current();
+ ctx.ui.panel({ title: 'Hello', markdown: line ? `> ${line.text}` : '_No subtitle_' });
+ });
+}
+
+module.exports = { activate };
+```
+
+An error thrown by a plugin is logged and does not crash SubMiner. A plugin that blocks with a long synchronous loop still freezes the app, so keep slow work asynchronous.
+
+### Types and cleanup
+
+The public types live in [`src/plugin-api.ts`](https://github.com/ksyasuda/SubMiner/blob/main/src/plugin-api.ts). A build emits `dist/plugin-api.d.ts`; copy that file into your plugin as `subminer.d.ts`, or copy the source file with that name. It has no imports from SubMiner internals. Electron's types must be available to your editor because `ui.openWindow` returns a `BrowserWindow`.
+
+JavaScript plugins can use the types through JSDoc:
+
+```js
+/** @param {import('./subminer').PluginContext} ctx */
+function activate(ctx) {
+ const { ipcMain } = require('electron');
+ ipcMain.handle(`${ctx.id}:info`, () => ({ media: ctx.media.current() }));
+ ctx.onDispose(() => ipcMain.removeHandler(`${ctx.id}:info`));
+}
+
+module.exports = { activate };
+```
+
+Use `ctx.signal` with `fetch` or other cancellable work. It aborts when unloading starts, before `deactivate` runs. `ctx.onDispose(fn)` registers synchronous cleanup for resources outside `ctx`, such as file watchers and Electron IPC handlers. The returned function runs the cleanup early, at most once. Registering cleanup after unloading starts runs it immediately. Timers and listeners registered after that point are removed immediately too. Use the returned activation cleanup or `deactivate` for asynchronous teardown, within the shared quit timeout.
+
+### `ctx` reference
+
+| Member | What it does |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `id`, `dir`, `settings` | Plugin id, plugin folder path, and `plugins.<id>.settings` |
+| `apiVersion` | The host's plugin API version, currently `1` |
+| `signal`, `onDispose(fn)` | Lifetime cancellation and cleanup for resources created outside `ctx` |
+| `dataDir` | `plugin-data/<id>/` next to your config file, for caches and state. Exists before `activate` runs |
+| `log.debug/info/warn/error(message)` | Write to the app log |
+| `every(ms, fn)`, `after(ms, fn)` | Repeating and one-shot timers. Return a function that cancels them |
+| `mpv.on(event, fn)` | Listen to mpv events (below). Returns an unsubscribe function |
+| `mpv.command(args)` | Send an mpv command, e.g. `['set', 'pause', 'yes']` |
+| `mpv.request(args)` | Await an mpv command result; rejects on command error, disconnect, or timeout |
+| `mpv.getProperty(name)` | Read an mpv property (Promise) |
+| `mpv.connected` | Whether mpv is connected |
+| `mpv.ensureRunning()` | Connect to mpv, starting an idle mpv if none is running. Resolves `false` if that fails |
+| `media.current()` | Cached `{ playbackId, path, title }`, or `null` when there is no connected media |
+| `media.on('change', fn, options)` | Subscribe to playback snapshots; immediately delivers the current snapshot unless `emitCurrent: false` |
+| `anki.on(event, fn)` | Listen to Anki events (below). Returns an unsubscribe function |
+| `anki.invoke(action, params, options)` | Send an AnkiConnect action to `ankiConnect.url`, e.g. `('sync')`. Resolves its result (below) |
+| `subtitles.current()` | The displayed line as `{ text, startTime, endTime }`, or `null` |
+| `subtitles.context({ before, after })` | `{ current, before, after }`. Neighbors come from the loaded subtitle file, or recent lines for streams |
+| `actions.register(name, fn)` | Add an action, bindable as `__plugin-action:<id>/<name>` |
+| `actions.run(actionId, payload)` | Run a built-in action, the same ids keybindings use, e.g. `openJimaku` or `mineSentence` |
+| `notify(message, { variant })` | Overlay notification. `variant` is `info`, `warning`, or `error` |
+| `ui.panel({ title, markdown })` | Open the plugin panel. Returns `{ update(content), close(), closed, signal }` |
+| `ui.openWindow({ html, preload })` | Open a window from the plugin folder (below). Returns the Electron `BrowserWindow` |
+| `exec(command, args, options)` | Run a program without a shell (Windows `.cmd`/`.bat` shims go through `cmd.exe`). Resolves `{ exitCode, stdout, stderr }` |
+| `unstable` | SubMiner internals. These change between releases without notice |
+
+A panel's `signal` aborts when the user closes it or another panel replaces it. Pass it to `exec` to stop work nobody will see. Closing or replacing a panel also cancels pending open requests, including while its window loads. Only one panel is open at a time. Panel markdown supports headings, lists, quotes, code, bold, and italics; HTML is shown as plain text.
+
+`exec` options are `stdin`, `cwd`, `env`, `timeoutMs`, and `signal`. It resolves for any exit code and rejects when the program can't start, times out, or is aborted.
+
+`ui.openWindow` takes `html` and an optional `preload`, both relative to the plugin folder, plus `title`, `width`, and `height`. Opening the same `html` again focuses the open window. The page runs with context isolation and no Node access. The preload is sandboxed too: it can `require('electron')` but nothing else, so bundle anything more into it. Expose what the page needs from the preload with `contextBridge`, and handle its messages with `ipcMain` from `require('electron')` in the plugin. Prefix channel names with the plugin id. Plugin windows close when SubMiner quits.
+
+`media` snapshots are immutable. `playbackId` changes on a new load, including reopening the same path. A title may arrive later with the same id. Disconnecting or ending playback delivers `null`. Use the id to discard stale asynchronous results. Snapshots describe cached playback state; they do not promise that external subtitle discovery has finished.
+
+`mpv.request` accepts string, number, and boolean arguments, e.g. `await ctx.mpv.request(['set_property', 'pause', true])`. It returns mpv's result data and rejects after 4 seconds. A timeout does not cancel the command in mpv, so a slow command may still complete. `mpv.command` remains available for commands whose result you do not need.
+
+mpv events: `connection-change`, `subtitle-change`, `subtitle-timing`, `time-pos-change`, `duration-change`, `pause-change`, `fullscreen-change`, `media-path-change`, `media-title-change`, `subtitle-track-change`, `subtitle-track-list-change`, `secondary-subtitle-change`, `secondary-subtitle-track-change`, `secondary-subtitle-delay-change`, `secondary-subtitle-visibility`, `client-message`, `file-loaded`, and `end-file`. `file-loaded` has no payload. `end-file` gives `{ reason, playlistEntryId, error }`, where `reason` is `eof`, `stop`, `quit`, `error`, `redirect`, or `unknown`.
+
+Anki events: `card-mined` gives `{ noteIds, notes }` once SubMiner has finished filling in a mined card (sentence, audio, image, and field grouping). For YouTube cards whose media waits on the download, it fires once that media is added or the download fails. With `ankiConnect.behavior.autoUpdateNewCards` off, it fires as soon as SubMiner sees the card. If field grouping merged the card into an older one, `noteIds` contains the older card's id.
+
+Each `notes` entry has `{ originalNoteId, noteId, provenance }`. `originalNoteId` identifies the note before merges; `noteId` is the note that kept its content. `provenance` is `{ minedAt, media, subtitle }`, captured before asynchronous creation or the AnkiConnect proxy's upstream request. `minedAt` is Unix time in milliseconds. `media` uses the snapshot format above, and `subtitle` uses `{ text, startTime, endTime }`. Either may be `null`. Polling cannot establish the original source, so its provenance is `null` rather than the currently playing file.
+
+`subtitles.current()` resolves parsed cues using the current subtitle delay and returns their times on the subtitle file's timeline.
+
+Sentence-card provenance also uses the subtitle file's timeline. Multi-line mining converts the history range using the subtitle delay when mining starts; changing the delay between those lines can affect the reported range.
+
+Several original notes can merge into one kept note. `notes` preserves each source, while `noteIds` contains unique kept ids. Existing listeners using only `noteIds` continue to work. Cards mined from the stats dashboard do not emit this event.
+
+`anki.invoke` takes `{ timeoutMs }` (default 10 seconds), rejects on an Anki error, and never retries, so an action like `sync` or `addNote` runs at most once.
diff --git a/docs-site/public/config.example.jsonc b/docs-site/public/config.example.jsonc
index 1dba331f..cf2a4e8c 100644
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -218,6 +218,14 @@
"overlayPosition": "top-right" // Position for in-overlay notification cards. Values: top-left | top | top-right
}, // Overlay notification display behavior.
+ // ==========================================
+ // Plugins
+ // JavaScript plugins loaded from <config dir>/plugins/<id>/ at startup.
+ // Plugins run inside SubMiner with full access to your system. Only enable code you trust.
+ // Restart SubMiner after changing plugins.
+ // ==========================================
+ "plugins": {}, // Plugins to load at startup, keyed by directory name under <config dir>/plugins/. Each entry is { "enabled": true, "settings": { ... } }; settings are passed to the plugin as ctx.settings.
+
// ==========================================
// Keyboard Shortcuts
// Overlay keyboard shortcuts. Set a shortcut to null to disable.
diff --git a/docs-site/shortcuts.md b/docs-site/shortcuts.md
index ed0466c1..44cb6f33 100644
--- a/docs-site/shortcuts.md
+++ b/docs-site/shortcuts.md
@@ -138,6 +138,8 @@ The plugin's `v` replaces mpv's own subtitle visibility toggle. When the overlay
}
```
+To run a [plugin](/plugins) action, use `["__plugin-action:<plugin id>/<action>"]` as the command.
+
Mouse button names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`. Scroll wheel names are `WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, and `WHEEL_RIGHT`. See [keybindings](/configuration#keybindings) and [shortcuts configuration](/configuration#shortcuts-configuration) in the config reference.
## Automatic mpv bindings
diff --git a/docs-site/usage.md b/docs-site/usage.md
index 674c21d1..f32dcb6f 100644
--- a/docs-site/usage.md
+++ b/docs-site/usage.md
@@ -104,6 +104,7 @@ subminer doctor # check dependencies, config, and the mpv soc
subminer generate-subs video.mkv # make Japanese subtitles from the audio
subminer logs -e # export a log ZIP for bug reports
subminer app --setup # reopen first-run setup
+subminer app --plugin-action <id>/<name> # run a plugin action
subminer -u # update SubMiner
```
diff --git a/docs-site/websocket-texthooker-api.md b/docs-site/websocket-texthooker-api.md
index 31183713..f8cc01af 100644
--- a/docs-site/websocket-texthooker-api.md
+++ b/docs-site/websocket-texthooker-api.md
@@ -206,7 +206,7 @@ The same pattern works for n8n or Zapier workflows, Discord notifiers, or append
## mpv script messages
-SubMiner has no in-app plugin SDK. Besides the streams above, you can drive it from other mpv scripts and from the [launcher CLI](/launcher-script).
+SubMiner also supports [JavaScript app plugins](/plugins) for playback events, mining events, actions, and custom UI. Besides the streams above, you can drive it from other mpv scripts and from the [launcher CLI](/launcher-script).
The mpv plugin accepts these script messages:
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 0392a434..b16d0395 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -37,6 +37,7 @@ Update checks and startup launcher migration share a serialized update-state sto
- `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/main/runtime/subtitle-selection.ts` reads and validates mpv subtitle tracks and applies primary/secondary selections. Its opt-in session shortcut opens the shared overlay modal window, with renderer focus and subtitle suppression handled by the modal registry.
- `src/shared/session-key-sequences.ts` rejects sequence prefixes reserved by single-key actions. The session-binding compiler reserves configured and built-in overlay keys; `src/main/runtime/session-bindings-runtime.ts` adds active mpv bindings and publishes the effective list to both the plugin artifact and the renderer through `session-bindings:changed`. mpv no-op `ignore` bindings do not reserve prefixes.
+- `src/core/services/plugins/` owns user plugins: discovery from `<config dir>/plugins/<id>/plugin.json` for ids enabled in `plugins`, the per-plugin `ctx`, guarded callbacks, and `exec` (no shell, AppImage `LD_LIBRARY_PATH` dropped). `main.ts` supplies the host's deps, attaches each new mpv client so plugin listeners survive client replacement, starts plugins from the app-ready path after logging is configured, and unloads them first in the `will-quit` cleanup, before any teardown. Plugins run in the main process with no sandbox. `src/plugin-api.ts` is the standalone public v1 type contract; internal mpv event and session-action types derive from it. Manifests may declare `apiVersion`, which is checked before loading code. Async activation is bounded and actions wait only for their own plugin. The host owns cached media snapshots and playback ids, including repeated loads of the same path. `ctx.signal` aborts as unloading starts; `ctx.onDispose` manages outside resources and late registrations are disposed immediately. Awaitable `ctx.mpv.request` uses the existing request/response transport. Plugin actions are the `runPluginAction` session action (keybinding command `__plugin-action:<id>/<name>`, CLI `--plugin-action <id>/<name>`); `runAction` waits for an in-progress load so a cold-start CLI action is not dropped. Each plugin gets `<config dir>/plugin-data/<id>/` as `ctx.dataDir`. `ctx.anki` carries the `card-mined` event with unique kept `noteIds` and per-original-note records. Sentence-card creation snapshots media and subtitle context before asynchronous work; the proxy snapshots before forwarding an upstream request. `AnkiIntegration` keeps provenance under original ids through merges and queued YouTube jobs; polling uses null provenance. The event is fed by `AnkiIntegration.setCardsReadyCallback`: polling, the AnkiConnect proxy, and sentence-card creation report a note once its enrichment finishes (or when they see it, if auto-update is off); `AnkiIntegration` holds a sentence card's report until field grouping finishes, and the pending YouTube media queue reports notes whose media it is still waiting on (directly or through the note field grouping merged them into), which is later than `recordCardsMined` (stats counts at add time). Stats-dashboard mining does not emit it. `ctx.anki.invoke` sends one action to the effective `ankiConnect.url` with no retries. `src/main/runtime/plugin-window-runtime.ts` owns plugin windows (`ctx.ui.openWindow`): one window per plugin + HTML path, raised above the overlay like the settings windows, destroyed on unload. `src/main/runtime/plugin-panel-runtime.ts` owns the single `plugin-panel` modal: a new panel aborts the previous handle's signal, updates broadcast to both overlay windows keyed by `panelId`, and the latest content is re-sent once the renderer acknowledges the open.
- `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.
diff --git a/docs/architecture/domains.md b/docs/architecture/domains.md
index 343343b9..bc29ba91 100644
--- a/docs/architecture/domains.md
+++ b/docs/architecture/domains.md
@@ -34,6 +34,7 @@ Read when: you need to find the owner module for a behavior or test surface
- 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-*`
+- User plugins: `src/core/services/plugins/` (host, `ctx`, `exec`), `src/main/runtime/plugin-panel-runtime.ts` (panel modal), `src/main/runtime/plugin-window-runtime.ts` (plugin windows), `src/renderer/modals/plugin-panel*.ts`; examples in `assets/plugins/`
- 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/`
diff --git a/docs/workflow/verification.md b/docs/workflow/verification.md
index a58cfba8..99671eee 100644
--- a/docs/workflow/verification.md
+++ b/docs/workflow/verification.md
@@ -123,7 +123,8 @@ whenever the behavior does not depend on a specific compositor.
per-window screenshots), mpv over its JSON IPC socket, and app commands through the
normal CLI handoff (`--mine-sentence`, `--toggle-subtitle-sidebar`, ...).
- Scenarios live in `e2e/*.e2e.test.ts` and share one session per file through
- `startE2eSession()`. Pass `config` to override settings for a scenario file.
+ `startE2eSession()`. Pass `config` to override settings for a scenario file, and `files`
+ to write files such as plugins into the isolated config dir before launch.
- On a failed startup the temp dir is kept and its path is in the error. Set
`SUBMINER_E2E_KEEP=1` to keep it after any run (`app-stdio.log`, `app.log`, `mpv.log`,
`mpv-stdio.log`).
diff --git a/e2e/harness/session.ts b/e2e/harness/session.ts
index 8022535c..d4b29e8c 100644
--- a/e2e/harness/session.ts
+++ b/e2e/harness/session.ts
@@ -28,6 +28,8 @@ type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
export type E2eSessionOptions = {
/** Deep-merged over the harness config, for scenarios that need other settings. */
config?: JsonObject;
+ /** Files written before launch, keyed by path relative to the config dir (e.g. plugins). */
+ files?: Record<string, string>;
};
export type AppTarget = {
@@ -57,6 +59,8 @@ export type E2eSession = {
mainProcess: () => Promise<CdpPage>;
/** Runs a CLI command (e.g. `--mine-sentence`) against the running instance. */
runAppCommand: (...args: string[]) => Promise<void>;
+ /** After loading a file: waits for the app's autoplay resume, then leaves mpv paused. */
+ settleAfterResume: () => Promise<void>;
dispose: () => Promise<void>;
};
@@ -155,6 +159,30 @@ async function openPage(cdpPort: number, urlPart: string): Promise<CdpPage> {
return page;
}
+// mpv starts paused and the app resumes each newly loaded file once the overlay
+// and tokenizer are ready, so that resume marks the file as ready. Scenarios
+// expect a paused player, and the app retries its resume for a moment, so keep
+// pausing until the pause has held for longer than that retry window.
+async function settleAfterResume(mpv: MpvClient): Promise<void> {
+ await waitUntil(async () => (await mpv.command('get_property', 'pause')) === false, {
+ description: 'SubMiner to resume playback once the file is ready',
+ timeoutMs: 30_000,
+ });
+ let pausedSince: number | null = null;
+ await waitUntil(
+ async () => {
+ if ((await mpv.command('get_property', 'pause')) !== true) {
+ pausedSince = null;
+ await mpv.command('set_property', 'pause', true);
+ return false;
+ }
+ pausedSince ??= Date.now();
+ return Date.now() - pausedSince >= 1_500;
+ },
+ { description: 'playback to stay paused after the resume', timeoutMs: 40_000 },
+ );
+}
+
export async function startE2eSession(options: E2eSessionOptions = {}): Promise<E2eSession> {
if (!fs.existsSync(path.join(repoRoot, 'dist', 'main-entry.js'))) {
throw new Error('dist/ is missing. Run `bun run build` before the e2e harness.');
@@ -193,6 +221,15 @@ export async function startE2eSession(options: E2eSessionOptions = {}): Promise<
const config = mergeConfig(buildConfig(mpvSocketPath, anki.url), options.config ?? {});
fs.writeFileSync(path.join(userDataDir, 'config.jsonc'), JSON.stringify(config, null, 2));
+ for (const [relativePath, content] of Object.entries(options.files ?? {})) {
+ const filePath = path.resolve(userDataDir, relativePath);
+ const inside = path.relative(userDataDir, filePath);
+ if (!inside || inside.startsWith('..') || path.isAbsolute(inside)) {
+ throw new Error(`E2E file path must stay inside the config dir: ${relativePath}`);
+ }
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
+ fs.writeFileSync(filePath, content);
+ }
const env: EnvDelta = {
set: {
@@ -287,27 +324,7 @@ export async function startE2eSession(options: E2eSessionOptions = {}): Promise<
teardown.push(mpv.close);
const app = await launchApp(['--start']);
- // mpv starts paused and the app resumes it once the overlay and tokenizer
- // are ready, so that resume marks the end of startup.
- await waitUntil(async () => (await mpv.command('get_property', 'pause')) === false, {
- description: 'SubMiner to resume playback after overlay startup',
- timeoutMs: 30_000,
- });
- // Hand scenarios a paused player. The app retries its resume for a moment,
- // so keep pausing until the pause has held for longer than that retry window.
- let pausedSince: number | null = null;
- await waitUntil(
- async () => {
- if ((await mpv.command('get_property', 'pause')) !== true) {
- pausedSince = null;
- await mpv.command('set_property', 'pause', true);
- return false;
- }
- pausedSince ??= Date.now();
- return Date.now() - pausedSince >= 1_500;
- },
- { description: 'playback to stay paused after startup', timeoutMs: 40_000 },
- );
+ await settleAfterResume(mpv);
const pages: CdpPage[] = [];
teardown.push(() => pages.forEach((page) => page.close()));
@@ -331,6 +348,7 @@ export async function startE2eSession(options: E2eSessionOptions = {}): Promise<
return page;
},
runAppCommand: (...args) => runAppCommand(target, args),
+ settleAfterResume: () => settleAfterResume(mpv),
dispose,
};
} catch (error) {
diff --git a/e2e/plugins.e2e.test.ts b/e2e/plugins.e2e.test.ts
new file mode 100644
index 00000000..88496ce7
--- /dev/null
+++ b/e2e/plugins.e2e.test.ts
@@ -0,0 +1,346 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test, { after } from 'node:test';
+import type { CdpPage } from './harness/cdp';
+import { FIXTURE_CUES } from './harness/fixtures';
+import { OVERLAY_PAGE, startE2eSession, type E2eSession } from './harness/session';
+import { waitUntil } from './harness/wait';
+
+// Bun caps node:test hooks at 5s whatever their timeout option says, so the
+// session boots inside whichever test runs first and every test budgets for it.
+const TEST_TIMEOUT_MS = 120_000;
+
+// Opens a panel describing the subtitle context and a child process result, and
+// logs when the panel's signal aborts so the test can see the close reach main.
+const PROBE_PLUGIN = `
+const { ipcMain } = require('electron');
+
+exports.activate = (ctx) => {
+ ipcMain.handle('e2e-probe:info', () => ({ dataDir: ctx.dataDir, greeting: ctx.settings.greeting }));
+ ctx.onDispose(() => ipcMain.removeHandler('e2e-probe:info'));
+ ctx.media.on('change', (media) => ctx.log.info('probe media ' + JSON.stringify(media)));
+ ctx.anki.on('card-mined', ({ notes }) => ctx.log.info('probe mined ' + JSON.stringify(notes)));
+ ctx.actions.register('subtitle', () => ctx.log.info('probe subtitle ' + JSON.stringify(ctx.subtitles.current())));
+ ctx.actions.register('request', async () => {
+ const title = await ctx.mpv.request(['get_property', 'media-title']);
+ ctx.log.info('probe request ' + JSON.stringify(title));
+ try { await ctx.mpv.request(['subminer-no-such-command']); }
+ catch { ctx.log.info('probe request rejected'); }
+ });
+ ctx.actions.register('window', () => {
+ ctx.ui.openWindow({ html: 'ui/index.html', preload: 'preload.js', title: 'E2E Probe Window' });
+ });
+ ctx.mpv.on('end-file', ({ reason }) => ctx.log.info('probe end-file ' + reason));
+ ctx.actions.register('show', () => {
+ const { before, current, after } = ctx.subtitles.context({ before: 1, after: 1 });
+ const panel = ctx.ui.panel({ title: 'Probe', markdown: '_working_' });
+ panel.signal.addEventListener('abort', () => ctx.log.info('probe panel aborted'));
+ ctx
+ .exec(process.execPath, ['-e', 'process.stdout.write("child-ok")'], {
+ env: { ELECTRON_RUN_AS_NODE: '1' },
+ signal: panel.signal,
+ })
+ .then((result) =>
+ panel.update({
+ markdown: [
+ '## ' + ctx.settings.greeting,
+ '',
+ '- before: ' + before.map((line) => line.text).join('|'),
+ '- current: **' + (current ? current.text : '') + '**',
+ '- after: ' + after.map((line) => line.text).join('|'),
+ '- exec: ' + result.stdout,
+ ].join('\\n'),
+ }),
+ )
+ .catch((error) => panel.update({ markdown: 'exec failed: ' + error.message }));
+ });
+};
+`;
+
+const PROBE_PRELOAD = `
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('probe', { info: () => ipcRenderer.invoke('e2e-probe:info') });
+`;
+
+const PROBE_WINDOW_HTML = `<!doctype html>
+<html>
+ <head><title>E2E Probe Window
+
+ loading
+
+
+