Open-Source Hybrid Music Player

面向本地音乐库、HiFi 输出和长期可维护架构的跨平台桌面播放器。

Latest Release  |  QQ群聊  |  Discord  |  快速上手  |  用户手册  |  HiFi  |  Q/A  |  Linux 构建  |  架构概览  |  English README  |  Roadmap

ECHO 是上一代完整播放器，重点在于把本地播放、歌词、MV、下载、插件、投屏和共听等体验功能做进一个桌面应用里。但ECHO的内存占用高,性能差

ECHO NEXT 则是面向长期维护和高性能曲库重新设计的新架构版本，它不是在旧代码上继续堆功能，而是把曲库、音频、Renderer、Preload、原生宿主和系统集成重新拆层。

简单说，ECHO 更像已经成型的功能型播放器；ECHO NEXT 更像一次工程底座重建。它优先解决旧架构里最容易拖累体验的部分：大曲库扫描、SQLite 持久化、专辑墙分页、封面缓存、原生音频宿主、ABI 检查、Linux 构建和可测试的模块边界。部分体验功能已经迁移或重做，部分功能仍在按 Roadmap 继续补齐。

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

ECHO NEXT 是一个完整的桌面音乐产品工程，而不是简单的播放器界面。它覆盖 Electron 主进程、React 渲染层、SQLite 曲库、原生音频宿主、封面缓存、系统媒体控制、网络元数据、歌词、MV、下载和跨平台打包链路。

项目的核心目标是把听歌场景里经常被拆散的能力收束成一条稳定的桌面端体验链路：本地曲库负责长期管理，音频核心负责可靠输出，Renderer 负责清晰交互，原生宿主负责 HiFi 能力，测试脚本和文档负责发布前的回归边界。

如果你只是想尽快把 ECHO NEXT 跑起来，按下面顺序走即可。Windows 是当前主要开发和验证平台；Linux 用户请先看后面的 Linux 用户构建。

如果你只看界面和文档，通常不需要额外折腾原生工具链；如果要跑完整开发环境、音频宿主或打包，就需要准备好 C++ 构建工具。

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

首次安装会拉取 Electron、React、SQLite、封面处理、音频宿主相关依赖。切换 Node/Electron 版本后，如果遇到 native module ABI 问题，优先使用仓库脚本修复，不要手动替换二进制文件。

npm run dev

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

npm run dev:full

ECHO NEXT 不鼓励无意义地全量跑测试。你改什么，就验证什么：

• 想体验应用：先 npm install，再 npm run dev。
• 想验证 HiFi/原生输出：用 npm run dev:full，并确认音频宿主能正常构建。
• 想构建 Windows 包：使用 npm run build:win。
• 想构建 Linux 包：请在 Linux x64、WSL2、Linux VM 或 CI runner 中使用 npm run build:linux。
• 只是改 README：不用跑项目测试，别浪费时间。

这一节面向普通使用者，而不是开发者。ECHO NEXT 的核心使用方式是：先建立本地曲库，再围绕曲目、专辑、艺术家、歌词、MV 和音频输出进行管理与播放。

首次启动后，先进入曲库或设置中的本地音乐目录管理，把你的音乐文件夹加入 ECHO NEXT。应用会在后台扫描文件，读取曲目、专辑、艺术家、时长、封面和嵌入式元数据，并把结果写入本地 SQLite 曲库。

扫描期间可以继续浏览界面。大曲库第一次导入需要一些时间，后续增量扫描会尽量跳过未变化的文件。若文件被移动、删除或磁盘暂时不可用，曲库会保留可追踪状态，避免简单粗暴地丢失已有信息。

曲库建立后，可以通过歌曲、专辑、艺术家、搜索和播放历史等入口浏览内容。专辑墙和列表会使用分页、虚拟列表和轻量封面缓存，目标是在大曲库下仍然保持滚动和切换稳定。

如果封面、标题、专辑或艺术家信息不符合预期，优先检查源文件的嵌入式标签。网络元数据只作为候选或补全来源，不应该随意覆盖你手动整理过的强来源字段。

选择曲目后即可播放，也可以把歌曲、专辑或搜索结果加入播放队列。播放控制区负责上一首、下一首、暂停、进度、音量和当前曲目信息；系统媒体控制会尽量同步当前播放状态。

