Merge pull request #958 from ITManCHINA/web-audio-optimization

✨ feat: Web Audio 音频输出优化

Author: imsyy

src/components/Setting/config/play.ts

@@ -544,6 +544,63 @@ export const usePlaySettings = (): SettingConfig => {
               set: (v) => handleAudioEngineSelect(v),
             }),
           },
+          {
+            key: "audioLatencyHint",
+            label: "Web Audio 延迟策略",
+            type: "select",
+            tags: [{ text: "Beta", type: "warning" }],
+            description:
+              "调整 Web Audio 的延迟策略，修改后需重启。<br>" +
+              "“低延迟模式（interactive）”延迟更低但可能不稳定；<br>" +
+              "“高效能模式（playback）”延迟偏高但播放更稳定。<br>" +
+              "已针对“高效能模式（playback）”补偿了音频输出延迟，理论上不会造成歌词与音频不同步的问题。",
+            options: [
+              { label: "低延迟模式（interactive）", value: "interactive" },
+              { label: "高效能模式（playback）", value: "playback" },
+            ],
+            value: computed({
+              get: () => settingStore.audioLatencyHint,
+              set: (v) => {
+                window.$dialog.warning({
+                  title: "更改延迟策略",
+                  content: "此操作需要重启应用才能生效，是否立即重启？",
+                  positiveText: "重启",
+                  negativeText: "取消",
+                  onPositiveClick: () => {
+                    settingStore.audioLatencyHint = v;
+                    if (isElectron) {
+                      window.electron.ipcRenderer.send("win-restart");
+                    } else {
+                      window.location.reload();
+                    }
+                  },
+                });
+              },
+            }),
+            show: computed(
+              () =>
+                settingStore.playbackEngine === "web-audio" &&
+                settingStore.audioEngine === "element",
+            ),
+          },
+          {
+            key: "audioDelayCompensation",
+            label: "音频与歌词同步补偿",
+            type: "input-number",
+            description:
+              "手动补偿音频与歌词进度延迟。<br>正值歌词变快，负值歌词进度变慢。<br>适用于移动端等自动延迟检测不准的设备。",
+            tags: [{ text: "Beta", type: "warning" }],
+            show: computed(() => settingStore.audioLatencyHint === "playback"),
+            min: -1000,
+            max: 1000,
+            step: 10,
+            suffix: "ms",
+            value: computed({
+              get: () => settingStore.audioDelayCompensation,
+              set: (v) => (settingStore.audioDelayCompensation = v ?? 0),
+            }),
+            defaultValue: 0,
+          },
           {
             key: "playSongDemo",
             label: "播放试听",

src/core/audio-player/AudioElementPlayer.ts

@@ -196,7 +196,12 @@ export class AudioElementPlayer extends BaseAudioPlayer {
     if (this.isInternalSeeking) {
       return this.targetSeekTime;
     }
-    return this.audioElement.currentTime || 0;
+    // 基础时间 - 自动延迟补偿 + 手动延迟补偿
+    return (
+      (this.audioElement.currentTime || 0) -
+      this.compensatedLatency +
+      this.audioDelayCompensation / 1000
+    );
   }
 
   /** 获取是否暂停状态 */

src/core/audio-player/BaseAudioPlayer.ts

@@ -1,3 +1,4 @@
+import { useSettingStore } from "@/stores";
 import { TypedEventTarget } from "@/utils/TypedEventTarget";
 import type { IExtendedAudioContext } from "@/types/audio/context";
 import { AudioEffectManager } from "./AudioEffectManager";
@@ -65,6 +66,11 @@ export abstract class BaseAudioPlayer
   /** 输入节点 (子类将源连接到此处) */
   protected inputNode: GainNode | null = null;
 
+  protected compensatedLatency = 0;
+
+  /** 用户手动设置的音频延迟补偿 (毫秒) */
+  protected audioDelayCompensation = 0;
+
   protected effectManager: AudioEffectManager | null = null;
 
   /** 初始化状态 */
@@ -103,6 +109,14 @@ export abstract class BaseAudioPlayer
       processedNode.connect(this.gainNode);
       this.gainNode.connect(getSharedMasterInput());
 
+      const settingStore = useSettingStore();
+      if (settingStore.audioLatencyHint === "playback") {
+        this.compensatedLatency =
+          (this.audioCtx.outputLatency || 0) + (this.audioCtx.baseLatency || 0);
+      } else {
+        this.compensatedLatency = 0;
+      }
+
       // 应用初始音量
       this.gainNode.gain.value = this.volume;
 
@@ -478,6 +492,14 @@ export abstract class BaseAudioPlayer
     return this.effectManager ? this.effectManager.getFilterGains() : [];
   }
 
+  /**
+   * 设置歌词同步偏移
+   * @param offset 偏移量 (毫秒)
+   */
+  public setAudioDelayCompensation(offset: number): void {
+    this.audioDelayCompensation = offset;
+  }
+
   /** 加载资源 */
   public abstract load(url: string): Promise<void>;
 

src/core/audio-player/IPlaybackEngine.ts

