Home
Softono
EchoMusic

EchoMusic

Open source MIT Vue
Website GitHub
1.9K
Stars
117
Forks
4
Issues
5
Watchers
1 week
Last Commit
Mobile Development Music Streaming

About EchoMusic

🎉 一个简约的第三方酷狗概念版音乐播放器

Platforms

Web Self-hosted

Languages

Vue

Links

Website Source Code
h
Published by
hoowhoami
Visit View Profile

README.md

View on GitHub

EchoMusic

EchoMusic Logo

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

Electron Vue 3 TypeScript Rust Platform License

✨ 核心特性

  • 极致美学：精心适配桌面端布局，支持深浅色模式与主题色自定义，完美兼顾信息密度、个性表达与沉浸式体验。
  • 数据安全：官方服务器直连，数据不经过第三方服务器，保证用户数据安全。
  • 音乐推荐：支持歌曲、歌单、歌手、专辑、排行榜等内容推荐。
  • 多维探索：支持歌曲、歌手、专辑、歌单、歌词、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 发布。

音质音效

  • 音质：DSD臻品音质、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 本地持久化存储，负责设置、播放队列与状态快照
    • echo-spectrum-capture：系统音频捕获与频谱分析，为插件 ctx.audio.spectrum 提供处理后的频谱帧

🖼️ 界面截图

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

🚀 快速开始

前置要求

  • Node.js 18+
  • pnpm 9+
  • Rust（编译原生模块需要）
  • mpv / libmpv（播放引擎，macOS: brew install mpv，Linux: apt install libmpv-dev，Windows: 自行下载 libmpv-2.dll 到 build\mpv 目录）
  • Linux 构建系统音频捕获模块需要 ALSA 开发库（Debian/Ubuntu: sudo apt install libasound2-dev）

本地开发

  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/xxx/Projects/Work/EchoMusic/node_modules/electron/path.txt'

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

    cd node_modules/.pnpm/[email protected]/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 中被排除。推荐使用各 addon 自带的 napi-rs 构建脚本生成平台对应的 .node：

    cd native/echo-mpv-player
npm install
npm run build

cd ../echo-media-controls
npm install
npm run build

cd ../echo-storage
npm install
npm run build

cd ../echo-spectrum-capture
npm install
npm run build

cd ../..

    echo-spectrum-capture 负责系统音频频谱捕获：Windows 使用 WASAPI loopback，Linux 使用系统 monitor/loopback 输入，macOS 使用 ScreenCaptureKit。macOS 首次使用频谱可视化或 ctx.audio.spectrum 时，需要在“系统设置 -> 隐私与安全性 -> 屏幕与系统音频录制”中授权 EchoMusic；开发模式下也可能需要授权 Terminal、Electron 或当前启动进程。

  4. 启动本地开发服务器

    pnpm dev

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

插件系统

EchoMusic 支持在线插件源浏览安装与本地插件扩展。插件可以提供高自由度的扩展能力。

👉 插件开发文档

🏗️ 编译发布

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

手动编译：

pnpm build

📦 打包产物

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

macOS

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

交流群

💡 灵感来源

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

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

📄 免责声明

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

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

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

⚖️ 开源协议

基于 MIT License 协议发布。

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