如果播放设备断开、驱动异常或音频宿主出现问题，ECHO NEXT 会尽量保持应用可用，并通过状态提示说明问题。遇到播放问题时，优先确认当前输出设备、音频模式和文件本身是否正常。

ECHO NEXT 支持本地歌词、在线歌词候选、歌词匹配、翻译或罗马音等体验能力。匹配算法会尽力自动选择，但音乐元数据、同名歌曲、版本差异和网络来源都可能影响结果；不准确时建议手动选择或修正来源。

MV 同样依赖曲目信息和候选结果。若自动匹配不理想，可以通过手选结果或调整曲目信息提高准确度。算法无法保证每一首歌都完美命中，这属于音乐数据库天然复杂度。

在音频设置中可以查看或选择输出设备、输出模式、EQ、Preamp、采样率状态和 bit-perfect 提示。Windows 下重点支持 WASAPI Shared、WASAPI Exclusive 和 ASIO 相关能力；Linux 版音频链路会按平台能力继续推进。

启用 EQ、Preamp 或其他 DSP 后，信号会被处理，此时不应再视为 bit-perfect。DirectSound 等兼容模式更适合故障排查或特殊设备，不是默认 HiFi 路径。

设置页会集中管理播放、歌词、曲库、缓存、外部工具、系统集成和危险操作。涉及数据库、缓存目录、曲库重建或删除的操作请先确认说明；ECHO NEXT 倾向于先归档、再修复，避免误删用户数据。

如果 C 盘空间紧张，建议关注缓存目录、封面缓存、下载目录和日志目录的实际占用。迁移目录前请确保目标磁盘稳定可用。

发布版本请优先从 GitHub Release 获取。反馈问题时，请提供系统版本、ECHO NEXT 版本、复现步骤、预期行为、实际行为、截图和必要日志。只说“不能用”“不好用”“做得不对”通常无法定位问题。

不合理要求、情绪化挑刺、无法复现的问题、要求绕过会员或版权限制的请求不会被接受。本项目是本地播放器优先，网络平台接入不是当前中心方向。

ECHO NEXT 不是旧播放器的界面翻新，而是一套重新拆分边界的桌面音乐系统。它把播放器 UI、音乐库、音频输出、原生宿主、SQLite 持久化和系统集成放在各自清晰的层级里，目标是在大曲库、复杂元数据和 HiFi 输出场景下仍然保持稳定。

项目重点不是堆叠功能清单，而是把真实使用中最容易失控的部分做扎实：本地扫描不阻塞界面，专辑墙不在 Renderer 中重组全库，播放时钟来自输出侧，原生模块有明确的打包与 ABI 检查，测试和烟测脚本能覆盖关键路径。

ECHO NEXT 的 HiFi 不是一个界面标签，而是一条尽量少干扰播放链路的工程边界。播放器 UI、曲库扫描、封面生成、网络补全和系统集成不会直接挤进音频输出热路径；真正的播放、解码、设备状态和输出模式由 Audio Core 与独立原生音频宿主承载。

当前重点包括：

• 独立 echo-audio-host：把音频输出从 Renderer 生命周期里拆出去，降低界面刷新、曲库扫描和页面状态变化对播放稳定性的影响。
• WASAPI Shared / WASAPI Exclusive：Windows 下支持共享模式与独占模式，独占模式用于更直接的设备输出链路。
• ASIO 探测与接入边界：面向专业声卡和低延迟场景保留 ASIO 能力，同时遵守驱动与平台差异。
• 采样率与输出状态回传：让界面能展示当前输出路径、设备状态、采样率状态和 bit-perfect 提示。
• EQ 与 bit-perfect 明确分离：启用 EQ、Preamp 或其他 DSP 时会清楚表达信号链路已被处理，不把 DSP 输出伪装成 bit-perfect。
• 稳定优先：DirectSound 等兼容模式保留为用户显式选择，不作为静默默认；音频错误、设备断开和宿主异常会尽量降级处理，而不是让播放器崩溃。

HiFi 目标不是承诺所有设备、驱动和格式都能神奇变好，而是把输出链路做得可解释、可验证、可维护：该直出的地方尽量直出，该提示的地方明确提示，该回退的地方保留用户选择。

