hoowhoami/EchoMusic

EchoMusic —— 一个专为桌面端打造的简约、精致、功能强大的第三方音乐播放器。

• 极致美学：精心适配桌面端布局，支持深浅色模式与主题色自定义，完美兼顾信息密度、个性表达与沉浸式体验。
• 数据路径透明：核心音乐请求由本地服务直接访问对应平台；项目不提供音频中转或云端账号托管。第三方插件具备独立网络能力，安装前请确认来源可信。
• 音乐推荐：支持歌曲、歌单、歌手、专辑、排行榜等内容推荐。
• 多维探索：支持歌曲、歌手、专辑、歌单、歌词、MV 全方位搜索，快速发现心仪旋律。
• 外部歌单导入：支持网易云、QQ 音乐、酷我、酷狗、汽水、Spotify、Apple Music 导入。
• 进阶播放：支持播放队列管理、播放模式切换、音量调节、进度拖动、倍速播放、淡入淡出切歌等核心播放能力。
• 私人 FM：智能推荐个性化电台，发现更多好音乐。
• 音乐云盘：支持本地音频和跨平台文件导入，快速将专属音乐同步至云端存储。
• 听歌识曲：支持麦克风和系统音频捕获，快速识别正在播放的歌曲。
• 歌曲详情：支持查看歌曲档案及播放详情。
• 分享功能：支持将你喜欢的歌曲、歌单、专辑、歌手、插件一键分享给好友或社交平台。
• 歌曲评论：支持查看歌曲评论与评论楼层跳转。
• 歌词显示：支持 LRC/YRC 逐字歌词解析、歌词选择、歌词翻译、正则过滤、滚动同步、全屏歌词、写真模式、桌面歌词。
• 音频增强：内置跨平台音效引擎，支持 10 段均衡器（按完整频响自动前级补偿）、LUFS 响度标准化和 WAV/IRS 空间音效；也可导入兼容音效引擎，扩展更多预设、可调参数与组合音效。
• 实时频谱分析：直接从播放引擎提取音频数据，使用 FFT 进行实时频谱分析，为插件提供低延迟、高精度的频谱帧。
• 系统媒体控制：原生集成 macOS MPNowPlayingInfoCenter、Windows SMTC、Linux MPRIS，支持系统媒体按键和进度同步。
• 网络投放：支持发现并投放到 DLNA / AirPlay 设备，保留本机播放队列与投放状态。
• 系统集成：支持窗口控制、系统托盘、托盘快捷控制、全局快捷键、开机自启动、启动时最小化和 mini 模式。
• 音频设备：支持切换音频输出设备、独占模式输出。
• 插件扩展：支持在线插件源浏览安装与本地插件加载，自定义页面、侧边栏入口、设置项、播放器按钮、歌曲右键菜单与播放事件监听。
• 持久化能力：支持设置、播放历史、收藏、播放状态等本地持久化。
• 跨平台支持：完整适配 macOS、Windows 与 Linux 系统。
• 应用更新：内置版本检测与更新日志；支持自动更新的平台可在应用内下载安装，macOS 当前提供 DMG 手动更新入口。
• 持续集成：完善的 GitHub Actions 配置，支持多平台自动构建与 Release 发布。

• Desktop Shell: Electron 43.7
• Frontend: Vue 3.5 + TypeScript 5.9
• Build Tool: Vite 8
• State Management: Pinia + 原生 SQLite 持久化
• UI Primitives: Reka UI
• CSS: Tailwind CSS v4.3
• Routing: Vue Router
• Package Manager: pnpm
• Backend Service: Node.js（内置本地服务，进程内直接调用）
• Audio Engine: FFmpeg 解码 + SoundTouch 变速处理 + 原生音频输出（通过 Rust NAPI addon 进程内嵌入）
• Native Addons: napi-rs（Rust 编写的原生扩展）

• 首页
• 播放页

• Node.js 22.12+
• pnpm 9+
• Rust stable（项目中的音频模块声明最低 Rust 1.87，建议使用当前 stable）
• C/C++ 编译工具链及 LLVM/libclang（原生依赖与 bindgen 生成绑定需要）

