[Feature]: 添加歌曲元数据修改功能

[Azincc]

背景与痛点

无法修正错误的元数据

期望方案

添加歌曲元数据修改功能，支持在客户端内补充或修正曲名、专辑、歌手等信息

备选方案

No response

影响平台

No response

其他补充

No response

提交前确认

• 我已搜索现有 issues，确认不是重复需求

[Azincc]

1. 背景

当前 Echoes 已支持通过 Embed Service 进行离线下载和自动元数据写入，但对于“音乐库内已有歌曲”的元数据错误场景，缺少用户可控的修正能力。

典型问题包括：

• 标题、歌手、专辑信息错误
• 封面缺失或错误
• 歌词缺失或不匹配
• 自动识别结果不稳定，用户无法手动选择更合适的方案

因此需要新增一套“候选元数据获取 + 用户预览选择 + 服务端写回文件标签”的能力，提升音乐库元数据质量和可维护性。

2. 产品目标

本功能的目标是：

• 允许用户对音乐库内已有歌曲发起元数据修正
• 由 Embed Service 返回多个候选元数据方案供用户预览
• 允许用户选择一个候选方案，并在 Echoes 中进一步手工修改
• 由 Embed Service 将用户最终确认的元数据写入音频文件
• 写入完成后触发 Navidrome 扫描，使客户端可见最新结果

3. MVP 范围

MVP 包含：

• 单曲元数据修改
• 获取候选元数据列表
• 候选预览
• 用户选择候选后进行少量手工编辑
• 提交最终完整元数据对象
• 服务端异步写标签
• 封面下载并内嵌
• 歌词写入标签或 sidecar 文件
• 写入后触发 Navidrome 扫描
• Echoes 轮询任务状态并提示结果

MVP 不包含：

• 批量元数据修改
• 最小化字段传输
• session_id / candidate_id / patch 协议
• 乐观锁 / revision 冲突控制
• 字段级混合拼装多个候选
• 历史版本回滚
• 人工上传本地图片作为封面
• 桌面端批量对比编辑器

4. 核心原则

MVP 采用“简单直传”方案：

• Embed Service 返回 1 个 current 对象 + 1 个 candidates JSON 列表
• Echoes 回传 1 个最终确认的 metadata JSON 对象
• 不对传输体积做额外优化
• 优先保证链路清晰、可调试、可快速落地

5. 用户角色

目标用户：

• 使用 Echoes 管理 Navidrome 音乐库的普通用户
• 对歌曲标签、封面、歌词质量有要求的重度用户

6. 用户故事

6.1 主用户故事

作为用户，我希望在 Echoes 中对某首歌曲发起元数据修正，以便查看多个可能的元数据方案，并将我确认后的结果写回文件。

6.2 子用户故事

• 作为用户，我希望在歌曲菜单中直接看到“修改元数据”入口
• 作为用户，我希望看到当前元数据和候选元数据，方便对比
• 作为用户，我希望选择某个候选后还能手动微调字段
• 作为用户，我希望知道当前写入是否成功、失败、还是仍在处理中
• 作为用户，我希望写入完成后在 Echoes 中尽快看到新结果

7. 使用流程

7.1 主流程

1. 用户在 Echoes 的歌曲操作菜单中点击“修改元数据”
2. Echoes 将当前歌曲信息发送给 Embed Service
3. Embed Service 定位本地文件，读取当前标签，并调用候选来源生成元数据候选列表
4. Echoes 展示当前元数据与候选列表
5. 用户点击某个候选，查看详细预览
6. 用户可直接确认，或对候选内容做手工修改
7. Echoes 将最终完整元数据对象提交给 Embed Service
8. Embed Service 创建异步任务并开始写标签
9. Echoes 轮询任务状态并展示进度
10. Embed Service 写入完成后触发 Navidrome 扫描
11. Echoes 在任务成功后刷新歌曲详情与相关页面展示

7.2 异常流程

