@video-lab/player-core 3.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +57 -23
  2. package/dist/index.cjs +518 -147
  3. package/dist/index.d.cts +21 -18
  4. package/dist/index.d.mts +21 -18
  5. package/dist/index.mjs +517 -146
  6. package/package.json +2 -2
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { DanmakuItem, DeliveredPlayerEvent, ErrorCode, HlsConfig, LocaleConfig, MediaMetadata, MediaSource, PageFullscreenAdapter, PlaybackContext, PlaybackKernel, PlayerConfig, PlayerError, PlayerEvent, SourceEntry, SubtitleTrack } from "@video-lab/protocol";
1
+ import { DanmakuItem, ErrorCode, HlsConfig, LocaleConfig, MediaMetadata, MediaSource, PageFullscreenAdapter, PlaybackContext, PlaybackKernel, PlayerConfig, PlayerError, PlayerEvent, SourceEntry, SubtitleTrack } from "@video-lab/protocol";
2
2
  //#region src/env.d.ts
3
3
  /**
4
4
  * 运行环境探测。
@@ -12,12 +12,13 @@ interface EnvInput {
12
12
  /**
13
13
  * MediaSource Extensions 是否可用。FLV / hls.js 都依赖它。
14
14
  *
15
- * **iOS 全系没有标准 MSE**(全部浏览器都是 WebKit 内核),所以 flv.js 起不来,
16
- * 且 Safari 的 `<video>` 不认 FLV 容器 —— 没有原生兜底,这是 iOS 强制 HLS 的根因。
15
+ * 对当前 SDK 支持的 iPhone Safari 路径，标准 `window.MediaSource` 不可用，
16
+ * 所以仅识别该 API 的 flv.js 起不来；Safari 的 `<video>` 也没有 FLV 原生容器兜底。
17
17
  *
18
18
  * ⚠️ 严格说 iOS 17.1+ 引入了 `ManagedMediaSource`(MSE 的受控变体),平台层面
19
- * 已非绝对不可能。但本 SDK 用的 flv.js 停止维护、未迁移到 MMS(只认 `window.MediaSource`),
20
- * 故当前判定仍然成立。若将来评估换 mpegts.js 等支持 MMS 的内核,这里需重新讨论(须走 ADR)。
19
+ * 已非平台能力上的绝对不可能。但本 SDK 的 flv.js 路径未迁移到 MMS(只认 `window.MediaSource`),
20
+ * 故当前产品结论是“不支持 iPhone Safari 播放 FLV”。若将来换用支持 MMS 或软解的内核，
21
+ * 这里需重新评估(须走 ADR)。
21
22
  *
22
23
  * ⚠️⚠️ **这个布尔只回答「flv.js 跑不跑得起来」,别把 MMS 混进来**(ADR-056)。
23
24
  * hls.js 认 MMS、flv.js 不认 —— 两个不同的问题,不许共用一个布尔。
@@ -25,11 +26,12 @@ interface EnvInput {
25
26
  */
26
27
  hasMediaSource: boolean;
27
28
  /**
28
- * `ManagedMediaSource` 是否可用(iOS 17.1+ / macOS Safari 17.1+)。
29
+ * `ManagedMediaSource` 是否实际可用（Safari 17.1 引入不等于所有环境都无条件可用）。
29
30
  *
30
31
  * **只有 hls.js 用得上它**(1.5+ 支持,1.6.16 默认 `preferManagedMediaSource: true`)。
31
32
  * 它的存在是 ADR-056 能把 iOS 的 HLS 从原生换到 hls.js 的**唯一**技术前提 ——
32
- * iPhone 上 `window.MediaSource` 至今不存在(真机实测),没有 MMS 就只能回原生。
33
+ * 仓库已记录的 iPhone 16 Pro / iPhone OS 18.7 / Safari Version 27.0 能力探测结果为
34
+ * `MediaSource=false` / `ManagedMediaSource=true`；这是能力探测，不是 FLV 播放成功证明。
33
35
  */
34
36
  hasManagedMediaSource?: boolean;
35
37
  }
