Normalize generated Anki audio by default (#135)

src/anki-integration.test.ts

@@ -860,13 +860,18 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
   assert.equal(storedMedia.length, 2);
 });
 
-test('AnkiIntegration does not use mpv stream indexes for ready cached YouTube audio', async () => {
-  const audioCalls: Array<{ path: string; audioStreamIndex?: number }> = [];
+test('AnkiIntegration passes audio normalization config for ready cached YouTube audio', async () => {
+  const audioCalls: Array<{
+    path: string;
+    audioStreamIndex?: number;
+    normalizeAudio?: boolean;
+  }> = [];
 
   const integration = new AnkiIntegration(
     {
       media: {
         audioPadding: 0,
+        normalizeAudio: false,
       },
     },
     {} as never,
@@ -896,13 +901,21 @@ test('AnkiIntegration does not use mpv stream indexes for ready cached YouTube a
         endTime: number,
         audioPadding?: number,
         audioStreamIndex?: number,
+        normalizeAudio?: boolean,
       ) => Promise<Buffer>;
     };
     generateAudio: () => Promise<Buffer | null>;
   };
   internals.mediaGenerator = {
-    generateAudio: async (path, _startTime, _endTime, _audioPadding, audioStreamIndex) => {
-      audioCalls.push({ path: path.path, audioStreamIndex });
+    generateAudio: async (
+      path,
+      _startTime,
+      _endTime,
+      _audioPadding,
+      audioStreamIndex,
+      normalizeAudio,
+    ) => {
+      audioCalls.push({ path: path.path, audioStreamIndex, normalizeAudio });
       return Buffer.from('audio');
     },
   };
@@ -913,6 +926,7 @@ test('AnkiIntegration does not use mpv stream indexes for ready cached YouTube a
     {
       path: '/tmp/subminer-youtube-media-cache/media.mkv',
       audioStreamIndex: undefined,
+      normalizeAudio: false,
     },
   ]);
 });

src/anki-integration.ts

@@ -348,6 +348,7 @@ export class AnkiIntegration {
             endTime,
             audioPadding,
             audioStreamIndex,
+            this.config.media?.normalizeAudio !== false,
           ),
         generateScreenshot: (videoPath, timestamp, options) =>
           this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
@@ -502,6 +503,7 @@ export class AnkiIntegration {
             endTime,
             audioPadding,
             audioStreamIndex,
+            this.config.media?.normalizeAudio !== false,
           ),
         generateScreenshot: (videoPath, timestamp, options) =>
           this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
@@ -996,6 +998,7 @@ export class AnkiIntegration {
       endTime,
       this.config.media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
+      this.config.media?.normalizeAudio !== false,
     );
   }
 

src/anki-integration/card-creation.ts

@@ -65,6 +65,7 @@ interface CardCreationMediaGenerator {
     endTime: number,
     audioPadding?: number,
     audioStreamIndex?: number,
+    normalizeAudio?: boolean,
   ): Promise<Buffer | null>;
   generateScreenshot(
     path: MediaInput,
@@ -842,6 +843,7 @@ export class CardCreationService {
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
       ),
+      this.deps.getConfig().media?.normalizeAudio !== false,
     );
   }
 

src/anki-integration/pending-youtube-media-queue.ts

