Skip to content

feat: 完善本地 TTML 歌词匹配机制(支持专辑消歧与三档匹配强度) - #238

Open
kid141252010 wants to merge 3 commits into
SPlayer-Dev:devfrom
kid141252010:feat/local-ttml-match-level
Open

kid141252010 wants to merge 3 commits into
SPlayer-Dev:devfrom
kid141252010:feat/local-ttml-match-level

Conversation

@kid141252010

@kid141252010 kid141252010 commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

改动类型

  • 新功能(feat)
  • 缺陷修复(fix)
  • 重构 / 优化(不改变对外行为)
  • 文档(docs)
  • 其他(请在「改动说明」中注明)

是否包含破坏性变更

  • 是(请在「改动说明」中详细描述)
  • 否

改动说明

背景与动机

此前本地 TTML 歌词库(localLyricRepo)在按标题匹配时,仅根据歌名进行匹配,同名文件只有 1 首时直接命中,多首且艺术家不符时依然兜底返回第 1 首。这不仅会导致不同歌手的“同名异曲”被错误覆盖,也会导致同一歌手同一歌曲的“不同专辑版本”(如录音室版 vs. 演唱会 Live 版)因缺乏专辑元数据匹配而选错版本、时间戳错乱。

主要改动

  1. 补全 AMLL 专辑元数据提取:
    • 在 localLyricRepo 中解析 <amll:meta key="album" ...> 标签(并兼容 albumName),支持多专辑标签拼接合并。
  2. 新增三档匹配强度(LocalLyricMatchLevel):
    • 严格 (strict):必须通过平台数字 ID 精确命中,或歌名与艺术家完全一致;双方均有专辑时专辑也必须匹配(严格杜绝录音室与现场版错配);不接受模糊包含,元数据缺失时不匹配。
    • 标准 (standard,默认推荐):歌名必须一致,艺术家必须匹配(支持合唱、feat. 包含);多版本时根据专辑匹配度自动择优消歧(专辑一致优先);双方均有明确艺术家但互不相干时坚决拒绝兜底,避免同名异曲误匹配。
    • 宽松 (loose):保持原有宽松容错行为,多候选时按艺术家与专辑评分挑选最佳候选,无匹配兜底首个。
  3. 设置项交互与 UI 布局:
    • 在设置中心“歌词设置” $\to$ “TTML 歌词” 分组中,将“匹配强度”下拉选择框置于“启用本地 TTML 歌词库”的从属配置中(紧随“歌词库目录”之后),并与开关状态联动。
    • 支持实时热生效:修改匹配强度后即时重新计算当前歌曲歌词,并使下一首预加载缓存失效重算。
  4. 国际化与工具复用:
    • 复用 utils.ts 中的 artistMatches、normalizeTrackArtists 和 bothContains;
    • 补全 zh-CN 与 en-US 翻译。

关联 Issue

测试情况

  • 类型检查:运行 pnpm typecheck(Node 与 Web 端类型编译)均通过。
  • 自动化测试:运行 pnpm test:web,10 个测试文件(57 个用例)全部通过。
  • 多场景验证:
    • 同名同歌手不同专辑场景(如录音室版 vs. 演唱会版):标准模式能精准根据专辑名挑中最优匹配版本;严格模式下专辑冲突时拒绝错配。
    • 同名异曲场景(歌手完全不同):标准模式和严格模式均能正确拒绝匹配,正常 fallback 到在线歌词。
    • 合唱 / feat. 场景:标准模式支持包含匹配正常命中。
  • 代码格式化:已运行 Prettier 格式化所有修改文件,符合项目编码规范。

自查清单

  • 本 PR 只包含一个主要功能 / 修复,没有夹带无关改动
  • 已在本地完整测试通过;AI 生成的代码同样自行测试并审阅过,未做未经验证的提交
  • 已运行 pnpm format,并确认 pnpm typecheck、pnpm lint 通过
  • 改动涉及原生模块时已 pnpm build:native 验证;未手写 native/*/index.d.ts
  • 已向 dev 分支提交

@kid141252010
kid141252010 force-pushed the feat/local-ttml-match-level branch from 2d07e72 to 8f438a3 Compare September 5, 2026 06:02
@kid141252010 kid141252010 changed the title feat: 支持本地 TTML 歌词三档匹配强度与设置选项 feat: 完善本地 TTML 歌词匹配机制(支持专辑消歧与三档匹配强度) Sep 11, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant