🐞 fix: 切换引擎自动重启 & 修复进度定时器 & 添加一些注释

imsyy · imsyy · commit 32c4aa62b95d · 2026-01-08T15:47:08.000+08:00
diff --git a/electron/main/ipc/ipc-system.ts b/electron/main/ipc/ipc-system.ts
@@ -33,6 +33,13 @@ const initSystemIpc = (): void => {
     app.quit();
   });
 
+  // 重启应用
+  ipcMain.on("restart-app", () => {
+    ipcLog.info("🔄 Restarting application...");
+    app.relaunch();
+    app.exit(0);
+  });
+
   // 获取系统全部字体
   ipcMain.handle("get-all-fonts", async () => {
     try {
diff --git a/src/components/Setting/PlaySetting.vue b/src/components/Setting/PlaySetting.vue
@@ -102,9 +102,10 @@
           </n-text>
         </div>
         <n-select
-          v-model:value="settingStore.audioEngine"
+          :value="settingStore.audioEngine"
           :options="Object.values(audioEngineData)"
           class="set"
+          @update:value="handleEngineChange"
         />
       </n-card>
       <n-card v-if="!isElectron" class="set-item">
@@ -117,13 +118,20 @@
       <n-card v-if="isElectron" class="set-item">
         <div class="label">
           <n-text class="name">音频输出设备</n-text>
-          <n-text class="tip" :depth="3">新增或移除音频设备后请重新打开设置</n-text>
+          <n-text class="tip" :depth="3">
+            {{
+              settingStore.audioEngine === "ffmpeg"
+                ? "FFmpeg 引擎不支持切换输出设备"
+                : "新增或移除音频设备后请重新打开设置"
+            }}
+          </n-text>
         </div>
         <n-select
           v-model:value="settingStore.playDevice"
           class="set"
           :options="outputDevices"
           :render-option="renderOption"
+          :disabled="settingStore.audioEngine === 'ffmpeg'"
           @update:value="playDeviceChange"
         />
       </n-card>
@@ -487,6 +495,34 @@ const showSpectrumsChange = (value: boolean) => {
   settingStore.showSpectrums = value;
 };
 
+// 处理音频引擎切换
+const handleEngineChange = (newEngine: "element" | "ffmpeg") => {
+  const oldEngine = settingStore.audioEngine;
+  if (newEngine === oldEngine) return;
+
+  // 先保存新的引擎设置
+  settingStore.audioEngine = newEngine;
+
+  // 弹出确认对话框
+  window.$dialog.warning({
+    title: "切换音频引擎",
+    content: "音频引擎切换需要重启应用才能生效。是否立即重启？",
+    positiveText: "立即重启",
+    negativeText: "稍后",
+    onPositiveClick: () => {
+      // 立即重启应用
+      if (isElectron) {
+        window.electron.ipcRenderer.send("restart-app");
+      } else {
+        window.location.reload();
+      }
+    },
+    onNegativeClick: () => {
+      window.$message.info("引擎将在下次启动时生效");
+    },
+  });
+};
+
 onMounted(() => {
   if (isElectron) {
     getOutputDevices();
diff --git a/src/core/audio-player/AudioEffectManager.ts b/src/core/audio-player/AudioEffectManager.ts
@@ -92,6 +92,10 @@ export class AudioEffectManager {
     return dataArray;
   }
 
+  /**
+   * 获取低频音量
+   * @returns 低频音量 (0-1)
+   */
   public getLowFrequencyVolume(): number {
     if (!this.analyserNode) return 0;
 
diff --git a/src/core/audio-player/AudioElementPlayer.ts b/src/core/audio-player/AudioElementPlayer.ts
@@ -2,14 +2,19 @@ import { AUDIO_EVENTS, BaseAudioPlayer, type AudioEventType } from "./BaseAudioP
 
 /**
  * 基于 HTMLAudioElement 的播放器实现
+ *
+ * 使用原生 HTML5 Audio 元素进行音频播放，支持大多数常见格式
+ * 通过 MediaElementAudioSourceNode 连接到 Web Audio API 音频图谱
  */
 export class AudioElementPlayer extends BaseAudioPlayer {
+  /** 内部 Audio 元素 */
   private audioElement: HTMLAudioElement;
+  /** MediaElementAudioSourceNode 用于连接 Web Audio API */
   private sourceNode: MediaElementAudioSourceNode | null = null;
 
-  /** Seek 锁 */
+  /** Seek 锁，用于在 seek 过程中返回稳定的 currentTime */
   private isInternalSeeking = false;
-  /** 目标时间缓存 */
+  /** 目标时间缓存，用于在 seek 过程中返回稳定的 currentTime */
   private targetSeekTime = 0;
 
   constructor() {
@@ -23,6 +28,10 @@ export class AudioElementPlayer extends BaseAudioPlayer {
     });
   }
 
+  /**
+   * 当音频图谱初始化完成时调用
+   * 创建 MediaElementAudioSourceNode 并连接到输入节点
+   */
   protected onGraphInitialized(): void {
     if (!this.audioCtx || !this.inputNode) return;
 
@@ -35,66 +44,107 @@ export class AudioElementPlayer extends BaseAudioPlayer {
     }
   }
 
+  /**
+   * 加载音频资源
+   * @param url 音频地址
+   */
   public async load(url: string): Promise<void> {
     this.audioElement.src = url;
     this.audioElement.load();
   }
 
+  /**
+   * 执行底层播放
+   * @returns 播放 Promise
+   */
   protected async doPlay(): Promise<void> {
     return this.audioElement.play();
   }
 
+  /**
+   * 执行底层暂停
+   */
   protected doPause(): void {
     this.audioElement.pause();
   }
 
+  /**
+   * 跳转到指定时间
+   * @param time 目标时间（秒）
+   */
   public async seek(time: number): Promise<void> {
     this.isInternalSeeking = true;
     this.targetSeekTime = time;
 
     await super.seek(time);
   }
 
+  /**
+   * 执行底层 Seek
+   * @param time 目标时间（秒）
+   */
   protected doSeek(time: number): void {
     if (Number.isFinite(time)) {
       this.audioElement.currentTime = time;
     }
   }
 
+  /**
+   * 设置播放速率
+   * @param value 速率值 (0.5 - 2.0)
+   */
   public setRate(value: number): void {
     this.audioElement.playbackRate = value;
   }
 
+  /**
+   * 获取当前播放速率
+   * @returns 当前速率值
+   */
   public getRate(): number {
     return this.audioElement.playbackRate;
   }
 
+  /**
+   * 设置音频输出设备
+   * @param deviceId 设备 ID
+   */
   protected async doSetSinkId(deviceId: string): Promise<void> {
     if (typeof this.audioElement.setSinkId === "function") {
       await this.audioElement.setSinkId(deviceId);
     }
   }
 
+  /** 获取当前音频源地址 */
   public get src(): string {
     return this.audioElement.src || "";
   }
 
+  /** 获取音频总时长（秒） */
   public get duration(): number {
     return this.audioElement.duration || 0;
   }
 
+  /**
+   * 获取当前播放时间（秒）
+   * 如果正在 Seek，返回目标时间以避免进度跳回
+   */
   public get currentTime(): number {
-    // 如果正在 Seek (无论是等待淡出，还是正在缓冲)，强制返回目标时间以避免进度跳回
     if (this.isInternalSeeking) {
       return this.targetSeekTime;
     }
     return this.audioElement.currentTime || 0;
   }
 
+  /** 获取是否暂停状态 */
   public get paused(): boolean {
     return this.audioElement.paused;
   }
 
+  /**
+   * 获取错误码
+   * @returns 错误码 (0: 无错误, 1: ABORTED, 2: NETWORK, 3: DECODE, 4: SRC_NOT_SUPPORTED)
+   */
   public getErrorCode(): number {
     if (!this.audioElement.error) return 0;
     switch (this.audioElement.error.code) {
@@ -113,6 +163,7 @@ export class AudioElementPlayer extends BaseAudioPlayer {
 
   /**
    * 监听原生 DOM 事件并转发为标准事件
+   * 将 HTMLAudioElement 的事件转换为 BaseAudioPlayer 的统一事件格式
    */
   private bindInternalEvents() {
     const events: AudioEventType[] = Object.values(AUDIO_EVENTS);
diff --git a/src/core/audio-player/BaseAudioPlayer.ts b/src/core/audio-player/BaseAudioPlayer.ts
@@ -172,19 +172,14 @@ export abstract class BaseAudioPlayer extends EventTarget {
    */
   public async seek(time: number) {
     this.cancelPendingPause();
-
     // 如果已经暂停，直接跳转
     if (this.paused) {
       this.doSeek(time);
       return;
     }
-
     this.applyFadeTo(0, SEEK_FADE_TIME);
-
     await new Promise((resolve) => setTimeout(resolve, SEEK_FADE_TIME * 1000));
-
     this.doSeek(time);
-
     this.applyFadeTo(this.volume, SEEK_FADE_TIME);
   }
 
@@ -278,18 +273,22 @@ export abstract class BaseAudioPlayer extends EventTarget {
     }
   }
 
+  /** 获取频率数据 */
   public getFrequencyData(): Uint8Array {
     return this.effectManager ? this.effectManager.getFrequencyData() : new Uint8Array(0);
   }
 
+  /** 获取低频音量 */
   public getLowFrequencyVolume(): number {
     return this.effectManager ? this.effectManager.getLowFrequencyVolume() : 0;
   }
 
+  /** 设置滤波器增益 */
   public setFilterGain(index: number, value: number) {
     this.effectManager?.setFilterGain(index, value);
   }
 
+  /** 获取滤波器增益 */
   public getFilterGains(): number[] {
     return this.effectManager ? this.effectManager.getFilterGains() : [];
   }
@@ -321,6 +320,11 @@ export abstract class BaseAudioPlayer extends EventTarget {
   public abstract get paused(): boolean;
   public abstract getErrorCode(): number;
 
+  /**
+   * 触发事件
+   * @param type 事件类型
+   * @param detail 事件详情
+   */
   protected emit(type: Exclude<AudioEventType, "error">): void;
   protected emit(type: typeof AUDIO_EVENTS.ERROR, detail: AudioErrorDetail): void;
   protected emit(type: AudioEventType, detail?: AudioErrorDetail): void {
@@ -331,6 +335,12 @@ export abstract class BaseAudioPlayer extends EventTarget {
     }
   }
 
+  /**
+   * 添加事件监听
+   * @param type 事件类型
+   * @param listener 事件监听器
+   * @param options 事件选项
+   */
   public override addEventListener<K extends keyof AudioEventMap>(
     type: K,
     listener: (this: BaseAudioPlayer, ev: AudioEventMap[K]) => unknown,
@@ -339,6 +349,12 @@ export abstract class BaseAudioPlayer extends EventTarget {
     super.addEventListener(type, listener as EventListenerOrEventListenerObject, options);
   }
 
+  /**
+   * 移除事件监听
+   * @param type 事件类型
+   * @param listener 事件监听器
+   * @param options 事件选项
+   */
   public override removeEventListener<K extends keyof AudioEventMap>(
     type: K,
     listener: (this: BaseAudioPlayer, ev: AudioEventMap[K]) => unknown,
diff --git a/src/core/audio-player/ffmpeg-engine/FFmpegAudioPlayer.ts b/src/core/audio-player/ffmpeg-engine/FFmpegAudioPlayer.ts
diff --git a/src/core/player/PlayerController.ts b/src/core/player/PlayerController.ts

Original file line number	Diff line number	Diff line change
`@@ -92,6 +92,10 @@ export class AudioEffectManager {`
`92`	`92`	`return dataArray;`
`93`	`93`	`}`
`94`	`94`
	`95`	`+ /**`
	`96`	`+ * 获取低频音量`
	`97`	`+ * @returns 低频音量 (0-1)`
	`98`	`+ */`
`95`	`99`	`public getLowFrequencyVolume(): number {`
`96`	`100`	`if (!this.analyserNode) return 0;`
`97`	`101`