PROJECT KNOWLEDGE BASE
Generated: 2026-04-11 01:00:58 (Asia/Shanghai) Commit: 26da4c2 Branch: main
OVERVIEW
Ceru Music (澜音) is an Electron + Vue 3 + TypeScript desktop music player that relies on user-supplied plugins for lawful music metadata. The repo mixes Node/Electron main process code, Vue renderer, and an external website/docs bundle.
STRUCTURE
./
├── src/ # main Electron code + renderer + shared types
│ ├── main/ # Electron main process (IPC, services, plugin host)
│ ├── renderer/ # Vue 3 renderer (nested src/, assets, auto-import setup)
│ ├── preload/ # Context bridge exposing safe IPC APIs
│ ├── common/ # Shared TS types + lyric utilities
│ └── types/ # Extra shared declarations
├── docs/ # VitePress documentation site
├── website/ # Static marketing microsite
├── scripts/ # Helper Node scripts (auth test, AST dump)
├── resources/ # Build assets (icons, thumbar artwork)
├── assets/ # Screenshots + readme media
└── .github/workflows/ # CI pipelines (build + release sync)
WHERE TO LOOK
| Task | Location | Notes |
|---|---|---|
| Electron main IPC, services, windowing | src/main/ | Home of download manager, plugin host, music SDK wrappers, IPC events |
| Renderer UI + state | src/renderer/src/ | Vue 3 + Pinia. Components auto-imported via unplugin. Entry at main.ts |
| Preload bridge APIs | src/preload/index.ts | Defines channel surface exposed to renderer, keep in sync with IPC events |
| Shared types/utilities | src/common/, src/types/ | Basic TS declarations reused by main + renderer |
| Docs site | docs/ | VitePress (see .vitepress config), high-level guides |
| CI/CD + release sync | .github/workflows/ | Builds, release publishing, WebDAV/Alist sync |
| Desktop resources | resources/, build/ | Icons, NSIS scripts, thumbar images used by packaging |
CODE MAP
| Symbol | Type | Location | Refs | Role |
|---|---|---|---|---|
createWindow | function | src/main/index.ts | electron entry | Creates main BrowserWindow, manages bounds + tray integration |
setupDownloadManager | function | src/main/index.ts | ipc/events | Configures download worker, lyrics/url fetchers, IPC handlers |
CeruMusicPluginHost | class | src/main/services/plugin/manager/CeruMusicPluginHost.ts | plugins | Runs Ceru plugins in sandbox, mediates host <-> plugin bridge |
useSettingsStore | Pinia store | src/renderer/src/store/Settings.ts | renderer | Global settings state with persisted preferences |
FullPlay.vue | component | src/renderer/src/components/Play/FullPlay.vue | player UI | Main player UI w/ apple-music-like lyrics + comments overlay |
CONVENTIONS
- Formatting: Prettier (single quotes, no semicolons, 2-space indent, 100 char width). ESLint is extremely relaxed—runtime correctness over strict typing.
- Path aliases:
@common,@renderer,@types,@assets,@store,@services. Match tsconfig + electron.vite aliases before moving files. - Auto-imports: Vue composition APIs plus naive-ui/tdesign components, and most local components are globally available (see
src/renderer/auto-imports.d.ts&components.d.ts). Pinia helpers still require explicit imports. - Package manager: Yarn. Scripts assume yarn commands, CI locks to Node 22.
- IPC naming:
download:*,music:*,plugin:*channels followdomain:actionscheme. Keep renderer + preload definitions synchronized.
ANTI-PATTERNS (THIS PROJECT)
- Don’t fail downloads on lyric errors (
DownloadManager.ts): treat lyrics as optional to keep queue healthy. - Avoid per-task resume loops (
DownloadManager.ts): batch state changes so the queue isn’t double-processed. - Don’t re-register global event listeners in layouts (
HomeLayout.vue): centralize inApp.vueto prevent conflicts. - Sync audio timers only when drift >2s (
PlayMusic.vue): prevents jitter in DLNA playback. - Use requested page index for comment paging (
GlobalPlayStatus.ts): some APIs are 0-based; using response page leads to infinite fetch loops. - Enable fuzzy search only for short queries (
utils/search.ts): long queries would match noise. - When converting buffers, handle byteOffset (
RecognitionWorker.vue): Node Buffer != ArrayBuffer.
UNIQUE STYLES
- Triple asset pools (
assets/,resources/,src/renderer/src/assets/)—know which pipeline consumes each before editing. - Renderer state uses Pinia with persisted slices (see
pinia-plugin-persistedstate), plus custom pub/sub inControlAudio. - Music SDK layer blends TS + legacy JS vendor blobs per platform—expect uneven style.
- Docs + marketing site both live in-repo (
docs/,website/), but they are separate builds.
COMMANDS
yarn dev # Electron dev with hot reload
yarn build # Typecheck + electron-vite production build
yarn build:win|mac|linux # Platform-specific electron-builder targets
yarn test # Jest (ts-jest) test suite
yarn docs:dev # VitePress docs dev server
NOTES
- CI release workflow (
.github/workflows/main.yml) builds three platforms in parallel and pushes artifacts to GitHub Release + WebDAV mirrors. Keep file names stable. - Electron mirrors configured via
.npmrc(npmmirror) to speed Chinese network—retain when updating dependencies. - Worker thread (
src/main/workers/downloadWorker.ts) shares code with main through@common—changing interfaces requires dual updates.