✨ opt: 补充playback模式下的手动延迟补偿

Author: ITManCHINA

src/components/Setting/config/lyric.ts

@@ -368,6 +368,21 @@ export const useLyricSettings = (): SettingConfig => {
             }),
             defaultValue: 500,
           },
+          {
+            key: "lyricSyncOffset",
+            label: "歌词同步微调",
+            type: "input-number",
+            description: "手动调整歌词与声音的同步，正值歌词提前，负值歌词延后。",
+            min: -1000,
+            max: 1000,
+            step: 10,
+            suffix: "ms",
+            value: computed({
+              get: () => settingStore.lyricSyncOffset,
+              set: (v) => (settingStore.lyricSyncOffset = v || 0),
+            }),
+            defaultValue: 0,
+          },
         ],
       },
       {

src/core/audio-player/AudioElementPlayer.ts

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

src/core/audio-player/BaseAudioPlayer.ts

@@ -67,6 +67,9 @@ export abstract class BaseAudioPlayer
 
   protected compensatedLatency = 0;
 
+  /** 用户手动设置的歌词同步偏移量 (毫秒) */
+  protected syncOffset = 0;
+
   protected effectManager: AudioEffectManager | null = null;
 
   /** 初始化状态 */
@@ -487,6 +490,14 @@ export abstract class BaseAudioPlayer
     return this.effectManager ? this.effectManager.getFilterGains() : [];
   }
 
+  /**
+   * 设置歌词同步偏移
+   * @param offset 偏移量 (毫秒)
+   */
+  public setSyncOffset(offset: number): void {
+    this.syncOffset = 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 偏移量 (毫秒)
+   */
+  setSyncOffset(offset: number): void;
+
   /**
    * 设置音频输出设备
    * @param deviceId 设备 ID

src/core/player/AudioManager.ts

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

src/stores/setting.ts

@@ -260,6 +260,8 @@ export interface SettingState {
   wordFadeWidth: number;
   /** 歌词时延调节步长（毫秒） */
   lyricOffsetStep: number;
+  /** 歌词同步微调（毫秒） */
+  lyricSyncOffset: number;
   /** 启用在线 TTML 歌词 */
   enableOnlineTTMLLyric: boolean;
   /** 启用 QM 歌词 */
@@ -610,6 +612,7 @@ export const useSettingStore = defineStore("setting", {
     hidePassedLines: false,
     wordFadeWidth: 0.5,
     lyricOffsetStep: 500,
+    lyricSyncOffset: 0,
     enableOnlineTTMLLyric: false,
     enableQQMusicLyric: false,
     lyricPriority: "auto",