给酷狗概念版做一个桌面播放器（EchoMusic）

第三方音乐客户端在桌面端已经有不少选择，网易云、QQ 音乐、YouTube Music 都有各自的壳，酷狗概念版一直没有对应的桌面客户端。EchoMusic 就是从零搭出来的那个：Electron 做外壳，Vue 3 做界面，播放引擎用 Rust 写成原生模块嵌进进程里。

EchoMusic 是一个用 TypeScript 与 Vue 3 编写的第三方酷狗概念版桌面音乐播放器，支持 macOS、Windows 与 Linux，可搜索播放歌曲、导入跨平台歌单并管理云盘音乐。

仓库在 GitHub 上有 3382 个 Star、248 个 Fork，开放 Issue 只有 1 个，主要语言 TypeScript，采用 GPL-3.0 许可证。代码构成里 TypeScript 占 36.7%、Vue 26.9%、Rust 17.6%，Rust 那部分对应的是原生音频模块。

第一次用它需要知道的事

• 源码构建的版本门槛是 Node.js 22.12+、pnpm 9+、Rust stable。仓库说明音频模块声明的最低 Rust 版本是 1.87，建议直接用当前 stable。
• 原生模块需要 C/C++ 编译工具链和 LLVM/libclang，bindgen 生成绑定时会用到。macOS 走 brew install llvm pkg-config，Windows 走 winget install LLVM.LLVM，Linux 需要装 clang libclang-dev。
• .node 产物不随源码提交，pnpm dev 和 pnpm build 都不会自动编译它们。首次开发、改过 Rust 代码、或者换了系统与 CPU 架构，都要手动重新编译一遍。
• Linux 上要么用 deb 包，要么自己装 libmpv。AppImage 和 tar.gz 版本需要 sudo apt install libmpv2 或 sudo pacman -S mpv。播放引擎的 Linux 后端同时启用 ALSA、PulseAudio 和 PipeWire，三个后端的开发库都要装齐。
• 仓库里没有说明运行阶段需要管理员权限，但 Linux 下安装系统依赖这一步要用 sudo。

最短上手路径

1. 克隆仓库并拉取子模块：git clone https://github.com/hoowhoami/EchoMusic.git，随后 cd EchoMusic 与 git submodule update --init --recursive。
2. 在仓库根目录执行 pnpm install。server 子模块已经作为 pnpm workspace 成员管理，这一步会一并装好它的运行依赖。
3. 逐个编译原生模块：进入 native/<模块名>，依次执行 npm install 和 npm run build。需要用到的模块是 echo-audio-player、echo-audio-capture、echo-media-controls、echo-sqlite-store、echo-opencc、echo-upnp、echo-airplay，macOS 和 Windows 还要加上 echo-platform-adaptor。
4. 在仓库根目录跑 README 给出的 node -e 检查脚本，确认每个 .node 产物都存在；它只校验文件在不在，不校验架构是否匹配。
5. 执行 pnpm dev 启动。首页、搜索、播放可以直接用，收藏、歌单、评论这类依赖账号数据的能力要先登录。

它实际上能做哪些事

播放与音频

• 播放控制覆盖队列管理、播放模式切换、音量调节、进度拖动、倍速播放和淡入淡出切歌，另外支持切换音频输出设备和独占模式输出。倍速处理走的是 SoundTouch，解码走 FFmpeg。
• 内置跨平台音效引擎，提供 10 段均衡器（按完整频响自动做前级补偿）、LUFS 响度标准化，以及 WAV/IRS 两种空间音效。也能导入兼容这套引擎的第三方音效包来扩展预设和组合音效。
• 歌词支持 LRC 与 YRC 逐字解析、歌词选择、歌词翻译、正则过滤、滚动同步，另有全屏歌词、写真模式、桌面歌词和页面歌词换肤。简繁转换由 echo-opencc 原生模块承担。

内容与歌单

• 搜索覆盖歌曲、歌手、专辑、歌单、歌词和 MV；首页推荐包含歌曲、歌单、歌手、专辑与排行榜。私人 FM 支持切换推荐池、喜欢与不喜欢，并新增了电台模式。
• 外部歌单导入支持网易云、QQ 音乐、酷我、酷狗、汽水、Spotify 和 Apple Music 七个来源。
• 音乐云盘可以导入本地音频和跨平台文件，同步到云端存储后跨设备播放。听歌识曲提供麦克风采集与系统音频捕获两条路径。

扩展与系统集成

