EchoMusic

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

---

✨ 核心特性

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

🛠️ 技术栈

• Desktop Shell: Electron 43.4
• 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 编写的原生扩展）
  • echo-audio-player：播放引擎封装，使用 vendored ffmpeg-audio 与 soundtouch-rs，支持淡入淡出、音效引擎、音量均衡、倍速播放、输出设备切换、独占输出与实时频谱分析
  • echo-audio-capture：跨平台系统输出与麦克风输入采集，提供设备选择、连续缓冲、快照和可配置 PCM 格式转换能力，用于听歌识曲等功能
  • echo-media-controls：系统媒体控制集成（macOS/Windows/Linux 原生 API）
  • echo-sqlite-store：SQLite 本地持久化存储，负责设置、播放队列与状态快照

🖼️ 界面截图

• 首页
• 发现
• 私人FM
• 听歌识曲
• 歌词
• 歌曲详情
• 歌曲评论
• 播放列表
• 专辑
• 歌手
• 搜索
• 个人中心
• 设置

🚀 快速开始

前置要求

• Node.js 22.12+
• pnpm 9+
• Rust（编译原生模块需要）
• FFmpeg 开发库（编译播放引擎原生模块需要；运行时不依赖外部 ffmpeg 可执行文件）
• Windows 编译 echo-audio-player 时还需要 LLVM/libclang（bindgen 生成 FFmpeg 绑定需要）

Windows 上如遇到 Unable to find libclang，先安装 LLVM，并确保 LIBCLANG_PATH 指向包含 libclang.dll 的目录：

winget install LLVM.LLVM
setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"

重新打开终端后再执行原生模块构建命令。若使用 Visual Studio 自带的 LLVM，也可以把 LIBCLANG_PATH 设置为对应的 VC\Tools\Llvm\x64\bin 目录。

本地开发

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.4.1/node_modules/electron/
   mkdir -p dist
   curl -L -o /tmp/electron.zip "https://npmmirror.com/mirrors/electron/v43.4.1/electron-v43.4.1-linux-x64.zip"
   unzip -o /tmp/electron.zip -d dist/
   printf '%s' './electron' > path.txt

3. 编译 Rust 原生模块

   倘若出现如下报错:

   Error: Cannot find module '/home/myname/EchoMusic/native/echo-audio-player/echo-audio-player.node'
   [error] [PlayerController] Failed to load echo-audio-player addon

   需要手动编译 Rust 原生模块，因为 *.node 文件在 .gitignore 中被排除。推荐使用各 addon 自带的 napi-rs 构建脚本生成平台对应的 .node：

   cd native/echo-audio-player
   pnpm install --ignore-workspace
   pnpm exec napi build --release --no-const-enum
   
   cd ../echo-media-controls
   npm install
   npm run build
   
   cd ../echo-sqlite-store
   npm install
   npm run build
   
   cd ../..

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。

手动编译：

pnpm build

📦 打包产物

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

macOS

当前发行版使用 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
• SPlayer - 一个简约的音乐播放器
• ffmpeg-audio - 基于 FFmpeg 的 Rust 音频解码库
• soundtouch-rs - Rust 音频变速处理库
• MoeKoeMusic - 一款开源简洁高颜值的酷狗第三方客户端

📄 免责声明

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

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

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

⚖️ 开源协议

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

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