ECHO Next 技术栈与能力支持

ECHO Next 是面向本地曲库、HiFi 输出和长期维护的桌面音乐播放器。它不是一个套在网页播放器外面的壳，而是一个由前端界面、Electron 桌面后端、本地数据库、原生音频宿主、媒体处理管线和受控插件系统组成的桌面应用工程。

本页是能力与技术栈说明。需要按 GitHub 当前 main 分支核对版本号、依赖、构建脚本和平台产物时，请看 GitHub 源码快照。

项目的技术目标很明确：

• 本地音乐库优先，网络能力只作为补全和扩展。
• 播放稳定性优先，高级输出能力必须服务于可靠播放。
• 大曲库可长期维护，列表、封面、搜索、扫描和缓存都要可分页、可恢复、可诊断。
• 用户数据安全优先，插件、远程源、网络元数据和批量操作都必须有清晰边界。

总体架构

ECHO Next 采用典型的 Electron 多进程桌面架构，但并不把业务全部堆在 Renderer 中。React 只负责界面表达和用户交互，真正的曲库、播放、数据库、系统集成和原生输出由主进程服务与原生宿主分层承担。

层级	技术与职责
前端界面层	React 18、TypeScript、Vite，负责页面、列表、播放器、歌词、MV、设置、插件面板和状态呈现
预加载桥接层	Electron preload，向 Renderer 暴露受控 API，隔离 Node、文件系统、数据库和原生能力
桌面后端层	Electron Main + TypeScript services，负责窗口、IPC、曲库、播放、缓存、插件、远程源、诊断和系统集成
本地数据层	SQLite + better-sqlite3，保存曲库索引、专辑、艺术家、封面引用、播放记录、网络候选和配置状态
媒体处理层	music-metadata、taglib-wasm、sharp、FFmpeg 工具链，负责标签、封面、技术信息、转码/探测辅助
音频输出层	原生 echo-audio-host、音频桥接服务、WASAPI、ASIO、DSD / DoP、HQPlayer 等输出链路
扩展层	本地插件沙箱、权限模型、provider、panel、命令、主题预设和受控网络 API
发布与官网层	Astro、Starlight、GitHub Releases、electron-updater 静态更新源和自动化发布脚本

这套分层的核心价值是：前端可以快速迭代体验，但不能直接越权触碰数据库、真实文件、音频设备或系统能力；后端服务可以承载重任务，但必须通过稳定 IPC 和任务队列控制风险；原生能力可以增强音频输出，但不能让整个应用被单个设备或驱动拖垮。

前端技术栈

ECHO Next 前端使用 React + TypeScript 构建，运行在 Electron Renderer 中。

技术	作用
React 18	构建页面、组件、状态驱动 UI 和交互流程
React DOM	Renderer 页面渲染
TypeScript 5	约束组件、IPC 类型、业务数据结构和共享类型
Vite / electron-vite	负责 Renderer、Main、Preload 的开发和构建
@vitejs/plugin-react	React 开发体验和构建支持
@tanstack/react-virtual	大列表、歌曲列表、专辑墙等虚拟滚动场景
lucide-react	图标系统
CSS / 主题变量	应用主题、布局、动效、透明度、圆角、字体和响应式界面
@fontsource	内置字体资源，降低系统字体差异带来的 UI 波动

前端主要负责这些用户界面：

• 歌曲、专辑、艺术家、文件夹、收件箱、播放历史、收藏、播放队列和歌单。
• 底部播放器、播放状态、设备状态、输出提示、错误提示和恢复入口。
• 歌词页、MV 页、迷你播放器、桌面歌词和沉浸式播放界面。
• 设置页中的播放、输出、歌词、MV、外观、曲库、插件、集成和诊断。
• 插件页的权限、日志、命令、面板、导入导出和主题预设。

前端不直接做这些事情：

• 不直接扫盘。
• 不直接访问 SQLite。
• 不直接读取真实音频文件。
• 不直接控制 WASAPI、ASIO、DSD 或原生音频设备。
• 不直接授予插件系统权限。

这些能力都必须经过 preload 暴露的受控 API，再由主进程服务处理。

桌面后端技术栈

ECHO Next 的“后端”不是传统 Web 后端，而是运行在 Electron Main 进程中的桌面后端。它负责连接系统能力、本地文件、数据库、原生宿主和前端界面。

