@video-lab/player-core 4.1.0 → 4.1.2

package/README.md

@@ -103,6 +103,8 @@ window.addEventListener('pagehide', () => player.destroy(), { once: true })
 
 **换内核会明确报错。** hls.js / flv.js 的内核插件在构造时注册,运行时换不了。`load()` 一个需要不同内核的源时抛 `E_METHOD_NOT_SUPPORTED`,而不是悄悄播不出来。消费方需要销毁 player 用新 source 重建。
 
+**新源加载失败只经 `error` 事件报告一次。** `load()` 在这次换源有结论时 resolve：新源起播、源故障已通过 `error` 报出、被更新的 `load()` 取代或播放器销毁。它只在换源前的校验失败(非法 source、换内核、改构造期配置、选不出可播放源)时 reject(ADR-136)。
+
 **直播的 `duration` 是 0,不是 Infinity。** Infinity 过不了 JSON 序列化(变成 null),而事件要跨 iframe 传,所以在源头就归一成 0。
 
 ## 环境探测与测试

package/dist/index.cjs

@@ -120,6 +120,27 @@ function detectEnv(input) {
 		requiresHls: isIOS || isWeChat || isUC || isQuark || !input.hasMediaSource
 	};
 }
+/** flv.js `isSupported()` 用的同一句基线:连它都报不支持,hls.js / flv.js 都不会开始播放 */
+const MSE_BASELINE_TYPE = "video/mp4; codecs=\"avc1.42E01E,mp4a.40.2\"";
+/**
+* 标准 MSE 是否**可用**,而不只是存在(ADR-135)。
+*
+* 小米浏览器(MiuiBrowser 20.28)暴露了 `MediaSource`,但 `isTypeSupported` 对所有
+* H.264/AAC 组合都回 false —— 实际 `addSourceBuffer` 能成功,是它报错了能力。
+* hls.js 信了前者,对声明了 CODECS 的主清单报 `manifestIncompatibleCodecsError`(不可重试)。
+* 按基线判为不可用后,SourceRouter 走原生 HLS,而该浏览器原生 HLS 播放、拖动都正常。
+*
+* 没有 `isTypeSupported` 的实现仍按「存在即可用」,只收紧「明确报不支持」这一种情况。
+*/
+function hasUsableMediaSource(mediaSource) {
+	if (typeof mediaSource === "undefined") return false;
+	if (typeof mediaSource.isTypeSupported !== "function") return true;
+	try {
+		return mediaSource.isTypeSupported(MSE_BASELINE_TYPE);
+	} catch {
+		return false;
+	}
+}
 /**
 * 从当前浏览器读环境。SSR 场景(没有 window / navigator)返回一个保守的默认值:
 * 当作没有 MSE,于是强制走 HLS —— 宁可保守也不要在服务端渲染时误判成能播 FLV。
@@ -132,7 +153,7 @@ function detectEnvFromGlobals() {
 	});
 	return detectEnv({
 		userAgent: navigator.userAgent,
-		hasMediaSource: typeof window.MediaSource !== "undefined",
+		hasMediaSource: hasUsableMediaSource(window.MediaSource),
 		hasManagedMediaSource: typeof window.ManagedMediaSource !== "undefined"
 	});
 }
@@ -3154,8 +3175,15 @@ function createPlayer(options) {
 	let recovery = null;
 	let eventStreamReady = false;
 	const deferredEvents = [];
+	/**
+	* 挂起中的 `load()` 的结束口(ADR-136)。换源后的源故障只经 `error` 事件报告一次;
+	* 由它结束 `load()`,不再等 xgplayer `switchURL` —— 那个 Promise 只认 xgplayer 自己的
+	* `error` / `canplay`,而 HLS 致命错误走 `HLS_ERROR`,不会触发它(#145)。
+	*/
+	let settlePendingLoad = null;
+	const isSourceFault = (event, eventSession) => event.event === "error" && !destroyed && eventSession === sessionId && event.payload.code !== "E_SUBTITLE_LOAD_FAILED" && event.payload.code !== "E_DANMAKU_SEND_FAILED" && event.payload.code !== "E_METHOD_NOT_SUPPORTED";
 	const reportRecoveryFault = (event, eventSession) => {
-		if (event.event === "error" && !destroyed && eventSession === sessionId && event.payload.code !== "E_SUBTITLE_LOAD_FAILED" && event.payload.code !== "E_DANMAKU_SEND_FAILED" && event.payload.code !== "E_METHOD_NOT_SUPPORTED") recovery?.fault(event.payload, eventSession);
+		if (event.event === "error" && isSourceFault(event, eventSession)) recovery?.fault(event.payload, eventSession);
 	};
 	const emit = (event) => {
 		if (destroyed) return;
@@ -3166,6 +3194,7 @@ function createPlayer(options) {
 		}
 		const eventSession = sessionId;
 		notify(delivered);
+		if (isSourceFault(event, eventSession)) settlePendingLoad?.();
 		reportRecoveryFault(event, eventSession);
 	};
 	let playerRef = null;
