feat(anki): add media timing review before card creation (#203)

src/anki-integration/card-creation.ts

@@ -3,7 +3,13 @@ import {
   getConfiguredWordFieldName,
   getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import { AnkiConnectConfig, type CardKind, type WordCardKind } from '../types/anki';
+import {
+  AnkiConnectConfig,
+  type CardKind,
+  type MediaTimingReviewDecision,
+  type MediaTimingReviewRequest,
+  type WordCardKind,
+} from '../types/anki';
 import { createLogger } from '../logger';
 import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
@@ -55,6 +61,7 @@ interface CardCreationClient {
   storeMediaFile(filename: string, data: Buffer): Promise<void>;
   findNotes(query: string, options?: { maxRetries?: number }): Promise<number[]>;
   retrieveMediaFile(filename: string): Promise<string>;
+  deleteNotes(noteIds: number[]): Promise<void>;
 }
 
 interface CardCreationMediaGenerator {
@@ -137,12 +144,16 @@ interface CardCreationDeps {
   };
   getFallbackDurationSeconds: () => number;
   appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
+  removeKnownWordNote: (noteId: number) => void;
   isUpdateInProgress: () => boolean;
   setUpdateInProgress: (value: boolean) => void;
   trackLastAddedNoteId?: (noteId: number) => void;
   trackLastAddedDuplicateNoteIds?: (noteId: number, duplicateNoteIds: number[]) => void;
   findDuplicateNoteIds?: (expression: string, noteInfo: CardCreationNoteInfo) => Promise<number[]>;
   recordCardsMinedCallback?: (count: number, noteIds?: number[]) => void;
+  reviewMediaTiming?: (
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ) => Promise<MediaTimingReviewDecision>;
 }
 
 export class CardCreationService {
@@ -456,6 +467,30 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
 
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'audio',
+              text: mpvClient.currentSubText,
+              startTime,
+              endTime,
+              noteId,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          await this.deps.client.deleteNotes([noteId]);
+          this.deps.removeKnownWordNote(noteId);
+          this.deps.showStatusNotification('Card deleted.');
+          return;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        let sentenceText = mpvClient.currentSubText;
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentenceText = timingDecision.text?.trim() || sentenceText;
+        }
+
         const updatedFields: Record<string, string> = {};
         const errors: string[] = [];
         let miscInfoFilename: string | null = null;
@@ -465,30 +500,33 @@ export class CardCreationService {
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const sentenceField = sentenceCardConfig.sentenceField;
         if (sentenceField) {
-          const processedSentence = this.deps.processSentence(mpvClient.currentSubText, fields);
+          const processedSentence = this.deps.processSentence(sentenceText, fields);
           updatedFields[sentenceField] = processedSentence;
         }
 
         const audioFieldName = sentenceCardConfig.audioField;
-        try {
-          const audioFilename = this.generateAudioFilename();
-          const audioBuffer = await this.mediaGenerateAudio(
-            mpvClient.currentVideoPath,
-            startTime,
-            endTime,
-          );
+        if (!skipMedia) {
+          try {
+            const audioFilename = this.generateAudioFilename();
+            const audioBuffer = await this.mediaGenerateAudio(
+              mpvClient.currentVideoPath,
+              startTime,
+              endTime,
+              exactReviewedRange ? 0 : undefined,
+            );
 
-          if (audioBuffer) {
-            await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-            updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
-            miscInfoFilename = audioFilename;
+            if (audioBuffer) {
+              await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
+              updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
+              miscInfoFilename = audioFilename;
+            }
+          } catch (error) {
+            log.error('Failed to generate audio for audio card:', (error as Error).message);
+            errors.push('audio');
           }
-        } catch (error) {
-          log.error('Failed to generate audio for audio card:', (error as Error).message);
-          errors.push('audio');
         }
 
-        if (shouldGenerateImage(this.deps.getConfig())) {
+        if (!skipMedia && shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -497,6 +535,7 @@ export class CardCreationService {
               startTime,
               endTime,
               animatedLeadInSeconds,
+              exactReviewedRange,
             );
 
             const imageField = this.deps.getConfig().fields?.image;
@@ -569,9 +608,29 @@ export class CardCreationService {
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'sentence',
+              text: sentence,
+              startTime,
+              endTime,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          this.deps.showStatusNotification('Card creation cancelled.');
+          return false;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentence = timingDecision.text?.trim() || sentence;
+        }
+
         const config = this.deps.getConfig();
-        const generateAudio = shouldGenerateAudio(config);
-        const generateImage = shouldGenerateImage(config);
+        const generateAudio = !skipMedia && shouldGenerateAudio(config);
+        const generateImage = !skipMedia && shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
         const videoPath = generateImage
           ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
@@ -736,6 +795,7 @@ export class CardCreationService {
             generateAudio,
             generateImage,
             volumeScale,
+            ...(exactReviewedRange ? { mediaPaddingSeconds: 0 } : {}),
           });
           await this.deps.showNotification(noteId, label, 'media queued');
           return true;
@@ -751,7 +811,12 @@ export class CardCreationService {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
-              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
+              ? await this.mediaGenerateAudio(
+                  audioSourcePath,
+                  startTime,
+                  endTime,
+                  exactReviewedRange ? 0 : undefined,
+                )
               : null;
 
             if (audioBuffer) {
@@ -769,7 +834,13 @@ export class CardCreationService {
         if (generateImage) {
           try {
             const imageFilename = this.generateImageFilename();
-            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
+            const imageBuffer = await this.generateImageBuffer(
+              videoPath!,
+              startTime,
+              endTime,
+              0,
+              exactReviewedRange,
+            );
 
             const imageField = config.fields?.image;
             if (imageBuffer && imageField) {
@@ -821,6 +892,7 @@ export class CardCreationService {
     videoPath: MediaInput,
     startTime: number,
     endTime: number,
+    audioPaddingOverride?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
@@ -831,7 +903,7 @@ export class CardCreationService {
       videoPath,
       startTime,
       endTime,
-      this.deps.getConfig().media?.audioPadding,
+      audioPaddingOverride ?? this.deps.getConfig().media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
@@ -849,13 +921,16 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
+    exactReviewedRange = false,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
       return null;
     }
 
-    const timestamp = mpvClient.currentTimePos || 0;
+    const timestamp = exactReviewedRange
+      ? startTime + (endTime - startTime) / 2
+      : mpvClient.currentTimePos || 0;
 
     if (this.deps.getConfig().media?.imageType === 'avif') {
       let imageStart = startTime;
@@ -871,7 +946,7 @@ export class CardCreationService {
         videoPath,
         imageStart,
         imageEnd,
-        this.deps.getConfig().media?.audioPadding,
+        exactReviewedRange ? 0 : this.deps.getConfig().media?.audioPadding,
         {
           fps: this.deps.getConfig().media?.animatedFps,
           maxWidth: this.deps.getConfig().media?.animatedMaxWidth,