# 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` 映射逻辑