### Index

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
  name: "SPlayer"
  text: "一个简约的音乐播放器"
  tagline: 基于 Vue 3 + TypeScript + Naïve UI + Electron 开发 · 项目已进入维护模式
  actions:
    - theme: brand
      text: 立即获取
      link: /download
    - theme: alt
      text: 使用指南
      link: /guide
    - theme: alt
      text: API
      link: /api

features:
  - title: 🎵 丰富的音乐功能
    details: 支持扫码登录、手机号登录、每日签到、云贝签到、私人FM、每日推荐歌曲、云盘音乐等完整功能
  - title: 💻 桌面歌词
    details: 支持桌面歌词显示，可自定义样式、位置、字体大小等，支持逐字歌词和歌词翻译
  - title: 📁 本地音乐管理
    details: 支持本地歌曲管理及分类，简易的本地音乐标签编辑及封面修改，支持播放部分无版权歌曲
  - title: 🎨 主题自适应
    details: 封面主题色自适应，支持全站着色，Light / Dark / Auto 模式自动切换
  - title: ⬇️ 下载功能
    details: 支持下载歌曲/批量下载，最高支持 Hi-Res，需具有相应会员账号
  - title: 🔄 多种部署方式
    details: 支持 Docker、Vercel、服务器部署，也可本地部署，提供完整的 API 接口和 WebSocket 控制
---