安装 Xcode Command Line Tools 和 LLVM（以下依赖安装命令使用 Homebrew）：

xcode-select --install
brew install llvm pkg-config
export LIBCLANG_PATH="$(brew --prefix llvm)/lib"

已安装 Command Line Tools 时跳过第一条命令。在设置了 LIBCLANG_PATH 的同一终端中执行后续构建。

安装 Visual Studio Build Tools 的“使用 C++ 的桌面开发”工作负载及 Windows SDK，使用 MSVC Rust 工具链；编译 ARM64 时还需安装对应的 ARM64 C++ 工具。LLVM/libclang 可通过以下 PowerShell 命令安装、配置：

winget install LLVM.LLVM
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"

LIBCLANG_PATH 必须指向包含 libclang.dll 的目录。以上设置立即作用于当前终端；如需持久化，可再执行 setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"，新终端才会读取该持久化设置。也可使用 Visual Studio 自带 LLVM 的相应目录。

以 Debian / Ubuntu 为例，安装编译工具、libclang 和音频后端开发库；后半部分为运行 Electron 所需的桌面依赖：

sudo apt-get update
sudo apt-get install -y build-essential pkg-config clang libclang-dev \
  libasound2-dev libpulse-dev libpipewire-0.3-dev \
  libgtk-3-dev libnotify-dev libnss3 libxss1 libxtst6 xdg-utils

其他发行版安装对应软件包。播放引擎的 Linux 后端同时启用 ALSA、PulseAudio 和 PipeWire，不能只安装其中一个后端的开发库。

1. 克隆仓库

   git clone https://github.com/hoowhoami/EchoMusic.git
   cd EchoMusic
   git submodule update --init --recursive

2. 安装依赖

   pnpm install

   server 子模块已作为 pnpm workspace 成员管理，上述命令会自动一并安装其运行依赖，无需再单独进入 server 目录执行 npm install。

   在Linux下，可能会出现如下报错:

   Error: ENOENT: no such file or directory, open '/home/xxx/Projects/Work/EchoMusic/node_modules/electron/path.txt'

   需手动下载并解压Electron到对应目录：

   cd node_modules/.pnpm/electron@43.7.2/node_modules/electron/
   mkdir -p dist
   curl -L -o /tmp/electron.zip "https://npmmirror.com/mirrors/electron/v43.7.2/electron-v43.7.2-linux-x64.zip"
   unzip -o /tmp/electron.zip -d dist/
   printf '%s' './electron' > path.txt

