fix(asr): [PKG-ASR-07] apply native playback volume only once

2026-10-10 21:06:15 -08:00 · 2026-09-13 15:22:40 +08:00
1 parent 93208e59e1
commit 3e3bed2b93
@@ -0,0 +1,39 @@
+# PKG-ASR-07：修复 ASR 音量二次衰减
+
+ASR-05 的原生验证发现，2.1.0 和 ASR-04 候选都在 `video:volumechange` 中把
+`art.volume` 再写入播放 gain。原生 MediaElementAudioSource 已包含视频音量，
+二次应用导致 50% 设置约为 25% 输出振幅，25% 设置约为 6.25%。Chromium 和 Firefox
+均复现。此缺陷单独增加任务与风险记录，ASR-05 的完整设备验收继续独立跟踪。
+
+删除重复的 volume 监听器及 capture/graph 转发方法，内部播放 gain 保持 1。
+视频继续拥有音量/静音控制。公开选项、工厂、回调、返回值和停止/销毁语义不变；
+这是输出音量的行为修复，升级后调过音量的播放可能比旧版更响，不应声称声音字节
+完全不变。PCM 仍随主视频音量缩放，静音时为零，不自动改为捕获外部音轨。
+
+## 实测方法与验证
+
+`test/browser/asr-playback.spec.js` 在原生 gain 与 destination 之间插入 unity
+AnalyserNode，以同一本地 AAC 的全音量 RMS 归一化。设置 1/0.5/0.25、静音和取消静音；
+候选允许 10% 窗口处理误差，要求线性振幅，旧发布版要求其原有平方衰减。
+候选另检查 stop 后音量变化仍正确、采集停止、pause/play 后恢复正确输出。
+该方法检查浏览器图信号，不代替物理扬声器或声卡测量。
+
+修复前候选 Chromium 线性断言失败，报告和 trace 保留。修复后：
+
+- 208 项定向 ASR 单元/分发测试通过，main/legacy 各 25 项生命周期通过。
+- source 原生组 20 通过/10 跳过；main、legacy 各 8 通过/4 跳过。合计
+  36 通过、18 明确的 Windows WebKit 无 WebAudio 跳过，0 failed/flaky。
+- 包含发布核心 5.4.0 和候选核心，原生 PCM/WAV、字幕、暂停、切源、stop/restart、
+  context 最终关闭及音量验证。来源提交的核心 5.3.1 未发布到 npm，不能伪造其发布
+  基线；相邻稳定 5.3.0 对照与物理设备仍由 ASR-05 继续取证。
+- 正常三格式构建、docs 副本字节、分包 strict、定向 lint 通过。
+  更新产物重新隔离安装，17 配置声明/真实导出矩阵通过；原有 NodeNext 类型诊断
+  继续明确保留。没有重复整仓 CI，没有增加依赖或改版本。
+
+输入哈希、红绿报告和包安装摘要见
+[音量验证记录](../baselines/asr-volume-validation.json)。本次新产物取代 ASR-03/04
+记录的候选哈希；旧证据保留为对应历史提交的观察，不自动宣称覆盖新产物。
+
+本任务不关闭捕获流 fallback 的原生拓扑、CORS、audio-track 组合或 Safari/设备
+门槛。回退本提交会恢复已复现的音量二次衰减。子代理同期生成的离线 demo 与旧核心
+取证属于 ASR-05 后续工作，不混入本项完成声明。
@@ -2,9 +2,9 @@

 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。

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

-状态：todo 82 / doing 16 / blocked 0 / done 127 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 82 / doing 16 / blocked 0 / done 128 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -17,7 +17,7 @@
 | artplayer | 5.4.1 | CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, CORE-11, CORE-12, CORE-13, CORE-14, CORE-15, CORE-16, CORE-17, CORE-18, CORE-19, CORE-20, CORE-21, CORE-23, CORE-22, CORE-24, CORE-25, ENG-12 |
 | artplayer-plugin-ads | 2.1.0 | PKG-ADS-01, PKG-ADS-02, PKG-ADS-03, PKG-ADS-04, PKG-ADS-05, PKG-ADS-06 |
 | artplayer-plugin-ambilight | 1.1.0 | PKG-AMBILIGHT-01, PKG-AMBILIGHT-02, PKG-AMBILIGHT-03, PKG-AMBILIGHT-04, PKG-AMBILIGHT-PROXY-01, PKG-AMBILIGHT-05, PKG-AMBILIGHT-06, PKG-FACTORY-01 |