模块	主要职责
Electron Main	应用生命周期、窗口管理、协议注册、系统集成和进程编排
IPC 服务	校验 Renderer 请求，暴露曲库、播放、设置、插件、远程源等受控能力
Library Service	文件扫描、元数据读取、封面缓存、专辑聚合、艺术家索引、分页查询和曲库健康
Audio Service	播放会话、设备状态、解码管线、输出桥接、音频诊断和恢复边界
Plugin Service	插件 manifest 校验、沙箱执行、权限确认、命令/provider/panel 管理
Network / Remote Services	WebDAV、媒体服务器、在线元数据、远程浏览和网络任务隔离
Diagnostics	日志、健康报告、缓存统计、错误状态和问题反馈辅助
Updater / Release	与 GitHub Release 和静态更新源配合，支持版本更新链路

主进程服务层的设计原则是“业务集中、边界稳定、重任务隔离”。Renderer 只拿到渲染所需的结构化结果，不拿数据库连接、文件句柄或原生对象。

本地数据与曲库索引

ECHO Next 使用 SQLite 作为本地曲库索引和状态存储。SQLite 适合桌面应用：部署简单、读写快、无需独立服务进程，也便于备份、迁移和诊断。

技术	用途
SQLite	保存本地曲库、专辑、艺术家、播放记录、封面引用、候选元数据和配置状态
better-sqlite3	Node/Electron 侧的同步 SQLite 访问层，由主进程服务集中调用
分页查询	歌曲列表、专辑墙、艺术家页和远程库不把全量数据塞进 Renderer
索引与排序	支持标题、艺术家、专辑、路径、最近播放、导入时间等查询维度
WAL / 事务策略	支撑扫描、批量更新和缓存刷新时的数据一致性
健康报告	用于发现缺失文件、缓存异常、标签问题和曲库维护风险

曲库能力覆盖：

• 导入本地文件夹。
• 扫描 MP3、FLAC、WAV、M4A、AAC、OGG、OPUS、WMA、ALAC、AIFF、APE、WV、DSF、DFF、CUE 等常见或进阶音频格式。
• 读取标题、艺术家、专辑、专辑艺术家、曲序、碟号、年份、流派、时长、编码、采样率、位深等信息。
• 提取嵌入封面、同目录封面和生成默认封面。
• 建立歌曲、专辑、艺术家、文件夹、收件箱、收藏、历史和播放列表视图。
• 支持重扫、缺失文件识别、移动修复候选、重复歌曲筛选和标签写入边界。

曲库索引不是用户真实音频文件的替代品。ECHO 可以记录、扫描、缓存、补全和展示音乐数据，但不应在没有用户明确确认的情况下删除、覆盖或移动真实文件。

媒体处理技术栈

ECHO Next 的媒体处理以本地文件事实为第一优先级。嵌入标签、同目录封面和用户手动编辑比网络结果更可信。

技术	用途
music-metadata	读取常见音频文件的嵌入标签、时长和技术信息
taglib-wasm	支持标签读取/写入相关能力，适合需要更精细标签处理的路径
sharp	生成封面缩略图、专辑封面和大图缓存
FFmpeg 工具链	辅助音频探测、解码、格式处理和部分导出/转换场景
iconv-lite	处理部分旧编码文本、歌词或标签兼容问题
pinyin-pro / opencc-js	中文搜索、繁简转换、拼音索引和别名匹配
kuroshiro / kuromoji	日文假名、罗马音和歌词/搜索增强

媒体处理管线遵守几个规则：

• 本地嵌入标签优先。
• 同目录封面优先于网络封面。
• 网络元数据只进入候选，不直接替代高可信字段。
• 封面以本地缓存路径进入 Renderer，不向列表返回大块二进制。
• 大曲库扫描必须可分批、可跳过未变化文件、可诊断失败原因。

音频与播放技术栈

音频是 ECHO Next 的核心。项目优先保证基础播放稳定，再提供更高级的 HiFi 输出、设备控制和外部链路。

技术 / 模块	作用
Native Audio Host	原生音频宿主，承载低层输出、设备状态和播放恢复边界
Audio Session	管理当前播放会话、队列、时钟、状态同步和错误恢复
Decoder Pipeline	解码、探测、格式判断和播放前准备
Native Output Bridge	主进程和原生音频宿主之间的输出桥接
WASAPI Shared	Windows 日常稳定输出，适合多数设备
WASAPI Exclusive	独占设备输出，适合确认稳定的 DAC 或专业接口
ASIO	面向原厂专业声卡驱动和录音接口
DSD / DoP	面向支持 DSD 的 DAC
HQPlayer	作为外部专业播放链路的控制与交接入口
SMTC Host	Windows 系统媒体控制集成
ReplayGain / EQ / DSP	音量增益、均衡、声道、重采样、变速等声音处理

