Skip to content

feat: 支持本地 TTML 歌词三档匹配强度与设置选项 - #238

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

feat: 支持本地 TTML 歌词三档匹配强度与设置选项#238
kid141252010 wants to merge 1 commit into
SPlayer-Dev:devfrom
kid141252010:feat/local-ttml-match-level

Conversation

@kid141252010

Copy link
Copy Markdown
Contributor

改动类型

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

是否包含破坏性变更

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

改动说明

背景与动机

此前本地 TTML 歌词库(localLyricRepo)在按标题匹配时,将艺术家仅作为“软性消歧”而非硬门槛(同名文件只有 1 首时直接命中;有多首且艺术家都不符合时依然兜底返回第 1 首)。由于本地 TTML 库具有最高覆盖优先级(Override),这会导致“同名异曲”(例如不同歌手但歌名相同的情况)被强制错误匹配并置顶展示,同时打断了后续在线正确歌词的检索流程。

主要改动

  1. 新增三档匹配强度(LocalLyricMatchLevel
    • 严格 (strict):必须通过网易云/QQ 平台 ID 精确命中,或歌名与艺术家完全一致;不接受子串包含,元数据缺失时不匹配;彻底杜绝误匹。
    • 标准 (standard,默认推荐):歌名必须一致,且艺术家必须匹配(支持完全一致、多歌手拆分、合唱、feat. 包含关系);单方缺失艺术家元数据时允许容错;双方均有明确艺术家但互不相干时坚决拒绝兜底,避免同名异曲误匹配。
    • 宽松 (loose):保持原先行为,歌名一致即可强行匹配,适合本地文件标签极不规范的用户。
  2. 设置项交互与 UI 布局
    • 在设置中心“歌词设置” $\to$ “TTML 歌词” 分组中,将“匹配强度”下拉选择框置于“启用本地 TTML 歌词库”的从属配置中(紧随“歌词库目录”之后),并与开关状态联动。
    • 支持实时热生效:修改匹配强度后,即时重新计算当前歌曲歌词,并同步使下一首预加载缓存失效重算。
  3. 国际化与工具复用
    • 导出并复用 electron/main/apis/common/lyric/utils.ts 中的 artistMatchesnormalizeTrackArtists
    • 补充 zh-CNen-US 多语言翻译。

关联 Issue

测试情况

  • 类型检查:运行 pnpm typecheck(Node 与 Web 端类型编译)均通过。
  • 自动化测试:运行 pnpm test:web,10 个测试文件(57 个用例)全部通过。
  • 逻辑与边界测试
    • 同名异曲场景(歌手完全不同):标准模式和严格模式均能正确拒绝匹配,正常 fallback 到在线歌词;宽松模式保持原兜底匹配。
    • 合唱 / 合作曲场景(如 周杰伦 / 五月天阿信):标准模式与严格模式均能正常精确命中。
    • feat. 包含场景:标准模式正常命中,严格模式拒绝模糊匹配。
    • 歌曲缺少艺术家元数据场景:标准模式与宽松模式容错命中,严格模式拒绝。
  • 代码格式化:已运行 Prettier 格式化所有修改文件,符合项目编码规范。

截图 / 录屏

呃懒

自查清单

  • 本 PR 只包含一个主要功能 / 修复,没有夹带无关改动
  • 已在本地完整测试通过;AI 生成的代码同样自行测试并审阅过,未做未经验证的提交
  • 已运行 pnpm format,并确认 pnpm typecheckpnpm 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
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