docs(audio): [PKG-AUDIO-01] freeze released synchronization contract

2026-10-24 23:51:20 -08:00 · 2026-09-12 01:48:42 +08:00
1 parent 26b2983daf
commit 8c0a2feed3
@@ -35,6 +35,10 @@ BASE-01 于 2026-09-10 固定核心与 chapter 的 npm 发布内容，数据在

 ## 公共 API 报告

+Audio Track 的后续包基线由 PKG-AUDIO-01 独立冻结，见
+[契约和重跑](audio-track-contract.md) 及 [1.1.0 归档来源](audio-track-release.json)。
+它不改写本目录初始 BASE 快照，媒体/类型/设备通过范围由后续任务提供。
+
 BASE-02 已在内置浏览器取得核心/chapter 的同步 API 和描述符快照，见 [覆盖与重跑](api-coverage.md) 和 [冻结报告](public-api.json)。事件/生命周期、DOM、类型、分发和其他包仍由各自任务补齐。

 ## 事件与生命周期报告
@@ -0,0 +1,94 @@
+# Audio Track 1.1.0 兼容基线
+
+PKG-AUDIO-01；源码起点 26b2983daf9edf9c798ce6a1638deeb3c36ba778。
+固定来源、逐文件 SHA-256、npm SRI、历史源码及比较结果见
+[audio-track-release.json](audio-track-release.json)。不覆盖 BASE-01 的历史快照。
+
+## 来源与范围
+
+npm 观察到 1.0.0、1.1.0，采集时 latest 为 1.1.0。本次实际归档范围为 **1.1.0**，
+不是所有历史版本。六文件归档完整性通过，manifest、README、公开声明与起点源码
+在 LF 规范化后相同，发布 ESM 与源码工厂经 AST 提取/esbuild 规范化后相同。
+这证明比较范围内的逻辑一致，不能代替真实媒体行为测试。
+
+registry gitHead daf133b22630b4a0eecfa3336bbddab0e9119d96 对应本地包版本 1.0.2，
+不是该 npm 1.1.0 源码的充分证明；因此保留归档完整性和独立工厂比较。
+manifest 无 runtime/peer 依赖、无核心/浏览器/TS 最低版本承诺。
+旧核心对照使用现有冻结的 5.4.0；这只是具体检查点，不宣称最低支持版本为 5.4.0。
+
+## 公开形状及调用
+
+```js
+const attach = artplayerPluginAudioTrack({ url: '/audio.aac', offset: 0, sync: 0.3 })
+// ArtPlayer 注册时调用 attach(art)
+const result = art.plugins.artplayerPluginAudioTrack
+result.update({ url: '/next.aac', offset: 0.2 })
+const audio = result.audio // 同一 HTMLAudioElement，可直接操作
+```
+
+工厂配置为必传对象；工厂同步返回安装函数，安装同步返回 `{ name, audio, update }`。
+name 固定为 `artplayerPluginAudioTrack`，update 同步返回 undefined。没有额外公开 destroy、
+事件、UI、CSS、静态版本或 SDK。插件创建独立 Audio 元素，不替换主视频，也不自动静音主视频；
+因此含原音轨的主视频可能与外部音频同时播放，这是现有行为，不静默改变音量策略。
+每次安装创建独立状态；配置在安装时解构，调用工厂后、安装前的对象修改会生效。
+
+| 输入或行为 | 1.1.0 源码/发布实现事实 | 兼容与后续验证 |
+| --- | --- | --- |
+| url | 初始仅 truthy 时赋给 audio.src，preload 为 auto | URL 字符串交给浏览器解析，无 SDK |
+| offset | 默认 0，目标 audio 时间是 art.currentTime + offset | 正数音频领先、负数滞后；负目标/超时长在 02 实测 |
+| sync | 默认 0.3，仅绝对偏差严格大于阈值才 seek | 等于阈值不写；未校验负数、NaN、Infinity，不能凭猜测新增拒绝规则 |
+| update | truthy 且不同 URL 才赋 src；playing 时调用 play；之后才更新 offset/sync | 同 URL 不重载，空 URL 不清源；JS 允许只传 offset/sync，且不立即同步 |
+| audio | 公开真实元素，同一引用贯穿安装/更新/销毁 | 不换为不可访问封装，不用新元素实现每次切源 |
+| 音量/倍率 | 初始 volume/muted 来自 art；倍率 video?.playbackRate 或 1 | 后续 video:volumechange/ratechange 同步，无自有主视频 mute |
+| play 拒绝 | 三个调用点各自 catch 并 console.warn 原错误 | 没有返回给调用者的 play Promise、没有自定义错误事件 |
+
+| ArtPlayer 事件 | 外部音频行为 |
+| --- | --- |
+| play | 有 URL 才同步目标时间，随后 audio.play |
+| pause | audio.pause |
+| seek | 有 video/URL 才同步时间 |
+| video:timeupdate | art.playing 时同步时间 |
+| video:ratechange | 读 art.video.playbackRate |
+| video:volumechange | 同步 art.volume 和 art.muted |
+| video:waiting | audio.pause |
+| video:playing | 有 URL 且 art.playing 才 audio.play，不主动 sync |
+| destroy | pause、src = ''、load，按此顺序 |
+
+没有定时器或自建请求；浏览器拥有媒体加载。当前九个 emitter 回调没有插件自身解绑，
+依赖核心销毁清空事件。没有 closed 状态，外部保留的 update 可在销毁后写入新 src。
+这些是源码观察，02 用受控复现及真实媒体验证；不能只凭观察称内存泄漏已复现。
+
+## 类型和分发
+
+公开默认导出为 `(option: Option) => (art: Artplayer) => Result`，Option.url 必需、
+offset/sync 可选；Result.audio 为 HTMLAudioElement，update(option: Option): void。
+Option/Result 未具名导出，消费者可用 Parameters/ReturnType 提取；04 保留这些旧合法调用。
+JS 的 update({ offset: 1 }) 与声明不一致，允许拓宽 update 为部分配置，但不弱化字段类型。
+docs 编辑器声明还同时包含 export default/export =，由 04 做语义验证及生成修正，
+本步不声称编辑器或 TS 消费已经通过。
+
+root exports 使用 types + import(mjs)/require(js)，legacy import/require 都指向 legacy.js；
+main/module/types/legacy 的完整值冻结在 manifest。UMD 全局名与默认导出一致。
+保留 `/legacy`、旧文件路径、同步注册和未加载 DOM 时的导入边界；实际各格式消费由 02/04/06 验证。
+当前版本保持 1.1.0，REL-09 按用户要求准备 2.0.0，未获 npm 发布授权。
+
+## 文档、样本与差异归属
+
+README 仅说明插件名、Demo 和 MIT；其 `example=audio-track` 与真实
+`docs/assets/example/audio.track.js` 不一致。common.js 直接拼接名称，无连字符转换。
+实际示例使用本地 sprite-fight.mp4 + sprite-fight.aac，二者存在；没有演示 update、
+偏移边界或销毁。06 应修链接并以正式 8082 demo 验证，不能拿静态文件存在作为播放通过。
+
+| 风险 | 当前证据等级 | 负责任务 |
+| --- | --- | --- |
+| AUDIO-LIFE-01：销毁后 update 可写 src，监听/异步播放归属缺少终止守卫 | 源码事实，未作浏览器泄漏结论 | 02/03/05 |
+| AUDIO-SYNC-01：偏移边界及切源/缓冲恢复缺少媒体时序证据 | 待取证，不预设所有当前行为是缺陷 | 02/03/05 |
+| AUDIO-TYPE-01：update 部分配置和编辑器声明不一致 | 源码/声明事实 | 04 |
+| AUDIO-DEMO-01：README 示例名不匹配、维护说明缺失 | 源码/文件事实 | 06 |
+
+## 重跑
+
+`node refactor/scripts/audio-contract.mjs`：重验固定归档、六文件、manifest、历史 Git 内容与工厂。
+首次仅从固定 npm URL 下载至忽略缓存；不安装、不执行归档脚本、不覆盖基线。
+`node --test refactor/scripts/audio-contract.test.mjs`：包含该验证及规范化工具的有意行为变化检查。
+本步不改生产代码/声明/构建产物；所有媒体、类型和设备验收仍是后续任务。
@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 1,
+  "task": "PKG-AUDIO-01",
+  "capturedAt": "2026-09-11T17:44:31.880Z",
+  "sourceCommit": "26b2983daf9edf9c798ce6a1638deeb3c36ba778",
+  "registryObservation": {
+    "registryUrl": "https://registry.npmjs.org/artplayer-plugin-audio-track",
+    "distTags": {
+      "latest": "1.1.0"
+    },
+    "versions": [
+      "1.0.0",
+      "1.1.0"
+    ],
+    "publishedAt": "2026-03-12T14:21:57.424Z",
+    "note": "Observed metadata; not a promise of future latest version or support for every older release."
+  },
+  "release": {
+    "name": "artplayer-plugin-audio-track",
+    "version": "1.1.0",
+    "metadataUrl": "https://registry.npmjs.org/artplayer-plugin-audio-track/1.1.0",
+    "tarball": "https://registry.npmjs.org/artplayer-plugin-audio-track/-/artplayer-plugin-audio-track-1.1.0.tgz",
+    "integrity": "sha512-pvvHvTSqC2+sBelwYyjAv2CVmaQgG9KpX+i96t/e8oyZRX/JuepC9iSVIp7GzB3AtliFzhVamksT+8lXvD3RCg==",
+    "sha256": "7e84f6a2f4bfada428a77ef04b749bf3db53e0149fa1afe7bf5749d925e801ff",
+    "archiveBytes": 2205,
+    "registryGitHead": "daf133b22630b4a0eecfa3336bbddab0e9119d96",
+    "files": {
+      "package/README.md": "9a03352433ae90cb9d3198e17571c9bb598334b84a77a3a1df2c4b000ce8347d",
+      "package/dist/artplayer-plugin-audio-track.js": "473f39f1d750f0722cca7e857c12c3c978ebe3c3b2352e325f1248318e508683",
+      "package/dist/artplayer-plugin-audio-track.legacy.js": "d8dc74bce76112d7430c98e3165605e32fde5d3c603be4b496eac58f574576cb",
+      "package/dist/artplayer-plugin-audio-track.mjs": "4ac599bc5a1a6ecb0cb1942d4269528bfb2cd9d047f988de61fe671a77ad14cd",
+      "package/package.json": "c466ae55c40e8f6bdd97bec20fcf916c8c4f44eef3e47694638be005eb445df7",
+      "package/types/artplayer-plugin-audio-track.d.ts": "27bc0dfedacb7e0188cb668ac8708874a86b00d489f1636037c2465d3344437e"
+    },
+    "manifest": {
+      "name": "artplayer-plugin-audio-track",
+      "version": "1.1.0",
+      "description": "audio-track plugin for ArtPlayer",
+      "author": "Harvey Zhao <laozhaochaguan@gmail.com>",
+      "license": "MIT",
+      "homepage": "https://artplayer.org",
+      "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zhw2590582/ArtPlayer.git"
+      },
+      "bugs": {
+        "url": "https://github.com/zhw2590582/ArtPlayer/issues"
+      },
+      "keywords": [
+        "html5",
+        "video",
+        "player"
+      ],
+      "exports": {
+        ".": {
+          "types": "./types/artplayer-plugin-audio-track.d.ts",
+          "import": "./dist/artplayer-plugin-audio-track.mjs",
+          "require": "./dist/artplayer-plugin-audio-track.js"
+        },
+        "./legacy": {
+          "types": "./types/artplayer-plugin-audio-track.d.ts",
+          "import": "./dist/artplayer-plugin-audio-track.legacy.js",
+          "require": "./dist/artplayer-plugin-audio-track.legacy.js"
+        }
+      },
+      "main": "dist/artplayer-plugin-audio-track.js",
+      "module": "./dist/artplayer-plugin-audio-track.mjs",
+      "types": "types/artplayer-plugin-audio-track.d.ts",
+      "legacy": "dist/artplayer-plugin-audio-track.legacy.js",
+      "browserslist": "last 1 Chrome version"
+    }
+  },
+  "source": {
+    "packages/artplayer-plugin-audio-track/package.json": "c466ae55c40e8f6bdd97bec20fcf916c8c4f44eef3e47694638be005eb445df7",
+    "packages/artplayer-plugin-audio-track/README.md": "9a03352433ae90cb9d3198e17571c9bb598334b84a77a3a1df2c4b000ce8347d",
+    "packages/artplayer-plugin-audio-track/types/artplayer-plugin-audio-track.d.ts": "27bc0dfedacb7e0188cb668ac8708874a86b00d489f1636037c2465d3344437e",
+    "packages/artplayer-plugin-audio-track/src/index.js": "470237ebd62e8fb8537e809db03fd02871844d41c03d422a22956bd2756ac28e",
+    "docs/assets/example/audio.track.js": "9ed26b2ee006e1a430db68b2a1b308c4801dd3a4cc87c74e8a8f5ccf3456ac8d",
+    "docs/assets/ts/artplayer-plugin-audio-track.d.ts": "e0815cb05be2366957df77f0de81a46f863c4d8e0a0697fac1258c4f48da85ea"
+  },
+  "comparisons": [
+    {
+      "file": "package.json",
+      "publishedLF": "c466ae55c40e8f6bdd97bec20fcf916c8c4f44eef3e47694638be005eb445df7",
+      "workspaceLF": "c466ae55c40e8f6bdd97bec20fcf916c8c4f44eef3e47694638be005eb445df7",
+      "equal": true
+    },
+    {
+      "file": "README.md",
+      "publishedLF": "9a03352433ae90cb9d3198e17571c9bb598334b84a77a3a1df2c4b000ce8347d",
+      "workspaceLF": "9a03352433ae90cb9d3198e17571c9bb598334b84a77a3a1df2c4b000ce8347d",
+      "equal": true
+    },
+    {
+      "file": "types/artplayer-plugin-audio-track.d.ts",
+      "publishedLF": "27bc0dfedacb7e0188cb668ac8708874a86b00d489f1636037c2465d3344437e",
+      "workspaceLF": "27bc0dfedacb7e0188cb668ac8708874a86b00d489f1636037c2465d3344437e",
+      "equal": true
+    }
+  ],
+  "functionComparison": {
+    "sha256": "6a758f0a88567283ae44bc9d1fa0906161f6ce9d384803637d7124c2dc1b87da",
+    "typescript": "5.9.3",
+    "esbuild": "0.27.7",
+    "scope": [
+      "artplayerPluginAudioTrack"
+    ],
+    "excludes": [
+      "bundler wrappers"
+    ],
+    "note": "Historical source at sourceCommit; normalized factory comparison is not runtime acceptance."
+  }
+}