ECHO Next Tech Stack And Capabilities
This page is for people who want to see how the software is layered internally. You do not need it for everyday listening — start with Quick Start and the User Guide instead.
ECHO is a local music player. The window is drawn with web technology, but disk scanning, the library, playback, and sound-card control do not happen in page scripts. The UI handles display and clicks; the real work is done by main-process services and a native audio program.
To verify version numbers, dependencies, and build scripts against the current GitHub
mainbranch, see the GitHub Source Snapshot.
A few principles:
- Manage the local library first. Online covers and lyrics are only fill-ins.
- Guarantee stable sound first. Advanced output is a bonus and must never break basic playback.
- However large the library, lists and scans are batched, and failures must be diagnosable.
- Plugins, remote libraries, and batch tag edits all have boundaries. Nothing deletes your music silently.
Overall architecture
Section titled “Overall architecture”The UI (Renderer) only handles pages and clicks. The library, playback, database, system capabilities, and sound cards are handled in layers by the main process and the native audio program.
| Layer | Technology and responsibility |
|---|---|
| Frontend UI | React 18, TypeScript, Vite; pages, lists, player, lyrics, MV, settings, plugin panels, and state display |
| Preload bridge | Electron preload; exposes controlled APIs to the Renderer, isolating Node, the filesystem, the database, and native capabilities |
| Desktop backend | Electron Main + TypeScript services; windows, IPC, library, playback, caching, plugins, remote sources, diagnostics, system integration |
| Local data | SQLite + better-sqlite3; library index, albums, artists, cover references, play history, network candidates, and config state |
| Media processing | music-metadata, taglib-wasm, sharp, FFmpeg toolchain; tags, covers, technical info, transcode/probe support |
| Audio output | Native echo-audio-host, audio bridge services, WASAPI, ASIO, DSD / DoP, HQPlayer output chains |
| Extensions | Local plugin sandbox, permission model, providers, panels, commands, theme presets, controlled network API |
| Website and releases | Astro, Starlight, GitHub Releases, electron-updater static update feed, and release automation scripts |
The benefits of this layering are direct: changing the UI cannot accidentally touch the database or the sound card; heavy tasks go through background queues; one broken sound-card driver should not take the whole app down.
Frontend stack
Section titled “Frontend stack”The ECHO Next frontend is built with React + TypeScript and runs in the Electron Renderer.
| Technology | Role |
|---|---|
| React 18 | Pages, components, state-driven UI, and interaction flows |
| React DOM | Renderer page rendering |
| TypeScript 5 | Types for components, IPC, business data structures, and shared types |
| Vite / electron-vite | Development and builds for Renderer, Main, and Preload |
| @vitejs/plugin-react | React development experience and build support |
| @tanstack/react-virtual | Virtual scrolling for large lists, song lists, and album walls |
| lucide-react | Icon system |
| CSS / theme variables | App themes, layout, motion, transparency, corner radius, fonts, and responsive UI |
| @fontsource | Bundled fonts to reduce UI variance from system fonts |
The frontend is responsible for these user-facing surfaces:
- Songs, albums, artists, folders, inbox, play history, favorites, play queue, and playlists.
- The bottom player, playback state, device state, output hints, error hints, and recovery entry points.
- The lyrics page, MV page, mini player, desktop lyrics, and immersive playback view.
- Settings pages for playback, output, lyrics, MV, appearance, library, plugins, integrations, and diagnostics.
- The plugin page: permissions, logs, commands, panels, import/export, and theme presets.
The frontend does not do any of the following directly:
- Scan disks.
- Access SQLite.
- Read real audio files.
- Control WASAPI, ASIO, DSD, or native audio devices.
- Grant plugin system permissions.
All of these capabilities must go through the controlled APIs exposed by preload and then be handled by main-process services.
Desktop backend stack
Section titled “Desktop backend stack”ECHO Next’s “backend” is not a traditional web backend. It is a desktop backend running in the Electron Main process, connecting system capabilities, local files, the database, the native host, and the frontend UI.
| Module | Main responsibility |
|---|---|
| Electron Main | App lifecycle, window management, protocol registration, system integration, process orchestration |
| IPC services | Validate Renderer requests; expose controlled library, playback, settings, plugin, and remote-source capabilities |
| Library Service | File scanning, metadata reading, cover caching, album aggregation, artist indexing, paged queries, library health |
| Audio Service | Playback sessions, device state, decode pipeline, output bridging, audio diagnostics, recovery boundaries |
| Plugin Service | Plugin manifest validation, sandboxed execution, permission confirmation, command/provider/panel management |
| Network / Remote Services | WebDAV, media servers, online metadata, remote browsing, and network task isolation |
| Diagnostics | Logs, health reports, cache stats, error state, and problem-report support |
| Updater / Release | Works with GitHub Releases and the static update feed for the update chain |
The design principle for the main-process service layer is “centralized business, stable boundaries, isolated heavy work”. The Renderer receives only the structured results it needs for rendering — never database connections, file handles, or native objects.
Local data and library index
Section titled “Local data and library index”ECHO Next uses SQLite for the local library index and state storage. SQLite suits desktop apps: simple deployment, fast reads and writes, no separate server process, and easy backup, migration, and diagnostics.
| Technology | Use |
|---|---|
| SQLite | Local library, albums, artists, play history, cover references, candidate metadata, config state |
| better-sqlite3 | Synchronous SQLite access on the Node/Electron side, called centrally by main-process services |
| Paged queries | Song lists, album walls, artist pages, and remote libraries never push full datasets into the Renderer |
| Indexing and sorting | Queries by title, artist, album, path, recently played, import time, and more |
| WAL / transaction strategy | Data consistency during scans, batch updates, and cache refreshes |
| Health reports | Detect missing files, cache anomalies, tag problems, and library maintenance risks |
Library capabilities cover:
- Importing local folders.
- Scanning MP3, FLAC, WAV, M4A, AAC, OGG, OPUS, WMA, ALAC, AIFF, APE, WV, DSF, DFF, CUE, and other common or advanced audio formats.
- Reading title, artist, album, album artist, track number, disc number, year, genre, duration, codec, sample rate, bit depth, and more.
- Extracting embedded covers, using same-folder covers, and generating default covers.
- Building song, album, artist, folder, inbox, favorites, history, and playlist views.
- Rescans, missing-file detection, move-repair candidates, duplicate filtering, and tag-write boundaries.
The library index is never a substitute for your real audio files. ECHO records, scans, caches, fills in, and displays music data, but it must not delete, overwrite, or move real files without explicit user confirmation.
Media processing stack
Section titled “Media processing stack”ECHO Next’s media processing treats local file facts as the top priority. Embedded tags, same-folder covers, and manual user edits are more trustworthy than network results.
| Technology | Use |
|---|---|
| music-metadata | Read embedded tags, duration, and technical info from common audio files |
| taglib-wasm | Tag read/write support for paths that need finer tag handling |
| sharp | Generate cover thumbnails, album covers, and large-image caches |
| FFmpeg toolchain | Audio probing, decoding, format handling, and some export/convert scenarios |
| iconv-lite | Legacy text encodings in lyrics or tags |
| pinyin-pro / opencc-js | Chinese search, simplified/traditional conversion, pinyin indexing, alias matching |
| kuroshiro / kuromoji | Japanese kana, romaji, and lyrics/search enhancement |
The media pipeline follows a few rules:
- Local embedded tags win.
- Same-folder covers beat network covers.
- Network metadata only enters the candidate pool; it never directly replaces high-confidence fields.
- Covers reach the Renderer as local cache paths, never as large binary blobs in lists.
- Large-library scans must be batchable, skip unchanged files, and report failure causes.
Audio and playback stack
Section titled “Audio and playback stack”Audio is the core of ECHO Next. The project guarantees stable basic playback first, then layers on HiFi output, device control, and external chains.
| Technology / module | Role |
|---|---|
| Native Audio Host | Native audio host for low-level output, device state, and playback recovery boundaries |
| Audio Session | Manages the current session, queue, clock, state sync, and error recovery |
| Decoder Pipeline | Decoding, probing, format detection, and pre-playback preparation |
| Native Output Bridge | Output bridging between the main process and the native audio host |
| WASAPI Shared | Everyday stable Windows output, right for most devices |
| WASAPI Exclusive | Exclusive device output for confirmed-stable DACs or professional interfaces |
| ASIO | For vendor professional sound-card drivers and recording interfaces |
| DSD / DoP | For DSD-capable DACs |
| HQPlayer | Control and hand-off entry point for an external professional playback chain |
| SMTC Host | Windows system media control integration |
| ReplayGain / EQ / DSP | Gain, equalization, channels, resampling, speed change, and other processing |
Output capabilities include:
- System output.
- WASAPI Shared / Exclusive.
- ASIO.
- DSD / DoP.
- HQPlayer workflows.
- EQ, Preamp, ReplayGain, Headroom, channel balance, resampling, speed change, Crossfade, and Automix.
- Sample rate, bit depth, codec, output device, bit-perfect state, and diagnostic hints.
The moment audio passes through EQ, ReplayGain, speed change, channel processing, resampling, system mixing, Bluetooth codecs, or a virtual sound card, it can no longer be called strictly bit-perfect. ECHO’s technical boundary is to display the current chain state honestly — never to dress up processed audio as raw pass-through.
Remote sources and network capabilities
Section titled “Remote sources and network capabilities”ECHO Next supports remote sources and online capabilities, but they are extensions, not replacements for the local library.
| Type | Supported direction |
|---|---|
| WebDAV / NAS | Browse and play files on your own servers |
| Jellyfin / Emby | Access your own media servers and music libraries |
| Subsonic / Navidrome | Connect to personal music services |
| DLNA / AirPlay / Connect | LAN playback and external device connections |
| Online metadata | Candidates for titles, artists, albums, covers, lyrics |
| Proxy and network settings | Handle access, sync, and candidate fetching in your network environment |
Network metadata uses a candidate-and-decision model:
- Network results enter a candidate table first.
- High-confidence results may only fill empty fields.
- Manual edits, embedded tags, same-folder covers, and folder structure take priority.
- Network covers must enter the local cover cache before display.
- Low-confidence results require user confirmation and are never applied silently.
ECHO does not officially provide music downloads, does not host, distribute, sell, or mirror copyrighted audio content, and does not support bypassing copy protection, cracking membership entitlements, or evading access controls.
Plugin system stack
Section titled “Plugin system stack”ECHO Next’s plugin system is a local extension mechanism, not an unrestricted script environment. Plugins are installed as folders, declare capabilities in echo.plugin.json, run their entry script in a controlled VM sandbox, and access a limited API through the permission model.
| Capability | Description |
|---|---|
| Manifest | Declares plugin id, version, entry, permissions, commands, providers, panels, settings, and theme presets |
| VM sandbox | Isolates the plugin runtime from Node, Electron, SQLite, and the host app’s DOM |
| Permission confirmation | Capabilities like library:read, playback:read, playback:control, and network require user confirmation |
| Commands | Plugins can register user-triggered commands |
| Providers | Plugins can provide metadata, lyrics, cover, or custom source candidates |
| Panels | Plugin panels render in sandboxed iframes and talk to the host over a controlled postMessage bridge |
| Settings / Storage | Plugins get their own small settings and JSON storage |
| Theme presets | Plugins can contribute structured theme presets that users import and fine-tune |
| Network API | v2 plugins access http / https through a controlled network API, never raw Node networking |
Plugins can extend the experience but never at the cost of playback stability. Plugins cannot directly operate the database, read arbitrary local files, modify audio buffers, hook the playback hot path, control native output devices, or run full-library background scans.
Website and release stack
Section titled “Website and release stack”ECHO Page is the website, docs, changelog, and static update feed for ECHO Next. It is separate from the desktop app and aims to be stable, cacheable, and easy to deploy.
| Technology | Use |
|---|---|
| Astro | Home page, download page, changelog, and static output |
| Starlight | Multilingual docs site, sidebar, search, table of contents, and docs layout |
| TypeScript | Types for site data, release records, component props, and utility scripts |
| Astro Content Collections | Manage docs and release content |
| Node.js scripts | Validate release content, sync GitHub Releases, generate the update feed |
| YAML | Generate the latest.yml read by the Electron updater |
| Sharp | Site image processing and build-time optimization |
| GitHub Releases | Distribute installers, portable builds, history, and release notes |
| electron-updater | The desktop auto-update chain |
| electron-builder | Windows NSIS and portable builds, plus Linux AppImage / deb artifacts |
ECHO Page carries no desktop business logic. Its job is to deliver download entry points, version info, docs, and the update feed reliably.
Platforms and builds
Section titled “Platforms and builds”ECHO Next currently targets Windows first while keeping the Linux build chain alive.
| Platform / artifact | Supported direction |
|---|---|
| Windows x64 | NSIS installer, portable build, WASAPI, ASIO, SMTC, native audio host |
| Linux x64 | AppImage, deb, Linux audio host, basic desktop integration |
| GitHub Releases | Public distribution of installers, portable builds, and release notes |
| Static update feed | Read by the desktop auto-updater |
Common development commands:
| Command | Purpose |
|---|---|
npm run dev | Build required native dependencies, then start the Electron + Vite dev environment |
npm run dev:full | Prepare the audio host and SMTC host, then start the full dev environment |
npm run typecheck | TypeScript type checking |
npm run test | Run Vitest tests |
npm run build | Build Main, Preload, and Renderer |
npm run build:win | Build the Windows installer and portable build |
npm run build:linux | Build Linux artifacts |
npm run verify:ffmpeg | Verify the FFmpeg toolchain |
npm run smoke:audio-host | Smoke-test the native audio host |
User-facing capabilities
Section titled “User-facing capabilities”From a user’s perspective, ECHO Next supports these core scenarios:
| Scenario | What is supported |
|---|---|
| Local library | Folder import, scanning, songs, albums, artists, folders, inbox, search, sort, paging, cover cache |
| Playback experience | Play queue, bottom player, history, favorites, playlists, system media controls, error recovery, playback diagnostics |
| HiFi output | System, WASAPI Shared, WASAPI Exclusive, ASIO, DSD / DoP, HQPlayer, bit-perfect hints |
| Sound processing | EQ, Preamp, ReplayGain, Headroom, channel processing, resampling, speed change, Crossfade, Automix |
| Lyrics and MV | Local lyrics, online candidates, translation, romaji, lyric offsets, MV matching, playback page |
| Metadata maintenance | Embedded tag reading, cover extraction, network candidates, tag-write boundaries, missing files, duplicates |
| Remote sources | WebDAV, NAS, Jellyfin, Emby, Subsonic / Navidrome, remote browsing and indexing |
| Extension ecosystem | Local plugins, commands, providers, panels, settings, storage, theme presets, controlled network API |
| Themes and appearance | Built-in themes, custom themes, plugin themes, transparency, corner radius, blur, motion, font styles |
| Diagnostics and maintenance | Logs, health reports, cache stats, audio device state, plugin errors, dangerous-action confirmation |
Outside official support
Section titled “Outside official support”To stay safe, stable, and compliant, the following are outside ECHO’s official support:
- Pirated, infringing, payment-bypassing, membership-cracking, or access-control-evading content sources.
- Third-party download sites, resource sites, scraper scripts, gray-area plugins, or APIs that cannot be publicly verified.
- Compatibility work for ASIO4ALL, FlexASIO, Voicemeeter, virtual sound cards, repacked drivers, and system-wide audio interception tools.
- Requests that ECHO help users obtain, search for, or download copyrighted content.
- Plugins directly operating SQLite, the real filesystem, the host DOM, the native audio host, or the audio hot path.
- Network metadata overwriting manual edits, embedded tags, same-folder covers, or other high-confidence local facts.
- Unlimited compatibility promises for problems with no reproduction, no logs, no system environment, and no file information.
ECHO helps users manage and play content they have the right to use, and it can extend the experience through plugins and remote sources. It will not become an infringing downloader, a cracking tool, or a host for uncontrolled scripts.
Technical principles
Section titled “Technical principles”ECHO Next’s stack was not chosen to stack buzzwords, but to keep the player stable long-term:
- The frontend focuses on interaction and never reaches directly into system capabilities.
- The main process centralizes business logic and security boundaries; every high-risk capability passes IPC validation.
- SQLite holds the local library facts; network results are only candidates and fill-ins.
- The native audio host owns the low-level output; the Renderer never touches the audio hot path.
- The plugin system defaults to minimum permission; extensions may never break playback stability.
- Large-library paths must be paged, cached, rate-limited, cancelable, and diagnosable.
- Docs and the website only publish information that is confirmed, maintainable, and not misleading.
That is where ECHO Next’s stack stands today: web technology for an efficient desktop UI, the Electron main process and local services for real desktop-app capabilities, SQLite and a media pipeline for large libraries, a native audio host for the critical playback chain, and a controlled plugin system for the ecosystem.