ECHO

ECHO NEXT

面向本地曲库、HiFi 输出和长期维护的源码可见桌面音乐播放器

English README  |  官网  |  官方文档  |  Latest Release  |  爱发电  |  项目架构  |  QQ 群聊  |  Discord  |  快速开始  |  用户教程  |  插件教程  |  插件制作  |  开发者计划  |  Linux 构建指南  |  开发与构建

反馈问题请保持礼貌；提问前建议先查阅 官方文档、README 和相关教程。

[!TIP] Debug 小提示：遇到设备或播放异常，先到 设置 > 播放 打开 低负载播放模式；反馈问题时请到 设置 > 关于 > 打开控制台，复制报错或导出日志。若只有某一首歌异常，请先换其他歌曲确认，单曲问题通常更可能来自文件本身。第三方音频驱动/包装层导致的问题不作为有效 issue 受理。 更新优先级：音频稳定性 > HiFi > 杂项功能 > 流媒体。

项目定位

ECHO NEXT 是 ECHO 系列的下一代桌面音乐播放器工程。它不是旧版本的简单换皮，而是围绕本地曲库、播放稳定性、原生音频输出、歌词、MV、远程来源、插件和桌面集成重新拆分架构边界。

项目优先级很明确：本地播放可靠，音频链路稳定，大曲库不卡顿，用户数据安全，网络能力只作为补全和扩展，不把播放器变成依赖在线平台的壳。

如果你只是想快速使用或排查问题，优先看 ECHO NEXT 官方文档。线上文档会持续补充安装、播放、曲库、插件、音频输出、Linux 构建和常见问题，比单个 README 更适合做长期索引。

[!IMPORTANT] ECHO NEXT 的核心仍然是本地音乐播放器。反馈问题请尽量提供可复现步骤、系统环境、版本、截图、日志和你实际操作的路径。 任何绕过会员、版权、平台限制或违反 DMCA 的功能请求都不会被接受。 情绪化表达、无复现依据的指责、针对个人审美或使用偏好的争论，也不会作为有效 issue 处理。

项目架构

ECHO NEXT 不是纯网页播放器。React 只负责界面和交互呈现，真正的曲库、播放、系统集成和原生音频输出由桌面后端与原生模块分层完成。

所以 ECHO NEXT 的前端不是完整产品本身，而是桌面服务和原生播放能力的可视化控制面。完整架构说明见 docs/ECHO_NEXT_ARCHITECTURE.md。

当前技术栈

版本号以 package.json 和 package-lock.json 为准；如果 README、文档或发布说明与锁文件冲突，请优先相信锁文件并提交文档修正。

音频输出建议

ECHO NEXT 会持续改善原生音频输出的稳定性，但不鼓励迷信“接口名称”。真正决定声音表现的核心仍然是 DAC / 声卡 / 耳放 / 耳机等硬件本身，而不是播放器里是否显示 ASIO 或独占。

• ASIO：优先使用设备原厂 ASIO 驱动。ASIO4ALL、FlexASIO、Voicemeeter 等第三方 ASIO 包装层行为不可控，通常也不会让不支持原生 ASIO 的设备获得真正音质提升；仅由此类包装层引起的问题，后续不作为专项维护方向。
• WASAPI Exclusive：更适合外置 DAC、USB 声卡和专业音频接口。电脑耳机孔、笔记本 3.5mm 或主板集成声卡通常没有必要强行开启独占，系统输出或 WASAPI Shared 往往更稳定省心。

适合谁

核心能力

快速开始

获取发布版

普通用户优先从 GitHub Releases 下载。Windows 用户通常选择安装包或便携版；Linux 用户可以选择 AppImage 或 deb 包，具体取决于发布版本提供的构建产物。

首次启动后，建议先导入一个较小的音乐文件夹确认扫描、封面、播放和歌词入口正常，再导入完整曲库。

推荐上手路线

完整教程见 docs/USER_GUIDE.md。

页面速查

ECHO NEXT 和 ECHO 的区别

ECHO 是上一代完整播放器，重点是把本地播放、歌词、MV、下载、插件、投屏和共听等体验集中在一个桌面应用里。

ECHO NEXT 更像一次底层重建。它把曲库、音频、Renderer、Preload、主进程、原生宿主和系统集成分层，避免在旧代码上继续堆功能。对用户来说，它追求更稳定的大曲库体验、更清晰的 HiFi 输出状态、更可靠的设置和更容易维护的功能边界。

如果你想要成熟功能集合，可以关注 ECHO；如果你更关心下一代架构、性能、Linux 适配和后续 HiFi 能力，ECHO NEXT 是新的主线。

ECHO 开发者计划

如果你想更深入参与 ECHO NEXT，可以申请加入 ECHO 开发者计划。

通过开发者申请后，你可以访问开发者仓库，参与更早期的功能讨论、开发和测试；符合条件的开发者也可以免费获得 ECHO Next Pro 等权益。申请时请准备以下信息：

所有为 ECHO 参与过仓库贡献的用户可以直接申请；申请时附上 QQ 和 GitHub ID 即可通过。

如果你有 Codeforces、AtCoder、洛谷等算法竞赛主页，也可以一并提供；这不是硬性要求，但会作为额外加分项。

开发与构建

开发环境推荐：

git clone https://github.com/moekotori/echo.git
cd echo
npm install
npm run dev

如果你需要同时构建音频宿主和 Windows SMTC 宿主：

npm run dev:full

常用命令：

文档改动通常只需要检查内容和格式；播放、数据库、扫描、音频宿主、SMTC、打包等改动再按对应范围做 focused check。

Nix / Flake 开发与构建

项目提供 Nix flake，包含开发环境、构建 derivation 和 nixpkgs overlay：

将 overlay 加入你的 nixpkgs 配置：

{
  inputs.echo-next.url = "github:moekotori/echo";

  outputs = { self, nixpkgs, echo-next, ... }: {
    nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
      modules = [
        ({ pkgs, ... }: {
          nixpkgs.overlays = [ echo-next.overlays.default ];
          environment.systemPackages = [ pkgs.echo-next ];
        })
      ];
    };
  };
}

或临时运行：

nix run github:moekotori/echo

direnv 用户可执行 direnv allow 自动加载开发环境。

覆盖范围

运行

LICENSE 是 source-available 非 OSS 许可，meta.license = lib.licenses.unfree，因此必须显式允许：

# 一次性
NIXPKGS_ALLOW_UNFREE=1 nix run --impure .#echo-next

# 或在 NixOS 配置里固定允许
nixpkgs.config.allowUnfreePredicate = pkg:
  builtins.elem (lib.getName pkg) [ "echo-next" ];

维护要点

• npmDepsHash 更新：改完 package-lock.json 后，把 package.nix 里的 npmDepsHash 改回 lib.fakeHash，运行一次 nix build .#echo-next，从报错里的 got: sha256-… 复制回写。
• npm_config_nodedir 必须 unset：npmConfigHook 会把 Node 22 source 注入 env，覆盖 --nodedir CLI；rebuild better-sqlite3 时必须 env -u npm_config_nodedir node-gyp …，否则会链接到 nodejs 而非 electron 的 V8 14，运行期抛 undefined symbol: v8::HandleScope::HandleScope(v8::Isolate*)。
• 不要把 --ignore-scripts 拿掉：postinstall 里的 ensure-native-abi.mjs 走 @electron/rebuild 联网下载 electron headers，sandbox 必跪；当前用 buildPhase 内显式 node-gyp rebuild --nodedir=${electron.headers} 取代它，更可控也更快。
• sharp musl 变种必须删：autoPatchelfHook 会把 sharp-linux-x64.node 的 libvips RPATH 优先绑到 sharp-libvips-linuxmusl-x64，运行期 dlopen 触发 ERR_DLOPEN_FAILED: libc.musl-x86_64.so.1。buildPhase 里 rm -rf node_modules/@img/sharp-linuxmusl-x64{,-libvips} 这一行不可省。
• 公开仓自带 stub：src/main/plugins/{MachineIdentity,EchoProLicensePlugin}.ts 是公开 stub（详见 .gitignore 的 ! 白名单两行），nix build 与 npm run typecheck 无需私有 overlay 即可通过。要启用 Pro 真实能力请用 npm run pro:pull 拉 ECHOPrivate 兄弟仓，私有文件以同名覆盖 stub。

