GitHub Source Snapshot

This page is based on the Moekotori/ECHO GitHub repository on the main branch. It is not a roadmap and does not promise future features. It records current source-backed engineering facts visible in README.md, package.json, and docs/ECHO_NEXT_*.md.

Repository Facts

Item	Current state
Repository	Moekotori/ECHO
Default branch	main
Visibility	Public
Package name	echo-next
Current package.json version	26.6.7
License	Apache-2.0
Electron appId	app.echo.next
Product / executable name	ECHO NEXT

End-user downloads should still follow GitHub Releases and the official website mirror notes. This snapshot is for understanding engineering structure and maintenance boundaries.

Product Positioning

The GitHub README positions ECHO NEXT as an open-source desktop music player for local libraries, HiFi output, and long-term maintenance. The source docs describe it as a boundary-first rebuild rather than another patch layer on top of old ECHO.

Current engineering priorities:

1. Reliable local playback.
2. Stable audio chain.
3. Large libraries without blocking the Renderer.
4. User data safety.
5. Network capabilities as completion and extension only, never above local library and playback stability.

Runtime Layers

The source architecture is layered like this:

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, plugins, remote sources

Important boundaries:

• Renderer owns pages, lists, lyrics, MV, settings, and playback control UI.
• Preload exposes typed window.echo.* APIs; it must not expose raw ipcRenderer, Node fs, path, or process.
• The main process composes windows, IPC, services, and system integration; domain logic belongs in services.
• Library Core is the local-library source of truth; the Renderer should not hold the full library or rebuild album walls in memory.
• Audio Core is the playback source of truth; the Renderer should not guess authoritative playback position.
• Native hosts handle audio output, DSP, SMTC, and low-level helpers that Electron/Node should not do directly.

Main Technology Stack

Area	Current GitHub dependency / signal
Desktop runtime	Electron ^37.10.3, electron-vite ^5.0.0, electron-builder ^26.8.1
Frontend	React ^18.2.0, React DOM ^18.2.0, TypeScript ^5.3.3, Vite ^7.3.3
UI and motion	lucide-react, motion, @tanstack/react-virtual, @fontsource/outfit
Local database	SQLite through better-sqlite3 ^12.9.0
Media processing	music-metadata, sharp, taglib-wasm, FFmpeg tooling
Text/search helpers	iconv-lite, pinyin-pro, opencc-js, kuroshiro, kuromoji
Playback/media	Native audio host, shaka-player, HQPlayer / Connect-related services
AirPlay RAOP	Optional dependency @lox-audioserver/node-libraop, with packaged airplayRaopHelper.cjs
Testing	Vitest ^4.1.6, Testing Library, jsdom, Playwright

Dependency names prove what the current source includes. They do not automatically make every scenario an official support promise. Public support boundaries still come from user docs, settings copy, and release notes.

Build Scripts

Key package.json scripts:

Script	Purpose
npm run dev	Rebuild native modules, ensure audio host, then start Electron + Vite development
npm run dev:full	Build the SMTC host too before starting full development
npm run build	Type-check, then run electron-vite build
npm run build:win	Full Windows build: native rebuild, FFmpeg verify, audio host, SMTC host, native scanner, Electron build, NSIS resources, electron-builder, and AirPlay package verification
npm run build:win:unsigned	Unsigned Windows build path that still runs AirPlay package verification
npm run build:linux	Build Linux x64 packages through scripts/build-linux.mjs
npm run test	Run Vitest
npm run typecheck	Run TypeScript type-checking
npm run verify:ffmpeg	Verify the FFmpeg toolchain
npm run verify:airplay-package	Verify packaged Windows AirPlay RAOP resources
npm run smoke:audio-host / smoke:native-scanner / smoke:smtc-host	Smoke-test native helpers

Documentation-only changes usually do not need a full desktop build. For ECHO Page docs, npm run build in this website repository is the direct validation. For desktop app changes, choose the platform and script that matches the touched surface.

Platforms And Artifacts

Platform	Current source configuration
Windows x64	NSIS installer and portable build, product name ECHO NEXT, shortcut name ECHO
Linux x64	AppImage and deb
macOS	No macOS build target in package.json

Windows packaged resources include:

• echo-audio-host.exe
• echo-smtc-host.exe
• echo-native-scanner.exe
• airplayRaopHelper.cjs
• electron-app/tools

Linux packaged resources include:

• echo-audio-host
• echo-native-scanner
• electron-app/tools-linux

The Linux source doc defines the current Linux boundary as x64 first-stage support: AppImage/deb, local library scanning, local WAV / FLAC / MP3 playback, Linux shared native output, and ALSA backend. Linux arm64, Flatpak, Snap, native JACK, native PipeWire, and Linux exclusive/bit-perfect HiFi backend should not be described as supported.

Source-Document Boundaries

Library Core

• SQLite is the local-library source of truth.
• Scans, metadata, covers, album grouping, search indexes, health reports, and move candidates stay inside main-process service boundaries.
• Renderer receives paged data only; it should not read SQL, hold the full library, generate covers, or rebuild album walls.
• Watcher and move repair behavior must stay conservative. No automatic deletion, automatic merging, or silent moving of real audio files.

Audio Core

• Audio Core owns playback, clock, output devices, decoding, DSP state, and HiFi explainability.
• Stable local playback is higher priority than lyrics, MV, downloads, network tasks, or plugins.
• Playback position should come from the output side or authoritative Audio Core state; Renderer timers are not authoritative.
• WASAPI Shared, WASAPI Exclusive, ASIO, DSD, ReplayGain, EQ, resampling, and bit-perfect states must be represented honestly.

Network Metadata

• Network metadata is weak completion, not a second metadata reader.
• pending / reading does not mean missing.
• Network results first go to candidate and decision tables. They must not overwrite manual, embedded, sidecar, or folder-structure facts.
• Network artwork must pass through the local cover cache before display; remote URLs are not final artwork truth.

Linux Build

• Linux packages must be built on Linux x64.
• build:linux checks platform, FFmpeg, native ABI, audio host, electron-builder artifacts, and packaged resources.
• CI success proves that packages were produced; it does not prove real desktop audio validation.

Maintenance Guidance

When updating this page, re-check the current GitHub package.json, README.md, and docs/ECHO_NEXT_*.md first. Do not publish old roadmap items, experimental ideas, issue discussion, or local unpublished branches as public capabilities.

If source facts and official website language conflict, prioritize user safety, playback stability, and actual release notes, then decide whether to update website docs or wait for the desktop implementation to stabilize.