KK-BOX 音乐播放器工程技能
1. 项目概览
KK-BOX 音乐播放器（界面品牌名「橙贴音乐播放器」，v1.2.0）是一款完全本地、绿色免安装的音乐播放器，两个交付形态：
- 桌面版（Electron 44.5.1 + Chromium 内核）：源码在
assets/electron-app/，内置 BASS 原生无损解码、10 段 EQ、歌词/桌面歌词、MV 播放、贴边吸附等。 - 网页版：
assets/web-player/KK-BOX音乐播放器.html，单文件自包含（无外部依赖），可直接双击打开或作为静态站发布。
完整功能清单、快捷键、解码格式矩阵、界面说明见 references/使用说明.md（权威文档，改动功能后同步更新它）。
2. 包内结构
| 路径 | 内容 |
|---|---|
references/使用说明.md |
完整使用说明 + 架构 + 打包/测试命令（权威文档） |
references/screenshots/ |
双界面截图与主题图 |
assets/web-player/ |
单文件网页版播放器（自包含） |
assets/icons/ |
22 枚界面图标 + LOGO（PNG） |
assets/electron-app/ |
Electron 桌面版源码（不含 node_modules） |
assets/electron-app/main.js |
主进程：窗口、GPU 看门狗、kkbass:// 协议、转码、播放列表 |
assets/electron-app/preload.js |
contextBridge 暴露的 IPC 接口面（window.api） |
assets/electron-app/lib/bass.js |
BASS FFI 解码桥（ffi-rs 调 bass.dll，PCM→WAV 流） |
assets/electron-app/lib/id3.js |
标签解析：ID3v2 / Vorbis / ilst / APEv2 / ID3v1 |
assets/electron-app/renderer/ |
界面：index.html（双界面）+ 歌词窗 + 视频窗 + mpegts.js |
assets/electron-app/bass/ |
bass.dll + 11 个解码插件（约 870KB） |
assets/electron-app/tools/ffmpeg.exe |
视频转码 / 终极兜底解码（UPX 压缩，约 25MB） |
scripts/tests/ |
回归测试（纯 Node）+ samples/ 测试音频 + *_out.txt 上次结果 |
scripts/tools/upx.exe |
构建期压缩 ffmpeg 用 |
scripts/optimize_dist.py |
打包后体积优化脚本 |
3. 核心工作流
3.1 运行网页版
直接打开 assets/web-player/KK-BOX音乐播放器.html。要以在线链接分享时，用 sites 工具发布该文件所在目录（language 设为 static，entryHtml 指向该文件名）。
3.2 桌面版开发运行
cd assets/electron-app
npm install # 首次：安装 electron / electron-packager / ffi-rs
npm start # electron .
依赖未随包分发（node_modules 不在包内）；ffi-rs 需要预编译 .node，npm install 会自动拉取。
3.3 改代码前必须掌握的架构要点
- 解码分流：Chromium 原生支持的格式（MP3/WAV/FLAC/OGG/M4A/Opus）走内核硬件解码；不支持的（WMA/APE/WV/TTA/MPC/AIFF/AC3/SPX/MP2/ALAC）走 BASS 原生解码；两者都失败才回退 ffmpeg。改解码逻辑时保持这条三级链。
- BASS 桥（
lib/bass.js）：ffi-rs 进程内调 bass.dll，32 位浮点优先、不支持自动降 16 位；通过自定义kkbass://协议向渲染层供流（支持 Range/206/seek）。 - 标签（
lib/id3.js）：APE/WavPack/MPC/TTA 的 APEv2 标签在文件末尾；旧工具 GBK 标签需 UTF-8 失败后回退系统码页。 - GPU 策略：默认硬件加速 + GPU 崩溃看门狗（60 秒内崩溃 3 次自动切软件渲染并写入 config.json）；强制软件渲染用
--disable-gpu或环境变量KKBOX_SOFTWARE_RENDER=1。 - BASS 组件定位顺序：随包
bass/目录 → 环境变量KKBOX_BASS_DIR→config.json的bassDir→ 由ProgramFiles环境变量推导的标准安装位置（Program Files 下的 AIMP）→ 回退 ffmpeg。不扫描盘符、不探测个人目录。 - 渲染层通信：只走
window.api（preload.js 白名单），新增能力必须同时在 main.js 注册 ipcMain handler 并在 preload.js 暴露。
3.4 安全约定（改代码时勿破坏）
- 环境变量白名单：全工程只读取两个业务变量——
KKBOX_BASS_DIR（BASS 组件目录）与KKBOX_SOFTWARE_RENDER（强制软件渲染）；BASS 定位另外读取系统标准变量ProgramFiles/ProgramFiles(x86)。严禁新增遍历、打印环境变量的代码，禁止把系统级凭据写进日志或 stdout。 - 无私钥/无凭证：代码与随包文件中不含任何私钥、证书、口令；
config.json只存界面偏好。新增需要密钥的能力时，一律走平台密钥管理或系统安全存储，禁止硬编码或随包分发。 - 无个人绝对路径：所有路径按
__dirname相对推导或经环境变量/命令行传入；测试样本路径用KKBOX_TEST_MP4等环境变量注入，打包产物路径用KKBOX_DIST_MAIN/KKBOX_DIST_DIR覆盖。
3.5 回归测试（纯 Node，无需 GUI）
cd assets/electron-app
node ../scripts/tests/test_bass.js # BASS 解码 + 虚拟 WAV 流 + 位精确性
node ../scripts/tests/test_bassproto.js # kkbass:// 协议（Range/206/404/seek）
node ../scripts/tests/test_ape_tags.js # APEv2 / ID3v1
node ../scripts/tests/test_id3.js # ID3v2 / Vorbis / ilst
node ../scripts/tests/test_lyric.js # 歌词本地匹配
node ../scripts/tests/test_lrc.js # LRC / SRT 解析
改完解码、标签、歌词、协议相关代码后必须全套跑一遍；*_out.txt 是上次通过的结果，可作比对基线。Electron 端到端测试需本机已 npm install。
3.6 重新打包绿色版 EXE
cd assets/electron-app
npx electron-packager . KK-BOX音乐播放器 --platform=win32 --arch=x64 ^
--icon=icon.ico --out=../dist --overwrite --app-version=1.2.0
cd ../..
python scripts/optimize_dist.py
改了 tools/ffmpeg.exe 后需重新压缩：scripts/tools/upx.exe -9 assets/electron-app/tools/ffmpeg.exe。打包产物 dist/ 未包含在本包内，按需生成。
4. 授权与合规（重要）
assets/electron-app/bass/ 内的 BASS 及官方插件是 un4seen 的非商业授权软件。本包仅供个人自用与学习；对外分发前要么自行向 un4seen 购买授权，要么删除这些 DLL——程序会自动从标准安装位置寻找，找不到则回退 ffmpeg，功能降级但不报错。向用户提分发建议时必须带上这条提醒。
5. 边界
- 本包不含 node_modules、dist 打包产物、构建备份等中间文件。
- 播放器完全本地运行，不联网（仅歌词搜索会访问 lrclib.net，用户主动触发）。
- 修改功能后同步更新
references/使用说明.md，保持文档与代码一致。
