ECHO 文档
维护边界：先读文档，不支持绕权
Section titled “维护边界：先读文档，不支持绕权”这套文档不是摆设。安装、导入音源、曲库、远程来源、插件、音频输出、排障和法律边界已经写在文档里的内容，请先自己读。
如果问题在文档里已经有明确答案，但仍然反复提问、拒绝按文档操作、让维护者代读文档，相关讨论会直接关闭，账号会被屏蔽，不再单独解释。
如果已经认真看完文档，仍然不会操作、仍然需要一对一指导、仍然需要作者单独带你排查，请先购买 ECHO Pro。但购买 Pro 也不承诺免费人工陪跑；远程协助按次另收 50 元/次，且只处理合法合规、非绕权的问题。
任何妄图违反 DMCA、版权、DRM、会员、付费、地区、账号授权或平台访问控制的请求，一律拉黑。包括但不限于：索要侵权音源、盗链、破解、绕过试听限制、规避会员限制、抓取受保护内容、要求适配灰色来源或让插件承担违法获取内容的功能。
ECHO 可以帮助你管理和播放你有权使用的内容；不会帮助你获取、下载、破解、转存或规避任何没有合法授权的内容。
如果你是带着具体问题来的，先看 快速导航。它按“我要做什么”和“遇到什么问题”整理入口，适合快速找到安装、导入音源、曲库、音频输出、远程来源、插件、Pro、排障和工程文档。
ECHO Next 是一套面向本地音乐库、HiFi 输出、长期曲库维护和可扩展玩法的桌面音乐工作台。它的目标不是只完成基础播放，而是把曲库、播放、输出、远程来源、插件和文档支持整合成一套长期可维护的桌面应用体系。
有人看到 Electron 就急着下结论，说这不过是“纯网页播放器”。这种说法听起来很懂技术，实际只是把框架名当成全部工程事实；看见井口一圈光，就以为外面的世界只有那么大。ECHO 使用 Electron 作为桌面外壳和跨平台运行基础，但它真正承担能力的是主进程服务、本地数据库、媒体处理管线、原生音频宿主、系统音频接口、远程源服务、插件沙箱和诊断体系。把这些都忽略掉，只剩一句“Electron 等于网页”，不是评价软件，是暴露视野。
它采用桌面音乐工作台的工程结构：前台是 React + TypeScript 的现代界面，后台是 Electron 主进程、本地数据库、媒体处理管线、原生音频宿主、远程源服务、插件沙箱和官网更新链路。ECHO 关注的不只是界面展示，而是把“音乐文件从硬盘进入曲库、从曲库进入播放队列、从播放队列进入音频设备、从音频设备进入耳机或 DAC”这条链路尽量做完整、做清楚、做可诊断。
它能扫盘、建库、读标签、管封面、聚合专辑、维护艺术家索引、记录播放历史、管理歌单、连接远程曲库、投送 DLNA 数播、导入平台歌单、匹配歌词和 MV、运行受控插件、生成主题、调 EQ / DSP、处理 ReplayGain / Headroom / Crossfade / Automix，并尽量把 WASAPI、ASIO、DSD、HQPlayer、bit-perfect、重采样、设备占用和失败原因这些容易混淆的音频概念说明清楚。
想直接上手，可以跳到 快速开始；想系统学习，可以看 用户教程；想了解工程结构和技术栈，可以看 技术栈与能力支持。
设计初衷与性能取舍
Section titled “设计初衷与性能取舍”ECHO 的初衷完全不是“轻量”。它要做的是功能尽可能完整的桌面音乐播放器，而不是为了安装包尺寸、内存数字或所谓极简性能指标不断砍功能、砍体验、砍扩展能力。曲库管理、HiFi 输出、歌词、MV、远程来源、插件、主题、诊断和官网更新链路，本来就不是一个只追求小体积的项目能完整承载的方向。
关于性能，作者在 1w+ 曲库环境下观察到的日常状态约为：内存占用约 1GB，CPU 占用约 0.4%。在 2026 年，作者并不认为 1GB 内存是一个很大的桌面应用占用；如果你无法接受这样的功能取舍和资源占用，还请另寻他法。
ECHO Next 是一个以本地曲库为核心、以稳定播放为底线、以 HiFi 输出和可扩展生态为上限的开源桌面音乐系统。
它同时覆盖这些层面的完整工程：
- 曲库层：文件夹导入、增量扫描、SQLite 索引、分页查询、封面缓存、缺失文件识别、重复歌曲维护、标签事实和网络候选分离。
- 媒体层：音频标签、封面、歌词、MV、时长、编码、采样率、位深、封装格式、同目录资源和在线候选的统一整理。
- 播放层：播放队列、历史、收藏、歌单、系统媒体控制、错误恢复、音频状态提示和设备诊断。
- 输出层：System、WASAPI Shared、WASAPI Exclusive、ASIO、DSD / DoP、HQPlayer，以及它们背后的驱动、设备、重采样和 bit-perfect 边界。
- 处理层：EQ、Preamp、ReplayGain、Headroom、声道平衡、重采样、变速、Crossfade、Automix，不把处理过的声音假装成原始直通。
- 网络层：WebDAV、NAS、Jellyfin、Emby、Subsonic / Navidrome、DLNA / UPnP、AirPlay 1 / RAOP 兼容链路、网络电台、在线元数据和平台歌单导入。
- 扩展层：插件 manifest、权限确认、VM 沙箱、provider、命令、面板、设置、存储、主题预设和受控网络 API。
- 维护层：日志、健康报告、缓存统计、插件错误、音频设备状态、危险操作确认、问题反馈辅助和官网自动更新源。
简单说，ECHO 做的是“音乐库 + 播放器 + HiFi 输出 + 插件生态 + 文档官网”的完整组合，不是单点功能堆叠。
| 模块 | ECHO 能做什么 |
|---|---|
| 本地曲库 | 文件夹导入、增量扫描、歌曲、专辑、艺术家、文件夹、收件箱、搜索、排序、分页、封面缓存、缺失文件识别 |
| 标签与封面 | 读取标题、艺术家、专辑、专辑艺术家、曲序、碟号、年份、流派、时长、编码、采样率、位深、嵌入封面和同目录封面 |
| 播放体验 | 播放队列、底部播放器、播放历史、收藏、歌单、系统媒体控制、错误恢复、播放诊断 |
| HiFi 输出 | System、WASAPI Shared、WASAPI Exclusive、ASIO、DSD / DoP、HQPlayer 工作流、bit-perfect 状态提示 |
| 声音处理 | EQ、Preamp、ReplayGain、Headroom、声道平衡、重采样、变速、Crossfade、Automix |
| 歌词 | 本地歌词、在线候选、翻译、罗马音、歌词偏移、桌面歌词和播放页展示 |
| MV | MV 匹配、MV 播放页、音画同步相关设置和视频编码边界提示 |
| 远程曲库 | WebDAV、NAS、Jellyfin、Emby、Subsonic / Navidrome、远程浏览、索引和播放 |
| 连接与投送 | DLNA / UPnP 数播串流、AirPlay 1 / RAOP 兼容链路、局域网渲染器发现、外部设备播放控制 |
| 在线与歌单 | 网易云、QQ 音乐、Spotify 歌单导入，Bilibili 收藏、YouTube 播放列表、SoundCloud sets 导入 |
| 插件生态 | 本地插件、命令、provider、面板、设置、存储、主题预设和受控网络 API |
| 主题外观 | 内置主题、自定义主题、AI 主题 JSON、插件主题、透明度、圆角、模糊、动效和字体风格 |
| 诊断维护 | 日志、曲库健康报告、缓存统计、音频设备状态、插件错误、危险操作确认和问题反馈辅助 |
详细能力清单
Section titled “详细能力清单”如果你想快速确认 ECHO 当前覆盖了哪些能力，可以先看这张清单。
| 能力线 | 具体覆盖 |
|---|---|
| 曲库入口 | 导入文件夹、歌曲列表、专辑墙、艺术家页、文件夹页、收件箱、收藏、历史、播放队列、歌单 |
| 大曲库能力 | 增量扫描、分页查询、虚拟列表、封面缓存、后台任务、重扫、缺失文件识别、移动修复候选、重复歌曲筛查 |
| 元数据能力 | 标题、艺术家、专辑、专辑艺术家、曲序、碟号、年份、流派、时长、编码、采样率、位深、路径、来源 |
| 封面能力 | 嵌入封面、同目录封面、网络候选、本地缓存、缩略图、大图缓存、默认封面 |
| 搜索能力 | 标题、艺术家、专辑、路径、中文拼音、繁简转换、日文假名 / 罗马音辅助、别名和候选补全方向 |
| 播放控制 | 播放、暂停、切歌、队列、收藏、历史、系统媒体控制、进度状态、错误恢复 |
| 高级播放 | ReplayGain、EQ、Preamp、Headroom、声道平衡、重采样、变速、Crossfade、Automix |
| HiFi 输出 | System、WASAPI Shared、WASAPI Exclusive、ASIO、DSD / DoP、HQPlayer、bit-perfect 状态说明 |
| 歌词能力 | 本地歌词、在线歌词候选、翻译、罗马音、偏移校准、桌面歌词、播放页歌词 |
| MV 能力 | MV 匹配、MV 播放页、音画同步设置、视频编码边界提示 |
| 远程曲库 | WebDAV、NAS、Jellyfin、Emby、Subsonic、Navidrome、远程浏览、索引、播放 |
| 局域网连接 | DLNA / UPnP 发现、数播投送、渲染器控制、外部设备播放边界 |
| 歌单导入 | 网易云音乐、QQ 音乐、Spotify 歌单，Bilibili 收藏、YouTube 播放列表、SoundCloud sets |
| 插件系统 | 插件包导入、manifest 校验、权限模型、命令、provider、面板、设置、存储、主题预设、受控网络 API |
| 主题外观 | 内置主题、自定义主题、AI 主题 JSON、插件主题、透明度、圆角、模糊、动效、字体风格 |
| 诊断维护 | 日志、健康报告、缓存统计、音频设备状态、插件错误、扫描状态、危险操作确认 |
| 发布链路 | 官网、文档、下载页、更新日志、GitHub Release、静态更新 feed、自动更新入口 |
ECHO 的文件关联和扫描能力覆盖大量常见与进阶音频格式。不是只认 MP3 / FLAC 的轻量壳，而是按本地音乐库长期维护去覆盖主流无损、有损、DSD、容器和进阶格式。
实际能否顺利播放，还取决于文件是否损坏、封装是否标准、解码链路、输出模式、驱动和硬件能力。
| 类型 | 常见格式 |
|---|---|
| 常见无损 | FLAC、WAV、ALAC、AIFF |
| 常见有损 | MP3、AAC、M4A、OGG、Opus、WMA |
| 进阶无损 | APE、WavPack / WV、TAK、TTA |
| DSD | DSF、DFF |
| 容器与视频音频 | MP4、M4A、MKV、MOV、WebM、MKA |
| 其它格式 | MPC、CAF、DTS、CUE 等 |
首次验证不要一上来挑战全格式边界。最稳路线是先用 MP3、FLAC、WAV、M4A 跑通导入和播放，再测试 APE、DSD、CUE、高采样率、多声道或远程来源。
HiFi 输出能力
Section titled “HiFi 输出能力”ECHO 的音频输出不是只给一个设备下拉框。它要回答的是：当前声音从哪里来、被谁处理过、交给哪个后端、设备有没有独占、采样率有没有变化、DSP 有没有介入、为什么它不该被叫作 bit-perfect。
| 输出能力 | 适合谁 |
|---|---|
| System | 普通电脑、蓝牙耳机、笔记本扬声器、第一次排障 |
| WASAPI Shared | Windows 日常听歌、常见 USB DAC、长期稳定播放 |
| WASAPI Exclusive | 希望独占设备、按曲目采样率打开 DAC、减少系统混音干扰 |
| ASIO | 原厂专业声卡驱动、录音接口、明确需要 ASIO 的设备 |
| DSD / DoP | DAC 和驱动明确支持 DSD 的用户 |
| HQPlayer | 外部 HQPlayer 升频、滤波、卷积、NAA 或专业播放链路 |
ECHO 会尽量把音频状态说清楚。只要开启 EQ、ReplayGain、变速、声道工具、重采样、系统混音、蓝牙编码或虚拟声卡，就不能把结果叫作严格 bit-perfect。你可以追求更好听，也可以追求更原生，但界面不应该把处理过的声音伪装成原始直通。
如果你只是想稳定听歌，System / WASAPI Shared 就够用；如果你要使用 DAC、独占输出、ASIO、DSD 或 HQPlayer，ECHO 会提供入口，也会把风险和排障顺序说明清楚。高级输出不是单个开关，而是一条需要设备、驱动、格式和设置共同稳定的链路。
曲库管理能力
Section titled “曲库管理能力”本地曲库是 ECHO 的核心。导入文件夹之后，ECHO 会把文件、标签、封面、专辑、艺术家、播放历史和缓存状态组织成可搜索、可分页、可维护的索引。
它关注的是长期使用：
- 新歌进入
收件箱，方便先检查再归档。 - 歌曲、专辑、艺术家、文件夹都能作为不同入口。
- 大列表不应一次性塞满界面，而要分页、虚拟滚动和缓存。
- 标签、封面、网络候选和本地事实要分清优先级。
- 文件缺失、移动、重复、封面异常和标签混乱都应该能诊断，而不是只让用户重建数据库。
远程源、歌单和在线能力
Section titled “远程源、歌单和在线能力”ECHO 支持远程和在线能力，但它们是扩展，不是盗链器或下载器。
| 能力 | 支持方向 |
|---|---|
| WebDAV / NAS | 浏览和播放你有权访问的远程文件 |
| Jellyfin / Emby | 连接自己的媒体服务器和音乐库 |
| Subsonic / Navidrome | 以个人音乐服务方式浏览远程曲库 |
| DLNA / UPnP | 把当前歌曲投送到局域网数播、功放、电视或渲染器 |
| AirPlay | AirPlay 1 / RAOP 兼容链路；暂不支持 AirPlay 2 |
| 网络电台 | 播放公开网络电台流 |
| 歌单导入 | 读取网易云、QQ 音乐、Spotify 等平台中你可访问的歌单信息 |
| 视频收藏导入 | 导入 Bilibili 收藏、YouTube 播放列表、SoundCloud sets 作为可浏览集合 |
| 在线元数据 | 提供标题、艺术家、专辑、封面、歌词等候选 |
这些能力必须遵守版权、账号、地区、服务条款和访问权限。ECHO 官方不提供音乐下载服务，不提供用于获取音乐内容的下载功能，不托管、分发、售卖或镜像受版权保护的音频内容，也不支持绕过会员、破解权限或规避平台访问控制。插件音源接口只是技术扩展点，不代表官方音源或官方背书；第三方插件、接口、账号、URL 或内容来源产生的法律责任由接入者自行承担。
插件、主题和可扩展玩法
Section titled “插件、主题和可扩展玩法”ECHO 的插件系统不是“随便跑脚本”的危险入口，而是有 manifest、权限、沙箱、命令、provider、面板和受控网络 API 的本地扩展机制。
插件可以做这些事：
- 注册用户手动触发的命令。
- 提供歌词、封面、元数据或自定义音源候选。
- 显示受控插件面板。
- 保存插件自己的设置和小型数据。
- 贡献主题预设，让用户继续微调。
插件不能直接操作 SQLite、真实文件系统、主应用 DOM、音频热路径或原生输出设备。能扩展，但不能牺牲播放稳定性。
主题方面，ECHO 支持内置主题、自定义主题和 AI 生成主题 JSON。你可以调整颜色、透明度、圆角、模糊、字体和动效，但主题仍然要遵守结构化格式，不是随便把一段 CSS 扔进应用里。
| 你现在想做什么 | 推荐入口 |
|---|---|
| 下载并安装 ECHO Next | 安装与下载 |
| 第一次打开软件，连下载和安装也需要一步步看 | 零基础安装启动教程 |
| 已经装好软件，不知道先点哪里 | 快速开始 |
| 想系统看完整使用教程 | 用户教程 |
| 想导入、整理、维护本地曲库 | 曲库管理 |
| 想导入网易云、QQ 音乐、Spotify 等歌单 | 歌单导入教程 |
| 想调输出设备、WASAPI、ASIO、bit-perfect | 音频输出 |
| 想知道为什么其它软件能用、ECHO 却不承诺照做 | 为什么其他软件能这样，ECHO 不行？ |
| 想理解 EQ、DSP、削波和 Headroom | EQ 指南 |
| 想连接 WebDAV、Jellyfin、Emby、Subsonic，或需要云服务器跑 Navidrome | 远程来源 和 云盘 / Subsonic 教程；没有服务器可看雨云推荐 |
| 想确认下载、插件音源和法律责任边界 | 下载与插件音源法律边界 |
| 想把 ECHO 投到数播、功放或电视 | DLNA / 数播串流教程 |
| 想了解 AirPlay 支持边界 | AirPlay 支持边界 |
| 想写插件或看权限边界 | 插件创作指南 |
| 想做主题或让 AI 帮你生成主题 | AI 主题生成指南 |
| 想反馈 bug 或让别人帮你排查 | 如何解决问题 |
| 想看工程能力和技术栈 | 技术栈与能力支持 |
新用户建议路线
Section titled “新用户建议路线”- 先看 安装与下载，确认你拿到的是最新版本。
- 如果连下载、安装、第一次打开都不熟，先看 零基础安装启动教程。
- 按 快速开始 导入一个小文件夹，不要一上来扫完整大盘。
- 确认能播放、能看到封面、能搜索歌曲。
- 再导入完整曲库。
- 需要更高级输出时，再看 音频输出 和 EQ 指南。
- 需要在线能力时，再配置 远程来源、歌单导入、网络电台 或插件。
- 需要排查问题时，优先带上 ECHO 版本、系统版本、输出设备、文件格式、远程源类型、复现步骤和截图。
如果你只想快速听歌，直接从 快速开始 开始。先跑通，再折腾高级输出、远程源、DSP 和插件，这样最稳。
使用 AI 辅助理解
Section titled “使用 AI 辅助理解”如果你读完仍然不知道怎么操作，可以把相关文档链接、你的系统环境和具体问题交给 AI 辅助理解。下面这些外部链接会在新标签页打开，不会覆盖当前 ECHO 官网页面：
豆包 / DeepSeek / ChatGPT / Claude
作者不会逐一回答“这个功能怎么用”之类的问题。请先自查本文档和对应页面；如果仍然看不懂，可以把文档链接、系统环境和具体问题交给 AI 辅助理解。排查问题时也不要把所有电脑异常都先归因于 ECHO：例如系统网络异常、驱动、权限、杀软拦截、设备占用等，通常需要先排查本机环境。