-| artplayer-plugin-asr | 2.1.0 | PKG-ASR-01, PKG-ASR-02, PKG-ASR-03, PKG-ASR-04, PKG-ASR-05, PKG-ASR-06 |
+| artplayer-plugin-asr | 2.1.0 | PKG-ASR-01, PKG-ASR-02, PKG-ASR-03, PKG-ASR-04, PKG-ASR-05, PKG-ASR-06, PKG-ASR-07 |
 | artplayer-plugin-audio-track | 1.1.0 | PKG-AUDIO-01, PKG-AUDIO-02, PKG-AUDIO-03, PKG-AUDIO-04, PKG-AUDIO-05, PKG-AUDIO-06 |
 | artplayer-plugin-auto-thumbnail | 1.1.0 | PKG-AUTO-THUMB-01, PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-04, PKG-AUTO-THUMB-05, PKG-AUTO-THUMB-06 |
 | artplayer-plugin-chapter | 1.1.0 | PILOT-01, PKG-CHAPTER-01, PKG-CHAPTER-02, PKG-CHAPTER-03, PKG-CHAPTER-04, PKG-CHAPTER-05, PKG-CHAPTER-06 |
@@ -255,8 +255,9 @@
 | PKG-ASR-02 | artplayer-plugin-asr<br>建立特有行为与错误测试 | PKG-ASR-01, ENG-03, ENG-05 | PCM/WAV、chunk 时序、回调慢/拒绝、重复初始化与停止 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
 | PKG-ASR-03 | artplayer-plugin-asr<br>整理内部职责与资源 | PKG-ASR-02, CORE-10, CORE-18 | AudioContext/Worklet/Stream 生命周期和背压分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | done |
 | PKG-ASR-04 | artplayer-plugin-asr<br>迁移自有源码和公开类型 | PKG-ASR-03, ENG-04, ENG-06, CORE-07 | 主线程/Worklet/音频 buffer 与异步回调类型 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | done |
-| PKG-ASR-05 | artplayer-plugin-asr<br>验证新旧核心和组合 | PKG-ASR-04, CORE-22 | 真实 WebAudio 分块、播放暂停/切源/销毁，不引入网络 ASR | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
+| PKG-ASR-05 | artplayer-plugin-asr<br>验证新旧核心和组合 | PKG-ASR-04, CORE-22, PKG-ASR-07 | 真实 WebAudio 分块、播放暂停/切源/销毁，不引入网络 ASR | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-ASR-06 | artplayer-plugin-asr<br>验证分发并同步文档 | PKG-ASR-05, ENG-07 | asr.js、Worklet 资源、输出格式与声明证据 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
+| PKG-ASR-07 | artplayer-plugin-asr<br>修复原生播放音量二次衰减 | PKG-ASR-04 | 移除重复音量应用；保留新旧原生音频振幅对照及正式产物验收 | Chromium/Firefox 两核心和 source/main/legacy 输出音量线性、静音和 stop/restart 正确；旧版平方衰减单独保留；单元/类型/真实安装通过，不代替设备验收 | H | done |

 ## 5 包迁移：artplayer-plugin-ads

@@ -568,3 +569,4 @@
 - 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)
 - CORE-25: [记录](changes/2026-09-13-CORE-25-defaults-ssr.md) [记录](baselines/defaults-ssr-validation.json)
 - ENG-12: [记录](changes/2026-09-13-ENG-12-library-public.md) [记录](baselines/library-public-validation.json)
+- PKG-ASR-07: [记录](changes/2026-09-13-PKG-ASR-07-playback-volume.md) [记录](baselines/asr-volume-validation.json)
@@ -1,5 +1,18 @@
 # 进度与证据