• 无候选结果：展示“未找到可用候选元数据”
• 封面下载失败：允许继续写入其他字段
• 歌词获取失败：允许继续写入其他字段
• 文件定位失败：直接返回失败并提示
• 标签写入失败：任务失败
• Navidrome 扫描失败：标签已写成功，但提示“扫描失败，刷新可能延迟”

8. 功能需求

8.1 入口

需求：

• 在 Echoes 的歌曲操作菜单中新增“修改元数据”入口
• 仅对音乐库内已有歌曲展示该入口
• 当 Embed Service 未配置或未启用时，入口可点击但需提示配置缺失原因

验收：

• 用户能在歌曲菜单中稳定看到入口
• 未配置时提示明确，不出现静默失败

8.2 获取候选元数据

需求：

• Echoes 调用 Embed Service 获取候选列表
• Embed Service 至少返回：
  • 当前文件元数据 current
  • 候选数组 candidates
• 每个候选至少包含：
  • 来源 source
  • 置信度 confidence
  • 完整元数据对象 metadata

候选来源建议：

• 当前文件已有标签
• MusicBrainz 指纹识别
• MusicBrainz 文本搜索
• GDStudio 搜索结果

验收：

• 对正常歌曲，接口可返回 1~5 个候选
• 返回结构稳定、前端可直接渲染

8.3 候选预览

需求：

• Echoes 页面需展示：
  • 当前元数据
  • 候选列表
  • 候选详情预览
• 用户点击候选后，将候选完整元数据填充至编辑表单
• 页面需支持查看候选封面预览
• 页面需支持查看歌词是否存在

验收：

• 用户可明确识别每个候选的差异
• 用户切换候选时，编辑表单同步更新

8.4 手工编辑最终对象

需求：

• 用户选择候选后，可以继续编辑最终对象
• MVP 支持编辑字段：
  • title
  • artist
  • album
  • albumArtist
  • trackNumber
  • discNumber
  • year
  • genre
  • lyrics
  • coverUrl
  • comment
  • composer
  • label

校验要求：

• title 不能为空
• artist 不能为空
• 数字字段非法时需阻止提交
• coverUrl 可为空
• lyrics 可为空

验收：

• 用户修改后的内容会作为最终对象提交
• 非法输入不能直接进入提交流程

8.5 提交最终元数据

需求：

• Echoes 将最终确认的完整 metadata JSON 对象发送给 Embed Service
• Embed Service 接收后创建异步 apply job
• 返回 job_id 和初始状态

验收：

• 提交后前端可拿到 job_id
• 可进入后续状态轮询

8.6 服务端写回

需求：

• Embed Service 负责：
  • 定位音频文件
  • 下载封面并内嵌
  • 写入元数据标签
  • 写入歌词
  • 必要时写 .lrc
  • 写入成功后触发 Navidrome 扫描

写回策略：

• 封面下载失败时不中断全流程，可跳过封面
• 歌词为空时跳过歌词写入
• 标签写入失败时任务失败
• 扫描失败时记录 warning，不回滚已写入标签

验收：

• MP3/FLAC 至少支持现有 tagger 能力范围内的写入
• 成功写回后文件元数据确实被修改

8.7 任务状态展示

需求：

• Echoes 轮询任务状态
• 建议状态：
  • queued
  • reading
  • resolving_cover
  • resolving_lyrics
  • tagging
  • scanning
  • done
  • failed

验收：

• 用户能看到进行中状态
• 成功和失败结果有明确反馈

8.8 成功后的刷新

需求：

• 任务成功后，Echoes 需刷新至少以下页面数据：
  • 当前歌曲详情
  • 所在专辑页
  • 搜索结果页
  • 当前播放器展示

验收：

• 写入完成后，用户可在合理时间内看到新元数据

9. 数据结构

9.1 Song 定位对象

{
  "id": "subsonic-song-id",
  "path": "Artist/Album/01 - Title.flac",
  "libraryId": "default"
}

