跳到主要内容

音乐库管理

音乐统一由 src/theme/Root.tsx 挂载的 GlobalMusicPlayer/Client.tsx 播放。GlobalMusicPlayer/Controls.tsx 提供悬浮入口及选歌面板，MusicLibrary 仅作为面板内部按需加载的选歌组件，不再单独发布音乐库页面。歌曲数据仍在 src/components/GlobalMusicPlayer/playlist.ts，不要建立第二套播放器或重复歌单数据。

/my-playlist 保留为兼容入口，转到首页并打开选歌面板。任意站内页面使用 ?music=open 可打开面板；打开面板不自动播放，点选歌曲后才播放。文章内 MusicTrackPlayer 继续通过事件控制同一个播放器。原生播放列表按钮也打开这个选歌面板，全屏歌词由用户主动打开。

音频文件​

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

  • 文件命名：歌名-歌手.扩展名，例如 大海-张雨生.flac、MineMine.wav。
  • 周杰伦专辑类放到 static/music/周杰伦/，playlist 注册时保留子目录前缀，例如 周杰伦/一路向北.wav。
  • 扩展名支持 mp3 / wav / flac，URL 通过 toEncodedUrl 编码。
  • 不引用外部音频 URL，文件先本地化；部署时沿用共享音频目录，不将大文件加入 Git。

playlist 注册​

playlist.ts 的三个基础分组继续保留：favoriteTracks（我喜欢的音乐）、jayTracks（周杰伦）、ambientTracks（白噪音）。宝宝音乐从 /music/baby-music/manifest.json 按需载入，筛选和歌手分组由现有工具函数派生。

在对应分组末尾追加 localTrack('歌名', '歌手', '文件名')，函数根据 localLyricsFileByAudioFile 自动挂载歌词：

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

歌手归属与字段一致性​

  • 合作歌手用 & 分隔，例如 '周杰伦 & 费玉清'。
  • primaryArtistOf 取主要歌手归一，避免合作版本产生重复歌手条目。
  • 同一首歌不要在多个基础分组重复注册；KTV 等维度使用派生筛选分组。
  • 不同版本（live/remix/cover）可以独立注册，文件名后缀区分。

歌词映射​

src/components/GlobalMusicPlayer/localLyrics.ts 由脚本生成，不手工编辑。添加音频后运行：

python3 scripts/download_music_lyrics.py

添加与删除​

添加单曲时，先放好音频，在 playlist 注册，再生成歌词映射。删除时同步移除 playlist 条目、音频及对应歌词，并重新运行映射脚本，避免留下失效引用。

验证与发布​

本地运行 npm run start，在任意页面打开右下角音乐按钮，检查搜索、歌单和歌手选择、点选播放、暂停收起、进度恢复、换页连续播放和主动切换全屏歌词。验证 /my-playlist 与 ?music=open 都能打开面板且不会自动播放。桌面和手机宽度都要检查溢出、滚动和关闭入口。

遵循仓库构建与发布流程。音乐组件相关 PR 通过 music-player-check.yml 执行类型检查、文档检查、构建及浏览器回归；浏览器测试使用生成的音频夹具，不替代上线后对真实音频文件的检查。