┌─────────────────────────────────────────────────────────────┐
│ React Renderer                                               │
│ 页面、组件、虚拟列表、主题、播放控制、资料展示                 │
└──────────────────────────────┬──────────────────────────────┘
                               │ Typed Preload Bridge
┌──────────────────────────────▼──────────────────────────────┐
│ Electron Main Process                                        │
│ IPC、窗口、生命周期、协议、系统集成、服务组合                  │
├──────────────────────────────┬──────────────────────────────┤
│ Library Core                  │ Audio Core                   │
│ SQLite、扫描、元数据、封面     │ 解码、输出桥、设备、状态时钟     │
└──────────────┬───────────────┴──────────────┬───────────────┘
               │                              │
┌──────────────▼──────────────┐   ┌───────────▼───────────────┐
│ Worker-ready Interfaces      │   │ Native Audio Host          │
│ FileScanner / MetadataReader │   │ WASAPI / ASIO / EQ / PCM   │
│ CoverExtractor               │   │ output-side timing         │
└──────────────────────────────┘   └───────────────────────────┘

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

更完整的设计约束见 ECHO_NEXT_ARCHITECTURE.md、ECHO_NEXT_LIBRARY_CORE.md 和 ECHO_NEXT_AUDIO_CORE.md。

ECHO NEXT 正在从架构核心向完整播放器体验推进。

已落地或正在验证的重点包括：

• Electron 37、React 18、TypeScript、Vite 构建链
• 类型化 Preload API 和集中 IPC 注册
• SQLite 曲库模型、迁移、分页曲目与专辑读取
• 文件夹导入、后台扫描、扫描进度、取消扫描和增量跳过
• 本地封面提取、WebP 缓存和专辑墙持久化
• 本地文件播放、音频设备查询、输出模式状态和原生音频宿主集成
• SMTC、Last.fm、Discord Presence、下载、歌词、MV、流媒体搜索等模块化实现
• Vitest 单元测试、原生 ABI 检查、FFmpeg 工具链检查和音频烟测脚本

路线图见 ECHO_NEXT_ROADMAP.md。

• 本地音乐文件夹导入、扫描进度、取消扫描和缺失文件标记
• 曲目列表分页读取、虚拟列表渲染和专辑墙懒加载
• 专辑、艺术家、封面、播放历史、收藏和队列相关数据模型
• 输出设备查询、播放状态同步、播放进度和音频采样率状态展示
• 10-band EQ、Preamp、预设管理和 bit-perfect 状态提示
• 网易云、QQ 音乐、Spotify、Bilibili、YouTube、SoundCloud 等 Provider 边界
• NCM 转换、FFmpeg、yt-dlp 等外部工具链集成
• 英文、简体中文、日文等多语言资源基础
• 单元测试、压力测试、桌面烟测和稳定性复盘文档

ECHO NEXT 已经加入 Linux 构建适配。当前 Linux 目标以 x64 桌面环境为主，构建产物包括 AppImage 和 deb 包。Linux 包必须在 Linux x64 环境中构建，可以使用原生 Linux、WSL2、Linux 虚拟机或 Linux CI runner。

项目没有把 Windows 到 Linux 的交叉打包作为默认路径，因为 Linux 包需要 Linux 版 echo-audio-host、Linux 打包工具链，以及 AppImage/deb 相关校验。npm run build:linux 会在非 Linux 或非 x64 环境下直接失败并给出提示。

Linux 版音频宿主当前提供基于 JUCE 的 shared native output。Windows SMTC、WASAPI Exclusive 和 ASIO 仍然是 Windows-only 能力；Linux 用户可以正常构建和验证桌面包，但 HiFi 输出能力的完整度会随 Linux 音频链路继续推进。

Windows 是当前主要开发和验证平台。Linux x64 构建脚本已提供，macOS 支持会随原生音频链路继续完善。

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

项目包含 better-sqlite3、sharp、原生音频宿主和外部工具链。首次安装或切换 Node/Electron ABI 后，如果原生模块不匹配，请优先运行项目脚本而不是手动替换二进制文件。

npm run dev

如需同时构建音频宿主和 SMTC 宿主后再启动：

npm run dev:full

开发环境下可以单独构建或同步音频宿主：

npm run build:audio-host
npm run sync:audio-host

