Merge branch 'dev' into pr/f

Author: MoYingJi

.gitignore

@@ -36,4 +36,7 @@ target
 docs/.vitepress/cache
 docs/.vitepress/dist
 
+# AI
 .trae/*
+.cursor/*
+.claude/*

CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SPlayer is a desktop music player built with **Electron + Vue 3 + TypeScript**. It uses Naive UI for components, Pinia for state management, and integrates with NetEase Cloud Music API, Last.fm, and Subsonic/Navidrome streaming services. Native Rust modules provide OS-level features (taskbar lyrics on Windows, MPRIS on Linux, SMTC on Windows, Discord RPC).
+
+## Commands
+
+```bash
+pnpm dev                # Start dev environment (builds native modules + launches Electron)
+pnpm build              # Full production build (typecheck + electron-vite build)
+pnpm build:win          # Package for Windows
+pnpm build:mac          # Package for macOS
+pnpm build:linux        # Package for Linux
+pnpm lint               # ESLint (--max-warnings=0, zero tolerance)
+pnpm format             # Prettier
+pnpm typecheck          # Full TypeScript check (node + web)
+pnpm typecheck:node     # Main process + preload TypeScript check
+pnpm typecheck:web      # Renderer process TypeScript check
+```
+
+Set `SKIP_NATIVE_BUILD=true` to skip Rust native module compilation during dev.
+
+## Architecture
+
+### Process Model (Electron)
+
+- **Main process** (`electron/main/`): Window management, IPC handlers, SQLite database, system tray, global shortcuts, Fastify API server, native module integration
+- **Preload** (`electron/preload/`): Context bridge exposing `window.api.store` and `window.logger` to renderer
+- **Renderer** (`src/`): Vue 3 SPA — the UI
+
+### IPC Layer
+
+18 IPC modules in `electron/main/ipc/` handle all main↔renderer communication: `ipc-cache`, `ipc-file`, `ipc-lyric`, `ipc-media`, `ipc-mpv`, `ipc-socket`, `ipc-store`, `ipc-taskbar`, `ipc-tray`, `ipc-window`, `ipc-system`, `ipc-shortcut`, `ipc-update`, `ipc-protocol`, `ipc-mac-statusbar`, `ipc-thumbar`, `ipc-renderer-log`.
+
+### Renderer Architecture (`src/`)
+
+- **Stores** (`stores/`): Pinia with persistedstate — `data` (songs/user), `status` (playback), `setting` (config), `local` (local music), `music`, `streaming`, `shortcut`
+- **Core** (`core/`): `audio-player/` (playback engine), `automix/`, `player/` (state), `resource/` (caching)
+- **API** (`api/`): Axios-based, organized by domain (song, playlist, login, streaming, lastfm)
+- **Composables** (`composables/`): `useInit`, `useSongMenu`, `useQualityControl`, etc.
+- **Components** (`components/`): AMLL (lyrics), Card, Common, Global, Layout, List, Menu, Modal, Player, Search, Setting, UI
+
+### Native Modules (`native/`)
+
+Rust-based, built via `scripts/build-native.ts`:
+- `taskbar-lyric` — Windows taskbar lyrics display
+- `external-media-integration` — OS media integration
+- `smtc-for-splayer` — Windows System Media Transport Controls
+- `mpris-for-splayer` — Linux MPRIS support
+- `discord-rpc-for-splayer` — Discord Rich Presence
+- `ferrous-opencc-wasm` — Chinese character conversion (WASM)
+
+### Embedded Server
+
+`electron/server/` runs a Fastify instance (port 25884 default) wrapping NetEase Cloud Music API, proxied via `/api` in dev.
+
+## Path Aliases
+
+```
+@/       → src/
+@emi/    → native/external-media-integration
+@shared/ → src/types/shared
+@opencc/ → native/ferrous-opencc-wasm/pkg
+@native/ → native/
+```
+
+## Code Conventions
+
+- **Language**: Comments and commit messages in Chinese
+- **Vue**: Composition API with `<script setup>`, TypeScript throughout
+- **Auto-imports**: Vue, vue-router, @vueuse/core, and naive-ui composables are auto-imported (no explicit imports needed)
+- **Naive UI components**: Auto-resolved via `unplugin-vue-components`
+- **Unused variables**: Prefix with `_` to suppress lint warnings
+- **Prettier**: Double quotes, trailing commas, 2-space indent, 100 char width
+- **Workers**: Heavy computation (audio analysis) runs in worker threads (`electron/main/workers/`)
+- **TypeScript**: Composite project — `tsconfig.node.json` (main/preload/scripts) and `tsconfig.web.json` (renderer)

electron/main/ipc/ipc-cache.ts

@@ -115,14 +115,17 @@ const initCacheIpc = (): void => {
   });
 
   // 检查是否存在音乐缓存
-  ipcMain.handle("music-cache-check", async (_event, id: number | string, quality?: string) => {
-    try {
-      return await musicCacheService.hasCache(id, quality);
-    } catch (error) {
-      processLog.error("Check music cache failed:", error);
-      return null;
-    }
-  });
+  ipcMain.handle(
+    "music-cache-check",
+    async (_event, id: number | string, quality?: string, md5?: string) => {
+      try {
+        return await musicCacheService.hasCache(id, quality, md5);
+      } catch (error) {
+        processLog.error("Check music cache failed:", error);
+        return null;
+      }
+    },
+  );
 
   // 下载并缓存音乐
   ipcMain.handle(

electron/main/ipc/ipc-taskbar.ts

@@ -8,56 +8,26 @@ import taskbarLyricManager from "../utils/taskbar-lyric-manager";
 
 let cachedIsPlaying = false;
 
+/** 读取完整任务栏配置 */
 const getTaskbarConfig = (): TaskbarConfig => {
-  const store = useStore();
-  return {
-    mode: store.get("taskbar.mode", "taskbar"),
-    maxWidth: store.get("taskbar.maxWidth", 300),
-    position: store.get("taskbar.position", "automatic"),
-    autoShrink: store.get("taskbar.autoShrink", false),
-    margin: store.get("taskbar.margin", 10),
-    minWidth: store.get("taskbar.minWidth", 10),
-    enabled: store.get("taskbar.enabled", false),
-    floatingAlign: store.get("taskbar.floatingAlign", "right"),
-    floatingAutoWidth: store.get("taskbar.floatingAutoWidth", true),
-    floatingWidth: store.get("taskbar.floatingWidth", 300),
-    floatingHeight: store.get("taskbar.floatingHeight", 48),
-    floatingAlwaysOnTop: store.get("taskbar.floatingAlwaysOnTop", false),
-
-    showWhenPaused: store.get("taskbar.showWhenPaused", true),
-    showCover: store.get("taskbar.showCover", true),
-    themeMode: store.get("taskbar.themeMode", "auto"),
-    fontFamily: store.get("taskbar.fontFamily", ""),
-    globalFont: store.get("taskbar.globalFont", ""),
-    fontWeight: store.get("taskbar.fontWeight", 0),
-    animationMode: store.get("taskbar.animationMode", "slide-blur"),
-    singleLineMode: store.get("taskbar.singleLineMode", false),
-    showTranslation: store.get("taskbar.showTranslation", true),
-    showRomaji: store.get("taskbar.showRomaji", true),
-    showWordLyrics: store.get("taskbar.showWordLyrics", true),
-  };
+  return useStore().get("taskbar");
 };
 