已知运行时降级日志（非 Bug）

nix run 启动后会看到以下日志，全部预期：

• [DiscordPresence] RPC initialization failed { error: 'Could not connect' } — Discord IPC socket 不可达，未运行 Discord 即如此。
• wayland_wp_color_manager.cc … Unable to set image transfer function — 运行环境不支持 wp_color_manager 协议，Chromium 自身的 warning，不影响渲染。
• Error occurred in handler for 'connect:*': Error: echo_pro_required — Pro stub 触发的"未解锁"分支，对应 Connect / AirPlay 等付费功能；公开版预期行为。

数据目录（XDG Base Directory）

Linux 上 ECHO NEXT 遵循 XDG Base Directory 规范 管理用户数据。 路径按以下顺序确定：先读取对应环境变量，若未设置则回退到硬编码默认值。

实际目录为 ${对应目录}/echo-next，例如默认配置为 ~/.config/echo-next。

首次启动时会自动将旧 ~/.config/ECHO NEXT 中的数据迁移到以上布局。 Windows / macOS 继续使用 Electron 默认的 userData 路径，不受影响。

架构概览

React Renderer
  pages, components, virtual lists, settings, player controls
        |
Typed Preload Bridge
        |
Electron Main Process
  IPC, windows, lifecycle, services, system integration
        |
        +-- Library Core
        |     SQLite, scans, metadata, covers, folders, playlists
        |
        +-- Audio Core
        |     AudioSession, decoder pipeline, output bridge, device state
        |
        +-- Native Hosts
        |     echo-audio-host, WASAPI, ASIO, EQ, SMTC helper
        |
        +-- Experience Services
              lyrics, MV, streaming, downloads, plugins, remote sources

Renderer 只负责交互和展示，不直接扫描目录、不生成封面、不解析音频文件、不计算权威播放进度。主进程通过类型化 IPC 暴露受控能力，重任务进入 Library Core、Audio Core、原生宿主或独立服务。

算法致敬

ECHO NEXT 不是算法竞赛项目，但很多体验都离不开 ACM / ICPC 那类经典算法思想。这里记录项目实际用到或直接借鉴的部分，也向这些朴素但可靠的算法致敬。

也特别致敬 KMP、Trie、AC 自动机、动态规划、图搜索、并查集、堆和最短路这些经典算法训练。即使它们不一定都以教科书形态出现在代码里，工程里的“快、稳、边界清楚”，很多都来自这些基础训练。

反馈规范

有效反馈应包含：系统版本、ECHO NEXT 版本、安装版或开发模式、问题页面、复现步骤、预期行为、实际行为、截图、日志或诊断报告。如果是播放问题，请附上输出模式、设备、音频格式，以及是否只影响某些文件。

不接受绕过会员、版权、平台限制或 DRM 的请求。不接受没有复现路径的情绪化否定，也不接受与本地播放器核心方向无关的大型平台接入要求。

提 issue 前建议先做三件事：

提问规范参考

以下内容转载自 Stop-Ask-Questions-The-Stupid-Ways，用于补充反馈问题前应提供的信息。

别像弱智一样提问

Stop-Ask-Questions-The-Stupid-Ways

短域名服务

• https://git.io/how-to-ask
• https://git.io/asking-question
• https://git.io/stop-stupid

你真的准备好了吗？

感谢群友 for you 提供

避免 xy-problem

• 参考地址: http://xyproblem.info/

XY Problem 表示

1. 提问者想要解决 原问题 X ，且觉得解决了 引申问题 Y 就能解决 X 问题
2. 提问者对外提出了解决 Y 的的请求
3. 回答者帮助提问者解决 Y 问题。（浪费了回答者和提问者双方的时间）