生产打包会通过 Electron Builder 的 extraResources 将宿主程序和工具目录带入安装包。发布前不要依赖 ../ECHO 之类的本地迁移路径。

Windows 构建：

npm run build:win

构建产物输出到 dist/，包含 NSIS 安装包和 Portable 包。Electron Builder 配置位于 package.json，当前应用标识为 app.echo.next，产品名为 ECHO NEXT。

Linux 构建：

npm run build:linux

Linux 用户建议在 Ubuntu、Debian 系发行版、WSL2、Linux VM 或 Linux CI runner 中构建。不要在 Windows shell 里直接构建 Linux 包，脚本会阻止这种交叉打包。

Ubuntu 依赖示例：

sudo apt update
sudo apt install cmake g++ pkg-config fakeroot dpkg rpm binutils
sudo apt install \
  libasound2-dev libjack-jackd2-dev \
  libfreetype-dev libfontconfig1-dev \
  libx11-dev libxcomposite-dev libxcursor-dev libxext-dev \
  libxinerama-dev libxrandr-dev libxrender-dev

完整构建：

npm ci
npm run build:linux

npm run build:linux 会依次完成：

1. 构建 Linux 版 electron-app/build/echo-audio-host。
2. 执行 TypeScript 与 electron-vite 生产构建。
3. 运行 electron-builder --linux。
4. 校验打包后的 Linux 音频宿主、AppImage 和 deb 产物。

预期产物：

