From 04166f3f012af4d847116b94f72bfb19619247ff Mon Sep 17 00:00:00 2001
From: sudacode <suda@sudacode.com>
Date: Mon, 17 Aug 2026 09:27:35 -0700
Subject: [PATCH] feat(anki): add runtime toggle for media timing review

- Add session-only runtime option with live config hot-reload support
- Document the runtime palette toggle
---
 changes/media-timing-review.md                   |  2 +-
 docs-site/anki-integration.md                    |  2 +-
 docs-site/configuration.md                       |  9 +++++----
 src/config/config.test.ts                        |  1 +
 src/config/definitions/options-integrations.ts   |  1 +
 src/config/definitions/runtime-options.ts        | 14 ++++++++++++++
 src/config/settings/registry.test.ts             |  1 +
 src/core/services/config-hot-reload.test.ts      |  2 ++
 src/core/services/config-hot-reload.ts           |  1 +
 .../runtime/config-hot-reload-handlers.test.ts   |  9 +++++++++
 src/main/runtime/config-hot-reload-handlers.ts   |  3 +++
 src/runtime-options.test.ts                      | 16 ++++++++++++++++
 src/shared/ipc/validators.ts                     |  1 +
 src/types/runtime-options.ts                     |  1 +
 14 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/changes/media-timing-review.md b/changes/media-timing-review.md
index c03c7627..0092abcc 100644
--- a/changes/media-timing-review.md
+++ b/changes/media-timing-review.md
@@ -1,4 +1,4 @@
 type: added
 area: mining
 
-- Added optional pre-generation timing review for word, sentence, and audio cards with a compact speech-weighted waveform, clearly labeled mined-line boundaries, drag and keyboard adjustments, audio preview with a sweeping playhead, exact screenshot and AVIF timing, and cancellation choices that include keeping a card without media.
+- Added optional pre-generation timing review for word, sentence, and audio cards with a compact speech-weighted waveform, clearly labeled mined-line boundaries, drag and keyboard adjustments, audio preview with a sweeping playhead, exact screenshot and AVIF timing, cancellation choices that include keeping a card without media, and a session-only runtime toggle.
diff --git a/docs-site/anki-integration.md b/docs-site/anki-integration.md
index 2d10b5cf..63bb3667 100644
--- a/docs-site/anki-integration.md
+++ b/docs-site/anki-integration.md
@@ -181,7 +181,7 @@ The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<time
 
 Set `media.reviewTiming` to `true` to pause playback and review each word, sentence, or audio card before its media is generated. The review opens with the subtitle range plus configured audio padding. Drag either edge of the clip to trim it, drag the middle to slide it without changing its length, or press anywhere else on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys, by 100 ms alone or 500 ms with Shift, and the 100 ms buttons do the same. Space previews the selection with a playhead that sweeps the clip, Enter confirms, and Escape cancels. The Earlier and Later buttons reveal another two seconds of available timeline without moving the selected clip. A speech-weighted waveform shows the mined subtitle as a tinted band with labeled line-start and line-end rails, making adjacent dialogue easier to distinguish. SubMiner uses a center channel when one carries dialogue, then falls back to a speech-band mono mix. Waveform analysis failure leaves the timing controls available. The confirmed range is exact: SubMiner does not apply audio padding a second time. Static screenshots use its midpoint, and animated AVIF clips use the full confirmed range.
 
-Canceling the review lets you keep editing, finish with the original timing, keep or create the card without audio or an image, or discard the card. Discard deletes an existing Yomitan or audio card and skips creation for a direct sentence card. Clipboard updates and stats-dashboard mining do not open timing review. Audio preview failure does not block confirmation or card creation. The option is disabled by default and hot-reloads.
+Canceling the review lets you keep editing, finish with the original timing, keep or create the card without audio or an image, or discard the card. Discard deletes an existing Yomitan or audio card and skips creation for a direct sentence card. Clipboard updates and stats-dashboard mining do not open timing review. Audio preview failure does not block confirmation or card creation. The option is disabled by default and hot-reloads. You can also toggle **Review Media Timing** for the current session from the runtime options palette (`Ctrl/Cmd+Shift+O`).
 
 ### Screenshots (Static)
 
diff --git a/docs-site/configuration.md b/docs-site/configuration.md
index 5653aa0a..f13c8ea5 100644
--- a/docs-site/configuration.md
+++ b/docs-site/configuration.md
@@ -873,9 +873,10 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope
 
 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.
 
-Current runtime options cover automatic card updates, known-word highlighting,
-known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
-highlighting, known-word match mode, and Kiku field grouping mode.
+Current runtime options cover automatic card updates, media timing review,
+known-word highlighting, known-word maturity coloring, N+1 annotation, JLPT
+underlines, frequency highlighting, known-word match mode, and Kiku field
+grouping mode.
 
 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
 