@@ -136,6 +136,12 @@ export interface IPlaybackEngine {
    */
   getRate(): number;
 
+  /**
+   * 设置音频延迟手动补偿
+   * @param offset 偏移量 (毫秒)
+   */
+  setAudioDelayCompensation(offset: number): void;
+
   /**
    * 设置音频输出设备
    * @param deviceId 设备 ID

src/core/audio-player/MpvPlayer.ts

@@ -268,6 +268,11 @@ export class MpvPlayer extends EventTarget implements IPlaybackEngine {
     }
   }
 
+  public setAudioDelayCompensation(offset: number): void {
+    // MPV 引擎不使用 Web Audio API，此设置无效
+    void offset;
+  }
+
   public getErrorCode(): number {
     return this._errorCode;
   }

src/core/audio-player/ffmpeg-engine/FFmpegAudioPlayer.ts

@@ -371,6 +371,11 @@ export class FFmpegAudioPlayer extends BaseAudioPlayer {
     return this.currentTempo;
   }
 
+  public setAudioDelayCompensation(offset: number): void {
+    // FFmpeg 引擎使用独立的时钟同步机制，此设置无效
+    void offset;
+  }
+
   public async setTempo(tempo: number) {
     if (!this.worker) return;
     const trueTime = this.currentTime;

src/core/automix/SharedAudioContext.ts

@@ -1,3 +1,4 @@
+import { useSettingStore } from "@/stores";
 import type { IExtendedAudioContext } from "@/types/audio/context";
 
 /** 共享音频上下文 */
@@ -13,14 +14,17 @@ let masterLimiter: DynamicsCompressorNode | null = null;
  */
 export const getSharedAudioContext = (): IExtendedAudioContext => {
   if (!sharedContext) {
+    const settingStore = useSettingStore();
     const AudioContextClass =
       window.AudioContext ||
       (
         window as unknown as {
           webkitAudioContext: typeof AudioContext;
         }
       ).webkitAudioContext;
-    sharedContext = new AudioContextClass() as IExtendedAudioContext;
+    sharedContext = new AudioContextClass({
+      latencyHint: settingStore.audioLatencyHint,
+    }) as IExtendedAudioContext;
   }
   return sharedContext;
 };

src/core/player/AudioManager.ts

@@ -366,6 +366,15 @@ class AudioManager extends TypedEventTarget<AudioEventMap> implements IPlaybackE
     return this.engine.getRate();
   }
 
+  /**
+   * 设置音频延迟手动补偿
+   * @param offset 偏移量 (毫秒)
+   */
+  public setAudioDelayCompensation(offset: number): void {
+    // FFmpeg 和 MPV 引擎可能没有实现此方法
+    this.engine.setAudioDelayCompensation?.(offset);
+  }
+
   /**
    * 设置输出设备
    */
@@ -504,6 +513,16 @@ export const useAudioManager = (): AudioManager => {
       settingStore.playbackEngine,
       settingStore.audioEngine,
     );
+
+    // 监听音频延迟补偿变化
+    watch(
+      () => settingStore.audioDelayCompensation,
+      (offset) => {
+        win[AUDIO_MANAGER_KEY]?.setAudioDelayCompensation(offset);
+      },
+      { immediate: true }, // 立即执行一次以应用初始值
+    );
+
     console.log(`[AudioManager] 创建新实例, engine: ${win[AUDIO_MANAGER_KEY].engineType}`);
   }
   return win[AUDIO_MANAGER_KEY];

src/stores/setting.ts

@@ -154,6 +154,8 @@ export interface SettingState {
   playDevice: "default" | string;
   /** 音频引擎: element (原生) 或 ffmpeg */
   audioEngine: "element" | "ffmpeg";
+  /** Web Audio 延迟策略 */
+  audioLatencyHint: "interactive" | "playback";
   /** 自动播放 */
   autoPlay: boolean;
   /** 预载下一首 */
@@ -224,6 +226,8 @@ export interface SettingState {
   wordFadeWidth: number;
   /** 歌词时延调节步长（毫秒） */
   lyricOffsetStep: number;
+  /** 音频延迟手动补偿（毫秒） */
+  audioDelayCompensation: number;
   /** 启用在线 TTML 歌词 */
   enableOnlineTTMLLyric: boolean;
   /** 启用 QM 歌词 */
@@ -513,6 +517,7 @@ export const useSettingStore = defineStore("setting", {
     songLevel: "exhigh",
     playDevice: "default",
     audioEngine: "element",
+    audioLatencyHint: "interactive",
     autoPlay: false,
     useNextPrefetch: true,
     songVolumeFade: true,
@@ -557,6 +562,7 @@ export const useSettingStore = defineStore("setting", {
     hidePassedLines: false,
     wordFadeWidth: 0.5,
     lyricOffsetStep: 500,
+    audioDelayCompensation: 0,
     enableOnlineTTMLLyric: false,
     enableQQMusicLyric: false,
     lyricPriority: "auto",

src/types/audio/context.ts

@@ -1,4 +1,5 @@
 /** 扩充 AudioContext 接口以支持 setSinkId (实验性 API) */
 export interface IExtendedAudioContext extends AudioContext {
   setSinkId(deviceId: string): Promise<void>;
+  readonly latencyHint?: "playback" | "interactive";
 }