dist/linux-unpacked/resources/echo-audio-host
dist/*.AppImage
dist/*.deb

更完整的 Linux 构建说明见 ECHO_NEXT_LINUX_BUILD.md。

发布前建议至少执行：

npm run lint
npm run test
npm run verify:ffmpeg
npm run smoke:audio-host

音频、曲库和桌面行为的人工检查可参考 docs/ 下的 smoke test 与稳定性文档。

src/
  main/
    app/             Electron 生命周期、窗口、托盘、更新与桌面集成
    audio/           Audio Core、解码、输出桥、设备、EQ、播放状态
    database/        SQLite schema、迁移和数据库创建
    diagnostics/     日志、崩溃恢复和诊断
    downloads/       下载服务
    integrations/    SMTC、Discord、Last.fm 等系统或外部服务集成
    ipc/             IPC 注册和通道处理
    library/         曲库、扫描、元数据、封面、专辑、远程源和网络补全
    lyrics/          歌词解析、匹配、罗马音和在线歌词源
    mv/              本地和在线 MV 匹配
    streaming/       流媒体搜索、缓存、Provider Registry 和播放解析
  preload/           类型化 Context Bridge
  renderer/
    app/             应用布局、路由和 Provider
    components/      播放器、曲库、歌词、专辑、设置等 UI 组件
    hooks/           Renderer 交互 Hook
    pages/           页面入口
    stores/          播放状态和队列状态
    styles/          主题、布局和模块样式
  shared/            跨进程常量、类型和工具函数

native/
  audio-host/        原生音频宿主
  audio-engine/      EQ 和音频处理模块
  smtc-host/         Windows SMTC 宿主

electron-app/
  build/             本地构建出的宿主程序
  tools/             FFmpeg、yt-dlp、NCMConverter 等外部工具

docs/                架构、音频、曲库、构建、稳定性和发布文档
scripts/             构建、检查、烟测和维护脚本

• Renderer 保持轻量：列表分页、封面懒加载，重任务不进入界面线程。
• SQLite 是曲库事实来源：重启后读取持久化数据，不重新解析整库。
• 元数据合并可追踪：字段来源有优先级，网络补全只能补缺，不能覆盖强来源。
• 音频输出独立：播放、解码、设备和输出状态与 UI 生命周期解耦。
• 原生能力可验证：ABI、FFmpeg、音频宿主和 SMTC 宿主都提供脚本化检查。
• 发布流程显式化：构建、测试、工具链检查和烟测文档共同构成发布闸门。

• Architecture
• Roadmap
• Library Core
• Audio Core
• EQ
• Linux Build
• UI Guide

不是。ECHO NEXT 是重建架构后的新主线，重点在大曲库、稳定播放、原生输出、SQLite 持久化、可维护模块边界和跨平台构建。部分 ECHO 功能会迁移或重做，但不会直接把旧架构整块搬过来。

当前已经围绕独立音频宿主、WASAPI Shared、WASAPI Exclusive、ASIO 探测、采样率状态、EQ 和 bit-perfect 提示建立了链路。后续会继续补齐更细的设备兼容、格式边界和平台差异。

不是。EQ、Preamp 和其他 DSP 都会改变信号链路。ECHO NEXT 会把 DSP 状态和 bit-perfect 状态分开表达，避免把处理后的输出误称为 bit-perfect。

Linux 版已经有构建适配和基于 JUCE 的 shared native output，但 Windows 专属的 WASAPI Exclusive、ASIO 和 SMTC 不会在 Linux 上直接可用。Linux HiFi 链路会按平台能力继续推进。

因为项目维护时间有限，真正有价值的问题应该能帮助定位、复现或改进。请提交具体环境、复现步骤、预期行为、实际行为和必要日志。情绪化挑刺、无依据否定、重复催促和不合理要求不会提高优先级。

只跑和你改动相关的检查。文档修改通常不需要跑测试；音频、数据库、扫描、打包等改动则应该选择对应的 focused check，并在 PR 中说明命令和结果。

Open-Source Hybrid Music Player

A cross-platform desktop music player built for local libraries, HiFi output, and long-term maintainability.

ECHO NEXT is not a visual refresh of the old ECHO player. It is a new architecture for a desktop music system: Electron owns the app shell and native resources, React owns the player interface, SQLite owns the library state, and the native audio host owns the output path.

The project is designed around high-performance local libraries, stable playback, traceable metadata, and a clearer separation between UI work and audio work. Heavy operations such as scanning, cover extraction, metadata parsing, and native output should not compete with the renderer hot path.

ECHO is the previous full-featured player, focused on bringing local playback, lyrics, MV, downloads, plugins, casting, and listening features into a desktop app. ECHO NEXT is the new mainline for a more maintainable and performance-oriented foundation.

If you want the mature feature set of the older app, follow ECHO. If you care more about the next architecture, large-library performance, Linux packaging, native audio boundaries, and ongoing HiFi work, ECHO NEXT is the direction.

HiFi in ECHO NEXT is not just a badge in the UI. It is an engineering boundary that keeps playback and output state away from expensive UI and library work.

• echo-audio-host carries native output outside the renderer lifecycle.
• WASAPI Shared and WASAPI Exclusive are supported on Windows.
• ASIO probing and integration are kept for professional audio devices and low-latency scenarios.
• Sample-rate and output-state feedback are surfaced to the app.
• EQ, Preamp, and DSP are clearly separated from bit-perfect output.
• Compatibility backends stay explicit user choices instead of silent defaults.

The goal is not to claim that every device, driver, or file magically becomes better. The goal is an output chain that is understandable, verifiable, and maintainable.

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

To build the audio host and SMTC host before starting development:

npm run dev:full

No. ECHO NEXT is a new architecture. Some features from ECHO will be migrated or rebuilt, but the old architecture is not being copied wholesale.

No. EQ, Preamp, and DSP change the signal path. ECHO NEXT keeps DSP state and bit-perfect state separate so the UI does not misrepresent processed output.

Not yet. Linux builds and a JUCE-based shared native output path are available, but Windows-only features such as WASAPI Exclusive, ASIO, and SMTC do not apply directly to Linux.

A useful issue includes environment details, reproduction steps, expected behavior, actual behavior, and logs or screenshots when relevant. Vague complaints, hostile demands, and preference-only arguments are not useful.

Thanks to everyone who has contributed to ECHO NEXT. GitHub commit contributors are also available in the repository graph: contributors.

• Moekotori
• Tkingxiao

1. Fork the repository and create a feature branch.
2. Run the focused checks for the area you changed.
3. Open a pull request with a clear description, screenshots or logs when useful, and the commands you used for verification.

ECHO NEXT 建立在这些优秀的开源项目之上：

• Electron
• React
• Vite
• electron-vite
• electron-builder
• better-sqlite3
• sharp
• music-metadata
• taglib-wasm
• Shaka Player
• Vitest

当前仓库尚未附带 LICENSE 文件。正式公开发布前，请先确认授权策略并补充对应许可证文本。