@@ -1020,7 +1021,7 @@ This example is intentionally compact. The option table below documents availabl
 | `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
 | `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness. Changes apply live.                                                                          |
 | `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
-| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                              |
+| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                                |
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
diff --git a/src/config/config.test.ts b/src/config/config.test.ts
index 423cef29..5167c946 100644
--- a/src/config/config.test.ts
+++ b/src/config/config.test.ts
@@ -2181,6 +2181,7 @@ test('runtime options registry is centralized', () => {
   const ids = RUNTIME_OPTION_REGISTRY.map((entry) => entry.id);
   assert.deepEqual(ids, [
     'anki.autoUpdateNewCards',
+    'anki.mediaReviewTiming',
     'subtitle.annotation.knownWords.highlightEnabled',
     'subtitle.annotation.knownWords.maturityEnabled',
     'subtitle.annotation.nPlusOne',
diff --git a/src/config/definitions/options-integrations.ts b/src/config/definitions/options-integrations.ts
index 678c7580..ed2dc191 100644
--- a/src/config/definitions/options-integrations.ts
+++ b/src/config/definitions/options-integrations.ts
@@ -202,6 +202,7 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
       description:
         'Review and preview subtitle media timing before SubMiner creates or enriches a mined card.',
+      runtime: runtimeOptionById.get('anki.mediaReviewTiming'),
     },
     {
       path: 'ankiConnect.media.generateImage',
diff --git a/src/config/definitions/runtime-options.ts b/src/config/definitions/runtime-options.ts
index 12a6ceb6..e14dda99 100644
--- a/src/config/definitions/runtime-options.ts
+++ b/src/config/definitions/runtime-options.ts
@@ -19,6 +19,20 @@ export function buildRuntimeOptionRegistry(
         behavior: { autoUpdateNewCards: value === true },
       }),
     },
+    {
+      id: 'anki.mediaReviewTiming',
+      path: 'ankiConnect.media.reviewTiming',
+      label: 'Review Media Timing',
+      scope: 'ankiConnect',
+      valueType: 'boolean',
+      allowedValues: [true, false],
+      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
+      requiresRestart: false,
+      formatValueForOsd: (value) => (value === true ? 'On' : 'Off'),
+      toAnkiPatch: (value) => ({
+        media: { reviewTiming: value === true },
+      }),
+    },
     {
       id: 'subtitle.annotation.knownWords.highlightEnabled',
       path: 'ankiConnect.knownWords.highlightEnabled',
diff --git a/src/config/settings/registry.test.ts b/src/config/settings/registry.test.ts
index f965e8e3..e550b820 100644
--- a/src/config/settings/registry.test.ts
+++ b/src/config/settings/registry.test.ts
@@ -352,6 +352,7 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.deck',
     'ankiConnect.media.normalizeAudio',
     'ankiConnect.media.mirrorMpvVolume',
+    'ankiConnect.media.reviewTiming',
     'ankiConnect.knownWords.highlightEnabled',
     'ankiConnect.knownWords.refreshMinutes',
     'ankiConnect.knownWords.addMinedWordsImmediately',
diff --git a/src/core/services/config-hot-reload.test.ts b/src/core/services/config-hot-reload.test.ts
index 38fcfcb6..e2b3391d 100644
--- a/src/core/services/config-hot-reload.test.ts
+++ b/src/core/services/config-hot-reload.test.ts
@@ -33,6 +33,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
   next.ankiConnect.deck = 'Mining';
   next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
   next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
+  next.ankiConnect.media.reviewTiming = !prev.ankiConnect.media.reviewTiming;
   next.ankiConnect.behavior.autoUpdateNewCards = !prev.ankiConnect.behavior.autoUpdateNewCards;
   next.ankiConnect.knownWords.highlightEnabled = !prev.ankiConnect.knownWords.highlightEnabled;
   next.ankiConnect.knownWords.refreshMinutes = prev.ankiConnect.knownWords.refreshMinutes + 5;
@@ -69,6 +70,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
       'ankiConnect.deck',
       'ankiConnect.media.normalizeAudio',
       'ankiConnect.media.mirrorMpvVolume',
+      'ankiConnect.media.reviewTiming',
       'ankiConnect.behavior.autoUpdateNewCards',
       'ankiConnect.knownWords.highlightEnabled',
       'ankiConnect.knownWords.refreshMinutes',
diff --git a/src/core/services/config-hot-reload.ts b/src/core/services/config-hot-reload.ts
index 4da9ca27..54550167 100644
--- a/src/core/services/config-hot-reload.ts
+++ b/src/core/services/config-hot-reload.ts
@@ -70,6 +70,7 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
   'ankiConnect.deck',
   'ankiConnect.media.normalizeAudio',
   'ankiConnect.media.mirrorMpvVolume',
+  'ankiConnect.media.reviewTiming',
   'ankiConnect.behavior.autoUpdateNewCards',
   'ankiConnect.knownWords.highlightEnabled',
   'ankiConnect.knownWords.refreshMinutes',
diff --git a/src/main/runtime/config-hot-reload-handlers.test.ts b/src/main/runtime/config-hot-reload-handlers.test.ts
index d8b2b761..d7d49f7a 100644
--- a/src/main/runtime/config-hot-reload-handlers.test.ts
+++ b/src/main/runtime/config-hot-reload-handlers.test.ts
@@ -156,6 +156,7 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
   const config = deepCloneConfig(DEFAULT_CONFIG);
   config.ankiConnect.media.normalizeAudio = false;
   config.ankiConnect.media.mirrorMpvVolume = false;
+  config.ankiConnect.media.reviewTiming = true;
   const ankiPatches: unknown[] = [];
 
   const applyHotReload = createConfigHotReloadAppliedHandler({
@@ -181,10 +182,18 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
     },
     config,
   );
+  applyHotReload(
+    {
+      hotReloadFields: ['ankiConnect.media.reviewTiming'],
+      restartRequiredFields: [],
+    },
+    config,
+  );
 
   assert.deepEqual(ankiPatches, [
     { media: { normalizeAudio: false } },
     { media: { mirrorMpvVolume: false } },
+    { media: { reviewTiming: true } },
   ]);
 });
 
diff --git a/src/main/runtime/config-hot-reload-handlers.ts b/src/main/runtime/config-hot-reload-handlers.ts
index 1a74e9d1..3b74510b 100644
--- a/src/main/runtime/config-hot-reload-handlers.ts
+++ b/src/main/runtime/config-hot-reload-handlers.ts
@@ -100,6 +100,9 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.media.mirrorMpvVolume')) {
     mediaPatch.mirrorMpvVolume = config.ankiConnect.media.mirrorMpvVolume;
   }
+  if (diff.hotReloadFields.includes('ankiConnect.media.reviewTiming')) {
+    mediaPatch.reviewTiming = config.ankiConnect.media.reviewTiming;
+  }
   if (Object.keys(mediaPatch).length > 0) {
     patch.media = mediaPatch;
   }
diff --git a/src/runtime-options.test.ts b/src/runtime-options.test.ts
index 5c5d2e47..e07e5b9b 100644
--- a/src/runtime-options.test.ts
+++ b/src/runtime-options.test.ts
@@ -82,3 +82,19 @@ test('RuntimeOptionsManager keeps known-word and n+1 annotation toggles separate
   assert.equal(effective.nPlusOne?.enabled, true);
   assert.deepEqual(patches, []);
 });
+
+test('RuntimeOptionsManager applies media timing review to the live Anki config', () => {
+  const baseConfig = structuredClone(DEFAULT_CONFIG.ankiConnect);
+  const patches: unknown[] = [];
+  const manager = new RuntimeOptionsManager(() => structuredClone(baseConfig), {
+    applyAnkiPatch: (patch) => {
+      patches.push(patch);
+    },
+    onOptionsChanged: () => undefined,
+  });
+
+  assert.equal(manager.getOptionValue('anki.mediaReviewTiming'), false);
+  assert.equal(manager.setOptionValue('anki.mediaReviewTiming', true).ok, true);
+  assert.equal(manager.getEffectiveAnkiConnectConfig().media?.reviewTiming, true);
+  assert.deepEqual(patches, [{ media: { reviewTiming: true } }]);
+});
diff --git a/src/shared/ipc/validators.ts b/src/shared/ipc/validators.ts
index 6487e3a3..8afb9213 100644
--- a/src/shared/ipc/validators.ts
+++ b/src/shared/ipc/validators.ts
@@ -53,6 +53,7 @@ const SESSION_ACTION_IDS: SessionActionId[] = [
 
 const RUNTIME_OPTION_IDS: RuntimeOptionId[] = [
   'anki.autoUpdateNewCards',
+  'anki.mediaReviewTiming',
   'subtitle.annotation.knownWords.highlightEnabled',
   'subtitle.annotation.knownWords.maturityEnabled',
   'subtitle.annotation.nPlusOne',
diff --git a/src/types/runtime-options.ts b/src/types/runtime-options.ts
index 9c2b423a..823248f6 100644
--- a/src/types/runtime-options.ts
+++ b/src/types/runtime-options.ts
@@ -1,5 +1,6 @@
 export type RuntimeOptionId =
   | 'anki.autoUpdateNewCards'
+  | 'anki.mediaReviewTiming'
   | 'subtitle.annotation.knownWords.highlightEnabled'
   | 'subtitle.annotation.knownWords.maturityEnabled'
   | 'subtitle.annotation.nPlusOne'