输出能力包括：

• System 输出。
• WASAPI Shared / Exclusive。
• ASIO。
• DSD / DoP。
• HQPlayer 工作流。
• EQ、Preamp、ReplayGain、Headroom、声道平衡、重采样、变速、Crossfade、Automix 等处理能力。
• 采样率、位深、编码、输出设备、bit-perfect 状态和诊断提示。

只要音频经过 EQ、ReplayGain、变速、声道处理、重采样、系统混音、蓝牙编码或虚拟声卡，就不能称为严格 bit-perfect。ECHO 的技术边界是如实展示当前链路状态，而不是把处理后的声音包装成原始直通。

远程源与网络能力

ECHO Next 支持远程来源和在线能力，但这些能力是扩展，不是本地曲库的替代。

类型	支持方向
WebDAV / NAS	浏览和播放用户自有服务器上的文件
Jellyfin / Emby	访问用户自己的媒体服务器和音乐库
Subsonic / Navidrome	连接个人音乐服务
DLNA / AirPlay / Connect	局域网播放与外部设备连接能力
在线元数据	提供标题、艺术家、专辑、封面、歌词等候选
流媒体搜索候选	在合规和权限边界内提供搜索、试听或播放解析入口
代理与网络设置	解决用户网络环境中的访问、同步和候选获取问题

网络元数据采用候选与决策模型：

• 网络结果先进入候选表。
• 高置信结果只允许补缺失字段。
• 用户手动编辑、嵌入标签、同目录封面和文件夹结构优先。
• 网络封面必须进入本地封面缓存后再展示。
• 低置信结果应由用户确认，不应静默覆盖。

ECHO 官方不提供音乐下载服务，不托管、分发、售卖或镜像受版权保护的音频内容，也不支持绕过版权保护、破解会员权限或规避访问控制。

插件系统技术栈

ECHO Next 的插件系统是本地扩展机制，不是无限制脚本执行环境。插件以文件夹形式安装，由 echo.plugin.json 声明能力，在受控 VM 沙箱中运行入口脚本，并通过权限模型访问有限 API。

能力	说明
Manifest	声明插件 id、版本、入口、权限、命令、provider、面板、设置和主题预设
VM 沙箱	隔离插件运行环境，避免直接接触 Node、Electron、SQLite 和主应用 DOM
权限确认	library:read、playback:read、playback:control、network 等能力需用户确认
Commands	插件可注册用户手动触发的命令
Providers	插件可提供元数据、歌词、封面或自定义音源候选
Panels	插件面板以 sandbox iframe 显示，通过受控 postMessage bridge 与宿主通信
Settings / Storage	插件拥有自己的小型设置和 JSON 存储
Theme Presets	插件可贡献结构化主题预设，用户导入后继续微调
Network API	v2 插件通过受控网络 API 访问 http / https，不能直接使用任意 Node 网络能力

插件可以扩展体验，但不能牺牲播放稳定性。插件不能直接操作数据库、读取任意本机文件、修改音频 buffer、Hook 播放热路径、控制原生输出设备或后台全库扫描。

官网与发布技术栈

ECHO Page 是 ECHO Next 的官网、文档、更新日志和静态更新源项目。它与桌面端分离，目标是稳定、可缓存、易部署。

技术	用途
Astro	构建官网首页、下载页、更新日志页和静态输出
Starlight	承载多语言文档站、侧边栏、搜索、目录和文档布局
TypeScript	约束站点数据、发布记录、组件 props 和工具脚本
Astro Content Collections	管理文档和版本发布内容
Node.js scripts	校验发布内容、同步 GitHub Release、生成更新源
YAML	生成 Electron updater 可读取的 latest.yml
Sharp	站点图片处理和构建期优化
GitHub Releases	发布安装包、便携版、历史版本和 release notes
electron-updater	桌面端自动更新链路
electron-builder	构建 Windows NSIS、portable，以及 Linux AppImage / deb 等产物

