refactor(mediabunny): [PKG-MB-06] own audio clocks, buffers and context lifecycle

2026-10-18 10:41:20 -08:00 · 2026-09-12 20:21:25 +08:00
1 parent 9d037dcbf9
commit ccee9157a7
@@ -0,0 +1,10 @@
+{
+  "task": "PKG-MB-06",
+  "sourceCommit": "9d037dcbf913fef2d2a9eb4f3924d6abf3ab5597",
+  "sourceSha256LF": {
+    "packages/artplayer-proxy-mediabunny/src/AudioEngine.js": "910d6831372e4895d55dec78010f281a199bc88f99735630a5a3b621f192ac35",
+    "packages/artplayer-proxy-mediabunny/src/MediaBunnyEngine.ts": "237d3d29fbf61a74df83dea11d862450dfd8f3b7fbd555dd5552b630ff0191e9",
+    "packages/artplayer-proxy-mediabunny/src/playback.ts": "0512f6a1b253d754b6644266327e368e0e18cce1cf9a3af62b6747ed55d691f7",
+    "packages/artplayer-proxy-mediabunny/dist/artplayer-proxy-mediabunny.js": "9c89a729197593ffcab11b64813b312f588f5515d2cb8acb0537d0a389a5209c"
+  }
+}
@@ -0,0 +1,72 @@
+# PKG-MB-06：音频解码、时钟与资源归属
+
+任务通过完整CI后标记done，并立即以专用本地提交交付。来源是9d037dcbf913fef2d2a9eb4f3924d6abf3ab5597，
+冻结旧AudioEngine、协调器、playback和main的LF哈希见[源码基线](../baselines/mb-audio-source.json)。
+候选文件、测试、产物和浏览器报告见[验证记录](../baselines/mb-audio-validation.json)。
+
+## 实现与拆分
+
+实际删除AudioEngine.js及临时AudioEngine.d.ts，迁移到AudioEngine.ts；拆出audio-clock、
+audio-context、audio-nodes、audio-pump、audio-task五个模块，分别管理时钟计算、
+Context/Gain、源节点、SDK迭代器/背压、取消等待/计时器。模块地图和维护命令同步到
+包内ARCHITECTURE.md。包内26个生产TS模块，没有遗留JS声明桥；index.js和m3u8.js
+分别由MB-08/07接续，不能据此声称整个包已经完成TS化。
+
+source、play和pump分别拥有取消状态。暂停会取消尚未完成的resume；新source在解析轨道
+之前就使旧音频操作失效。迟到的canDecode、resume、next不能重建context、写入sink、
+发出旧playing或排队旧节点。迭代器同步脱离引用、return只调用一次且观察拒绝。
+每批16buffer、0ms让出及1秒/50ms背压参数保留，任务释放包含ID零的计时器。
+复查新实现时消除了对单个长期未决Promise反复race的设计：每次读取完成就移除取消回调，
+避免正常长播放累积已完成读取的等待监听。这是源码审查改进，不声称已做长时间堆内存验收。
+
+节点在start前即登记归属，自然ended也断开连接并清除回调；暂停、seek、倍速与destroy
+停止/断开旧队列。一个节点失败仍尝试其余节点及Context/Gain清理，保留首个失败。
+后台解码失败先停止播放并报告一次MediaError；清理失败不会替换解码原始错误。
+Context/Gain设置成功后才安装引用；失败释放部分资源，销毁清空引用并观察close拒绝。
+真正异步的AudioContext.close通过浏览器状态轮询验证，不以固定两帧声称关闭完成。
+
+## 兼容边界与修复行为
+
+公开factory、canvas转发、声明、默认选项、三种分发入口及MediaBunny 1.56.1依赖保持原有契约。
+时钟仍按锚点和倍速计算，volume仍用平方增益，mute为零；暂停冻结位置，seek/rate更新锚点。
+无音轨但有视频仍使用Web Audio时钟，完全无轨道容器继续MB-04的明确拒绝行为。
+已完全过期的buffer不再创建无效节点，部分迟到buffer保留原offset计算。视频结束会停止
+音频时钟和余留节点，倍速切换会停止旧速节点。仍使用原生source.playbackRate，未引入保调算法。
+
+原先playback层缓存整个audio.play Promise；如今音频play可在取消时提前完成，该缓存不再
+能代表底层resume状态，因此去重下移到ContextOwner。协调器新意图各调用audio.play，
+实际原生resume仍共享一次。受控协调器测试的audio.play调用数由1改为2，新增实际AudioEngine
+测试验证play→pause→play的原生resume次数仍为1，只有当前意图启动视频。
+这项变化是内部归属修正，不能把stub调用数变化隐瞒为原样不变的测试。
+
+## 验证与证据边界
+
+- 37项新增音频断言：最终候选全部通过；同一断言对旧main为8通过/29失败，无取消或跳过。
+  首轮旧测试的一项等待夹具超时已归档；修正夹具在finally释放受控读后，最终旧基线没有超时。
+- 包专项183通过，main/legacy各159通过；每个产物命令含155候选断言及4个冻结正常事件对照。
+- 新增24项浏览器：Chromium/Firefox各8项实际Web Audio/SDK解码场景，Windows WebKit
+  8项精确能力缺失对照。包括暂停恢复、1×/2×、增益/静音、无音轨时钟、迟到buffer与resume、
+  seek后的HLS音画时钟取样。短时实际绘制帧与音频时钟偏差上限为250ms，报告保存原始样本；
+  这不是听觉输出、长时间漂移、物理设备或所有Safari安装的验收。
+- 同24项对旧main：20通过/4失败；失败是Chromium/Firefox音频与HLS暂停后节点/回调
+  仍保留的状态断言，不是加载超时。其他旧浏览器场景通过属于回归对照，不能算作复现缺陷。
+- 最终构建main运行全部六个MediaBunny浏览器文件，共78项：包含既有视频竞态、输入、
+  Stream取消及synthetic RAF。报告与整个results目录在下一次运行前归档。
+- 严格TS、lint、三格式构建、ESM默认factory和dist/docs逐字节一致性独立核验。
+- 本项不增加依赖；根test:unit与test:mediabunny加入音频测试，使完整CI持续执行。
+
+最终完整CI1344项（1189单元+14工程+141基线）通过，另44重复契约；316生产TS。
+最终78浏览器报告中，Chromium 27个播放帧取样最大偏差39.34ms，Firefox 28个取样最大
+偏差37.67ms。所有源码/测试/产物及报告哈希已复核，dist与docs/compiled三个格式一致。
+
+## 环境问题与后续
+
+一次Windows copyfile UNKNOWN发生在构建复制既有legacy生成文件时。保留失败日志和旧生成文件，
+核对唯一绝对路径后删除该生成目标，再由正常yarn build重建；未手改生成内容或停止用户进程。
+首轮78浏览器报告也保留，因为取消等待实现随后改进，最终产物重新构建并重跑对应验证。
+
+MB-LIFE-01仍open：音视频各自的取消与短时组合已覆盖，HLS UI拓扑/并发选择、长播放/AV同步、
+codec能力矩阵和全核心/插件组合仍由MB-07/08/09及能力风险条目处理。MB-10承担真实安装包、
+demo与MPL/source通知；本项通过不是npm发布许可或发布验收。
+
+回退通过revert本项专用提交，冻结旧实现保持可追溯。下一步MB-07整理m3u8.ts选择与拓扑清理。
@@ -61,3 +61,13 @@ VideoEngine与迭代器/渲染/海报职责已实际迁移TS，删除视频声
 执行yarn test:mediabunny及新增mediabunny-video.spec.js，按实际报告区分普通播放、
 真实帧竞态、能力对照和synthetic RAF。[变更](changes/2026-09-12-PKG-MB-05-video.md)与
 [验证](baselines/mb-video-validation.json)记录38个新断言、旧产物复现及真实解码场景。
