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

• 极致美学：精心适配桌面端布局，支持深浅色模式，兼顾信息密度与沉浸式体验。
• 数据安全：官方服务器直连，数据不经过第三方服务器，保证用户数据安全。
• 音乐推荐：支持歌曲、歌单、歌手、专辑、排行榜等内容推荐。
• 多维探索：支持歌曲、歌手、专辑、歌单、歌词、MV 全方位搜索，快速发现心仪旋律。
• 外部歌单导入：支持网易云、QQ 音乐、酷我、酷狗、汽水、Spotify、Apple Music 及文本歌单导入。
• 进阶播放：支持播放队列管理、播放模式切换、音量调节、进度拖动、倍速播放、淡入淡出切歌等核心播放能力。
• 私人 FM：智能推荐个性化电台，发现更多好音乐。
• 听歌识曲：支持麦克风和系统音频捕获，快速识别正在播放的歌曲。
• 歌曲详情：支持查看歌曲档案及播放详情。
• 歌曲评论：支持查看歌曲评论与评论楼层跳转。
• 歌词显示：支持 LRC/YRC 逐字歌词解析、歌词选择、正则过滤、滚动同步、全屏歌词、写真模式、桌面歌词。
• 音频增强：支持 10 段 EQ 均衡器、音量均衡（基于 LUFS 响度标准化）、空间音效（IR 文件导入/切换）与多种音效模式。
• 系统媒体控制：原生集成 macOS MPNowPlayingInfoCenter、Windows SMTC、Linux MPRIS，支持系统媒体按键和进度同步。
• 系统集成：支持窗口控制、系统托盘、托盘快捷控制、全局快捷键、开机自启动、启动时最小化和 mini 模式。
• 音频设备：支持切换音频输出设备、独占模式输出。
• 持久化能力：支持设置、播放历史、收藏、播放状态等本地持久化。
• 跨平台支持：完整适配 macOS、Windows 与 Linux 系统。
• 自动更新：内置应用更新检测与下载，支持静默更新。
• 持续集成：完善的 GitHub Actions 配置，支持多平台自动构建与 Release 发布。

• 音质：Hi-Res、SQ(flac)、HQ(320)、标准(128)
• 音效：人声、伴奏、钢琴、骨笛、尤克里里、唢呐、DJ、蝰蛇母带、蝰蛇全景声、蝰蛇超清、空间音效（自定义 IR）

• Desktop Shell: Electron 42.3
• Frontend: Vue 3.5 + TypeScript 5.9
• Build Tool: Vite 8
• State Management: Pinia + pinia-plugin-persistedstate
• UI Primitives: Reka UI
• CSS: Tailwind CSS v4.3
• Routing: Vue Router
• Package Manager: pnpm
• Backend Service: Node.js（内置本地服务，进程内直接调用）
• Audio Engine: libmpv（通过 Rust NAPI addon 进程内嵌入，零延迟直接函数调用）
• Native Addons: napi-rs（Rust 编写的原生扩展）
  • echo-mpv-player：libmpv 播放引擎封装，支持淡入淡出、EQ、音量均衡、空间音效
  • echo-media-controls：系统媒体控制集成（macOS/Windows/Linux 原生 API）
  • echo-storage：SQLite 本地持久化存储，负责设置、播放队列与状态快照

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

• Node.js 18+
• pnpm 9+
• Rust（编译原生模块需要）
• mpv / libmpv（播放引擎，macOS: brew install mpv，Linux: apt install libmpv-dev，Windows: 自行下载）

1. 克隆仓库

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

2. 安装依赖

   pnpm install
   cd server && npm install && cd ..

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

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

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

   cd node_modules/.pnpm/electron@42.3.1/node_modules/electron/
   mkdir -p dist
   curl -L -o /tmp/electron.zip "https://npmmirror.com/mirrors/electron/v42.3.1/electron-v42.3.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-mpv-player/echo-mpv-player.node'
   [error] [MpvController] Failed to load echo-mpv-player addon

   需要手动编译rust原生模块，因为*.node文件在.gitignore中被排除：

     cd native/echo-mpv-player
     cargo build --release
     cp target/release/libecho_mpv_player.so echo-mpv-player.node
   
     cd ../echo-media-controls
     cargo build --release
     cp target/release/libecho_media_controls.so echo-media-controls.node
   
     cd ../echo-storage
     cargo build --release
     cp target/release/libecho_storage.so echo-storage.node
   
     cd ../..

4. 启动本地开发服务器

   pnpm dev

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

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

手动编译：

pnpm build

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

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

• Telegram
• QQ群: 1036693403

本项目受到以下优秀开源项目的启发：

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

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

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

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

基于 MIT License 协议发布。

本项目使用 mpv 作为音频播放引擎（LGPL-2.1+ / GPL-2.0+），通过动态链接方式加载。