然而, 最终 Y 问题可能并不是 X 问题的一个合适的解决方法

因此， 提问者要避免创造这样的修罗场, 需要学会在问题之初就准确描述自己的根本问题。 学会描述问题

提问前你必须需要知道的事情

1. 要知道， Free 的正确翻译是 自由，而非 免费。
2. 要知道，愿意回答问题的人，都是 可爱 的人。
3. 要知道，向帮助你的人 付费 是一个高尚的行为。即使回答你的人不是为了钱。
4. 要知道，花钱买时间是一个常识。如果你不能认同，要么你钱包穷，要么你思想穷。
5. 要知道，给对方发工资的不是你或者你老板。
6. 要知道，提问的时候你才是 孙子，帮助你的人是 大爷。
7. 要知道，不回答你的问题对其他人没有任何损失。
8. 要知道，准确描述一件事情是一项基本生存技能。要学会 《提问的智慧》
9. 要知道，搜索是一项基本生存技能，学不会用 Google 的话，你可能真的不适合你所从事的行业。
10. 要知道，英文是一项基本生存技能，不认识英文的话，你可能真的不适合你所从事的行业。

幼儿园的小朋友都知道要有礼貌

请问
  ...问题描述...
谢谢

学会描述问题

向别人提问的时候，要学会正确的描述问题。 把对方当成你的老板，你在给他做报告。要用最精炼的文字和图片，向对方阐述明白一个事情的来龙去脉。

要知道，你不是我追的妹子，我没有时间来猜你想要什么。

记住，给别人的条件越多，你的问题解决越快。因为这不是解密游戏。

1. 请问一个关于 什么 的问题。
2. 我想要达到 什么样 效果，但是我这样做出现了 什么样 的问题。
3. 报错日志是 这样 的。（要 学会 画关键字）
4. 我尝试过 什么 方法来解决。
5. 我尝试搜索过了 什么 关键字，在里面找到了 这些 URL 的回答，尝试了还是没有解决问题。
6. 我用的是 什么 操作系统，版本号是多少。
7. 我用的是 什么 软件，版本号是多少。
8. 谢谢

千万别认为只有别人帮助你之后才需要说 谢谢。

学会什么时候贴图

像这种，IM 自动转义表情，贴出来的问题全是表情。

学会什么时候要圈出重点

千万不要认为别人的频率和你是同步的，然后像这样扔出一张图一个表情就了事了。

在工作中， 你@的人可能会多问一句什么情况。 但是在 IM 聊天群里面，就没有这么好运气了。

如下很难吗？

@xxx，我这边访问不了 git 仓库。
环境是: 环境是什么。

学会什么时候贴文字

什么是弱智一样的提问

萌新滚粗

相关文档

ECHO Next Pro

ECHO Next Pro 是给长期支持 ECHO NEXT 的用户准备的进阶权益入口。通过爱发电支持项目后，可以获得更多实验性与扩展能力；所有为项目做出贡献的 GitHub 用户也将免费获得此权益。

ECHO Next Pro 当前包含：

• 解锁 ECHO Connect 功能，可以连接 ECHO Mobile 安卓端并共享曲库。
• 抢先体验 ECHO 手机版。
• 解锁所有主题。
• 解锁网盘连接功能。
• 解锁 ECHO 插件功能。
• 加入 ECHO Donators 群。

支持入口：https://afdian.com/a/echonext

English Summary

ECHO NEXT is a source-available desktop music player focused on local libraries, stable playback, HiFi-oriented output, lyrics, MV, remote sources, plugins, and maintainable Electron architecture.

The project prioritizes local ownership and playback stability over online-platform dependency. See docs/USER_GUIDE.md for the full Chinese user guide.

License

ECHO NEXT is source-available under the ECHO NEXT Source-Available License. The license permits personal review, learning, and local builds, but prohibits cracks, bypassing entitlement or integrity checks, and unauthorized redistribution of modified builds.

Star 趋势