+
+## PKG-MB-06 音频归属与时钟
+
+实际AudioEngine迁移并拆为六个TS模块，包内26生产TS，无JS声明桥；m3u8/index由07/08接续。
+[变更](changes/2026-09-12-PKG-MB-06-audio.md)记录文件地图、resume归属下移、兼容边界和回退，
+[证据](baselines/mb-audio-validation.json)记录旧main 37断言8通过/29失败、候选专项183及
+main/legacy各159通过。最终78浏览器含16新增原生音频场景及8新增WebKit能力对照。
+同24音频浏览器断言对旧main20通过/4失败，失败为实际暂停后的节点清理；其余为回归对照。
+短时1×/2×帧/音频时钟偏差验证不替代长播放、听觉及设备验收；全部报告/results已归档。
+完整CI1344项及另44重复契约通过，316生产TS；完成后立即专用提交，MB-LIFE-01剩余范围仍open。
@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 222 项，范围 22 个包及工作区/示例。

-状态：todo 113 / doing 7 / blocked 0 / done 102 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 112 / doing 7 / blocked 0 / done 103 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -334,7 +334,7 @@
 | PKG-MB-03 | artplayer-proxy-mediabunny<br>整理 input 与加载取消 | PKG-MB-02, CORE-09 | input.js 源检测、输入资源、Range 与取消 | HLS 检测在 input 边界，旧来源类型和超时保持 | H | done |
 | PKG-MB-04 | artplayer-proxy-mediabunny<br>整理 VideoShim/EventTarget/Engine 协调 | PKG-MB-03, CORE-06, CORE-11 | shim 描述符、事件桥、加载状态和操作隔离 | 公开属性/同步异步返回与事件重入顺序保持 | H | done |
 | PKG-MB-05 | artplayer-proxy-mediabunny<br>整理视频解码、seek 和帧释放 | PKG-MB-04 | VideoEngine 调度、队列、晚帧处理和资源释放 | 暂停/seek/切源无旧帧覆盖，默认丢帧策略不变 | H | done |