3. 编译全部 Native 模块

   *.node 产物不随源码提交。首次开发、修改 Rust 代码或切换系统/CPU 架构后，都需要构建对应模块。根目录的 pnpm install 只覆盖根项目和 server workspace，pnpm dev / pnpm build 不会自动编译这些 Native 模块。

   模块目录	用途	构建平台
   native/echo-audio-player	播放、解码及音效处理	macOS / Windows / Linux
   native/echo-audio-capture	系统音频和麦克风采集	macOS / Windows / Linux
   native/echo-media-controls	系统媒体控制	macOS / Windows / Linux
   native/echo-sqlite-store	SQLite 持久化存储	macOS / Windows / Linux
   native/echo-opencc	歌词简繁转换	macOS / Windows / Linux
   native/echo-upnp	DLNA / UPnP 设备控制	macOS / Windows / Linux
   native/echo-airplay	AirPlay 设备发现与音频发送	macOS / Windows / Linux
   native/echo-platform-adaptor	系统窗口、任务栏等平台适配	macOS / Windows；Linux 无需构建

   以下命令均从仓库根目录执行，逐个安装模块的构建依赖并运行其 build 脚本（napi build --release --no-const-enum），遇到错误即停止。

   macOS / Linux（Bash）：

   bash <<'BASH'
   set -e
   addons=(echo-audio-player echo-audio-capture echo-media-controls echo-sqlite-store echo-opencc echo-upnp echo-airplay)
   if [[ "$(uname -s)" == "Darwin" ]]; then
     addons+=(echo-platform-adaptor)
   fi
   for addon in "${addons[@]}"; do
     (
       cd "native/$addon"
       npm install
       npm run build
     )
   done
   BASH

   Windows（PowerShell）：

   $addons = @("echo-audio-player", "echo-audio-capture", "echo-media-controls", "echo-sqlite-store", "echo-opencc", "echo-upnp", "echo-airplay", "echo-platform-adaptor")
   foreach ($addon in $addons) {
     Push-Location "native/$addon"
     try {
       npm install
       if ($LASTEXITCODE -ne 0) { throw "安装 $addon 构建依赖失败" }
       npm run build
       if ($LASTEXITCODE -ne 0) { throw "构建 $addon 失败" }
     } finally {
       Pop-Location
     }
   }

   每个模块会在自身目录生成同名 .node，例如 native/echo-audio-capture/echo-audio-capture.node。新模块不使用 index.node 作为产物名。仅执行 cargo build --release 不会将产物转换并放到应用期望的这个路径，应使用上述 napi-rs 脚本。

   检查产物（在仓库根目录执行，适用于三平台）：

   node -e 'const fs = require("node:fs"); const addons = ["echo-audio-player", "echo-audio-capture", "echo-media-controls", "echo-sqlite-store", "echo-opencc", "echo-upnp", "echo-airplay"]; if (process.platform === "darwin" || process.platform === "win32") addons.push("echo-platform-adaptor"); for (const name of addons) { const file = "native/" + name + "/" + name + ".node"; if (!fs.existsSync(file)) throw new Error("缺少产物: " + file); console.log(file); } console.log("当前 Node 平台/架构:", process.platform, process.arch);'

   此检查只确认文件存在。所有 .node 的平台和架构还必须与运行的 Electron 或打包目标一致：x64 与 arm64 产物不能混用。通常在目标平台、目标架构的环境中构建；交叉编译时，需先准备目标工具链、SDK 和 rustup target add <target>，再在每个模块目录运行 npx napi build --release --no-const-enum --target <target>，打包时选择相同架构。可参考 CI 构建矩阵。

   常见问题：

   • Cannot find module .../echo-*.node：检查对应模块是否构建成功、产物是否位于上述路径。
   • Unable to find libclang：检查 LLVM/libclang 安装与 LIBCLANG_PATH；它应指向库所在目录，而不是可执行文件。
   • Linux 报 ALSA / PulseAudio / PipeWire 的 pkg-config 错误：补齐上面的开发库，并确认 pkg-config 能找到目标架构的库。
   • FFmpeg 提示 Falling back to attempting to link the system's FFmpeg：检查 native/echo-audio-player/vendor/ffmpeg-audio/crates/ffmpeg_audio_sys/vendor/ 中的 ffmpeg_slim.zip 和 configs.zip 是否完整。默认构建不需要设置 FFMPEG_MODE=system；使用系统 FFmpeg 会引入额外的开发库及运行时动态库依赖。
   • 重编译后完全退出并重新启动 EchoMusic，已加载的 Native 模块不会随前端热更新重新加载。

4. 启动本地开发服务器

   pnpm dev

开发模式下会由 Electron 主进程自动拉起本地服务端。

需要观察 Electron 主进程、Renderer、GPU 等进程的内存变化时，可以开启启动阶段内存诊断日志：

ECHOMUSIC_MEMORY_DIAGNOSTICS=1 pnpm dev

日志会写入 Electron 日志文件，例如 macOS 下为：

~/Library/Logs/EchoMusic/echo-music-YYYY-MM-DD.log

EchoMusic 无需导入外部引擎即可使用内置音效能力。兼容的 DSP Provider 可以在“设置 → 音效管理”中导入、启用和切换，为播放器增加独立预设、参数设置及组合音效支持。播放器根据 Provider 声明的能力生成界面和应用音效，不依赖某个特定引擎的实现。

• DSP Provider 架构与接入协议
• 预设、参数与设置界面协议

EchoMusic 支持在线插件源和本地插件，可以扩展页面、音源、歌词、播放器交互、后台任务、独立浮窗与本地服务。插件运行在受信任的本地扩展环境中，并非浏览器扩展沙盒；请只安装来源可信的插件。

• 插件系统说明
• 完整插件开发指南
• 官方插件源与示例