+/** 根据配置更新窗口可见性 */
 const updateWindowVisibility = (config: TaskbarConfig) => {
   const tray = getMainTray();
-
-  if (tray) {
-    tray.setTaskbarLyricShow(config.enabled);
+  if (tray) tray.setTaskbarLyricShow(config.enabled);
+  if (!config.enabled) {
+    taskbarLyricManager.close(false);
+    return;
   }
-
-  const shouldBeVisible = config.enabled && (cachedIsPlaying || config.showWhenPaused);
-
+  taskbarLyricManager.create(config.mode);
+  const shouldBeVisible = cachedIsPlaying || config.showWhenPaused;
   taskbarLyricManager.setVisibility(shouldBeVisible);
 };
 
-const updateWindowLayout = (animate: boolean = true) => {
-  taskbarLyricManager.updateLayout(animate);
-};
-
 const initTaskbarIpc = () => {
-  // 在函数内部获取 store，确保在 app ready 事件之后
   const store = useStore();
-
   const initialConfig = getTaskbarConfig();
   if (initialConfig.enabled) {
     taskbarLyricManager.create(initialConfig.mode);
@@ -68,67 +38,30 @@ const initTaskbarIpc = () => {
     taskbarLyricManager.setContentWidth(width);
   });
 
-  ipcMain.on(
-    TASKBAR_IPC_CHANNELS.UPDATE_CONFIG,
-    (_event, partialConfig: Partial<TaskbarConfig>) => {
-      const oldConfig = getTaskbarConfig();
+  ipcMain.handle(TASKBAR_IPC_CHANNELS.GET_OPTION, () => getTaskbarConfig());
 
-      Object.entries(partialConfig).forEach(([key, value]) => {
+  // 设置配置（增量合并）
+  ipcMain.on(
+    TASKBAR_IPC_CHANNELS.SET_OPTION,
+    (_event, option: Partial<TaskbarConfig>, pushToWindow = true) => {
+      if (!option) return;
+      // 增量更新
+      const prev = getTaskbarConfig();
+      const next = { ...prev, ...option };
+      Object.entries(option).forEach(([key, value]) => {
         store.set(`taskbar.${key}`, value);
       });
-
-      const newConfig = getTaskbarConfig();
-
-      const modeChanged = newConfig.mode !== oldConfig.mode;
-
-      if (modeChanged) {
-        taskbarLyricManager.close(false);
+      // 推送到歌词窗口
+      if (pushToWindow) {
+        taskbarLyricManager.send(TASKBAR_IPC_CHANNELS.SYNC_STATE, {
+          type: "config-update",
+          data: option,
+        } as SyncStatePayload);
       }
-
-      if (newConfig.enabled && (!oldConfig.enabled || modeChanged)) {
-        taskbarLyricManager.create(newConfig.mode);
+      updateWindowVisibility(next);
+      if (next.enabled) {
+        taskbarLyricManager.updateLayout(false);
       }
-
-      if (
-        newConfig.enabled !== oldConfig.enabled ||
-        newConfig.showWhenPaused !== oldConfig.showWhenPaused ||
-        modeChanged
-      ) {
-        updateWindowVisibility(newConfig);
-      }
-
-      if (newConfig.enabled) {
-        if (newConfig.mode === "taskbar") {
-          if (
-            newConfig.maxWidth !== oldConfig.maxWidth ||
-            newConfig.position !== oldConfig.position ||
-            newConfig.autoShrink !== oldConfig.autoShrink ||
-            newConfig.margin !== oldConfig.margin ||
-            newConfig.minWidth !== oldConfig.minWidth
-          ) {
-            updateWindowLayout(true);
-          }
-        } else {
-          const floatingWidthChanged =
-            newConfig.floatingAutoWidth === false && newConfig.floatingWidth !== oldConfig.floatingWidth;
-          if (
-            newConfig.maxWidth !== oldConfig.maxWidth ||
-            newConfig.floatingAlign !== oldConfig.floatingAlign ||
-            newConfig.floatingAutoWidth !== oldConfig.floatingAutoWidth ||
-            floatingWidthChanged ||
-            newConfig.floatingHeight !== oldConfig.floatingHeight ||
-            newConfig.floatingAlwaysOnTop !== oldConfig.floatingAlwaysOnTop ||
-            modeChanged
-          ) {
-            updateWindowLayout(false);
-          }
-        }
-      }
-
-      taskbarLyricManager.send(TASKBAR_IPC_CHANNELS.SYNC_STATE, {
-        type: "config-update",
-        data: partialConfig,
-      } as SyncStatePayload);
     },
   );
 
@@ -174,9 +107,8 @@ const initTaskbarIpc = () => {
   // 把事件发射到 app 里不太好，但是我觉得也没有必要为了这一个事件创建一个事件总线
   // TODO: 如果有了事件总线，通过那个事件总线发射这个事件
   (app as EventEmitter).on("explorer-restarted", () => {
-    const currentEnabled = store.get("taskbar.enabled");
-    const currentMode = store.get("taskbar.mode", "taskbar");
-    if (currentEnabled && currentMode === "taskbar") {
+    const currentConfig = getTaskbarConfig();
+    if (currentConfig.enabled && currentConfig.mode === "taskbar") {
       taskbarLyricManager.close(false);
       setTimeout(() => {
         taskbarLyricManager.create("taskbar");

electron/main/ipc/ipc-window.ts

@@ -1,11 +1,13 @@
 import { app, BrowserWindow, ipcMain } from "electron";
+import { MpvService } from "../services/MpvService";
 import { useStore } from "../store";
 import { isDev } from "../utils/config";
 import { initThumbar } from "../thumbar";
 import { processProtocolFromCommand } from "../utils/protocol";
 import mainWindow from "../windows/main-window";
 import loadWindow from "../windows/load-window";
 import loginWindow from "../windows/login-window";
+import { processLog } from "../logger";
 
 /** 是否已首次启动 */
 let isFirstLaunch = false;
@@ -137,9 +139,21 @@ const initWindowsIpc = (): void => {
   });
 
   // 重启
-  ipcMain.on("win-restart", () => {
+  ipcMain.on("win-restart", async () => {
+    // 先停止 MPV 服务，避免占用资源
+    const mpvService = MpvService.getInstance();
+    try {
+      await mpvService.stop();
+      processLog.info("MPV 进程已停止");
+    } catch (err) {
+      processLog.error("停止 MPV 进程失败", err);
+    } finally {
+      mpvService.terminate();
+    }
+
+    // 重启应用
     app.relaunch();
-    app.quit();
+    app.exit(0);
   });
 
   // 向主窗口发送事件

electron/main/services/MpvService.ts

@@ -68,6 +68,8 @@ export class MpvService {
       "--demuxer-max-bytes=120MiB", // 增大缓存容量
       "--demuxer-readahead-secs=120", // 增加预读时间
       `--audio-device=${this.currentAudioDevice}`, // 使用当前设置的音频设备
+      "--audio-channels=auto", // 自动检测音频通道
+      "--demuxer-lavf-o=fflags=+discardcorrupt", // 容错处理，忽略损坏的数据
     ];
 
     // 关闭自动播放时，用启动参数强制暂停，避免启动后短暂自动播放
@@ -83,12 +85,21 @@ export class MpvService {
     //processLog.info("正在启动 MPV 进程...", args);
 
     try {
-      this.mpvProcess = spawn("mpv", args, { stdio: "ignore" });
+      this.mpvProcess = spawn("mpv", args, { stdio: ["ignore", "pipe", "pipe"] });
       // 将当前进程与本次播放请求关联，便于区分旧进程退出与新进程生命周期
       this.mpvProcessNonce = this.playNonce;
 
-      this.mpvProcess.on("exit", () => {
-        //processLog.warn(`MPV 进程已退出`);
+      // 捕获 stdout 和 stderr 用于调试
+      this.mpvProcess.stdout?.on("data", (data) => {
+        processLog.info("MPV stdout:", data.toString());
+      });
+
+      this.mpvProcess.stderr?.on("data", (data) => {
+        processLog.error("MPV stderr:", data.toString());
+      });
+
+      this.mpvProcess.on("exit", (code, signal) => {
+        processLog.warn(`MPV 进程已退出，退出码: ${code}, 信号: ${signal}`);
         this.mpvProcess = null;
         this.isConnected = false;
         this.client = null;