说明：

• id 用于业务定位
• path 用于服务端定位本地文件
• libraryId 用于区分音乐库

9.2 EditableMetadata

{
  "title": "",
  "artist": "",
  "album": "",
  "albumArtist": "",
  "trackNumber": 0,
  "discNumber": 0,
  "year": 0,
  "genre": "",
  "lyrics": "",
  "coverUrl": "",
  "comment": "",
  "composer": "",
  "label": ""
}

9.3 Candidate

{
  "source": "musicbrainz_fingerprint",
  "confidence": 0.97,
  "metadata": {
    "title": "Song Title",
    "artist": "Artist",
    "album": "Album",
    "albumArtist": "Artist",
    "trackNumber": 1,
    "discNumber": 1,
    "year": 2024,
    "genre": "Pop",
    "lyrics": "....",
    "coverUrl": "https://...",
    "comment": "",
    "composer": "",
    "label": ""
  }
}

10. 接口定义

10.1 获取候选元数据

POST /v1/metadata/candidates

请求：

{
  "song": {
    "id": "subsonic-song-id",
    "path": "Artist/Album/01 - Title.flac",
    "title": "Old Title",
    "artist": "Old Artist",
    "album": "Old Album",
    "albumArtist": "Old Album Artist",
    "trackNumber": 1,
    "discNumber": 1,
    "year": 2020,
    "genre": "Pop",
    "suffix": "flac",
    "libraryId": "default"
  }
}

响应：

{
  "current": {
    "title": "Old Title",
    "artist": "Old Artist",
    "album": "Old Album",
    "albumArtist": "Old Album Artist",
    "trackNumber": 1,
    "discNumber": 1,
    "year": 2020,
    "genre": "Pop",
    "lyrics": "",
    "coverUrl": "",
    "comment": "",
    "composer": "",
    "label": ""
  },
  "candidates": [
    {
      "source": "musicbrainz_fingerprint",
      "confidence": 0.97,
      "metadata": {
        "title": "New Title",
        "artist": "New Artist",
        "album": "New Album",
        "albumArtist": "New Artist",
        "trackNumber": 1,
        "discNumber": 1,
        "year": 2024,
        "genre": "Pop",
        "lyrics": "歌词内容",
        "coverUrl": "https://...",
        "comment": "",
        "composer": "",
        "label": ""
      }
    }
  ]
}

10.2 提交最终元数据

POST /v1/metadata/apply

请求：

{
  "song": {
    "id": "subsonic-song-id",
    "path": "Artist/Album/01 - Title.flac",
    "libraryId": "default"
  },
  "metadata": {
    "title": "最终标题",
    "artist": "最终歌手",
    "album": "最终专辑",
    "albumArtist": "最终专辑歌手",
    "trackNumber": 1,
    "discNumber": 1,
    "year": 2024,
    "genre": "Pop",
    "lyrics": "最终歌词",
    "coverUrl": "https://...",
    "comment": "",
    "composer": "",
    "label": ""
  }
}

响应：

{
  "job_id": "job_xxx",
  "status": "queued"
}

10.3 查询任务状态

GET /v1/metadata/jobs/{job_id}

响应：

{
  "job_id": "job_xxx",
  "status": "tagging",
  "message": "writing tags",
  "error": "",
  "created_at": "2026-04-21T10:00:00Z",
  "updated_at": "2026-04-21T10:00:03Z"
}

11. UI 需求

11.1 页面结构

建议使用独立页面或全屏弹层。

页面区域：

• 顶部：歌曲基础信息
• 当前元数据卡片
• 候选列表
• 编辑表单
• 提交按钮

11.2 候选卡片展示字段

每个候选至少展示：

• 来源
• 置信度
• 标题
• 歌手
• 专辑
• 是否有封面
• 是否有歌词

11.3 编辑表单字段

展示并可编辑：