@@ -272,6 +272,7 @@ export class PendingYoutubeMediaQueue {
           job.endTime,
           config.media?.audioPadding,
           undefined,
+          config.media?.normalizeAudio !== false,
         );
         if (audioBuffer) {
           await this.deps.client.storeMediaFile(audioFilename, audioBuffer);

src/config/config.test.ts

@@ -92,6 +92,7 @@ test('loads defaults when config is missing', () => {
     model: '',
     systemPrompt: '',
   });
+  assert.equal(config.ankiConnect.media.normalizeAudio, true);
   assert.equal(config.startupWarmups.lowPowerMode, false);
   assert.equal(config.startupWarmups.mecab, true);
   assert.equal(config.startupWarmups.yomitanExtension, true);

src/config/definitions/defaults-integrations.ts

@@ -51,6 +51,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       animatedMaxHeight: 0,
       animatedCrf: 35,
       syncAnimatedImageToWordAudio: true,
+      normalizeAudio: true,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,

src/config/definitions/domain-registry.test.ts

@@ -110,6 +110,7 @@ test('config option registry includes critical paths and has unique entries', ()
     'subtitleStyle.autoPauseVideoOnYomitanPopup',
     'ankiConnect.enabled',
     'subtitleStyle.nameMatchEnabled',
+    'ankiConnect.media.normalizeAudio',
     'anilist.characterDictionary.collapsibleSections.description',
     'mpv.executablePath',
     'mpv.launchMode',

src/config/definitions/options-integrations.ts

@@ -181,6 +181,12 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.media.generateAudio,
       description: 'Generate sentence audio for mined cards.',
     },
+    {
+      path: 'ankiConnect.media.normalizeAudio',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.normalizeAudio,
+      description: 'Normalize generated sentence audio loudness during media extraction.',
+    },
     {
       path: 'ankiConnect.media.generateImage',
       kind: 'boolean',

src/core/services/stats-server.ts

@@ -1206,6 +1206,7 @@ export function createStatsApp(
     const mediaGen = options?.createMediaGenerator?.() ?? new MediaGenerator();
 
     const audioPadding = ankiConfig.media?.audioPadding ?? 0;
+    const normalizeAudio = ankiConfig.media?.normalizeAudio !== false;
     const maxMediaDuration = ankiConfig.media?.maxMediaDuration ?? 30;
 
     const startSec = startMs / 1000;
@@ -1228,7 +1229,14 @@ export function createStatsApp(
 
     const audioPromise = generateAudio
       ? timeMiningPhase(mode, 'generateAudio', () =>
-          mediaGen.generateAudio(sourcePath, startSec, clampedEndSec, audioPadding),
+          mediaGen.generateAudio(
+            sourcePath,
+            startSec,
+            clampedEndSec,
+            audioPadding,
+            null,
+            normalizeAudio,
+          ),
         )
       : Promise.resolve(null);
 

src/media-generator.test.ts

@@ -163,6 +163,24 @@ test('generateAudio defaults to unpadded sentence timing', async () => {
   });
 });
 
+test('generateAudio normalizes sentence audio by default', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args[args.indexOf('-af') + 1], 'loudnorm=I=-18:TP=-1.5:LRA=11');
+  });
+});
+
+test('generateAudio can preserve raw sentence audio loudness', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, false);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args.includes('-af'), false);
+  });
+});
+
 test('generateAudio clips leading padding without adding it to trailing duration', async () => {
   await withStubbedFfmpeg(async (generator, argsPath) => {
     await generator.generateAudio('/video.mp4', 0.2, 1.2, 0.5);

src/media-generator.ts

@@ -24,6 +24,7 @@ import { createLogger } from './logger';
 import { normalizeMediaInput, type MediaInput } from './media-input';
 
 const log = createLogger('media');
+const AUDIO_NORMALIZATION_FILTER = 'loudnorm=I=-18:TP=-1.5:LRA=11';
 
 export type { MediaInput, MediaInputOptions } from './media-input';
 
@@ -264,6 +265,7 @@ export class MediaGenerator {
     endTime: number,
     padding: number = 0,
     audioStreamIndex: number | null = null,
+    normalizeAudio = true,
   ): Promise<Buffer> {
     const safePadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
     const start = Math.max(0, startTime - safePadding);
@@ -293,7 +295,11 @@ export class MediaGenerator {
         args.push('-map', `0:${audioStreamIndex}`);
       }
 
-      args.push('-vn', '-acodec', 'libmp3lame', '-q:a', '2', '-ar', '44100', '-y', outputPath);
+      args.push('-vn');
+      if (normalizeAudio) {
+        args.push('-af', AUDIO_NORMALIZATION_FILTER);
+      }
+      args.push('-acodec', 'libmp3lame', '-q:a', '2', '-ar', '44100', '-y', outputPath);
 
       this.logMediaDebug(
         `audio start ${inputDescription} start=${start} duration=${duration} padding=${safePadding}`,

src/types/anki.ts

@@ -74,6 +74,7 @@ export interface AnkiConnectConfig {
     animatedMaxHeight?: number;
     animatedCrf?: number;
     syncAnimatedImageToWordAudio?: boolean;
+    normalizeAudio?: boolean;
     audioPadding?: number;
     fallbackDuration?: number;
     maxMediaDuration?: number;

src/types/config.ts

@@ -235,6 +235,7 @@ export interface ResolvedConfig {
       animatedMaxHeight?: number;
       animatedCrf: number;
       syncAnimatedImageToWordAudio: boolean;
+      normalizeAudio: boolean;
       audioPadding: number;
       fallbackDuration: number;
       maxMediaDuration: number;