::: warning 项目已进入维护模式
SPlayer 后续仅进行必要的维护与重大问题修复，不再主动开发新功能。新功能与后续版本请关注 [SPlayer-Next](https://github.com/SPlayer-Dev/SPlayer-Next)。
:::

---

### Troubleshooting/Debug

# 调试模式和错误排查

本文介绍如何使用调试模式定位和解决 SPlayer 运行中遇到的问题。

## 启用调试模式

### 开发者工具

在 Electron 客户端中，可以通过以下方式打开开发者工具：

- **快捷键**：`Ctrl + Shift + I` (Windows/Linux) 或 `Cmd + Option + I` (macOS)

开发者工具包含以下面板：

| 面板            | 用途                   |
| --------------- | ---------------------- |
| **Console**     | 查看日志输出、错误信息 |
| **Network**     | 监控网络请求、API 调用 |
| **Application** | 查看本地存储、缓存数据 |
| **Sources**     | 调试前端代码           |

### 查看日志文件

应用运行日志保存在以下位置：

| 系统    | 路径                                          |
| ------- | --------------------------------------------- |
| Windows | `%APPDATA%\SPlayer\logs\`                     |
| macOS   | `~/Library/Application Support/SPlayer/logs/` |
| Linux   | `$XDG_CONFIG_HOME/SPlayer/logs/`              |

开发环境日志：`%APPDATA%\SPlayer\logs\dev\`（在原日志目录的 `dev` 子文件夹下）

原生模块日志：

- 外部媒体集成模块日志：`%APPDATA%\SPlayer\logs\external-media-integration\`

## 常见错误类型

### 网络错误

**症状**：无法加载歌曲、封面、歌词等资源

**排查步骤**：

1. 打开开发者工具 → Network 面板
2. 检查失败的请求（红色标记）
3. 查看响应状态码和错误信息

**常见原因**：

- API 服务器不可用
- 网络连接问题
- 代理配置错误
- CORS 跨域限制

### 播放错误

**症状**：歌曲无法播放、卡顿、无声音

**排查步骤**：

1. 检查 Console 面板是否有错误信息
2. 检查音频 URL 是否有效（Network 面板）
3. 确认系统音频输出设备正常

**常见原因**：

- 音频 URL 过期
- 音频格式不支持
- 系统音频设备问题
- 内存不足

### 渲染错误

**症状**：界面显示异常、白屏、组件不加载

**排查步骤**：

1. 查看 Console 面板的错误堆栈
2. 检查是否有 Vue 组件错误
3. 尝试清除缓存后重启

**解决方案**：

```bash
# 清除应用缓存（Windows）
rd /s /q "%APPDATA%\SPlayer\Cache"

# 清除应用缓存（macOS）
rm -rf ~/Library/Application\ Support/SPlayer/Cache

# 清除应用缓存（Linux）
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/SPlayer/Cache"
```

## 收集调试信息

如果需要提交 Issue，请收集以下信息：

1. **系统信息**
   - 操作系统版本
   - SPlayer 版本（如果是开发版本，还要带上 Commit ID）
   - Node.js 版本（如果是开发环境）

2. **错误信息**
   - Console 面板的完整错误日志
   - 相关的网络请求截图

3. **复现步骤**
   - 详细描述导致问题的操作步骤
   - 是否可以稳定复现

## 重置应用

如果问题持续存在，可以尝试重置应用：

::: warning 注意
重置会清除所有用户数据，包括登录状态、播放列表、设置等。
:::

```bash
# Windows
rd /s /q "%APPDATA%\SPlayer"

# macOS
rm -rf ~/Library/Application\ Support/SPlayer

# Linux
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/SPlayer"
```

重置后重新启动应用并登录即可。

---

### Troubleshooting/Macos

# macOS 常见问题

本文汇总 macOS 系统上使用 SPlayer 时可能遇到的常见问题及解决方案。

## 应用签名问题

### 无法打开应用

**症状**：双击应用后提示"无法打开，因为无法验证开发者"

**解决方案**：

1. 打开 **系统偏好设置** → **安全性与隐私** → **通用**
2. 点击 **仍要打开** 按钮
3. 或者在终端执行：
   ```bash
   xattr -cr /Applications/SPlayer.app
   ```

### Gatekeeper 阻止

如果系统持续阻止应用运行：

```bash
# 移除隔离属性
sudo xattr -r -d com.apple.quarantine /Applications/SPlayer.app

# 验证属性已移除
xattr -l /Applications/SPlayer.app
```

## 权限问题

### 麦克风/音频权限

**症状**：部分音频功能无法正常工作

**解决方案**：

1. 打开 **系统偏好设置** → **安全性与隐私** → **隐私**
2. 在左侧选择 **麦克风**
3. 确保 SPlayer 已勾选

### 网络权限

**症状**：首次启动时提示网络访问权限

**解决方案**：

点击 **允许** 授权应用访问网络。如果误点了拒绝：

1. 打开 **系统偏好设置** → **安全性与隐私** → **防火墙**
2. 点击 **防火墙选项**
3. 找到 SPlayer，设置为 **允许传入连接**

## 系统集成

### 媒体控制键不工作

**症状**：键盘上的播放/暂停、上一首、下一首键无响应

**可能原因**：

1. 其他应用占用了媒体控制键
2. 系统设置将媒体键分配给了其他功能

**解决方案**：

1. 关闭其他可能占用媒体键的应用（如 iTunes、Spotify）
2. 检查 **系统偏好设置** → **键盘** → **键盘快捷键** 中的媒体键设置

### 控制中心不显示

**症状**：macOS 控制中心的"正在播放"部分不显示 SPlayer

**说明**：

目前 SPlayer 在 macOS 上暂不支持系统级媒体集成（Now Playing）。此功能仅在 Windows 系统上通过 SMTC 实现。

## 性能问题

### 应用启动缓慢

**可能原因**：

1. 首次启动需要加载较多资源
2. 系统资源不足

**解决方案**：

1. 关闭不必要的后台应用
2. 检查 **活动监视器** 中的内存和 CPU 使用情况
3. 重启系统后再试

### 内存占用过高

**解决方案**：

1. 定期清理应用缓存
2. 减少同时打开的歌单数量
3. 关闭不必要的可视化效果

## 更新问题

### 自动更新失败

**症状**：检测到更新但无法下载或安装

**解决方案**：

1. 手动从 [GitHub Releases](https://github.com/SPlayer-Dev/SPlayer/releases) 下载最新版本
2. 删除旧版本后重新安装
3. 检查网络连接是否正常

---

### Troubleshooting/Macos Arm Api

# macOS ARM 设备 API 启动失败

在 Apple Silicon (M1/M2/M3) 设备上，可能会遇到 API 服务启动失败的问题。

## 问题现象

启动应用后，出现以下情况：

- 无法加载歌曲列表
- API 请求超时或失败
- 控制台显示 "API server failed to start" 错误

## 原因分析

### 1. Node.js 架构不匹配

如果系统中安装的 Node.js 是 x64 版本，在 ARM 设备上可能会有兼容性问题。

### 2. 依赖编译问题

部分原生 Node.js 模块需要针对 ARM 架构重新编译。

### 3. Rosetta 转译问题

通过 Rosetta 2 运行的 x64 应用可能与系统服务存在兼容性问题。

## 解决方案

### 方案一：使用 ARM 原生版本

确保下载并安装 ARM 架构的 SPlayer：

1. 访问 [GitHub Releases](https://github.com/SPlayer-Dev/SPlayer/releases)
2. 下载文件名包含 `arm64` 的版本
3. 删除旧版本后重新安装

### 方案二：检查 Node.js 架构

如果您在开发环境中遇到此问题：

```bash
# 检查 Node.js 架构
node -p "process.arch"

# 应该显示 arm64
# 如果显示 x64，需要重新安装 ARM 版本的 Node.js
```

**重新安装 ARM 版本 Node.js：**

```bash
# 使用 nvm 安装 ARM 版本
arch -arm64 zsh
nvm install 24

# 验证架构
node -p "process.arch"  # 应显示 arm64
```

### 方案三：重新编译依赖

在开发环境中，删除并重新安装依赖：

```bash
# 删除现有依赖
rm -rf node_modules
rm -rf native/*/target

# 重新安装
pnpm install

# 重新编译原生模块
pnpm build:native
```

## 开发环境专用

### 检查终端架构

确保终端以原生 ARM 模式运行：

```bash
# 检查当前架构
uname -m  # 应显示 arm64

# 如果显示 x86_64，说明在 Rosetta 模式下
# 请使用原生 ARM 终端
```

### 配置 Homebrew

确保 Homebrew 安装在正确的位置：

- ARM 版本：`/opt/homebrew/`
- x64 版本：`/usr/local/`

```bash
# 检查 Homebrew 位置
which brew
# ARM 版本应显示 /opt/homebrew/bin/brew
```

### 重装开发环境

如果问题持续存在：

```bash
# 1. 卸载 x64 版本的开发工具
brew uninstall node

# 2. 确保使用 ARM Homebrew
/opt/homebrew/bin/brew install node

# 3. 验证
node -p "process.arch"  # arm64
```

## 已知限制

- 部分依赖可能暂不支持 ARM 架构
- 某些功能可能需要 Rosetta 2 转译层
- 性能可能略低于原生 ARM 编译版本

## 反馈问题

如果上述方法都无法解决问题，请在 [GitHub Issues](https://github.com/SPlayer-Dev/SPlayer/issues) 提交问题，并附上：

1. macOS 版本
2. 芯片型号（M1/M2/M3）
3. `node -p "process.arch"` 输出
4. 完整的错误日志

---

### Troubleshooting/Macos Damaged

# Mac 系统应用显示已损坏

在 macOS 上打开 SPlayer 时，可能会遇到"应用已损坏，无法打开"的提示。这通常是由于 macOS 的安全机制导致的，而非应用本身损坏。

## 问题现象

打开应用时出现以下提示：

> "SPlayer" 已损坏，无法打开。您应该将它移到废纸篓。

或

> 无法打开 "SPlayer"，因为 Apple 无法检查其是否包含恶意软件。

## 原因分析

这是 macOS Gatekeeper 安全机制的正常行为。从非 Mac App Store 下载的应用，如果没有 Apple 签名认证，系统会阻止其运行。

SPlayer 目前未进行 Apple 开发者签名，因此会触发此保护机制。

## 解决方案

### 方法一：移除隔离属性（推荐）

打开 **终端** 应用，执行以下命令：

```bash
sudo xattr -r -d com.apple.quarantine /Applications/SPlayer.app
```

执行后输入管理员密码，然后重新打开应用即可。

### 方法二：临时允许任意来源

::: warning 安全提示
此方法会降低系统安全性，仅建议临时使用，安装完成后建议恢复设置。
:::

**步骤 1：允许任意来源**

```bash
sudo spctl --master-disable
```

**步骤 2：在设置中选择任意来源**

1. 打开 **系统偏好设置** → **安全性与隐私** → **通用**
2. 在"允许从以下位置下载的应用"中选择 **任何来源**

**步骤 3：恢复安全设置（安装后执行）**

```bash
sudo spctl --master-enable
```

### 方法三：右键打开

1. 在 Finder 中找到 SPlayer.app
2. 按住 `Control` 键并点击应用图标
3. 在弹出菜单中选择 **打开**
4. 在确认对话框中点击 **打开**

此方法可能需要重复 2-3 次才能成功。

## 验证应用完整性

如果担心应用完整性，可以验证下载文件的 SHA256 校验和：

```bash
# 计算下载文件的校验和
shasum -a 256 ~/Downloads/SPlayer-x.x.x-mac.dmg

# 与 GitHub Release 页面提供的校验和对比
```

## M 系列芯片注意事项

如果您使用的是 M1/M2/M3 芯片的 Mac：

1. 确保下载的是 ARM 版本（arm64）的安装包
2. 首次运行可能需要 Rosetta 2 转译（如果下载了 x64 版本）

安装 Rosetta 2：

```bash
softwareupdate --install-rosetta
```

## 仍然无法解决？

如果上述方法都无法解决问题：

1. 完全删除应用及其相关文件：

   ```bash
   rm -rf /Applications/SPlayer.app
   rm -rf ~/Library/Application\ Support/SPlayer
   rm -rf ~/Library/Caches/SPlayer
   ```

2. 重新从 [GitHub Releases](https://github.com/SPlayer-Dev/SPlayer/releases) 下载最新版本

3. 使用方法一移除隔离属性后再打开

---

### Troubleshooting/Ubuntu Sandbox

# Ubuntu 系统沙箱启动失败

在 Ubuntu 及其他 Linux 发行版上，可能会遇到 Electron 应用因沙箱限制而无法启动的问题。

## 问题现象

启动应用时出现以下错误：

```
[xxxx:xxxx:xxxx] FATAL:setuid_sandbox_host.cc(163)]
The SUID sandbox helper binary was found, but is not configured correctly.
```

或

```
Running as root without --no-sandbox is not supported.
```

## 原因分析

Electron 使用 Chromium 的沙箱机制来增强安全性。在某些 Linux 配置下，沙箱可能无法正常工作：

1. **用户命名空间未启用**：内核未开启用户命名空间功能
2. **权限问题**：沙箱辅助程序权限配置不正确
3. **容器/WSL 环境**：在容器或 WSL 中运行时沙箱受限

## 解决方案

### 方案一：启用用户命名空间（推荐）

这是最安全的解决方案：

```bash
# 检查当前状态
cat /proc/sys/kernel/unprivileged_userns_clone

# 如果输出 0，需要启用
echo 1 | sudo tee /proc/sys/kernel/unprivileged_userns_clone

# 永久启用（重启后生效）
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-local-userns.conf
sudo sysctl --system
```

### 方案二：配置沙箱权限

设置 chrome-sandbox 的正确权限：

```bash
# 找到 chrome-sandbox 文件位置
find /opt -name "chrome-sandbox" 2>/dev/null
# 或
find /usr -name "chrome-sandbox" 2>/dev/null

# 设置正确的权限和所有者
sudo chown root:root /path/to/chrome-sandbox
sudo chmod 4755 /path/to/chrome-sandbox
```

对于 AppImage 格式：

```bash
# 解压 AppImage
./SPlayer.AppImage --appimage-extract

# 设置权限
sudo chown root:root squashfs-root/chrome-sandbox
sudo chmod 4755 squashfs-root/chrome-sandbox

# 运行解压后的版本
./squashfs-root/splayer
```

### 方案三：禁用沙箱（不推荐）

::: danger 安全警告
禁用沙箱会降低应用的安全性，仅在其他方法无效时使用。
:::

**方法 1：命令行参数**

```bash
./SPlayer.AppImage --no-sandbox
```

**方法 2：环境变量**

```bash
export ELECTRON_DISABLE_SANDBOX=1
./SPlayer.AppImage
```

**方法 3：修改 .desktop 文件**

```bash
# 编辑桌面快捷方式
sudo nano /usr/share/applications/splayer.desktop

# 修改 Exec 行，添加 --no-sandbox
Exec=/path/to/SPlayer.AppImage --no-sandbox %U
```

## 特定发行版解决方案

### Ubuntu 22.04+

```bash
# 安装必要的库
sudo apt update
sudo apt install libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

# 启用用户命名空间
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-local-userns.conf
sudo sysctl --system
```

### Debian

```bash
# 安装依赖
sudo apt install libnotify4 libsecret-1-0

# 启用用户命名空间
sudo sysctl -w kernel.unprivileged_userns_clone=1
```

### Arch Linux

```bash
# 安装依赖
sudo pacman -S nss libxss alsa-lib libpulse

# 通常 Arch 默认已启用用户命名空间
```

### Fedora

```bash
# 安装依赖
sudo dnf install libXScrnSaver alsa-lib

# Fedora 通常不需要额外配置沙箱
```

## WSL 环境

在 Windows Subsystem for Linux 中运行 Electron 应用需要特殊配置：

1. **使用 WSL2**：WSL1 不支持图形界面应用
2. **安装 WSLg**：Windows 11 或 Windows 10 21H2+
3. **禁用沙箱**：WSL 环境中沙箱通常无法正常工作

```bash
# WSL 中运行
export DISPLAY=:0
./SPlayer.AppImage --no-sandbox
```

## Docker 容器

在 Docker 中运行需要额外的安全配置：

```dockerfile
# Dockerfile 示例
FROM node:24

# 安装依赖
RUN apt-get update && apt-get install -y \
    libnss3 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 \
    libxcomposite1 libxdamage1 libxfixes3 \
    libxrandr2 libgbm1 libasound2

# 必须添加 --no-sandbox 参数运行
```

运行容器时：

```bash
docker run --cap-add SYS_ADMIN splayer-container
```

## 验证修复

修复后，验证应用是否正常启动：

```bash
# 检查进程
ps aux | grep -i splayer

# 查看日志
./SPlayer.AppImage 2>&1 | head -50
```

## 仍有问题？

如果上述方法都无法解决问题，请提交 Issue 并附上：

1. Linux 发行版和版本
2. 完整的错误信息
3. `uname -a` 输出
4. `cat /proc/sys/kernel/unprivileged_userns_clone` 输出

---

### Troubleshooting/Windows7

# Windows 7 系统兼容性问题

SPlayer 基于 Electron 构建，对 Windows 7 的支持存在一定限制。

## 系统要求

::: warning 重要提示
从 Electron 23 开始，官方不再支持 Windows 7/8/8.1。SPlayer 使用的 Electron 版本可能已不再兼容这些系统。
:::

**推荐系统**：Windows 10 版本 1903 或更高版本

## 常见问题

### 应用无法启动

**症状**：双击应用无反应，或提示缺少系统组件

**原因**：

- 缺少必要的系统更新
- Electron 版本不兼容

**解决方案**：

1. 安装所有可用的 Windows 更新
2. 安装以下必要组件：
   - [.NET Framework 4.7.2](https://dotnet.microsoft.com/download/dotnet-framework/net472)
   - [Visual C++ Redistributable 2015-2022](https://aka.ms/vs/17/release/vc_redist.x64.exe)

### 缺少 API 函数

**症状**：提示 "The procedure entry point xxx could not be located"

**原因**：Windows 7 缺少部分现代 API 函数

**解决方案**：

1. 确保已安装 SP1 (Service Pack 1)
2. 安装 KB2533623 更新
3. 安装 KB3063858 更新

### 媒体功能缺失

**症状**：SMTC 媒体控制不可用

**说明**：Windows 7 不支持 SMTC (System Media Transport Controls)，这是 Windows 10 引入的功能。

### SSL/TLS 连接问题

**症状**：无法连接到 API 服务器，网络请求失败

**原因**：Windows 7 默认不支持 TLS 1.2

**解决方案**：

1. 安装 KB3140245 更新
2. 运行以下注册表修改（以管理员身份）：

```reg
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client]
"DisabledByDefault"=dword:00000000
"Enabled"=dword:00000001

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server]
"DisabledByDefault"=dword:00000000
"Enabled"=dword:00000001
```

## 兼容模式

如果仍然遇到问题，可以尝试兼容模式运行：

1. 右键点击 SPlayer.exe
2. 选择 **属性**
3. 切换到 **兼容性** 选项卡
4. 勾选 **以兼容模式运行这个程序**
5. 选择 **Windows 8**

## 历史版本

如果新版本无法在 Windows 7 上运行，可以尝试使用旧版本：

1. 访问 [GitHub Releases](https://github.com/SPlayer-Dev/SPlayer/releases)
2. 查找使用 Electron 22 或更早版本的发布
3. 下载对应的安装包

::: warning 安全警告
旧版本可能存在已知的安全漏洞，建议尽快升级到 Windows 10 或更高版本。
:::

## 升级建议

考虑到 Windows 7 已于 2020 年 1 月结束支持，强烈建议升级到 Windows 10/11：

1. **安全性**：Windows 7 不再收到安全更新
2. **兼容性**：越来越多的应用不再支持 Windows 7
3. **性能**：新系统通常有更好的性能优化
4. **功能**：可以使用 SMTC 等现代功能

## 相关链接

- [Windows 7 生命周期结束说明](https://docs.microsoft.com/zh-cn/lifecycle/products/windows-7)
- [Electron 系统要求](https://www.electronjs.org/docs/latest/tutorial/support#windows)

---

### Api

# API 接口文档

## 概述

本软件提供了本地 HTTP API 服务，用于控制播放器和访问音乐服务。默认端口为 `25884`

## 基础信息

- **基础 URL**: `http://localhost:25884`
- **API 前缀**: `/api`
- **响应格式**: JSON

## 统一响应格式

所有接口都遵循以下响应格式：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

### 状态码说明

- `200`: 成功
- `500`: 服务器错误

---

## 播放控制接口 (Control API)

**基础路径**: `/api/control`

### 播放

**接口**: `GET /api/control/play`

**描述**: 发送播放命令

**响应示例**:

```json
{
  "code": 200,
  "message": "播放命令已发送",
  "data": null
}
```

---

### 暂停

**接口**: `GET /api/control/pause`

**描述**: 发送暂停命令

**响应示例**:

```json
{
  "code": 200,
  "message": "暂停命令已发送",
  "data": null
}
```

---

### 播放/暂停切换

**接口**: `GET /api/control/toggle`

**描述**: 切换播放/暂停状态

**响应示例**:

```json
{
  "code": 200,
  "message": "播放/暂停切换命令已发送",
  "data": null
}
```

---

### 下一曲

**接口**: `GET /api/control/next`

**描述**: 播放下一首歌曲

**响应示例**:

```json
{
  "code": 200,
  "message": "下一曲命令已发送",
  "data": null
}
```

---

### 上一曲

**接口**: `GET /api/control/prev`

**描述**: 播放上一首歌曲

**响应示例**:

```json
{
  "code": 200,
  "message": "上一曲命令已发送",
  "data": null
}
```

---

### 获取状态

**接口**: `GET /api/control/status`

**描述**: 获取软件版本、环境数据和连接状态

**响应示例**:

```json
{
  "code": 200,
  "message": "获取状态成功",
  "data": {
    "version": {
      "app": "3.0.0-beta.6",
      "name": "SPlayer"
    },
    "environment": {
      "platform": "win32",
      "arch": "x64",
      "nodeVersion": "20.x.x",
      "electronVersion": "x.x.x",
      "chromeVersion": "x.x.x",
      "v8Version": "x.x.x"
    },
    "connected": true,
    "window": "available"
  }
}
```

**响应字段说明**:

- `version.app`: 软件版本号
- `version.name`: 软件名称
- `environment.platform`: 操作系统平台 (win32/darwin/linux)
- `environment.arch`: 系统架构 (x64/arm64)
- `environment.nodeVersion`: Node.js 版本
- `environment.electronVersion`: Electron 版本
- `environment.chromeVersion`: Chrome 版本
- `environment.v8Version`: V8 引擎版本
- `connected`: 是否已连接
- `window`: 窗口状态

---

### 获取当前播放信息

**接口**: `GET /api/control/song-info`

**描述**: 获取当前播放的歌曲信息

> [!WARNING]
> 请勿频繁调用此接口（如每秒调用一次）来获取播放进度，这会导致软件性能异常。
> 如需实时获取播放进度和状态，请使用 WebSocket 连接并监听相关事件。

**响应示例**:

```json
{
  "code": 200,
  "message": "获取当前播放信息成功",
  "data": {
    "playStatus": "play",
    "playName": "歌曲名",
    "artistName": "歌手名",
    "albumName": "专辑名",
    "currentTime": 123.45,
    "volume": 1,
    "playRate": 1,
    "id": 123456,
    "name": "歌曲名",
    "artists": "歌手名",
    "album": "专辑名",
    "cover": "http://...",
    "duration": 300,
    "lrcData": [],
    "yrcData": []
  }
}
```

---

## 云音乐 API (Netease API)

**基础路径**: `/api/netease`

### 使用说明

云音乐 API 支持所有 NeteaseCloudMusicApi Enhanced 的接口。接口路径会自动转换为 kebab-case 格式。

**示例**:

- `GET /api/netease/login/cellphone?phone=xxx&password=xxx`
- `GET /api/netease/user/playlist?uid=xxx`
- `GET /api/netease/song/detail?ids=xxx`

更多接口请参考 [NeteaseCloudMusicApi Enhanced 文档](https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced)

---

## 解锁 API (Unblock API)

**基础路径**: `/api/unblock`

### 云音乐解锁

**接口**: `GET /api/unblock/netease?id={songId}`

**描述**: 获取网易云音乐解锁后的播放链接

**请求参数**:

- `id` (必需): 歌曲 ID

**响应示例**:

```json
{
  "code": 200,
  "url": "https://..."
}
```

---

### 酷我解锁

**接口**: `GET /api/unblock/kuwo?keyword={keyword}`

**描述**: 获取酷我音乐解锁后的播放链接

**请求参数**:

- `keyword` (必需): 搜索关键词（歌曲名-歌手名）
- `songName` (可选): 歌曲名称，用于匹配校验
- `artist` (可选): 歌手名称，用于匹配校验

**响应示例**:

```json
{
  "code": 200,
  "url": "https://..."
}
```

---

### 波点解锁

**接口**: `GET /api/unblock/bodian?keyword={keyword}`

**描述**: 获取波点音乐解锁后的播放链接

**请求参数**:

- `keyword` (必需): 搜索关键词（歌曲名-歌手名）
- `songName` (可选): 歌曲名称，用于匹配校验
- `artist` (可选): 歌手名称，用于匹配校验

**响应示例**:

```json
{
  "code": 200,
  "url": "https://..."
}
```

---

## 全部 API 列表

**接口**: `GET /api`

**描述**: 获取所有 API 模块列表

**响应示例**:

```json
{
  "name": "SPlayer API",
  "description": "SPlayer API service",
  "author": "@imsyy",
  "list": [
    {
      "name": "NeteaseCloudMusicApi",
      "url": "/api/netease"
    },
    {
      "name": "UnblockAPI",
      "url": "/api/unblock"
    }
  ]
}
```

---

## 错误处理

当接口发生错误时，会返回以下格式：

```json
{
  "code": 500,
  "message": "错误描述",
  "data": null
}
```

常见错误：

- `主窗口未找到`: 应用程序主窗口未初始化
- `播放失败`: 播放操作执行失败
- `获取状态失败`: 状态获取失败

---

### 使用示例

#### cURL 示例

```bash
# 播放
curl http://localhost:25884/api/control/play

# 暂停
curl http://localhost:25884/api/control/pause

# 下一曲
curl http://localhost:25884/api/control/next

# 获取状态
curl http://localhost:25884/api/control/status
```

#### JavaScript 示例

```javascript
// 播放
fetch("http://localhost:25884/api/control/play")
  .then((res) => res.json())
  .then((data) => console.log(data));

// 获取状态
fetch("http://localhost:25884/api/control/status")
  .then((res) => res.json())
  .then((data) => console.log(data));
```

#### Python 示例

```python
import requests

# 播放
response = requests.get('http://localhost:25884/api/control/play')
print(response.json())

# 获取状态
response = requests.get('http://localhost:25884/api/control/status')
print(response.json())
```

---

## 注意事项

1. 所有接口仅在应用程序运行时可用
2. HTTP API 默认端口为 `25884`，可在环境变量 `VITE_SERVER_PORT` 中配置
3. WebSocket API 默认端口为 `25885`，可在应用程序设置中修改
4. 解锁接口仅供学习使用，请勿用于商业用途
5. 网易云音乐 API 需要登录后才能使用部分功能
6. 接口响应时间取决于网络状况和服务器负载
7. WebSocket 连接支持心跳检测（PING/PONG），建议客户端定期发送心跳以保持连接

---

---

### Contributing

# 贡献指南

感谢您对 SPlayer 的关注！本指南将帮助您了解如何为项目做出贡献。

## 前置知识

参与本项目开发需要掌握以下技术：

### 前端技术栈

| 技术           | 说明                  | 学习资源                                         |
| -------------- | --------------------- | ------------------------------------------------ |
| **Vue 3**      | 前端框架              | [官方文档](https://cn.vuejs.org/)                |
| **TypeScript** | 类型安全的 JavaScript | [官方手册](https://www.typescriptlang.org/docs/) |
| **Pinia**      | 状态管理              | [官方文档](https://pinia.vuejs.org/zh/)          |
| **Vite**       | 构建工具              | [官方文档](https://cn.vitejs.dev/)               |
| **Naive UI**   | UI 组件库             | [官方文档](https://www.naiveui.com/zh-CN/)       |

### 桌面端技术栈

| 技术         | 说明                 | 学习资源                                               |
| ------------ | -------------------- | ------------------------------------------------------ |
| **Electron** | 桌面应用框架         | [官方文档](https://www.electronjs.org/zh/docs/latest/) |
| **N-API**    | Node.js 原生模块接口 | [官方文档](https://nodejs.org/api/n-api.html)          |

### 原生模块开发 (可选)

如需开发原生插件，还需掌握：

| 技术            | 说明                   | 学习资源                                                     |
| --------------- | ---------------------- | ------------------------------------------------------------ |
| **Rust**        | 系统编程语言           | [Rust 程序设计语言](https://kaisery.github.io/trpl-zh-cn/)   |
| **napi-rs**     | Rust 编写 Node.js 扩展 | [官方文档](https://napi.rs/)                                 |
| **Windows API** | Windows 系统编程       | [MSDN 文档](https://docs.microsoft.com/zh-cn/windows/win32/) |

## 开发环境搭建

请参考 [使用指南](/guide.html#🛠-本地开发环境) 完成以下准备工作：

1. 安装 Node.js (v18+)
2. 安装 pnpm
3. 安装 Git
4. 克隆仓库并安装依赖
5. 安装 Rust 和 C++ 构建工具 (可选，若只开发 Web 版则不需要。开发桌面版则必选)

## Git 工作流

### 1. Fork 仓库

访问 [SPlayer 仓库](https://github.com/SPlayer-Dev/SPlayer)，点击右上角 **Fork** 按钮复制仓库到你的账号。

### 2. 克隆你的 Fork

```bash
# 克隆你的 Fork（替换 YOUR_USERNAME）
git clone https://github.com/YOUR_USERNAME/SPlayer.git
cd SPlayer

# 添加上游仓库
git remote add upstream https://github.com/SPlayer-Dev/SPlayer.git

# 验证远程仓库配置
git remote -v
# 应显示:
# origin    https://github.com/YOUR_USERNAME/SPlayer.git (fetch)
# origin    https://github.com/YOUR_USERNAME/SPlayer.git (push)
# upstream  https://github.com/SPlayer-Dev/SPlayer.git (fetch)
# upstream  https://github.com/SPlayer-Dev/SPlayer.git (push)
```

### 3. 同步上游更新

在开始新功能开发前，确保本地代码是最新的：

```bash
# 获取上游最新代码
git fetch upstream

# 切换到主分支
git checkout main

# 合并上游更新
git merge upstream/main

# 推送到你的 Fork
git push origin main
```

### 4. 创建功能分支

**永远不要直接在 main 分支上开发！**

```bash
# 创建并切换到新分支
git checkout -b feature/your-feature-name

# 分支命名规范：
# feature/xxx    - 新功能
# fix/xxx        - Bug 修复
# docs/xxx       - 文档更新
# refactor/xxx   - 代码重构
# style/xxx      - 代码格式调整
```

### 5. 开发与提交

```bash
# 进行开发...

# 查看更改
git status
git diff

# 暂存更改
git add .

# 提交（遵循 Conventional Commits 规范）
git commit -m "feat: 添加新功能描述"
```

**提交信息规范：**

| 类型       | 说明                           |
| ---------- | ------------------------------ |
| `feat`     | 新功能                         |
| `fix`      | Bug 修复                       |
| `docs`     | 文档更新                       |
| `style`    | 代码格式（不影响功能）         |
| `refactor` | 重构（既不是新功能也不是修复） |
| `perf`     | 性能优化                       |
| `test`     | 测试相关                       |
| `chore`    | 构建/工具相关                  |

示例：

```bash
git commit -m "feat: 添加歌词翻译显示功能"
git commit -m "fix: 修复播放列表滚动位置问题"
git commit -m "docs: 更新原生插件文档"
```

### 6. 推送分支

```bash
# 推送到你的 Fork
git push origin feature/your-feature-name
```

### 7. 创建 Pull Request

1. 访问你的 Fork 仓库页面
2. 点击 **Compare & pull request** 按钮
3. 填写 PR 标题和描述：
   - 清晰描述更改内容
   - 关联相关 Issue（如有）：`Closes #123`（详细信息可查看 [GitHub 文档](https://docs.github.com/zh/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)）
   - 提供测试方法或截图
4. 点击 **Create pull request**

### 8. 代码审查

- AI 会对 PR 进行初步审核（AI 有时会挑刺，只改你觉得有必要的即可）
- 维护者可能会提出修改建议
- 根据反馈进行修改并推送更新，你也可以选择说服维护者为什么你是对的
- PR 合并后，可删除功能分支

```bash
# 删除本地分支
git branch -d feature/your-feature-name

# 删除远程分支
git push origin --delete feature/your-feature-name
```

## 代码规范

### 代码风格

项目使用 ESLint 和 Prettier 进行代码规范检查：

```bash
# 检查代码规范
pnpm lint

# 自动格式化
pnpm format
```

提交前请确保您的代码通过规范检查。

### 目录结构

```
SPlayer/
├── src/                    # 前端源码
│   ├── components/         # Vue 组件
│   ├── stores/             # Pinia 状态管理
│   ├── views/              # 页面视图
│   ├── utils/              # 工具函数
│   └── types/              # TypeScript 类型定义
├── electron/               # Electron 主进程
│   ├── main/               # 主进程代码
│   └── preload/            # 预加载脚本
├── native/                 # Node.js 原生插件
│   ├── external-media-integration/   # 媒体控件集成模块
├── docs/                   # 文档
└── scripts/                # 构建脚本
```

## 常见问题

### Q: 如何解决合并冲突？

```bash
# 获取上游最新代码
git fetch upstream

# 在你的功能分支上 rebase
git rebase upstream/main

# 解决冲突后继续
git add .
git rebase --continue

# 强制推送（注意：仅在你自己的分支上使用）
git push origin feature/your-feature-name --force
```

### Q: 如何撤销最近的提交？

```bash
# 撤销最近一次提交（保留更改）
git reset --soft HEAD~1

# 撤销最近一次提交（丢弃更改）
git reset --hard HEAD~1
```

### Q: 如何修改最近的提交信息？

```bash
git commit --amend -m "新的提交信息"
```

## 获取帮助

如果您在贡献过程中遇到问题：

1. 查阅项目 [Issues](https://github.com/SPlayer-Dev/SPlayer/issues)
2. 提交新 Issue 描述您的问题

感谢您的贡献！🎉

---

### Guide

# 使用指南

本指南介绍如何安装和使用 SPlayer，以及如何搭建本地开发环境。

## 📦 安装方式

### 客户端下载

前往 [GitHub Releases](https://github.com/SPlayer-Dev/SPlayer/releases) 下载对应系统的安装包：

| 系统    | 安装包格式                        |
| ------- | --------------------------------- |
| Windows | `.exe` (安装版) / `.zip` (便携版) |
| macOS   | `.dmg`                            |
| Linux   | `.AppImage` / `.deb` / ...        |

### Docker 部署 (仅 Web 版)

#### 本地构建

> 建议拉取最新代码后本地构建，在线镜像可能更新不及时

```bash
# 构建镜像
docker build -t splayer .

# 运行容器
docker run -d --name SPlayer -p 25884:25884 splayer

# 或使用 Docker Compose
docker-compose up -d
```

#### 在线拉取

```bash
# 从 Docker Hub 拉取
docker pull imsyy/splayer:latest

# 从 GitHub Container Registry 拉取
docker pull ghcr.io/imsyy/splayer:latest

# 运行容器
docker run -d --name SPlayer -p 25884:25884 imsyy/splayer:latest
```

启动成功后访问 `http://localhost:25884`

### Vercel 部署

1. 先部署 [NeteaseCloudMusicApi](https://github.com/neteasecloudmusicapienhanced/api-enhanced) 并获取 API 地址
2. Fork 本仓库到你的 GitHub 账号
3. 复制 `/.env.example` 为 `/.env` 并配置：
   ```
   VITE_API_URL = "https://your-api-url.com"
   ```
4. 在 Vercel 导入项目
5. 设置 `Output Directory` 为 `out/renderer`
6. 点击 Deploy 完成部署

## 🛠 本地开发环境

### 系统要求

- **Node.js**: v22.0.0 或更高版本 (推荐 v24 LTS)
- **pnpm**: v8.0.0 或更高版本
- **Git**: 最新版本
- **操作系统**: Windows 10+, macOS 10.15+, 或 Linux

### 软件安装

#### 1. 安装 Node.js

访问 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本，或使用版本管理工具：

```bash
# Windows (使用 winget)
winget install OpenJS.NodeJS.LTS

# macOS (使用 Homebrew)
brew install node@24

# Linux (使用 nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 24
```

验证安装：

```bash
node --version   # 应显示 v22.x.x 或更高
npm --version
```

#### 2. 安装 pnpm

```bash
npm install pnpm

# 验证安装
pnpm --version
```

#### 3. 安装 Git

- Windows: 下载 [Git for Windows](https://git-scm.com/download/win)
- macOS: `brew install git`
- Linux: `sudo apt install git`

#### 4. 安装 Rust (可选，仅开发原生模块时需要)

访问 [rustup.rs](https://rustup.rs/) 安装 Rust 工具链：

```bash
# Windows: 下载运行 rustup-init.exe
# macOS/Linux:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 验证安装
rustc --version
cargo --version
```

#### 5. 安装 C++ 构建工具 (Windows 原生模块开发)

下载 [Visual Studio Build Tools](https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/)，安装时勾选：

- **使用 C++ 的桌面开发**
- MSVC v14x C++ x64/x86 build tools
- Windows 10/11 SDK

### 项目初始化

```bash
# 1. 克隆仓库
git clone https://github.com/SPlayer-Dev/SPlayer.git
cd SPlayer

# 2. 安装依赖
pnpm install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置 API 地址

# 4. 构建原生模块
pnpm build:native

# 5. 启动开发服务器
pnpm dev
```

### 常用开发命令

| 命令                | 说明                                 |
| ------------------- | ------------------------------------ |
| `pnpm dev`          | 启动开发服务器 (Electron + Vite HMR) |
| `pnpm dev:web`      | 仅启动 Web 版开发服务器              |
| `pnpm build`        | 构建 Web 版生产包                    |
| `pnpm build:win`    | 构建 Windows 客户端                  |
| `pnpm build:mac`    | 构建 macOS 客户端                    |
| `pnpm build:linux`  | 构建 Linux 客户端                    |
| `pnpm build:native` | 构建原生插件                         |
| `pnpm lint`         | 运行代码检查                         |
| `pnpm format`       | 格式化代码                           |

### 构建客户端

```bash
# 构建当前系统架构
pnpm build:win

# 构建指定架构
pnpm build:win -- --x64 --arm64

# 构建产物位于 dist/ 目录
```

### IDE 配置推荐

#### VS Code 扩展

- **Vue - Official**: Vue 3 语言支持
- **ESLint**: 代码规范检查
- **Prettier**: 代码格式化
- **rust-analyzer**: Rust 语言支持 (开发原生模块时)

## ⚠️ 重要提示

::: warning 许可协议

### 严肃警告

- 请务必遵守 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 许可协议
- 在您的修改、演绎、分发或派生项目中，必须同样采用 **AGPL-3.0** 许可协议，**并在适当的位置包含本项目的许可和版权信息**
- 若您用于售卖或其他盈利用途，**必须提供本项目的源代码及原项目链接**。另外由于本项目涉及第三方，**售卖后可能遭受法律或诉讼风险**。如若发现违反许可协议，作者保留追究法律责任的权利
- 禁止在二开项目中修改程序原版权信息（ 您可以添加二开作者信息 ）
- 感谢您的尊重与理解

:::

## 📢 免责声明

本项目部分功能使用了网易云音乐的第三方 API 服务，**仅供个人学习研究使用，禁止用于商业及非法用途**

同时，本项目开发者承诺 **严格遵守相关法律法规和网易云音乐 API 使用协议，不会利用本项目进行任何违法活动。** 如因使用本项目而引起的任何纠纷或责任，均由使用者自行承担。**本项目开发者不承担任何因使用本项目而导致的任何直接或间接责任，并保留追究使用者违法行为的权利**

请使用者在使用本项目时遵守相关法律法规，**不要将本项目用于任何商业及非法用途。如有违反，一切后果由使用者自负。** 同时，使用者应该自行承担因使用本项目而带来的风险和责任。本项目开发者不对本项目所提供的服务和内容做出任何保证

感谢您的理解

## 📜 开源许可

- **本项目仅供个人学习研究使用，禁止用于商业及非法用途**
- 本项目基于 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 许可进行开源
  1. **修改和分发：** 任何对本项目的修改和分发都必须基于 AGPL-3.0 进行，源代码必须一并提供
  2. **派生作品：** 任何派生作品必须同样采用 AGPL-3.0，并在适当的地方注明原始项目的许可证
  3. **注明原作者：** 在任何修改、派生作品或其他分发中，必须在适当的位置明确注明原作者及其贡献
  4. **免责声明：** 根据 AGPL-3.0，本项目不提供任何明示或暗示的担保。请详细阅读 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 以了解完整的免责声明内容
  5. **社区参与：** 欢迎社区的参与和贡献，我们鼓励开发者一同改进和维护本项目
  6. **许可证链接：** 请阅读 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 了解更多详情

## 😘 鸣谢

特此感谢为本项目提供支持与灵感的项目

- [NeteaseCloudMusicApi](https://github.com/Binaryify/NeteaseCloudMusicApi)
- [YesPlayMusic](https://github.com/qier222/YesPlayMusic)
- [UnblockNeteaseMusic](https://github.com/UnblockNeteaseMusic/server)
- [applemusic-like-lyrics](https://github.com/Steve-xmh/applemusic-like-lyrics)
- [Vue-mmPlayer](https://github.com/maomao1996/Vue-mmPlayer)
- [refined-now-playing-netease](https://github.com/solstice23/refined-now-playing-netease)
- [material-color-utilities](https://github.com/material-foundation/material-color-utilities)

---

### Native

# 原生插件集成指南

SPlayer 使用 Rust 编写的原生插件来实现更深度的系统集成。你可以在 `native` 文件夹下找到所有的原生插件。

目前 SPlayer 只有一个原生插件 `external-media-integration` 用于与 Windows、Linux 和 MacOS 上的媒体控件，以及 Discord RPC 进行集成。

## 外部媒体集成模块 (external-media-integration)

> [!NOTE]
> 在项目中可能会以 EMI 的缩写形式出现

### 功能介绍

该插件主要提供两大核心功能：系统级媒体控件集成和 Discord Rich Presence (RPC) 支持。

1. **系统媒体控件集成**
   - **跨平台支持**：
     - **Windows**: 集成系统媒体传输控件 (SMTC)，支持任务栏缩略图按钮和锁屏界面控制。
     - **Linux**: 使用 `mpris_server` 提供的高层抽象 `Player` 结构体，支持 GNOME/KDE 等桌面环境的媒体控制。
     - **MacOS**: 集成控制中心 (Control Center) 和锁屏媒体信息 (MPNowPlayingInfoCenter)。
   - **双向同步**：
     - **状态同步**：将播放器的播放/暂停状态、歌曲元数据（标题、歌手、专辑、封面）、播放进度实时同步到系统。
     - **控制响应**：响应系统的媒体按键事件，包括播放、暂停、上一首、下一首、进度跳转 (Seek)、随机/循环模式切换。

2. **Discord Rich Presence**
   - **实时状态展示**：在 Discord 个人资料中展示当前正在播放的歌曲信息。
   - **详细信息**：显示歌曲名、歌手、专辑封面、播放进度条。
   - **交互按钮**：提供 "Listen" 按钮，点击可跳转到歌曲链接（目前支持网易云音乐链接）。
   - **自定义配置**：支持配置暂停时是否显示、显示模式（强调歌名或歌手）等。

### 技术实现

该模块基于 Rust 语言编写，使用 [`napi-rs`](https://github.com/napi-rs/napi-rs) 构建为 Node.js 原生扩展 (Addon)，兼顾高性能与开发效率。

1. **架构设计**
   - **抽象层**：定义了 `SystemMediaControls` Trait，统一了不同平台的接口调用方式，使得 Electron 前端无需关心底层平台差异。
   - **多线程模型**：
     - **系统媒体控件**：直接在 N-API 线程中运行（Windows 实现内部有异步处理）。
     - **Discord RPC**：为了防止网络 IO 或 IPC 阻塞 Node.js 事件循环，Discord RPC 逻辑运行在独立的 Rust 线程 (`std::thread`) 中。主线程通过 `std::sync::mpsc` 通道发送更新指令。

2. **平台实现细节**
   - **Windows**: 依赖 `windows` crate，调用 WinRT API (`Windows.Media.Playback`, `Windows.Media.Control`)。通过创建一个内存中的 `MediaPlayer` 实例来获取并操作 `SystemMediaTransportControls` 接口，从而更新时间轴和媒体属性。
   - **Linux**: 依赖 `mpris-server` crate，使用 `mpris_server` 提供的高层抽象 `Player` 结构体来管理 MPRIS 接口，自动处理 D-Bus 通信和属性暴露。
   - **MacOS**: 使用 `objc2` 系列 crate (bindgen) 调用 Objective-C 运行时，操作 `MPNowPlayingInfoCenter` (信息显示) 和 `MPRemoteCommandCenter` (事件接收)。

3. **特色处理**
   - **Discord 时间戳 Hack**: 为了在 Discord 上实现“暂停”状态的视觉效果（进度条静止），在暂停时会将开始和结束时间戳平移到未来（+1年）以冻结计时器。注意冻结时播放进度会变成0.
   - **封面处理**: 针对网易云音乐的封面 URL 进行了特殊处理（添加缩放参数），以适应不同平台的显示需求。

### 目录结构

```
native/external-media-integration/
├── src
│    ├── discord.rs         # Discord RPC 集成
│    ├── lib.rs             # 包含了暴露给 Node.js 的函数
│    ├── logger.rs          # 日志系统
│    ├── model.rs           # 前后端通信的结构体等
│    └── sys_media          # 不同平台的媒体控件实现
│        ├── linux.rs       # Linux MPRIS 集成
│        ├── macos.rs       # MacOS MPNowPlayingInfoCenter 和 MPRemoteCommandCenter 集成
│        ├── mod.rs         # 定义跨平台的 SystemMediaControls 接口
│        └── windows.rs     # Windows SMTC 相关集成
├── Cargo.toml              # Rust 依赖配置
└── index.d.ts              # 自动生成的 TypeScript 类型定义
```

### 构建命令

```bash
cd native/external-media-integration
pnpm build           # 构建 release 版本
pnpm build:debug     # 构建 debug 版本
```

### 日志路径

`%APPDATA%/splayer/logs/external-media-integration/`

## 构建

在项目根目录运行以下命令可一次性构建所有原生模块：

```bash
pnpm build:native
```

此命令会执行 `scripts/build-native.ts` 脚本，构建所有模块并放入各自的根目录下以便 Node.js 加载

## 环境要求

### Rust 工具链

```bash
# 安装 Rust (访问 https://rustup.rs/)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 验证安装
rustc --version
cargo --version
```

### Windows 构建工具

SMTC 模块依赖 Windows SDK，需要安装：

1. 下载 [Visual Studio Build Tools](https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/)
2. 安装时勾选 **"使用 C++ 的桌面开发"**
3. 确保包含以下组件：
   - MSVC v14x C++ x64/x86 build tools
   - Windows 10/11 SDK

## 常见问题

### 模块加载失败

```
Error: The specified module could not be found
```

**解决方案**：

- 运行 `pnpm build:native` 编译原生模块
- 确保系统架构 (x64/arm64) 与编译目标匹配

### 链接错误

```
LINK : fatal error LNK1181: cannot open input file
```

**解决方案**：

- 检查 Visual Studio Build Tools 是否正确安装
- 确保 Windows SDK 已安装

### 在 Windows 上不显示媒体控件

- 仅 Windows 10 1607 及以上版本支持
- 打开右下角的控制中心，检查是否显示媒体控件
- 检查日志是否有报错

### 在 Linux 上不显示媒体控件

- 使用 `playerctl` 工具检查是否能看到并控制应用
- 直接调用 `D-Bus` 接口检查是否能看到应用
- 检查日志是否有报错

### 在 MacOS 上不显示媒体控件

- 检查右上角的控制中心是否显示媒体控件
- 通过系统级日志检查 MacOS 是否正在尝试将命令发送给原生插件: `log stream --predicate 'subsystem == "com.apple.MediaPlayer" OR eventMessage contains "RemoteCommand"' --info`
- 检查日志是否有报错

### Discord RPC 不显示

- 确保 Discord 客户端在后台运行
- 检查设置 → 活动隐私 → 允许其他人看到你的活动
- 查看应用设置中 Discord 状态开关是否开启

---

### Socket

# WebSocket API

**基础路径**: `ws://localhost:25885` (默认端口，可在设置中修改)

## 概述

WebSocket API 提供了实时双向通信能力，可以控制播放器并接收播放状态更新。

## 连接

```javascript
const ws = new WebSocket("ws://localhost:25885");
```

## 消息格式

所有消息都遵循以下 JSON 格式：

```json
{
  "type": "消息类型",
  "data": {}
}
```

## 控制播放器

**消息类型**: `control`

**请求格式**:

```json
{
  "type": "control",
  "data": {
    "command": "toggle|play|pause|next|prev"
  }
}
```

**命令说明**:

- `toggle` - 播放/暂停切换
- `play` - 播放
- `pause` - 暂停
- `next` - 下一曲
- `prev` - 上一曲

**响应格式**:

成功响应：

```json
{
  "type": "control-response",
  "data": {
    "success": true,
    "command": "toggle",
    "message": "播放/暂停切换命令已执行"
  }
}
```

错误响应：

```json
{
  "type": "error",
  "data": {
    "message": "错误信息"
  }
}
```

**使用示例**:

```javascript
// 连接 WebSocket
const ws = new WebSocket("ws://localhost:25885");

// 连接成功后发送控制命令
ws.onopen = () => {
  // 播放/暂停切换
  ws.send(
    JSON.stringify({
      type: "control",
      data: {
        command: "toggle",
      },
    }),
  );

  // 下一曲
  ws.send(
    JSON.stringify({
      type: "control",
      data: {
        command: "next",
      },
    }),
  );
};

// 接收消息
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log("收到消息:", message);
};
```

## 获取信息

**消息类型**: `get-song-info`

**请求格式**:

```json
{
  "type": "get-song-info"
}
```

**响应格式**:

成功响应：

```json
{
  "type": "song-info",
  "data": {
    "playStatus": "play",
    "playName": "歌曲名",
    "artistName": "歌手名",
    "albumName": "专辑名",
    "currentTime": 123.45,
    "volume": 1,
    "playRate": 1,
    "id": 123456,
    "name": "歌曲名",
    "artists": "歌手名",
    "album": "专辑名",
    "cover": "http://...",
    "duration": 300,
    "lrcData": [],
    "yrcData": []
  }
}
```

错误响应：

```json
{
  "type": "error",
  "data": {
    "message": "获取当前播放信息失败"
  }
}
```

## 事件广播

当播放器状态发生变化时，服务器会向所有连接的客户端广播消息。

### 欢迎消息

连接成功后，服务器会自动发送欢迎消息：

```json
{
  "type": "welcome",
  "data": {
    "message": "欢迎连接到 SPlayer WebSocket 服务",
    "timestamp": 1234567890123
  }
}
```

### 播放状态更新

当播放/暂停状态改变时触发：

```json
{
  "type": "status-change",
  "data": {
    "status": true, // true: 播放中, false: 暂停
    "timestamp": 1234567890123
  }
}
```

### 歌曲信息更新

当切换歌曲或歌曲信息加载完成时触发：

```json
{
  "type": "song-change",
  "data": {
    "title": "歌曲名 - 歌手",
    "name": "歌曲名",
    "artist": "歌手",
    "album": "专辑名",
    "duration": 240000, // 总时长(ms)
    "timestamp": 1234567890123
  }
}
```

### 播放进度更新

播放过程中实时触发（约 500ms 一次）：

```json
{
  "type": "progress-change",
  "data": {
    "currentTime": 12000, // 当前播放时间(ms)
    "duration": 240000, // 总时长(ms)
    "timestamp": 1234567890123
  }
}
```

### 歌词更新

当歌词数据加载或改变时触发：

```json
{
  "type": "lyric-change",
  "data": {
    "lrcData": [], // 普通歌词数据
    "yrcData": [], // 逐字歌词数据
    "timestamp": 1234567890123
  }
}
```

## 心跳检测

客户端可以发送 `PING` 消息进行心跳检测，服务器会自动回复 `PONG`：

```javascript
// 发送心跳
ws.send("PING");

// 服务器自动回复 PONG
```

## 错误处理

当发生错误时，服务器会发送错误消息：

```json
{
  "type": "error",
  "data": {
    "message": "错误描述信息"
  }
}
```

常见错误：

- `应用程序未找到或已销毁` - 应用程序主窗口未初始化
- `缺少 command 参数` - 控制命令缺少必需参数
- `未知的控制命令` - 不支持的控制命令
- `消息格式错误` - 消息不是有效的 JSON 格式

---

### Streaming

# 流媒体服务支持

SPlayer 支持连接兼容 Subsonic 协议的流媒体服务器（如 Navidrome、Subsonic、Airsonic 等），为您提供云端音乐播放体验。

## 功能特性

- **多服务器支持**：您可以同时配置多个服务器，并随时切换。
- **自动连接**：应用启动时会自动连接到上次使用的服务器。
- **歌词支持**：支持解析 Subsonic 协议返回的歌词（包括 Plain 文本和 Structured 格式），并自动转换为 LRC 格式显示。
- **分类浏览**：支持按 **单曲**、**歌手**、**专辑**、**歌单** 分类浏览库中资源。
- **无缝集成**：流媒体音乐可以像本地音乐一样加入播放列表、收藏和播放。

## 配置指南

1. 进入 **设置** -> **流媒体服务**，或在侧边栏点击 **流媒体** 页面。
2. 点击 **添加服务器** 按钮。
3. 填写服务器信息：
   - **名称**：自定义服务器名称（如 "My Navidrome"）。
   - **地址**：服务器的 URL（包含端口，如 `https://music.example.com`）。
   - **用户名**：您的账号。
   - **密码**：您的密码（或 Token）。
   - **类型**：选择 Navidrome 或 Subsonic。
4. 点击 **确认** 保存并连接。

## 常见问题

### 连接失败？

- 请检查服务器地址是否正确，是否包含 `http://` 或 `https://`。
- 确认服务器支持 Subsonic API，并已开启相关权限。
- 若使用自签名证书，应用可能默认拦截，请尝试配置 HTTPS 忽略证书错误（目前需自行确保网络环境安全）。

### 歌词不显示？

- 请确认服务端已正确刮削并存储了歌词。
- 对于 Navidrome，支持读取内嵌歌词或 `.lrc` 文件。

### 播放列表同步

- 目前支持读取服务端的歌单，在客户端创建的歌单暂不直接同步回服务端（取决于后续更新）。

---

### README

> [!CAUTION]
>
> # 本项目进入维护模式
>
> 项目已进入维护模式，后续仅进行必要的维护与重大问题修复，不再主动开发新功能
>
> 新功能及后续版本请移步 [SPlayer-Next](https://github.com/SPlayer-Dev/SPlayer-Next)

<div align="center">
<img alt="logo" height="100" width="100" src="public/icons/favicon.png" />
<h2> SPlayer </h2>
<p> 一个简约的音乐播放器 </p>

[API Docs](https://splayer.imsyy.top/api.html) | [开发版](https://github.com/imsyy/SPlayer/actions) | [发行版](https://splayer.imsyy.top/download.html)

<br />

[](https://github.com/imsyy/SPlayer/stargazers)
[](https://github.com/imsyy/SPlayer/releases)
[](https://github.com/imsyy/SPlayer/actions/workflows/release.yml)
[](https://github.com/imsyy/SPlayer/blob/dev/LICENSE)
[](https://github.com/imsyy/SPlayer/issues)
[](https://deepwiki.com/imsyy/SPlayer)

</div>



## 说明



> [!IMPORTANT]
>
> ### 严肃警告
>
> - 请务必遵守 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 许可协议
> - 在您的修改、演绎、分发或派生项目中，必须同样采用 **AGPL-3.0** 许可协议，**并在适当的位置包含本项目的许可和版权信息**
> - 若您用于售卖或其他盈利用途，**必须提供本项目的源代码及原项目链接**。另外由于本项目涉及第三方，**售卖后可能遭受法律或诉讼风险**。如若发现违反许可协议，作者保留追究法律责任的权利
> - 禁止在二开项目中修改程序原版权信息（ 您可以添加二开作者信息 ）
> - 感谢您的尊重与理解

- 本项目采用 [Vue 3](https://cn.vuejs.org/) + [TypeScript](https://www.typescriptlang.org/) + [Naïve UI](https://www.naiveui.com/) + [Electron](https://www.electronjs.org/zh/docs/latest/) 开发
- Node.js 版本要求：>= 20，包管理器：pnpm >= 10
- 默认会构建原生模块，需准备 Rust 工具链；如仅需要网页端构建或暂时跳过，可设置环境变量 `SKIP_NATIVE_BUILD=true`
- 支持网页端与客户端，由于设备有限，目前仅保证 Windows 系统的适配，其他平台如遇问题可以提 Issue 或自行解决后选择提 PR




- 欢迎各位大佬 `Star` 😍

## 🧑‍💻 开发

### 快速开始

1. 安装依赖：`pnpm install`
2. 复制 `.env.example` 为 `.env` 并按需修改
3. 启动开发：`pnpm dev`
4. 构建：
   - `pnpm build`
   - `pnpm build:win`

### 跳过原生模块构建

默认会编译 `native/*` 下的原生模块（需要 Rust）。如果你的场景不需要原生能力，可设置 `SKIP_NATIVE_BUILD=true` 后再执行 `pnpm dev` / `pnpm build`。

## 👀 Demo

- 在线演示：[SPlayer](https://splayer.20100907.xyz)

  > 如打不开，说明已经失效请自行前往 [获取](#️-获取)

## 🎉 功能

- ✨ 支持扫码登录
- 📱 支持手机号登录
- ~~📅 自动进行每日签到及云贝签到~~
- 💻 支持桌面歌词
- 💻 支持切换为本地播放器，此模式将不会连接网络
- 🎨 封面主题色自适应，支持全站着色
- 🌚 Light / Dark / Auto 模式自动切换
- 📁 本地歌曲管理及分类（建议先使用 [音乐标签](https://www.cnblogs.com/vinlxc/p/11347744.html) 进行匹配后再使用）
- 📁 本地音乐标签编辑及封面修改
- ➕ 新建歌单及歌单编辑
- ❤️ 收藏 / 取消收藏歌单或歌手
- ☁️ 云盘音乐上传
- 📂 云盘内歌曲播放
- 🔄 云盘内歌曲纠正
- 🗑️ 云盘歌曲删除
- 🌐 支持 Subsonic / Navidrome 等流媒体服务（多服务器支持、自动连接）
- 📝 支持逐字歌词
- 🔄 歌词滚动以及歌词翻译
- 📹 MV 与视频播放
- 🎶 音乐频谱显示
- ⏭️ 音乐渐入渐出
- 🔄 支持 PWA
- 💬 支持评论区
- 🎵 支持 Last.fm Scrobble（播放记录上报）
- 📱 移动端基础适配

## 🖼️ 界面展示

> 开发中，仅供参考

<details>
<summary> 主页面 </summary>



</details>

<details>
<summary> 播放页面 </summary>



</details>

<details>
<summary> 发现页面 </summary>



</details>

<details>
<summary> 歌单页面 </summary>



</details>

<details>
<summary> 评论页面 </summary>



</details>

<details>
<summary> 本地音乐 </summary>



</details>

## 📦️ 获取

### 二进制安装方案

#### 稳定版

通常情况下，可以在 [Releases](https://github.com/imsyy/SPlayer/releases) 中获取稳定版

也可前往 [SPlayer 官网](https://splayer.imsyy.top/) 获取稳定版

#### 开发版

可以通过 GitHub Actions 工作流获取最新的开发版

[Dev Workflow](https://github.com/imsyy/SPlayer/actions/workflows/dev.yml)

### 自行部署方案

#### ⚙️ Docker 部署

> 安装及配置 `Docker` 将不在此处说明，请自行解决

##### 本地构建

> 请尽量拉取最新分支后使用本地构建方式，在线部署的仓库可能更新不及时

```bash
# 构建
docker build -t splayer .

# 运行
docker run -d --name SPlayer -p 25884:25884 splayer
# 或使用 Docker Compose
docker-compose up -d
```

Docker 镜像内包含网页端以及运行所需的服务，默认通过 `25884` 端口访问。

##### 在线部署

```bash
# 从 Docker Hub 拉取
docker pull imsyy/splayer:latest
# 从 GitHub ghcr 拉取
docker pull ghcr.io/imsyy/splayer:latest

# 运行
docker run -d --name SPlayer -p 25884:25884 imsyy/splayer:latest
```

以上步骤成功后，将会在本地 [localhost:25884](http://localhost:25884/) 启动，如需更换端口，请自行修改命令行中的第一个端口号

#### ⚙️ Vercel 部署

> 其他部署平台大致相同，在此不做说明

1. 本程序依赖 [NeteaseCloudMusicApi](https://github.com/neteasecloudmusicapienhanced/api-enhanced) 运行，请确保您已成功部署该项目或兼容的项目，并成功取得在线访问地址
2. 点击本仓库右上角的 `Fork`，复制本仓库到你的 `GitHub` 账号
3. 复制 `/.env.example` 文件并重命名为 `/.env`
4. 将 `.env` 文件中的 `VITE_API_URL` 改为第一步得到的 API 地址

   ```js
   VITE_API_URL = "https://example.com";
   ```

5. 将 `Build and Output Settings` 中的 `Output Directory` 改为 `out/renderer`

   

6. 点击 `Deploy`，即可成功部署

#### ⚙️ 服务器部署

1. 重复 `⚙️ Vercel 部署` 中的 1 - 4 步骤
2. 克隆仓库

   ```bash
   git clone https://github.com/imsyy/SPlayer.git
   ```

3. 安装依赖

   ```bash
   pnpm install
   ```

4. 编译打包

   ```bash
   pnpm build
   ```

5. 将站点运行目录设置为 `out/renderer` 目录

#### ⚙️ 本地部署

1. 本地部署需要用到 `Node.js`（>= 20），可前往 [Node.js 官网](https://nodejs.org/zh-cn/) 下载安装包，请下载最新稳定版
2. 安装 pnpm（>= 10）

   ```bash
   corepack enable
   # 或
   npm install pnpm -g
   ```

3. 克隆仓库并拉取至本地，此处不再赘述
4. 使用 `pnpm install` 安装项目依赖（若安装过程中遇到网络错误，请使用国内镜像源替代，此处不再赘述）
5. 复制 `.env.example` 文件并重命名为 `.env` 并修改配置（如需跳过原生模块构建，可设置 `SKIP_NATIVE_BUILD=true`）
6. 打包客户端，请依据你的系统类型来选择，打包成功后，会输出安装包或可执行文件在 `/dist` 目录中，可自行安装

   > 默认情况下，构建命令仅会构建当前系统架构的版本。如需构建特定架构（如 x64 + arm64），请在命令后追加参数，例如：`pnpm build:win -- --x64 --arm64`

   | 命令               | 系统类型 |
   | ------------------ | -------- |
   | `pnpm build:win`   | Windows  |
   | `pnpm build:linux` | Linux    |
   | `pnpm build:mac`   | macOS    |

## 😘 鸣谢

特此感谢为本项目提供支持与灵感的项目：

- [NeteaseCloudMusicApi](https://github.com/neteasecloudmusicapienhanced/api-enhanced)
- [YesPlayMusic](https://github.com/qier222/YesPlayMusic)
- [UnblockNeteaseMusic](https://github.com/UnblockNeteaseMusic/server)
- [applemusic-like-lyrics](https://github.com/Steve-xmh/applemusic-like-lyrics)
- [Vue-mmPlayer](https://github.com/maomao1996/Vue-mmPlayer)
- [refined-now-playing-netease](https://github.com/solstice23/refined-now-playing-netease)
- [material-color-utilities](https://github.com/material-foundation/material-color-utilities)

## 🗺️ 贡献者联盟

欢迎加入我们 🥰! 一起为 SPlayer 贡献一份力量。
感谢以下所有贡献者 💖

<a href="https://github.com/imsyy/SPlayer/graphs/contributors" target="_blank" rel="noopener">
  <img src="https://contrib.rocks/image?repo=imsyy/SPlayer&max=30&anon=1&v=1"
    alt="SPlayer 项目贡献者"
    width="650"
    loading="lazy"
  />
</a>

## 📢 免责声明

本项目部分功能使用了网易云音乐的第三方 API 服务，**仅供个人学习研究使用，禁止用于商业及非法用途**

同时，本项目开发者承诺 **严格遵守相关法律法规和网易云音乐 API 使用协议，不会利用本项目进行任何违法活动。** 如因使用本项目而引起的任何纠纷或责任，均由使用者自行承担。**本项目开发者不承担任何因使用本项目而导致的任何直接或间接责任，并保留追究使用者违法行为的权利**

请使用者在使用本项目时遵守相关法律法规，**不要将本项目用于任何商业及非法用途。如有违反，一切后果由使用者自负。** 同时，使用者应该自行承担因使用本项目而带来的风险和责任。本项目开发者不对本项目所提供的服务和内容做出任何保证

感谢您的理解

## 📜 开源许可

- **本项目仅供个人学习研究使用，禁止用于商业及非法用途**
- 本项目基于 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 许可进行开源
  1. **修改和分发：** 任何对本项目的修改和分发都必须基于 AGPL-3.0 进行，源代码必须一并提供
  2. **派生作品：** 任何派生作品必须同样采用 AGPL-3.0，并在适当的地方注明原始项目的许可证
  3. **注明原作者：** 在任何修改、派生作品或其他分发中，必须在适当的位置明确注明原作者及其贡献
  4. **免责声明：** 根据 AGPL-3.0，本项目不提供任何明示或暗示的担保。请详细阅读 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 以了解完整的免责声明内容
  5. **社区参与：** 欢迎社区的参与和贡献，我们鼓励开发者一同改进和维护本项目
  6. **许可证链接：** 请阅读 [GNU Affero General Public License (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) 了解更多详情

## ⭐ Star History

[](https://star-history.com/#imsyy/SPlayer&Date)

---

### .Vitepress/Config.Ts

import { defineConfig } from "vitepress";

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "SPlayer",
  description: "一个简约的音乐播放器",
  lang: "zh-CN",
  ignoreDeadLinks: true,
  head: [
    ["link", { rel: "icon", href: "/favicon.png" }],
    ["meta", { name: "author", content: "imsyy" }],
    ["meta", { name: "keywords", content: "SPlayer,音乐播放器,网易云音乐,Electron,Vue3" }],
  ],
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    logo: "/favicon.png",
    siteTitle: "SPlayer",
    nav: [
      { text: "首页", link: "/" },
      { text: "下载", link: "/download" },
      { text: "使用指南", link: "/guide" },
      { text: "API", link: "/api" },
      { text: "SPlayer-Next", link: "https://github.com/SPlayer-Dev/SPlayer-Next" },
      { text: "GitHub", link: "https://github.com/SPlayer-Dev/SPlayer" },
    ],

    sidebar: [
      {
        text: "指南",
        items: [
          { text: "下载", link: "/download" },
          { text: "使用指南", link: "/guide" },
          { text: "流媒体服务", link: "/streaming" },
        ],
      },
      {
        text: "API",
        items: [
          { text: "API 接口文档", link: "/api" },
          { text: "WebSocket API", link: "/socket" },
        ],
      },
      {
        text: "开发指南",
        items: [
          { text: "原生插件", link: "/native" },
          { text: "贡献指南", link: "/contributing" },
        ],
      },
      {
        text: "故障排查",
        items: [
          { text: "调试模式和错误排查", link: "/troubleshooting/debug" },
          { text: "macOS 常见问题", link: "/troubleshooting/macos" },
          { text: "Mac 应用显示已损坏", link: "/troubleshooting/macos-damaged" },
          { text: "macOS ARM 设备 API 启动失败", link: "/troubleshooting/macos-arm-api" },
          { text: "Windows 7 系统兼容性问题", link: "/troubleshooting/windows7" },
          { text: "Ubuntu 系统沙箱启动失败", link: "/troubleshooting/ubuntu-sandbox" },
        ],
      },
    ],

    outline: {
      level: [2, 3],
      label: "文章目录",
    },

    socialLinks: [{ icon: "github", link: "https://github.com/SPlayer-Dev/SPlayer" }],

    footer: {
      message: "基于 AGPL-3.0 许可发布",
      copyright: "Copyright © 2025-present imsyy",
    },

    editLink: {
      pattern: "https://github.com/SPlayer-Dev/SPlayer/edit/dev/docs/:path",
      text: "查看或编辑此页",
    },

    lastUpdated: {
      text: "最后更新于",
      formatOptions: {
        dateStyle: "short",
        timeStyle: "medium",
      },
    },
  },
});

---