• 标题
• 歌手
• 专辑
• 专辑歌手
• 曲号
• 碟号
• 年份
• 流派
• 歌词
• 封面 URL
• 备注
• 作曲
• 厂牌

11.4 操作按钮

按钮包括：

• 重新获取候选
• 应用当前编辑结果
• 取消

12. 非功能需求

12.1 性能

• 候选获取接口在常规网络环境下建议 10 秒 内返回
• 候选数量建议不超过 5 个
• 前端轮询间隔建议 2~3 秒

12.2 兼容性

• Echoes 现有支持平台内保持一致行为
• 服务端优先支持当前已具备写标签能力的格式
• 至少覆盖 MP3、FLAC

12.3 可观测性

需要日志覆盖：

• 候选请求开始/结束
• 候选来源命中情况
• apply 请求开始/结束
• 封面下载结果
• 歌词解析结果
• 标签写入结果
• Navidrome 扫描结果

12.4 安全性

• 接口需沿用现有 X-API-Key
• 服务端必须校验文件路径处于音乐目录下
• 不允许任意路径写入

13. 边界与异常要求

必须覆盖以下场景：

• 歌曲 path 为空
• 服务端本地找不到文件
• 音频文件格式不支持
• 候选列表为空
• 封面 URL 无法下载
• 歌词过长或为空
• 目标文件被占用
• Navidrome 扫描接口失败
• 提交时用户手工删除了必填字段

处理原则：

• 能部分成功时尽量部分成功
• 标签写入失败视为任务失败
• 扫描失败视为“写入成功但刷新延迟”
• 错误文案需明确可读

14. 验收标准

14.1 功能验收

• 用户可从歌曲菜单进入“修改元数据”
• Echoes 可成功请求候选列表
• 候选列表可正常展示
• 用户可选择候选并手动修改
• Echoes 可将最终完整 metadata 对象提交给 Embed Service
• Embed Service 可完成写标签
• 写入成功后可触发 Navidrome 扫描
• Echoes 可展示任务状态与最终结果
• 刷新后可在客户端看到新元数据

14.2 异常验收

• 无候选时有明确提示
• 写标签失败时有明确提示
• 封面失败不影响其他字段写入
• 扫描失败会提示但不覆盖已写结果

15. 依赖关系

Echoes 侧依赖：

• 已配置的 Embed Service 地址与 API Key
• 当前歌曲可获取 id/path/libraryId
• 现有任务轮询机制可复用

Embed Service 侧依赖：

• 现有 tagger 写标签能力
• 可访问 MusicBrainz / GDStudio 等候选来源
• 可访问 Navidrome 扫描接口
• 可定位音乐目录中的实际文件

16. 后续演进方向

MVP 之后可考虑：

• session_id + candidate_id + patch，减少传输量
• 批量元数据修正
• 候选字段级混合选择
• 本地上传封面
• 修改前后 diff 视图
• 乐观锁与冲突检测
• 历史版本回滚
• 扫描去抖与合并触发

17. 开发建议

推荐实现顺序：

1. Embed Service 新增 candidates 接口
2. Embed Service 新增 apply 接口与异步 job
3. Echoes 新增“修改元数据”入口
4. Echoes 新增候选预览与编辑页面
5. Echoes 接入 apply job 轮询
6. 补齐异常处理与刷新逻辑

[Azincc]

当前有musicbranz的封面无法下载的情况

{"level":"WARN","ts":"2026-04-22T14:49:12.461+0800","caller":"musicbrainz/musicbrainz.go:698","msg":"musicbrainz request retrying","url":"https://coverartarchive.org/release/542fb03d-649e-4039-aeec-1ea49d2bc633/front","retry_attempt":3,"retry_max":3,"error":"musicbrainz request failed: Get \"https://coverartarchive.org/release/542fb03d-649e-4039-aeec-1ea49d2bc633/front\": EOF"}

[Azincc]

当前完成度不够，暂时搁置