@@ -50,9 +52,10 @@ interface Env {
50
52
  /** `ManagedMediaSource` 可用(iOS 17.1+ / Safari 17.1+)。只有 hls.js 认它 */
51
53
  hasManagedMediaSource: boolean;
52
54
  /**
53
- * 必须走 HLS 的环境:iOS(无 MSE,FLV 播不了)、微信 / QQ WebView、UC、夸克。
55
+ * 当前 SDK 必须走 HLS 的环境:iOS(缺少当前 flv.js 所需的标准 MSE)、
56
+ * 微信 / QQ WebView、UC、夸克。
54
57
  *
55
- * 这些环境里 FLV 要么无法解码(iOS 无 MSE),要么被浏览器内置播放器劫持
58
+ * 这些环境里 FLV 要么不在当前 SDK 支持范围(iPhone),要么被浏览器内置播放器劫持
56
59
  * (UC 见坑 #9、夸克见坑 #10)。编号以 .claude/context/xgplayer-pitfalls.md 为准。
57
60
  */
58
61
  requiresHls: boolean;
@@ -85,11 +88,6 @@ interface CreatePlayerOptions {
85
88
  * 契约事件后原样交出去——由 embed-app / react 包决定怎么分发。
86
89
  */
87
90
  onEvent?: (event: PlayerEvent) => void;
88
- /**
89
- * 兼容的完整投递流。生产端在这里生成 session、时钟和序号；旧 `onEvent` 保持 raw
90
- * `PlayerEvent` 形状不变。
91
- */
92
- onDeliveredEvent?: (event: DeliveredPlayerEvent) => void;
93
91
  /**
94
92
  * 运行环境。不传就从当前浏览器探测。
95
93
  * 测试时注入假的 UA 来验证平台分支(SourceRouter 就靠它)。
@@ -250,7 +248,12 @@ declare function isAutoplayBlocked(err: unknown): boolean;
250
248
  * mapXgplayerError({ errorType: 'timeout', message: '请求超时' })
251
249
  * // → { code: 'E_NETWORK_TIMEOUT', category: 'network', retryable: true, ... }
252
250
  */
253
- declare function mapXgplayerError(err: unknown): PlayerError;
251
+ /** 映射时需要的源上下文。不传时按直播 / 未知处理，行为与 #106 之前一致 */
252
+ interface ErrorMappingContext {
253
+ /** 当前源是否直播。`false` 时启用点播细化（ADR-107） */
254
+ live?: boolean;
255
+ }
256
+ declare function mapXgplayerError(err: unknown, context?: ErrorMappingContext): PlayerError;
254
257
  //#endregion
255
258
  //#region src/source-normalize.d.ts
256
259
  /** 归一化后的媒体源。三种写法(字符串 / 单源 / 多源)统一成这一种形态 */
@@ -294,7 +297,7 @@ declare function normalizeSource(source: MediaSource): NormalizedSource;
294
297
  /**
295
298
  * 播放内核。决定加载哪个 xgplayer 插件:
296
299
  * - `native` · 浏览器原生 `<video>`(MP4 永远走这个;HLS 只在**既没有 MSE 也没有 MMS** 时回落到这)
297
- * - `hls.js` · xgplayer-hls.js
300
+ * - `hls.js` · SDK 自有 OwnedHlsPlugin + hls.js/light
298
301
  * - `flv.js` · xgplayer-flv.js
299
302
  *
300
303
  * **MP4 永远是 native**:xgplayer-mp4 插件是硬阻塞(坑 #30 #31 #32,
@@ -327,13 +330,13 @@ interface RoutedSource {
327
330
  * 最早也只到 `beforeCreate`,拿不到这个时机。所以它是一个纯函数,
328
331
  * 由 create-player 在构造 player 前调用。纯函数也更好测:UA 直接传进来就行。
329
332
  *
330
- * 选择规则(ARCHITECTURE § 8.2):
333
+ * 选择规则（见 ADR-056 与 MEDIA-SOURCE-GUIDE）：
331
334
  * 1. iOS / 微信 / QQ / UC / 夸克 → **强制 HLS**;没 HLS 退 MP4;只剩 FLV 抛 `E_MEDIA_NOT_SUPPORTED`
332
335
  * 2. 其他平台:直播 `flv → hls → mp4`(FLV 延迟低);点播 `hls → mp4 → flv`(HLS 功能全)
333
336
  *
334
337
  * **降级只发生在选源这一刻,没有运行时兜底。** 上面的「→」是**候选缺失**时往下取
335
338
  * (没有 FLV 就用 HLS),**不是播放失败后换一个再试** —— 选完之后 `candidates` 里
336
- * 剩下的项没有任何代码会再读:ReconnectPlugin 重连 reload 的是同一个 URL(#192),
339
+ * 剩下的项没有任何代码会再读：统一恢复仍重拉同一个 URL(#192),
337
340
  * 而 `load()` 跨内核会直接抛 `E_METHOD_NOT_SUPPORTED`。想要真兜底就得销毁重建 player,
338
341
  * 那是一条要走 ADR 的独立能力(#217)。
339
342
  *
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { DanmakuItem, DeliveredPlayerEvent, ErrorCode, HlsConfig, LocaleConfig, MediaMetadata, MediaSource, PageFullscreenAdapter, PlaybackContext, PlaybackKernel, PlayerConfig, PlayerError, PlayerEvent, SourceEntry, SubtitleTrack } from "@video-lab/protocol";
1
+ import { DanmakuItem, ErrorCode, HlsConfig, LocaleConfig, MediaMetadata, MediaSource, PageFullscreenAdapter, PlaybackContext, PlaybackKernel, PlayerConfig, PlayerError, PlayerEvent, SourceEntry, SubtitleTrack } from "@video-lab/protocol";
2
2
  //#region src/env.d.ts
3
3
  /**
4
4
  * 运行环境探测。
@@ -12,12 +12,13 @@ interface EnvInput {
12
12
  /**
13
13
  * MediaSource Extensions 是否可用。FLV / hls.js 都依赖它。
14
14
  *
15
- * **iOS 全系没有标准 MSE**(全部浏览器都是 WebKit 内核),所以 flv.js 起不来,
16
- * 且 Safari 的 `<video>` 不认 FLV 容器 —— 没有原生兜底,这是 iOS 强制 HLS 的根因。
15
+ * 对当前 SDK 支持的 iPhone Safari 路径，标准 `window.MediaSource` 不可用，
16
+ * 所以仅识别该 API 的 flv.js 起不来；Safari 的 `<video>` 也没有 FLV 原生容器兜底。
17
17
  *
18
18
  * ⚠️ 严格说 iOS 17.1+ 引入了 `ManagedMediaSource`(MSE 的受控变体),平台层面
19
- * 已非绝对不可能。但本 SDK 用的 flv.js 停止维护、未迁移到 MMS(只认 `window.MediaSource`),
20
- * 故当前判定仍然成立。若将来评估换 mpegts.js 等支持 MMS 的内核,这里需重新讨论(须走 ADR)。
19
+ * 已非平台能力上的绝对不可能。但本 SDK 的 flv.js 路径未迁移到 MMS(只认 `window.MediaSource`),
20
+ * 故当前产品结论是“不支持 iPhone Safari 播放 FLV”。若将来换用支持 MMS 或软解的内核，
21
+ * 这里需重新评估(须走 ADR)。
21
22
  *
22
23
  * ⚠️⚠️ **这个布尔只回答「flv.js 跑不跑得起来」,别把 MMS 混进来**(ADR-056)。
23
24
  * hls.js 认 MMS、flv.js 不认 —— 两个不同的问题,不许共用一个布尔。
@@ -25,11 +26,12 @@ interface EnvInput {
25
26
  */
26
27
  hasMediaSource: boolean;
27
28
  /**
28
- * `ManagedMediaSource` 是否可用(iOS 17.1+ / macOS Safari 17.1+)。
29
+ * `ManagedMediaSource` 是否实际可用（Safari 17.1 引入不等于所有环境都无条件可用）。
29
30
  *
30
31
  * **只有 hls.js 用得上它**(1.5+ 支持,1.6.16 默认 `preferManagedMediaSource: true`)。
31
32
  * 它的存在是 ADR-056 能把 iOS 的 HLS 从原生换到 hls.js 的**唯一**技术前提 ——
32
- * iPhone 上 `window.MediaSource` 至今不存在(真机实测),没有 MMS 就只能回原生。
33
+ * 仓库已记录的 iPhone 16 Pro / iPhone OS 18.7 / Safari Version 27.0 能力探测结果为
34
+ * `MediaSource=false` / `ManagedMediaSource=true`；这是能力探测，不是 FLV 播放成功证明。
33
35
  */
34
36
  hasManagedMediaSource?: boolean;
35
37
  }
@@ -50,9 +52,10 @@ interface Env {
50
52
  /** `ManagedMediaSource` 可用(iOS 17.1+ / Safari 17.1+)。只有 hls.js 认它 */
51
53
  hasManagedMediaSource: boolean;
52
54
  /**
53
- * 必须走 HLS 的环境:iOS(无 MSE,FLV 播不了)、微信 / QQ WebView、UC、夸克。
55
+ * 当前 SDK 必须走 HLS 的环境:iOS(缺少当前 flv.js 所需的标准 MSE)、
56
+ * 微信 / QQ WebView、UC、夸克。
54
57
  *
55
- * 这些环境里 FLV 要么无法解码(iOS 无 MSE),要么被浏览器内置播放器劫持
58
+ * 这些环境里 FLV 要么不在当前 SDK 支持范围(iPhone),要么被浏览器内置播放器劫持
56
59
  * (UC 见坑 #9、夸克见坑 #10)。编号以 .claude/context/xgplayer-pitfalls.md 为准。
57
60
  */
58
61
  requiresHls: boolean;
@@ -85,11 +88,6 @@ interface CreatePlayerOptions {
85
88
  * 契约事件后原样交出去——由 embed-app / react 包决定怎么分发。
86
89
  */
87
90
  onEvent?: (event: PlayerEvent) => void;
88
- /**
89
- * 兼容的完整投递流。生产端在这里生成 session、时钟和序号；旧 `onEvent` 保持 raw
90
- * `PlayerEvent` 形状不变。
91
- */
92
- onDeliveredEvent?: (event: DeliveredPlayerEvent) => void;
93
91
  /**
94
92
  * 运行环境。不传就从当前浏览器探测。
95
93
  * 测试时注入假的 UA 来验证平台分支(SourceRouter 就靠它)。
@@ -250,7 +248,12 @@ declare function isAutoplayBlocked(err: unknown): boolean;
250
248
  * mapXgplayerError({ errorType: 'timeout', message: '请求超时' })
251
249
  * // → { code: 'E_NETWORK_TIMEOUT', category: 'network', retryable: true, ... }
252
250
  */
253
- declare function mapXgplayerError(err: unknown): PlayerError;
251
+ /** 映射时需要的源上下文。不传时按直播 / 未知处理，行为与 #106 之前一致 */
252
+ interface ErrorMappingContext {
253
+ /** 当前源是否直播。`false` 时启用点播细化（ADR-107） */
254
+ live?: boolean;
255
+ }
256
+ declare function mapXgplayerError(err: unknown, context?: ErrorMappingContext): PlayerError;
254
257
  //#endregion
255
258
  //#region src/source-normalize.d.ts
256
259
  /** 归一化后的媒体源。三种写法(字符串 / 单源 / 多源)统一成这一种形态 */
@@ -294,7 +297,7 @@ declare function normalizeSource(source: MediaSource): NormalizedSource;
294
297
  /**
295
298
  * 播放内核。决定加载哪个 xgplayer 插件:
296
299
  * - `native` · 浏览器原生 `<video>`(MP4 永远走这个;HLS 只在**既没有 MSE 也没有 MMS** 时回落到这)
297
- * - `hls.js` · xgplayer-hls.js
300
+ * - `hls.js` · SDK 自有 OwnedHlsPlugin + hls.js/light
298
301
  * - `flv.js` · xgplayer-flv.js
299
302
  *
300
303
  * **MP4 永远是 native**:xgplayer-mp4 插件是硬阻塞(坑 #30 #31 #32,
@@ -327,13 +330,13 @@ interface RoutedSource {
327
330
  * 最早也只到 `beforeCreate`,拿不到这个时机。所以它是一个纯函数,
328
331
  * 由 create-player 在构造 player 前调用。纯函数也更好测:UA 直接传进来就行。
329
332
  *
330
- * 选择规则(ARCHITECTURE § 8.2):
333
+ * 选择规则（见 ADR-056 与 MEDIA-SOURCE-GUIDE）：
331
334
  * 1. iOS / 微信 / QQ / UC / 夸克 → **强制 HLS**;没 HLS 退 MP4;只剩 FLV 抛 `E_MEDIA_NOT_SUPPORTED`
332
335
  * 2. 其他平台:直播 `flv → hls → mp4`(FLV 延迟低);点播 `hls → mp4 → flv`(HLS 功能全)
333
336
  *
334
337
  * **降级只发生在选源这一刻,没有运行时兜底。** 上面的「→」是**候选缺失**时往下取
335
338
  * (没有 FLV 就用 HLS),**不是播放失败后换一个再试** —— 选完之后 `candidates` 里
336
- * 剩下的项没有任何代码会再读:ReconnectPlugin 重连 reload 的是同一个 URL(#192),
339
+ * 剩下的项没有任何代码会再读：统一恢复仍重拉同一个 URL(#192),
337
340
  * 而 `load()` 跨内核会直接抛 `E_METHOD_NOT_SUPPORTED`。想要真兜底就得销毁重建 player,
338
341
  * 那是一条要走 ADR 的独立能力(#217)。
339
342
  *