@@ -4075,7 +4104,15 @@ function createPlayer(options) {
 			if (destroyed || revision !== loadRevision) return;
 			emitContextChange();
 			if (destroyed || revision !== loadRevision) return;
-			await player.switchURL(nextRouted.chosen.url);
+			settlePendingLoad?.();
+			await new Promise((resolve) => {
+				const settle = () => {
+					if (settlePendingLoad === settle) settlePendingLoad = null;
+					resolve();
+				};
+				settlePendingLoad = settle;
+				Promise.resolve(player.switchURL(nextRouted.chosen.url)).then(settle, settle);
+			});
 			if (destroyed || revision !== loadRevision) return;
 			getMediaSession(player)?.setMetadata(nextNormalized.metadata);
 		},
@@ -4099,6 +4136,7 @@ function createPlayer(options) {
 		*/
 		destroy() {
 			if (destroyed) return;
+			settlePendingLoad?.();
 			recovery?.destroy();
 			recoveryCleanup?.();
 			destroyed = true;
@@ -4199,6 +4237,9 @@ function buildXgplayerConfig(options, routed, normalized, emit, env, playableSta
 	const lowLatencyMode = normalized.hls?.lowLatencyMode === true;
 	return {
 		el: options.el,
+		...options.fullscreenTarget ? { fullscreenTarget: options.fullscreenTarget } : {},
+		width: "100%",
+		height: "100%",
 		url: routed.chosen.url,
 		isLive: live,
 		ignores: [

package/dist/index.d.cts

@@ -78,6 +78,12 @@ declare function detectEnvFromGlobals(): Env;
 interface CreatePlayerOptions {
   /** 挂载容器 */
   el: HTMLElement;
+  /**
+   * 原生全屏目标(ADR-133)。装配层传入同时包含播放器与 SDK 覆盖层的外层容器,
+   * 覆盖层才会进入 `document.fullscreenElement` 子树、在全屏期间可见。
+   * 不传时沿用 xgplayer 默认(播放器根元素)。内部装配参数,不属于 `PlayerConfig`。
+   */
+  fullscreenTarget?: HTMLElement;
   /** 宿主网页全屏布局；不经可序列化配置传递。 */
   pageFullscreen?: PageFullscreenAdapter;
   /** iframe 内部使用：等待宿主协商后开放入口。 */
@@ -153,6 +159,10 @@ interface PlayerCoreHandle {
    * 安全热切媒体路由。改变内核、`live`、`hls.lowLatencyMode` 或字幕配置会抛
    * `E_METHOD_NOT_SUPPORTED`，因为它们在播放器构造期确定；宿主须销毁后以新 source 重建。
    * 组合层的常规换源入口是 `source` prop，直接调用只适合 player-core / 高级句柄场景。
+   *
+   * 返回的 Promise 在这次换源有结论时 resolve(ADR-136)：新源起播、当前会话的源故障已经通过
+   * `error` 事件报出、被更新的 `load()` 取代或播放器销毁。resolve 不代表新源可播放；
+   * 新源加载失败只经 `error` 事件报告一次，不会让 `load()` reject。只有上面的校验失败才 reject。
    */
   load(source: MediaSource): Promise<void>;
   /**

package/dist/index.d.mts

@@ -78,6 +78,12 @@ declare function detectEnvFromGlobals(): Env;
 interface CreatePlayerOptions {
   /** 挂载容器 */
   el: HTMLElement;
+  /**
+   * 原生全屏目标(ADR-133)。装配层传入同时包含播放器与 SDK 覆盖层的外层容器,
+   * 覆盖层才会进入 `document.fullscreenElement` 子树、在全屏期间可见。
+   * 不传时沿用 xgplayer 默认(播放器根元素)。内部装配参数,不属于 `PlayerConfig`。
+   */
+  fullscreenTarget?: HTMLElement;
   /** 宿主网页全屏布局；不经可序列化配置传递。 */
   pageFullscreen?: PageFullscreenAdapter;
   /** iframe 内部使用：等待宿主协商后开放入口。 */
@@ -153,6 +159,10 @@ interface PlayerCoreHandle {
    * 安全热切媒体路由。改变内核、`live`、`hls.lowLatencyMode` 或字幕配置会抛
    * `E_METHOD_NOT_SUPPORTED`，因为它们在播放器构造期确定；宿主须销毁后以新 source 重建。
    * 组合层的常规换源入口是 `source` prop，直接调用只适合 player-core / 高级句柄场景。
+   *
+   * 返回的 Promise 在这次换源有结论时 resolve(ADR-136)：新源起播、当前会话的源故障已经通过
+   * `error` 事件报出、被更新的 `load()` 取代或播放器销毁。resolve 不代表新源可播放；
+   * 新源加载失败只经 `error` 事件报告一次，不会让 `load()` reject。只有上面的校验失败才 reject。
    */
   load(source: MediaSource): Promise<void>;
   /**

package/dist/index.mjs

@@ -94,6 +94,27 @@ function detectEnv(input) {
 		requiresHls: isIOS || isWeChat || isUC || isQuark || !input.hasMediaSource
 	};
 }
+/** flv.js `isSupported()` 用的同一句基线:连它都报不支持,hls.js / flv.js 都不会开始播放 */
+const MSE_BASELINE_TYPE = "video/mp4; codecs=\"avc1.42E01E,mp4a.40.2\"";
+/**
+* 标准 MSE 是否**可用**,而不只是存在(ADR-135)。
+*
+* 小米浏览器(MiuiBrowser 20.28)暴露了 `MediaSource`,但 `isTypeSupported` 对所有
+* H.264/AAC 组合都回 false —— 实际 `addSourceBuffer` 能成功,是它报错了能力。
+* hls.js 信了前者,对声明了 CODECS 的主清单报 `manifestIncompatibleCodecsError`(不可重试)。
+* 按基线判为不可用后,SourceRouter 走原生 HLS,而该浏览器原生 HLS 播放、拖动都正常。
+*
+* 没有 `isTypeSupported` 的实现仍按「存在即可用」,只收紧「明确报不支持」这一种情况。
+*/
+function hasUsableMediaSource(mediaSource) {
+	if (typeof mediaSource === "undefined") return false;
+	if (typeof mediaSource.isTypeSupported !== "function") return true;
+	try {
+		return mediaSource.isTypeSupported(MSE_BASELINE_TYPE);
+	} catch {
+		return false;
+	}
+}
 /**
 * 从当前浏览器读环境。SSR 场景(没有 window / navigator)返回一个保守的默认值:
 * 当作没有 MSE,于是强制走 HLS —— 宁可保守也不要在服务端渲染时误判成能播 FLV。
@@ -106,7 +127,7 @@ function detectEnvFromGlobals() {
 	});
 	return detectEnv({
 		userAgent: navigator.userAgent,
-		hasMediaSource: typeof window.MediaSource !== "undefined",
+		hasMediaSource: hasUsableMediaSource(window.MediaSource),
 		hasManagedMediaSource: typeof window.ManagedMediaSource !== "undefined"
 	});
 }
@@ -3128,8 +3149,15 @@ function createPlayer(options) {
 	let recovery = null;
 	let eventStreamReady = false;
 	const deferredEvents = [];
+	/**
+	* 挂起中的 `load()` 的结束口(ADR-136)。换源后的源故障只经 `error` 事件报告一次;
+	* 由它结束 `load()`,不再等 xgplayer `switchURL` —— 那个 Promise 只认 xgplayer 自己的
+	* `error` / `canplay`,而 HLS 致命错误走 `HLS_ERROR`,不会触发它(#145)。
+	*/
+	let settlePendingLoad = null;
+	const isSourceFault = (event, eventSession) => event.event === "error" && !destroyed && eventSession === sessionId && event.payload.code !== "E_SUBTITLE_LOAD_FAILED" && event.payload.code !== "E_DANMAKU_SEND_FAILED" && event.payload.code !== "E_METHOD_NOT_SUPPORTED";
 	const reportRecoveryFault = (event, eventSession) => {
-		if (event.event === "error" && !destroyed && eventSession === sessionId && event.payload.code !== "E_SUBTITLE_LOAD_FAILED" && event.payload.code !== "E_DANMAKU_SEND_FAILED" && event.payload.code !== "E_METHOD_NOT_SUPPORTED") recovery?.fault(event.payload, eventSession);
+		if (event.event === "error" && isSourceFault(event, eventSession)) recovery?.fault(event.payload, eventSession);
 	};
 	const emit = (event) => {
 		if (destroyed) return;
@@ -3140,6 +3168,7 @@ function createPlayer(options) {
 		}
 		const eventSession = sessionId;
 		notify(delivered);
+		if (isSourceFault(event, eventSession)) settlePendingLoad?.();
 		reportRecoveryFault(event, eventSession);
 	};
 	let playerRef = null;
@@ -4049,7 +4078,15 @@ function createPlayer(options) {
 			if (destroyed || revision !== loadRevision) return;
 			emitContextChange();
 			if (destroyed || revision !== loadRevision) return;
-			await player.switchURL(nextRouted.chosen.url);
+			settlePendingLoad?.();
+			await new Promise((resolve) => {
+				const settle = () => {
+					if (settlePendingLoad === settle) settlePendingLoad = null;
+					resolve();
+				};
+				settlePendingLoad = settle;
+				Promise.resolve(player.switchURL(nextRouted.chosen.url)).then(settle, settle);
+			});
 			if (destroyed || revision !== loadRevision) return;
 			getMediaSession(player)?.setMetadata(nextNormalized.metadata);
 		},
@@ -4073,6 +4110,7 @@ function createPlayer(options) {
 		*/
 		destroy() {
 			if (destroyed) return;
+			settlePendingLoad?.();
 			recovery?.destroy();
 			recoveryCleanup?.();
 			destroyed = true;
@@ -4173,6 +4211,9 @@ function buildXgplayerConfig(options, routed, normalized, emit, env, playableSta
 	const lowLatencyMode = normalized.hls?.lowLatencyMode === true;
 	return {
 		el: options.el,
+		...options.fullscreenTarget ? { fullscreenTarget: options.fullscreenTarget } : {},
+		width: "100%",
+		height: "100%",
 		url: routed.chosen.url,
 		isLive: live,
 		ignores: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/player-core",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -31,9 +31,9 @@
   "sideEffects": false,
   "dependencies": {
     "xgplayer": "3.0.26",
-    "hls.js": "1.6.16",
+    "hls.js": "1.6.19",
     "xgplayer-flv.js": "3.0.26",
-    "@video-lab/protocol": "4.1.0"
+    "@video-lab/protocol": "4.1.2"
   },
   "devDependencies": {
     "jsdom": "^24.0.0",