-| PKG-MB-06 | artplayer-proxy-mediabunny<br>整理音频解码、时钟与同步 | PKG-MB-04 | AudioEngine 时钟、缓冲和 AudioContext 归属 | AV sync、倍速、无音轨、静音/音量和暂停恢复通过 | H | todo |
+| PKG-MB-06 | artplayer-proxy-mediabunny<br>整理音频解码、时钟与同步 | PKG-MB-04 | AudioEngine 时钟、缓冲和 AudioContext 归属 | AV sync、倍速、无音轨、静音/音量和暂停恢复通过 | H | done |
 | PKG-MB-07 | artplayer-proxy-mediabunny<br>整理 HLS 配对轨道与 selector | PKG-MB-05, PKG-MB-06, CORE-14 | m3u8 配对、质量/音频选择及拓扑清理 | 实际选择高亮、切到无轨道来源清理、无重复 readiness | H | todo |
 | PKG-MB-08 | artplayer-proxy-mediabunny<br>完成 TS 与媒体能力声明 | PKG-MB-07, ENG-04, ENG-06 | 8 个自有 JS 模块迁移与 Result/shim 类型 | 解码器/Stream/DOM 类型清楚，旧 Option 和 art.mediabunny 使用保持 | H | todo |
 | PKG-MB-09 | artplayer-proxy-mediabunny<br>完成新旧核心和真实媒体组合 | PKG-MB-08, CORE-22 | 跨浏览器能力、长播放、DPiP、HLS 音轨/质量报告 | 资源释放、事件顺序、AV sync 与支持范围满足基线 | H | todo |
@@ -525,4 +525,5 @@
 - PKG-MB-03: [记录](changes/2026-09-12-PKG-MB-03-input.md) [记录](baselines/mb-input-validation.json)
 - PKG-MB-04: [记录](baselines/mb-coordination-source.json) [记录](changes/2026-09-12-PKG-MB-04-shim-checkpoint.md) [记录](baselines/mb-shim-checkpoint.json) [记录](changes/2026-09-12-PKG-MB-04-coordination.md) [记录](baselines/mb-coordination-validation.json)
 - PKG-MB-05: [记录](baselines/mb-video-source.json) [记录](changes/2026-09-12-PKG-MB-05-video.md) [记录](baselines/mb-video-validation.json)
+- PKG-MB-06: [记录](baselines/mb-audio-source.json) [记录](changes/2026-09-12-PKG-MB-06-audio.md) [记录](baselines/mb-audio-validation.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md)
@@ -1,5 +1,18 @@
 # 进度与证据

+## PKG-MB-06完成：音频解码、时钟与资源归属
+
+AudioEngine实际迁移TS，拆清clock、context、nodes、pump、task职责，删除最后音频声明桥。
+暂停/切源/销毁取消迟到resume和buffer，seek/rate释放旧速节点；时钟、增益与无音轨回退
+保持契约，播放协调器的原生resume去重下移到context owner。包内26生产TS，剩m3u8/index
+由07/08接续。37音频断言旧main8通过/29失败，候选专项183、main/legacy各159通过。
+最终78浏览器通过：含16新增原生音频场景及8新增能力对照；旧main同24音频浏览器
+20通过/4节点清理失败。短时1×/2×音画取样最大偏差约39/38ms，长播/听觉/设备仍MB-09。
+完整CI1344项通过，另44重复契约；316生产TS。源码/产物/报告哈希及三格式复制一致。
+见[变更](changes/2026-09-12-PKG-MB-06-audio.md)与[证据](baselines/mb-audio-validation.json)。
+222项：103 done、7 doing、112 todo；立即专用本地提交，下一项MB-07 HLS UI/拓扑。
+MB-LIFE-01剩余长播放、全组合及HLS UI范围仍open；不构成npm发布验收。
+
 ## PKG-MB-05完成：视频迭代器、seek、晚帧与RAF

 VideoEngine实际迁移TS，拆出frame读取/释放、renderer与poster职责，删除视频声明桥。
@@ -3648,7 +3648,7 @@
        "PKG-MB-07",
        "PKG-MB-09"
      ],