项目使用 GitHub Actions 进行自动化构建。每当推送 v* 格式的 Tag 时，会自动触发多平台构建并将二进制包上传至 Releases。

手动编译：

先完成“快速开始”中的依赖安装及全部 Native 模块构建，确认 .node 与打包架构一致，再在根目录执行：

pnpm build

pnpm build 执行类型检查、Vite 构建和 electron-builder 打包；npmRebuild 已关闭，打包过程只复制现有 Native 产物，不会替你补编译。Windows / macOS 需包含全部 8 个模块，Linux 需包含除 echo-platform-adaptor 外的 7 个模块。

除了推送 v* Tag 时运行的完整桌面发布流程，Actions 还提供独立的 Build Native Addons 手动 workflow。进入 GitHub Actions 后点击 Run workflow，可以分别勾选 macOS arm64/x64、Linux arm64/x64、Windows arm64/x64；默认全部勾选。选中的目标会在独立矩阵任务中并行编译，未选中的目标不会启动。

该流程只上传 GitHub Actions 的 CI artifact，不创建或发布 GitHub Release，也不是完整桌面安装包。每个目标生成一个独立 artifact，例如：

• EchoMusic-native-macos-arm64
• EchoMusic-native-macos-x64
• EchoMusic-native-linux-arm64
• EchoMusic-native-linux-x64
• EchoMusic-native-windows-arm64
• EchoMusic-native-windows-x64

artifact 内的目录根为 native，模块路径为 native/<模块文件夹>/<模块名>.node，例如 native/echo-audio-player/echo-audio-player.node。GitHub Actions 会自动将 artifact 打包；下载后解压到仓库根目录即可恢复本地 pnpm build 或 electron-builder 所需的目录布局。Linux 包含七个通用模块；macOS 和 Windows 额外包含 echo-platform-adaptor。x64 与 arm64 的 .node 产物不能混用。

该 workflow 与主桌面发布流程复用 pnpm 依赖缓存和 Rust 缓存，但每个平台在独立 runner 中编译并打包，避免不同架构覆盖同名 .node 文件。

• macOS：dmg、zip
• Windows：exe (nsis，x64/arm64)
• Linux：deb、rpm、AppImage、tar.gz

当前发行版使用 ad-hoc 签名，不支持 Squirrel.Mac 自动安装更新。应用内检查更新后，请下载对应架构的 DMG（Apple Silicon 选择 arm64，Intel 选择 x64），退出 EchoMusic，再将新版本拖入「应用程序」替换旧版本。

xattr -cr /Applications/EchoMusic.app && codesign --force --deep --sign - /Applications/EchoMusic.app

• Telegram
• QQ1群: 1036693403
• QQ2群: 491694809

感谢以下开源项目及其贡献者提供的支持：

• KuGouMusicApi - 酷狗音乐 NodeJS 版 API
• AMLL（Apple Music-like Lyrics） - 歌词渲染组件
• ffmpeg-audio - 基于 FFmpeg 的 Rust 音频解码库
• soundtouch-rs - Rust 音频变速处理库

本项目的设计与交互受到以下开源项目的启发：

• SPlayer - 一个简约的音乐播放器
• SPlayer-Next - 一个简约的音乐播放器
• MoeKoeMusic - 一款开源简洁高颜值的酷狗第三方客户端

本项目是基于公开 API 接口开发的第三方音乐客户端，仅供个人学习和技术研究使用。

• 数据来源：所有音乐数据通过公开接口获取，本项目不存储、不传播任何音频文件
• 版权声明：音乐内容版权归原平台及版权方所有，请尊重知识产权，支持正版音乐
• 使用限制：禁止将本项目用于任何商业用途或违法行为
• 责任声明：因使用本项目产生的任何法律纠纷或损失，均由使用者自行承担
• 争议处理：如版权方认为本项目侵犯其权益，请通过 Issues 联系，我们将积极配合处理

本项目不接受任何商业合作、广告或捐赠。

基于 GNU General Public License v3.0 协议发布，完整协议文本见 LICENSE。

第三方依赖与授权说明见 THIRD_PARTY_NOTICES.md。