• 插件系统支持在线插件源浏览安装和本地加载，插件可以自定义页面、侧边栏入口、设置项、播放器按钮、歌曲右键菜单，并监听播放事件。对外还提供本地 WebSocket API、TCP API、服务请求拦截 API 和实时频谱帧。插件具备独立网络能力，安装前要确认来源可信。
• 系统媒体控制原生对接 macOS 的 MPNowPlayingInfoCenter、Windows 的 SMTC、Linux 的 MPRIS，系统媒体按键和进度同步都能用。系统集成还包括窗口控制、系统托盘、托盘快捷控制、全局快捷键、开机自启动、启动时最小化和 mini 模式。网络投放支持发现并投放到 DLNA / AirPlay 设备，并保留本机播放队列与投放状态。

参数速查

• LIBCLANG_PATH：指向 libclang 所在目录。macOS 上是 export LIBCLANG_PATH="$(brew --prefix llvm)/lib"，Windows 上是 C:\Program Files\LLVM\bin。设置只在当前终端生效；Windows 下想让新终端也读到，得再执行一次 setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"。
• npm run build：原生模块的构建脚本，实际执行的是 napi build --release --no-const-enum。产物名是 <模块名>.node，新模块不再使用 index.node。只跑 cargo build --release 不会把产物放到应用期望的路径上。
• --target <target>：交叉编译时用，在每个模块目录里执行 npx napi build --release --no-const-enum --target <target>，打包时选相同架构。x64 与 arm64 产物不能混用。
• pnpm dev / pnpm build：仓库根目录的开发与打包命令，两者都不会触发原生模块编译。

应用侧的设置项没有以配置文件形式暴露给用户，主题色、深浅色模式这些在界面里改，改完写进本地持久化层。

输出与结果位置

• 原生模块的构建产物落在各自目录下，形如 native/echo-audio-capture/echo-audio-capture.node，仓库根目录的检查脚本按这个路径逐个校验。
• 设置、播放历史、收藏和播放状态做本地持久化，存储层是 native/echo-sqlite-store。
• 插件的安装来源分在线插件源和本地文件两种，安装后在标题栏的「更多」里进入插件管理。
• 安装包分发形式包括 deb、AppImage、tar.gz 与 Windows-ARM 版本，打包输出目录仓库里没有说明。

实际使用中的坑

• 进入歌单或从其他页面返回歌单时比较卡，刚点播放、切上一首下一首时也卡，加载时间偏长。这条反馈有 18 条评论，当前状态是已解决。
• 歌单数量超过一般用户上限（1001）时收藏失败，但界面仍然提示成功，涉及的场景包括创建歌单、收藏歌单和收藏专辑。这条有 8 条评论，已解决。
• 播放云盘歌曲时歌词界面没有刷新，停留在上一首的歌词。这条有 6 条评论，已解决。
• Linux 用户用 AppImage 或 tar.gz 安装后播放异常，原因是系统缺少 libmpv，需要手动 sudo apt install libmpv2 或 sudo pacman -S mpv；deb 包会自动拉取这个依赖。这条有 7 条评论，已解决。

替代方案一览

如果听歌主力在网易云，或者想靠插件把多个音源聚在一起，EchoMusic 帮不上忙，它只对接酷狗概念版一个曲库，上面另外两个项目覆盖的是别的场景。EchoMusic 在构建上的门槛也更高：原生模块要一 module 一 module 地编译，Linux 下还得先装 libmpv。不想碰命令行的人，直接从 Release 页取安装包比从源码构建省事得多。

别踩的合规线

EchoMusic 是第三方客户端，访问的是酷狗概念版的服务，它不提供音频中转，也不托管云端账号，核心音乐请求由本地服务直接访问对应平台。账号的使用要遵守平台的服务条款，账号异常、登录态失效这类结果由平台侧决定，客户端改不了。

插件具备独立网络能力，可以拦截和改写服务请求，装来源不明的插件等于把账号和请求内容交给对方，安装前必须确认来源可信。

仓库和每个 Release 说明都反复声明：本软件完全免费且开源，请勿通过任何付费渠道下载，付费获取说明你被骗了。这一点在二手交易平台和网盘分享里尤其要注意。

什么时候值得用它

你在电脑上听酷狗概念版的曲库，并且希望这个客户端同时覆盖 macOS、Windows 和 Linux，Windows-ARM 设备也在支持范围内。这类用户是 EchoMusic 的目标人群。

你在意歌词和音效的定制空间——逐字歌词、翻译、正则过滤、桌面歌词、10 段均衡器、LUFS 响度标准化、WAV/IRS 空间音效，这些在官方客户端里找不到对应入口。

你手上有跨平台的歌单要合并，七个来源的导入能力可以省掉手工搬运的功夫；同时你愿意接受从源码构建的流程，Node.js 22.12+、pnpm 9+、Rust stable 和一套 LLVM 工具链都是前置条件。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.4 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。