feat(audio-compressor): add Auto Track Gain to boost quiet tracks

Reads YouTube's per-track loudnessDb metadata and applies compensating
gain to tracks quieter than the reference level.

Closes #3032

Author: atrupb-Atila

src/i18n/resources/en.json

@@ -356,6 +356,12 @@
     },
     "audio-compressor": {
       "description": "Apply compression to audio (lowers the volume of the loudest parts of the signal and raises the volume of the softest parts)",
+      "menu": {
+        "auto-track-gain": "Auto track gain (boost quiet tracks)",
+        "maximum-gain": {
+          "label": "Maximum gain"
+        }
+      },
       "name": "Audio Compressor"
     },
     "auth-proxy-adapter": {

src/plugins/audio-compressor.ts

@@ -2,6 +2,19 @@ import { createPlugin } from '@/utils';
 import { t } from '@/i18n';
 import { type MusicPlayer } from '@/types/music-player';
 
+import type { MenuContext } from '@/types/contexts';
+import type { MenuTemplate } from '@/menu';
+
+export type AudioCompressorPluginConfig = {
+  enabled: boolean;
+  autoTrackGain: boolean;
+  maxTrackGainDb: number;
+};
+
+const MAX_TRACK_GAIN_CHOICES = [6, 9, 12, 15, 18, 24] as const;
+
+const dbToLinear = (db: number) => Math.pow(10, db / 20);
+
 const lazySafeTry = (...fns: (() => void)[]) => {
   for (const fn of fns) {
     try {
@@ -10,93 +23,147 @@ const lazySafeTry = (...fns: (() => void)[]) => {
   }
 };
 
-const createCompressorNode = (
-  audioContext: AudioContext,
-): DynamicsCompressorNode => {
-  const compressor = audioContext.createDynamicsCompressor();
-
+const configureCompressor = (compressor: DynamicsCompressorNode) => {
   compressor.threshold.value = -50;
   compressor.ratio.value = 12;
   compressor.knee.value = 40;
   compressor.attack.value = 0;
   compressor.release.value = 0.25;
-
-  return compressor;
 };
 
-class Storage {
-  lastSource: MediaElementAudioSourceNode | null = null;
-  lastContext: AudioContext | null = null;
-  lastCompressor: DynamicsCompressorNode | null = null;
+class Chain {
+  source: MediaElementAudioSourceNode | null = null;
+  context: AudioContext | null = null;
+  compressor: DynamicsCompressorNode | null = null;
+  trackGain: GainNode | null = null;
+
+  build(source: MediaElementAudioSourceNode, context: AudioContext) {
+    if (
+      this.source === source &&
+      this.context === context &&
+      this.compressor
+    ) {
+      return; // already built
+    }
 
-  connected: WeakMap<MediaElementAudioSourceNode, DynamicsCompressorNode> =
-    new WeakMap();
+    this.teardown();
 
-  connectToCompressor = (
-    source: MediaElementAudioSourceNode | null = null,
-    audioContext: AudioContext | null = null,
-    compressor: DynamicsCompressorNode | null = null,
-  ): boolean => {
-    if (!(source && audioContext && compressor)) return false;
+    this.source = source;
+    this.context = context;
 
-    const current = this.connected.get(source);
-    if (current === compressor) return false;
+    const compressor = context.createDynamicsCompressor();
+    const trackGain = context.createGain();
+    configureCompressor(compressor);
+    trackGain.gain.value = 1;
 
-    this.lastSource = source;
-    this.lastContext = audioContext;
-    this.lastCompressor = compressor;
+    this.compressor = compressor;
+    this.trackGain = trackGain;
 
-    if (current) {
-      lazySafeTry(
-        () => source.disconnect(current),
-        () => current.disconnect(audioContext.destination),
-      );
-    } else {
-      lazySafeTry(() => source.disconnect(audioContext.destination));
-    }
+    // Source was previously connected directly to destination by the
+    // renderer; detach that and route through our chain instead.
+    lazySafeTry(() => source.disconnect(context.destination));
 
-    try {
-      source.connect(compressor);
-      compressor.connect(audioContext.destination);
-      this.connected.set(source, compressor);
-      return true;
-    } catch (error) {
-      console.error('connectToCompressor failed', error);
-      return false;
-    }
-  };
+    source.connect(compressor);
+    compressor.connect(trackGain);
+    trackGain.connect(context.destination);
+  }
 
-  disconnectCompressor = (): boolean => {
-    const source = this.lastSource;
-    const audioContext = this.lastContext;
-    if (!(source && audioContext)) return false;
-    const current = this.connected.get(source);
-    if (!current) return false;
+  applyTrackGain(gainDb: number) {
+    if (!this.context || !this.trackGain) return;
+    this.trackGain.gain.linearRampToValueAtTime(
+      dbToLinear(gainDb),
+      this.context.currentTime + 0.1,
+    );
+  }
 
+  teardown() {
+    const { source, context, compressor } = this;
+    if (source && context && compressor) {
+      lazySafeTry(
+        () => source.disconnect(compressor),
+        () => source.connect(context.destination),
+      );
+    }
     lazySafeTry(
-      () => source.connect(audioContext.destination),
-      () => source.disconnect(current),
-      () => current.disconnect(audioContext.destination),
+      () => this.compressor?.disconnect(),
+      () => this.trackGain?.disconnect(),
     );
-    this.connected.delete(source);
-    return true;
-  };
+    this.compressor = null;
+    this.trackGain = null;
+    // Keep source/context refs so a re-enable can rebuild without waiting
+    // for the next audio-can-play event.
+  }
 }
 
-const storage = new Storage();
+const chain = new Chain();
+
+let currentConfig: AudioCompressorPluginConfig = {
+  enabled: false,
+  autoTrackGain: false,
+  maxTrackGainDb: 12,
+};
+
+const getContentLoudnessDb = (): number | null => {
+  try {
+    const player = document.querySelector('#movie_player') as
+      | (Element & { getPlayerResponse?: () => unknown })
+      | null;
+    const response = player?.getPlayerResponse?.() as
+      | {
+          playerConfig?: {
+            audioConfig?: {
+              loudnessDb?: number;
+              perceptualLoudnessDb?: number;
+            };
+          };
+        }
+      | undefined;
+    const loudnessDb =
+      response?.playerConfig?.audioConfig?.loudnessDb ??
+      response?.playerConfig?.audioConfig?.perceptualLoudnessDb;
+    return typeof loudnessDb === 'number' ? loudnessDb : null;
+  } catch {
+    return null;
+  }
+};
+
+const updateTrackGain = (retriesLeft = 4) => {
+  if (!currentConfig.autoTrackGain) {
+    chain.applyTrackGain(0);
+    return;
+  }
+
+  const loudnessDb = getContentLoudnessDb();
+  if (loudnessDb === null) {
+    if (retriesLeft > 0) {
+      // YT may not have populated loudness yet — retry shortly.
+      setTimeout(() => updateTrackGain(retriesLeft - 1), 400);
+    } else {
+      chain.applyTrackGain(0);
+    }
+    return;
+  }
+
+  // YT's loudnessDb is signed: positive = louder than reference, negative =
+  // quieter. Compensate quiet tracks; leave loud tracks alone.
+  const compensation = loudnessDb < 0 ? -loudnessDb : 0;
+  const target = Math.min(compensation, currentConfig.maxTrackGainDb);
+  chain.applyTrackGain(target);
+  console.log(
+    `[audio-compressor] track loudness ${loudnessDb.toFixed(1)} dB → ` +
+      `track gain ${target.toFixed(1)} dB`,
+  );
+};
 
 const audioCanPlayHandler = ({
   detail: { audioSource, audioContext },
 }: CustomEvent<Compressor>) => {
-  storage.connectToCompressor(
-    audioSource,
-    audioContext,
-    createCompressorNode(audioContext),
-  );
+  chain.build(audioSource, audioContext);
+  updateTrackGain();
 };
 
 const ensureAudioContextLoad = (playerApi: MusicPlayer) => {
-  if (playerApi.getPlayerState() !== 1 || storage.lastContext) return;
+  if (playerApi.getPlayerState() !== 1 || chain.context) return;
 
   playerApi.loadVideoById(
     playerApi.getPlayerResponse().videoDetails.videoId,
@@ -108,26 +175,72 @@ const ensureAudioContextLoad = (playerApi: MusicPlayer) => {
 export default createPlugin({
   name: () => t('plugins.audio-compressor.name'),
   description: () => t('plugins.audio-compressor.description'),
+  restartNeeded: false,
+  config: {
+    enabled: false,
+    autoTrackGain: false,
+    maxTrackGainDb: 12,
+  } as AudioCompressorPluginConfig,
+
+  menu: async ({
+    getConfig,
+    setConfig,
+  }: MenuContext<AudioCompressorPluginConfig>): Promise<MenuTemplate> => {
+    const config = await getConfig();
+
+    return [
+      {
+        label: t('plugins.audio-compressor.menu.auto-track-gain'),
+        type: 'checkbox',
+        checked: config.autoTrackGain,
+        click(item) {
+          setConfig({ autoTrackGain: item.checked });
+        },
+      },
+      {
+        label: t('plugins.audio-compressor.menu.maximum-gain.label'),
+        type: 'submenu',
+        submenu: MAX_TRACK_GAIN_CHOICES.map((db) => ({
+          label: `${db} dB`,
+          type: 'radio' as const,
+          checked: config.maxTrackGainDb === db,
+          click() {
+            setConfig({ maxTrackGainDb: db });
+          },
+        })),
+      },
+    ];
+  },
 
   renderer: {
+    async start({ getConfig }) {
+      currentConfig = await getConfig();
+      document.addEventListener('peard:audio-can-play', audioCanPlayHandler, {
+        passive: true,
+      });
+      // If the chain was previously built (plugin re-enable), rebuild now
+      // rather than waiting for the next track change.
+      if (chain.source && chain.context) {
+        chain.build(chain.source, chain.context);
+        updateTrackGain();
+      }
+    },
+
     onPlayerApiReady(playerApi) {
       ensureAudioContextLoad(playerApi);
     },
 
-    start() {
-      document.addEventListener('peard:audio-can-play', audioCanPlayHandler, {
-        passive: true,
-      });
-      storage.connectToCompressor(
-        storage.lastSource,
-        storage.lastContext,
-        storage.lastCompressor,
-      );
+    onConfigChange(newConfig: AudioCompressorPluginConfig) {
+      currentConfig = newConfig;
+      updateTrackGain();
     },
 
     stop() {
-      document.removeEventListener('peard:audio-can-play', audioCanPlayHandler);
-      storage.disconnectCompressor();
+      document.removeEventListener(
+        'peard:audio-can-play',
+        audioCanPlayHandler,
+      );
+      chain.teardown();
     },
   },
 });