From 1ecc49a5268758f393279a8fd51bdf5925262d3b Mon Sep 17 00:00:00 2001
From: sudacode <suda@sudacode.com>
Date: Mon, 7 Sep 2026 14:32:20 -0700
Subject: [PATCH] docs(anki): clarify sentence audio field placement

- Document separate sentence-audio and word-pronunciation fields
- Add timing review coverage for configured audio fields
---
 changes/preserve-word-audio.md                |  4 ++
 docs-site/anki-integration.md                 |  2 +
 .../note-update-workflow.test.ts              | 45 +++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 changes/preserve-word-audio.md

diff --git a/changes/preserve-word-audio.md b/changes/preserve-word-audio.md
new file mode 100644
index 00000000..73966388
--- /dev/null
+++ b/changes/preserve-word-audio.md
@@ -0,0 +1,4 @@
+type: docs
+area: anki
+
+- Clarify that the configured Anki audio field receives sentence clips, including media timing review, and should be separate from Yomitan's word pronunciation field.
diff --git a/docs-site/anki-integration.md b/docs-site/anki-integration.md
index 9c0a4acf..44f15de6 100644
--- a/docs-site/anki-integration.md
+++ b/docs-site/anki-integration.md
@@ -138,6 +138,8 @@ Field names are matched against your Anki note type case-insensitively (an exact
 
 These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
 
+The audio field receives the sentence clip from the video, including when media timing review is enabled. In Settings, set the Anki audio field to your note type's sentence-audio field, such as `SentenceAudio`, and keep it separate from the field Yomitan uses for word pronunciation. If both write to the same field, SubMiner can overwrite the pronunciation audio. Changing the mapping affects future updates; existing cards need their word audio restored separately.
+
 Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).
 
 ### Minimal Config
diff --git a/src/anki-integration/note-update-workflow.test.ts b/src/anki-integration/note-update-workflow.test.ts
index 06694d2c..87fbf216 100644
--- a/src/anki-integration/note-update-workflow.test.ts
+++ b/src/anki-integration/note-update-workflow.test.ts
@@ -121,6 +121,51 @@ test('NoteUpdateWorkflow updates sentence field and emits notification', async (
   assert.equal(harness.notifications.length, 1);
 });
 
+for (const audioField of ['SentenceAudio', 'ContextAudio']) {
+  for (const action of ['confirm', 'use-original'] as const) {
+    test(`NoteUpdateWorkflow respects the configured ${audioField} field with ${action} timing`, async () => {
+      const harness = createWorkflowHarness();
+      harness.deps.getConfig = () => ({
+        fields: { sentence: 'Sentence', audio: audioField },
+        media: { generateAudio: true, generateImage: false },
+      });
+      harness.deps.client.notesInfo = async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: 'taberu' },
+            ExpressionAudio: { value: '[sound:word.mp3]' },
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            ContextAudio: { value: '' },
+          },
+        },
+      ];
+      harness.deps.captureSubtitleMediaContext = () => ({
+        source: 'overlay',
+        text: 'subtitle-text',
+        startTime: 4,
+        endTime: 6,
+      });
+      harness.deps.reviewMediaTiming = async () => ({
+        action,
+        startTime: 4.2,
+        endTime: 5.8,
+      });
+      harness.deps.generateAudio = async () => Buffer.from('sentence audio');
+
+      await harness.workflow.execute(42);
+
+      assert.equal(harness.updates.length, 1);
+      assert.equal(harness.updates[0]?.fields.ExpressionAudio, undefined);
+      assert.deepEqual(harness.updates[0]?.fields, {
+        Sentence: 'subtitle-text',
+        [audioField]: '[sound:audio_1.mp3]',
+      });
+    });
+  }
+}
+
 test('NoteUpdateWorkflow uses configured fields for word-card enrichment with Lapis and Kiku enabled', async () => {
   const harness = createWorkflowHarness();
   harness.deps.getConfig = () => ({