-      "compatibleResolution": "Reproduce pending operations and destroy/source-switch races before migrating each owner; preserve public event and promise behavior while preventing stale resource use. MB-02 now reproduces late load rejection and uncancelled waiting/loadstart timers after destroy in all three historical implementations using a controlled host. Other interleavings and full-core native behavior are not yet verified. Expanded MB-02 baseline reproduces play-after-pause/destroy, rejected-play false state, seek-after-destroy and retained successful-load timeout timers in all three actual historical implementations; Range and active-timeout normal controls remain separate. MB-03 candidate owns pending Input before track selection and cancels load/HEAD/timers on source replacement, timeout and destroy; source/main/legacy regressions pass. Pending play/seek, late decoder work and full readiness coordination remain MB-04/05/06, so this risk stays open. MB-04 shim checkpoint fixes synthetic RAF retention and terminal event-listener cleanup, including engine cleanup exceptions. Closing the event bridge does not prove pending engine operations stopped; coordination remains in progress. MB-04 now guards play/seek/replacement completion, preserves explicit pause, observes stale failures and isolates reentrant event sequences. Decoder-internal late frames/audio and HLS UI races remain MB-05/06/07; risk stays open. MB-05 migrates VideoEngine and owns iterators, late first/second seek frames, pending reads, per-instance RAF and poster callbacks; same native race assertions fail on old main and pass on candidate. Independent CanvasSink pools also prevent multiple obsolete seek samples from overwriting queued current-frame pixels. Audio nodes, long-run AV sync and HLS UI topology remain MB-06/07/09.",
+      "compatibleResolution": "Reproduce pending operations and destroy/source-switch races before migrating each owner; preserve public event and promise behavior while preventing stale resource use. MB-02 now reproduces late load rejection and uncancelled waiting/loadstart timers after destroy in all three historical implementations using a controlled host. Other interleavings and full-core native behavior are not yet verified. Expanded MB-02 baseline reproduces play-after-pause/destroy, rejected-play false state, seek-after-destroy and retained successful-load timeout timers in all three actual historical implementations; Range and active-timeout normal controls remain separate. MB-03 candidate owns pending Input before track selection and cancels load/HEAD/timers on source replacement, timeout and destroy; source/main/legacy regressions pass. Pending play/seek, late decoder work and full readiness coordination remain MB-04/05/06, so this risk stays open. MB-04 shim checkpoint fixes synthetic RAF retention and terminal event-listener cleanup, including engine cleanup exceptions. Closing the event bridge does not prove pending engine operations stopped; coordination remains in progress. MB-04 now guards play/seek/replacement completion, preserves explicit pause, observes stale failures and isolates reentrant event sequences. Decoder-internal late frames/audio and HLS UI races remain MB-05/06/07; risk stays open. MB-05 migrates VideoEngine and owns iterators, late first/second seek frames, pending reads, per-instance RAF and poster callbacks; same native race assertions fail on old main and pass on candidate. Independent CanvasSink pools also prevent multiple obsolete seek samples from overwriting queued current-frame pixels. Audio nodes, long-run AV sync and HLS UI topology remain MB-06/07/09. MB-06 migrates AudioEngine into six checked modules, owns context/gain/nodes/iterators and removable cancellation waits, preserves clock and gain formulas, and invalidates pending resume/decoding across pause/source/destroy. Same old main fails 29 of 37 audio assertions and four native pause-cleanup cases; candidate passes with short native 1x/2x AV-clock samples. Long-run AV sync, full combinations and HLS UI topology remain MB-07/09, so risk stays open.",
      "closureCriteria": "Historical failing interleavings and candidate cancellation/cleanup pass with real media and event evidence, including long playback and track topology.",
      "status": "open",
      "evidence": [
@@ -3664,7 +3664,9 @@
        "refactor/changes/2026-09-12-PKG-MB-04-coordination.md",
        "refactor/baselines/mb-coordination-validation.json",
        "refactor/changes/2026-09-12-PKG-MB-05-video.md",
-        "refactor/baselines/mb-video-validation.json"
+        "refactor/baselines/mb-video-validation.json",
+        "refactor/changes/2026-09-12-PKG-MB-06-audio.md",
+        "refactor/baselines/mb-audio-validation.json"
      ]
    },
    {
@@ -3502,11 +3502,15 @@
      "dependsOn": [
        "PKG-MB-04"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "AudioEngine 时钟、缓冲和 AudioContext 归属",
      "acceptance": "AV sync、倍速、无音轨、静音/音量和暂停恢复通过",
-      "evidence": []
+      "evidence": [
+        "baselines/mb-audio-source.json",
+        "changes/2026-09-12-PKG-MB-06-audio.md",
+        "baselines/mb-audio-validation.json"
+      ]
    },
    {
      "id": "PKG-MB-07",