Skip to content

fix: 优化歌词加载并发流程,避免网络超时阻塞歌词展示与抢占 - #239

Open
kid141252010 wants to merge 1 commit into
SPlayer-Dev:devfrom
kid141252010:fix/amll-db-timeout
Open

fix: 优化歌词加载并发流程,避免网络超时阻塞歌词展示与抢占#239
kid141252010 wants to merge 1 commit into
SPlayer-Dev:devfrom
kid141252010:fix/amll-db-timeout

Conversation

@kid141252010

@kid141252010 kid141252010 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

By Google Gemini 3.8 Flash

改动类型

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

是否包含破坏性变更

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

改动说明

动机

  1. AMLL TTML DB 超时阻塞:原代码在 applyOnlineresolveStreamingByPreferenceresolveLyricForPreload 等多处同步 await resolveTTMLOverlay()。当 AMLL DB 服务端响应慢或超时(8s)时,会导致基础歌词、内嵌歌词或插件歌词迟迟无法展示,严重影响切歌体感。
  2. 多音源并发时慢平台拖累整体显示:开启「智能选择在线歌词」时,在线歌曲加载流程 loadPlatformLyric 缺少 onCandidate 即时提交回调,导致并发查询多个平台时,即使已有平台返回了歌词,仍会被其他慢响应或超时的平台(如酷狗网络波动)阻塞长达 8 秒。
  3. 低优先级候选覆盖已展示歌词:当插件或高优先级平台歌词已上屏时,正常加载流程的 onCandidate 回调无条件写入,可能导致已显示的优质歌词(如 TTML/QRC)被延迟返回的低优先级普通 LRC 降级覆盖。
  4. 无效 TTML 覆写清空有效歌词:后台 TTML 解析失败或有效行为空时直接提交,会导致已展示的有效歌词被清空且无法恢复。

主要变更

  1. TTML 异步非阻塞升级
    • resolveTTMLOverlay 改为后台静默触发(tryApplyTTMLOverlay),先即时呈现本地/内嵌/平台在线基础歌词,TTML 命中后再热替换升级;
    • 移除了预载流程和流媒体解析中对 TTML 的同步 await 阻塞。
  2. 候选即时上屏与防降级控制(commitIfBetter
    • 为在线歌曲(loadPlatformLyric)、本地歌曲和刷新偏好流程统一接入 commitIfBetter 作为 onCandidate 提交回调,任一平台就绪立即抢先展示,无需等待其他平台超时;
    • 提交前检查当前展示格式,严格确保只有更优格式(isBetterFormat)才允许覆盖,避免插件歌词或高优先级候选被后到的低优先级结果冲掉。
  3. TTML 解析内容有效性校验(hasParseableContent
    • TTML 升级前预先解析,确保至少解析出 1 行有效歌词才执行覆盖;若解析为空或失败则保留当前已展示歌词。
  4. 规范与文档对齐
    • 补充完善全中文 JSDoc 注释,清理冗余返回值,代码组织严格遵循 AGENTS.md 规范。

测试情况

  • 测试环境:Windows 11 (pwsh / Node.js)
  • 验证场景
    1. 模拟 AMLL DB 超时场景:基础在线歌词(LRC/YRC/QRC)秒级展示,无任何 8 秒阻塞感。
    2. 模拟多平台并发场景:网易云先返回 LRC 立即上屏展示,后续慢平台或超时平台不影响界面渲染;QQ 音乐返回 QRC 时立即平滑热替换。
    3. 插件优先测试:插件歌词提前提交后,后续普通在线候选到达不会将其降级覆盖。
    4. 畸形/空 TTML 测试:当 AMLL 返回无效空内容时,控制台发出告警并保留当前歌词,未出现歌词被清空为空白的情况。
  • 自动化检查
    • pnpm typecheck(Node + Web 目标)全绿通过。
    • npx eslint 检查通过,0 errors, 0 warnings。
    • npx prettier --check 格式检查全量通过。

自查清单

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

@kid141252010 kid141252010 reopened this Sep 6, 2026
@kid141252010 kid141252010 changed the title fix: 避免 AMLL DB 超时阻塞其它歌词展示与抢占 fix: 优化歌词加载并发流程,避免网络超时阻塞歌词展示与抢占 Sep 6, 2026
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