# yue-hui

**Repository Path**: sprouting/yue-hui

## Basic Information

- **Project Name**: yue-hui
- **Description**: 悦汇，一个听音乐的应用
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 悦汇



## 介绍

这个项目简单来说就是一个听音乐的桌面应用，做这个项目之前，使用了一些国内知名的音乐软件听歌，却发现有偷偷的删除音乐的情况，我本地本来有1000来首歌的，上传到听歌软件后丢失了一些，而且现在广告越来越多，也就不想自己弄个听歌软件的想法。

后面又尝试了一些比较老的听歌软件，特别是千千静听之前的免安装版本，整体的风格还是挺喜欢的，但这软件也太老了，一些功能无法支持，还存在一些乱建文件夹的情况，然后我自己又有一些特殊的需求，比如对我收藏的歌曲进行喜欢度排序，想要支持更多的频谱图等等，然后就有了这个音乐软件。

![image-20260915095044009](README.assets/image-20260915095044009.png)

![image-20260915095101351](README.assets/image-20260915095101351.png)

支持歌曲进度条跳转。

支持各种排序方式

![image-20260915095200373](README.assets/image-20260915095200373.png)

支持多种频谱

![image-20260915095233612](README.assets/image-20260915095233612.png)

![image-20260915095252847](README.assets/image-20260915095252847.png)

![image-20260915095302012](README.assets/image-20260915095302012.png)

![image-20260915095317903](README.assets/image-20260915095317903.png)

![image-20260915095330276](README.assets/image-20260915095330276.png)

![image-20260915095339163](README.assets/image-20260915095339163.png)





## 架构设计

技术栈为 Electron + electron-vite + Vue 3

标准 Electron 三进程模型，通过 `electron.vite.config.ts` 组织：

- **主进程** `src/main/index.ts`：窗口创建（无边框自绘标题栏）、设置读写、音乐库导入。扫描与去重在 `src/main/musicScan.ts`（纯逻辑，不依赖 electron），标签解析与 IPC 在 `src/main/musicLib.ts`。渲染进程不能读盘，故扫描 / 解析全在主进程完成。
- **preload** `src/preload/index.ts`：`contextBridge.exposeInMainWorld('electronAPI', ...)`，窗口开启 `contextIsolation`，渲染进程不能直接访问 Node。
- **渲染进程** `src/renderer/`：Vue UI。`views/Home.vue`（播放控制 + 音乐库 + 歌词）、`components/layout/TitleBar.vue`（自绘标题栏）、`stores/settingsStore.ts`（设置持久化）。`@` 路径别名指向 `src/renderer`。



### 目录结构

```
src/
  main/index.ts            主进程：窗口、设置读写
  main/musicScan.ts        音乐文件扫描与去重（纯逻辑，不依赖 electron，可独立测试）
  main/musicLib.ts         音频标签解析（music-metadata）与音乐库 IPC
  main/mediaProtocol.ts    本地音频播放协议 yuehui://（含 Range 支持）
  main/range.ts            HTTP Range 头解析（纯函数，可独立测试）
  main/lyric.ts            歌词 IPC（读取某首音频的同名歌词）
  main/lyricParse.ts       LRC 的查找 / 解码 / 解析（纯函数，可独立测试）
  main/trackDetail.ts      歌曲详情：音频参数 / 标签 / 文件信息的完整解析（纯逻辑，可独立测试）
  main/thumbar.ts          任务栏缩略图工具栏按钮（Windows）
  main/thumbarIcons.ts     按钮图标（base64 内联，由脚本生成，勿手改）
  preload/index.ts         contextBridge 暴露的 electronAPI
  renderer/
    App.vue                根组件 + 全局暗色调色板与通用样式（.btn/.input/.ellipsis）
    main.ts                应用入口（Pinia + Router）
    env.d.ts               渲染进程侧 electronAPI 类型声明
    types/index.ts         跨进程传输的数据类型（Track / AppSettings 等）
    router/index.ts        memory history 路由
    components/layout/     TitleBar.vue 等布局组件
    components/player/     spectrum.ts（频谱取数 / 动力学 / 路径生成，三种样式共用）
                           SpectrumBars.vue（柱状）/ SpectrumWave.vue（曲线）/ SpectrumLine.vue（线条）
                           SpectrumSpectrogram.vue（声谱图 / 瀑布图，两种配色）
                           SpectrumAurora.vue（极光：填充式霓虹光带 + 长曝光）
                           SpectrumStrands.vue（丝线：多线条 + 泛光，同一份数据的另一种渲染）
                           LyricsPanel.vue（歌词）/ CoverArt.vue（封面唱盘）
    views/Home.vue         主界面
    stores/settingsStore.ts 设置持久化（load / save / saveSync）
    stores/libraryStore.ts  曲库操作（导入 / 喜欢计数 / 分类 / 状态提示）
    stores/playerStore.ts   播放状态（当前曲 / 队列 / 进度 / 歌词时间轴）+ 播放会话的恢复与节流落盘（§22）
scripts/
  gen-thumbar-icons.mjs     生成任务栏按钮图标（node scripts/gen-thumbar-icons.mjs）
```





## 常用构建命令

```bash
npm run dev          # 开发模式（electron-vite dev）
npm run typecheck    # 类型检查：typecheck:web + typecheck:node
npm run typecheck:web   # 仅渲染进程（vue-tsc -p tsconfig.web.json）
npm run typecheck:node  # 仅主进程 / preload（tsc -p tsconfig.node.json）
npm run build        # 构建到 out/（main / preload / renderer 三端）
npm run preview      # 预览构建产物

# 最终打包
npm run build:win
```