musicdl-catalog-sync-suite/Music_Server/docs/superpowers/specs/2026-05-01-music-server-lyrics-inline-design.md

Music_Server Inline Lyrics Design

日期：2026-05-01
状态：已确认，可实现

背景

catalog-sync 现在会在下载歌曲时保存同名 .lrc，并且 NAS 上也已经启动历史歌曲补词任务。Music_Server 当前会把歌曲元数据分发给 MusicFree，但歌曲对象里没有歌词字段，导致客户端无法直接复用这些已落盘歌词。

目标

• Music_Server 在现有歌曲分发结果里内联歌词内容
• 返回字段使用 MusicFree 已支持的 rawLrc
• 直接复用 NAS 本地音乐库里与音频同目录、同名的 .lrc

非目标

• 不新增独立歌词接口
• 不新增歌词搜索、翻译歌词、远程歌词回源
• 不修改 catalog-sync 的下载逻辑

设计

数据来源

• 歌曲文件定位仍以 catalog_read.db 的 catalog_track_files 为准
• 仅当歌曲存在 backend_type = 'local_fs' 的可播放文件定位时，尝试读取歌词
• 歌词路径规则：<audio_path 去掉扩展名>.lrc

返回形态

• 在现有 musicItem 上新增可选字段 rawLrc
• 有歌词时返回字符串
• 没有歌词时不返回或为 null 均可；实现上优先省略空值

读取约束

• 仅允许在 LOCAL_LIBRARY_ROOT 根目录下解析歌词文件
• 使用与本地音频流相同的安全路径约束，防止越界访问
• 读取失败、文件不存在、编码异常时按“无歌词”处理，不影响歌曲列表接口

影响面

• 后端歌曲映射：搜索、歌单歌曲、榜单歌曲、歌手作品等所有 _to_music_item() 输出
• 插件资产：music_server.js、music_server_lan.js 需要透传 rawLrc

测试

• 路由测试：存在同名 .lrc 时，/mf/v1/search/songs 与 tracks 类接口返回 rawLrc
• 路由测试：未配置 LOCAL_LIBRARY_ROOT 或无 .lrc 时，不报错
• 插件资产测试：两个插件文件都包含 rawLrc 映射逻辑