+## PKG-ASR-07 原生音量修复完成
+
+ASR-05 原生验证发现旧版与候选都重复应用音量：50% 设置只有约25%输出振幅。
+新增独立修复任务，移除重复监听/转发，保留媒体原生音量与静音。修复前线性断言
+已在 Chromium 失败；修复后 source/main/legacy 两核心验证共36过、18明确能力跳过，
+涵盖原有采集生命周期和音量/静音/stop后播放与恢复。208定向及两产物各25生命周期
+通过，正常构建、strict/lint和重新隔离安装17配置通过。见[变更](changes/2026-09-13-PKG-ASR-07-playback-volume.md)
+与[证据](baselines/asr-volume-validation.json)。
+226项：128 done、16 doing、82 todo；206风险。旧版音量缺陷已修复；物理设备、fallback、
+跨源和插件组合仍属 ASR-05。子代理已准备离线示例，并确认来源核心5.3.1未发布；
+后续以真实相邻稳定5.3.0作扩大对照，不能伪造发布基线。无全量CI、推送或发布。
+
+
 ## PKG-ASR-04 公共类型与安装兼容完成

 保留根入口及 legacy 的旧工厂、void stop 和 NodeNext ESM 命名空间形状；新增
@@ -209,3 +209,4 @@
 | ASR-TYPE-01 | resolved / 已复现 | ASR declarations omit asynchronous stop and callback text results | PKG-ASR-04 |
 | ASR-CHUNK-01 | resolved / 已复现 | ASR tick discards underfilled chunks and overrun samples in source | PKG-ASR-02, PKG-ASR-03 |
 | ASR-LIFE-01 | resolved / 已复现 | ASR partial initialization, pause resume and stale callback cleanup need controlled evidence | PKG-ASR-02, PKG-ASR-03, PKG-ASR-05 |
+| ASR-VOLUME-01 | resolved / 已复现 | ASR applies media volume twice and squares playback amplitude | PKG-ASR-07 |
@@ -4617,6 +4617,26 @@
        "test/asr-encoding.test.js"
      ],
      "resolutionRationale": "Candidate ownership/race regression tests pass, including retired-port delivery and module failure before binding video. Actual Chromium/Firefox source/main/legacy with both cores verify pause, source change, explicit stop/restart and final close. Direct media contexts deliberately remain player-owned until destroy; disposable stream contexts close on stop. General native fallback/volume/device acceptance remains ASR-05 and SDK-11, not claimed by this specific fix."
+    },
+    {
+      "id": "ASR-VOLUME-01",
+      "title": "ASR applies media volume twice and squares playback amplitude",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "PKG-ASR-07"
+      ],
+      "evidence": [
+        "test/browser/asr-playback.spec.js",
+        "refactor/baselines/asr-volume-validation.json"
+      ],
+      "compatibleResolution": "Retain public volume API and apply it once through the media element.",
+      "closureCriteria": "Native graph amplitude is linear across volume changes, mute and ASR stop/restart; old behavior is separately reproduced.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-13-PKG-ASR-07-playback-volume.md",
+        "refactor/baselines/asr-volume-validation.json"
+      ],
+      "resolutionRationale": "Native Chromium/Firefox source/main/legacy on published and candidate core pass relative-amplitude assertions. Formal 2.1 baseline retains squared amplitude. The fix does not establish physical device or captured-fallback acceptance."
    }
  ]
 }
@@ -2701,7 +2701,8 @@
      ],
      "dependsOn": [
        "PKG-ASR-04",
-        "CORE-22"
+        "CORE-22",
+        "PKG-ASR-07"
      ],
      "status": "todo",
      "risk": "H",
@@ -4536,6 +4537,25 @@
        "changes/2026-09-13-ENG-12-library-public.md",
        "baselines/library-public-validation.json"
      ]
+    },
+    {
+      "id": "PKG-ASR-07",
+      "phase": "5 包迁移：artplayer-plugin-asr",
+      "title": "修复原生播放音量二次衰减",
+      "scope": [
+        "artplayer-plugin-asr"
+      ],
+      "dependsOn": [
+        "PKG-ASR-04"
+      ],
+      "status": "done",
+      "risk": "H",
+      "deliverable": "移除重复音量应用；保留新旧原生音频振幅对照及正式产物验收",
+      "acceptance": "Chromium/Firefox 两核心和 source/main/legacy 输出音量线性、静音和 stop/restart 正确；旧版平方衰减单独保留；单元/类型/真实安装通过，不代替设备验收",
+      "evidence": [
+        "changes/2026-09-13-PKG-ASR-07-playback-volume.md",
+        "baselines/asr-volume-validation.json"
+      ]
    }
  ]
 }