ECHO Page 不承载桌面端业务逻辑。它负责把下载入口、版本信息、文档和更新 feed 稳定地交付出去。

平台与构建

ECHO Next 当前主要面向 Windows，同时保留 Linux 构建链路。

平台 / 产物	支持方向
Windows x64	NSIS 安装包、Portable 便携版、WASAPI、ASIO、SMTC、原生音频宿主
Linux x64	AppImage、deb、Linux 音频宿主和基础桌面集成
GitHub Release	对外分发安装包、便携包和版本说明
静态更新源	供桌面端自动更新读取

常用开发命令：

命令	作用
npm run dev	构建必要原生依赖后启动 Electron + Vite 开发环境
npm run dev:full	同时准备音频宿主和 SMTC 宿主后启动完整开发环境
npm run typecheck	TypeScript 类型检查
npm run test	运行 Vitest 测试
npm run build	构建 Main、Preload 和 Renderer
npm run build:win	构建 Windows 安装包和便携版
npm run build:linux	构建 Linux 产物
npm run verify:ffmpeg	校验 FFmpeg 工具链
npm run smoke:audio-host	原生音频宿主烟测

ECHO 支持的用户能力

从用户角度看，ECHO Next 支持这些核心场景：

场景	支持内容
本地曲库	文件夹导入、扫描、歌曲、专辑、艺术家、文件夹、收件箱、搜索、排序、分页、封面缓存
播放体验	播放队列、底部播放器、历史、收藏、歌单、系统媒体控制、错误恢复和播放诊断
HiFi 输出	System、WASAPI Shared、WASAPI Exclusive、ASIO、DSD / DoP、HQPlayer、bit-perfect 提示
声音处理	EQ、Preamp、ReplayGain、Headroom、声道处理、重采样、变速、Crossfade、Automix
歌词与 MV	本地歌词、在线候选、翻译、罗马音、歌词偏移、MV 匹配和播放页
元数据维护	嵌入标签读取、封面提取、网络候选、标签写入边界、缺失文件和重复歌曲维护
远程来源	WebDAV、NAS、Jellyfin、Emby、Subsonic / Navidrome、远程浏览和索引
扩展生态	本地插件、命令、provider、面板、设置、存储、主题预设和受控网络 API
主题外观	内置主题、自定义主题、插件主题、透明度、圆角、模糊、动效和字体风格
诊断维护	日志、健康报告、缓存统计、音频设备状态、插件错误和危险操作确认

不属于官方支持范围

为了保证安全、稳定和合规，以下内容不属于 ECHO 官方支持范围：

• 盗版、侵权、绕过付费、破解会员或规避访问控制的内容来源。
• 第三方下载站、资源站、爬虫脚本、灰色插件或不可公开验证的接口。
• ASIO4ALL、FlexASIO、Voicemeeter、虚拟声卡、改包驱动和系统级音效拦截工具的兼容性适配。
• 要求 ECHO 帮用户获取、搜索、下载受版权保护内容的请求。
• 插件直接操作 SQLite、真实文件系统、主应用 DOM、原生音频宿主或音频热路径。
• 网络元数据覆盖用户手动编辑、嵌入标签或同目录封面等高可信本地事实。
• 为不可复现、无日志、无系统环境、无文件信息的问题做无限制适配承诺。

ECHO 可以帮助用户管理和播放自己有权使用的内容，也可以通过插件和远程源扩展体验；但它不会成为侵权下载器、破解工具或不受控脚本宿主。

技术原则

ECHO Next 的技术栈选择不是为了堆名词，而是为了让播放器长期稳定：

• 前端专注交互，不直接越权触碰系统能力。
• 主进程集中业务和安全边界，所有高风险能力经过 IPC 校验。
• SQLite 承载本地曲库事实，网络结果只作为候选和补全。
• 原生音频宿主承载底层输出，Renderer 不参与音频热路径。
• 插件系统默认最小权限，扩展能力不能破坏播放稳定性。
• 大曲库路径必须分页、缓存、限流、可取消、可诊断。
• 文档和官网只公开已经确认、可以维护、不会误导用户的信息。

这就是 ECHO Next 当前的技术栈定位：用 Web 技术提供高效率桌面界面，用 Electron 主进程和本地服务承担真实桌面应用能力，用 SQLite 和媒体处理管线管理大曲库，用原生音频宿主处理关键播放链路，再用受控插件系统扩展生态。