音乐库管理

音乐库渲染入口是 docs/04-人生丰富/04-音乐/04-音乐.mdx 引入的 <MusicLibrary /> 组件，数据源在 src/components/GlobalMusicPlayer/playlist.ts。

音频文件

所有音频文件统一放在 static/music/ 下。

• 文件命名：歌名-歌手.扩展名，歌手不固定时长就放末尾便于一眼辨别，例如 大海-张雨生.flac、MineMine.wav
• 周杰伦专辑类可以放到 static/music/周杰伦/ 子目录，playlist 注册时相对路径保留子目录前缀，例如 周杰伦/一路向北.wav
• 扩展名支持 mp3 / wav / flac，URL 通过 toEncodedUrl 处理编码（中日韩文件名会被编码）
• 引用原则：不允许引用任何外部音频 URL，文件必须本地化（与 仓库结构 一致）

playlist 注册

playlist.ts 内三个分组，对应音乐库侧栏的三个"歌单"：

• favoriteTracks —— 我喜欢的音乐（默认展示的分组，新增单曲优先放这里）
• jayTracks —— 周杰伦（专用分组，避免污染收藏列表长度）
• ambientTracks —— 白噪音（环境音、BBC 采样等）

每个分组末尾追加一条 localTrack('歌名', '歌手', '文件名')。localTrack 自动根据 localLyricsFileByAudioFile 映射挂载歌词：

localTrack('大海', '张雨生', '大海-张雨生.flac'),

歌手归属与字段一致性

• 合作歌曲歌手用 & 分隔，例如 '周杰伦 & 费玉清'
• primaryArtistOf 工具函数会取 & 前的歌手做归一，所以即使同一首歌的合作版本分别注册（周杰伦 和 周杰伦 & 梁心颐），歌手抽屉不会重复建条目
• 同一首歌不要在多个分组都注册（避免播放总数虚高）。如需分组表达，改用 musicFilterDefinitions 加"KTV 拿手曲目"等筛选维度
• 同一首歌的不同版本（live/remix/cover）可以独立注册，文件名后缀区分

歌词映射

localLyricsFileByAudioFile 在 src/components/GlobalMusicPlayer/localLyrics.ts，由 scripts/download_music_lyrics.py 自动生成。不要手工编辑该文件，加完音频后跑一次脚本即可补齐映射。运行方式：

python3 scripts/download_music_lyrics.py

添加单曲的标准流程

1. 把音频文件放到 static/music/（周杰伦专辑类放到 static/music/周杰伦/）
2. 在 playlist.ts 对应分组末尾追加一条 localTrack 调用
3. 跑 scripts/download_music_lyrics.py 补歌词映射（无可跳过）
4. 本地 npm run start 在 /my-playlist 验证能搜索到、能正常播放、歌词对齐
5. 提交并按 仓库结构 中"git push 前必须向用户确认"的流程发布

删除单曲

1. 删除 playlist.ts 中对应 localTrack 行
2. 删除 static/music/ 下对应音频
3. 删除歌词（如果有 .lrc 文件，并从 localLyrics.ts 中移除映射；或重新跑 scripts/download_music_lyrics.py 同步）
4. 不要留 dead 引用