@video-lab/player-core 4.1.1 → 4.1.3

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);reject 前会先暂停旧源,避免它在错误层下继续播放(ADR-137)。
+
 **直播的 `duration` 是 0,不是 Infinity。** Infinity 过不了 JSON 序列化(变成 null),而事件要跨 iframe 传,所以在源头就归一成 0。
 
 ## 环境探测与测试

package/dist/index.cjs

@@ -3175,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;
@@ -3187,6 +3194,7 @@ function createPlayer(options) {
 		}
 		const eventSession = sessionId;
 		notify(delivered);
+		if (isSourceFault(event, eventSession)) settlePendingLoad?.();
 		reportRecoveryFault(event, eventSession);
 	};
 	let playerRef = null;
@@ -4055,8 +4063,15 @@ function createPlayer(options) {
 		},
 		async load(source) {
 			if (destroyed) return;
+			const pauseBeforeReject = () => {
+				setPlayingIntent(false);
+				player.pause();
+			};
 			const parsedSource = _video_lab_protocol.MediaSourceSchema.safeParse(source);
-			if (!parsedSource.success) throwPlayerError("E_METHOD_NOT_SUPPORTED", `非法换源:${parsedSource.error.issues.map((i) => `${i.path.join(".") || "(根)"} ${i.message}`).join("; ")}`);
+			if (!parsedSource.success) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `非法换源:${parsedSource.error.issues.map((i) => `${i.path.join(".") || "(根)"} ${i.message}`).join("; ")}`);
+			}
 			const nextNormalized = normalizeSource(source);
 			const nextSessionId = newSessionId();
 			let nextRouted;
@@ -4067,11 +4082,18 @@ function createPlayer(options) {
 					event: "sourceroute",
 					payload: unsupportedRoutePayload(nextSessionId, nextNormalized, env)
 				});
+				pauseBeforeReject();
 				throw error;
 			}
-			if (nextRouted.kernel !== routed.kernel) throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源需要从 ${routed.kernel} 内核切到 ${nextRouted.kernel},运行时无法切换内核。请销毁当前 player 并用新的 source 重建。`);
+			if (nextRouted.kernel !== routed.kernel) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源需要从 ${routed.kernel} 内核切到 ${nextRouted.kernel},运行时无法切换内核。请销毁当前 player 并用新的 source 重建。`);
+			}
 			const constructionChanges = sourceConstructionChanges(normalized, nextNormalized);
-			if (constructionChanges.length > 0) throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源不能改变构造期 source 配置(${constructionChanges.join("、")})。播放器仍使用创建时的直播、HLS 与字幕插件配置。请销毁当前 player 并用新的 source 重建。`);
+			if (constructionChanges.length > 0) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源不能改变构造期 source 配置(${constructionChanges.join("、")})。播放器仍使用创建时的直播、HLS 与字幕插件配置。请销毁当前 player 并用新的 source 重建。`);
+			}
 			const revision = ++loadRevision;
 			naturalProof?.abort();
 			recovery?.setSession(nextSessionId);
@@ -4096,7 +4118,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);
 		},
@@ -4120,6 +4150,7 @@ function createPlayer(options) {
 		*/
 		destroy() {
 			if (destroyed) return;
+			settlePendingLoad?.();
 			recovery?.destroy();
 			recoveryCleanup?.();
 			destroyed = true;

package/dist/index.d.cts

@@ -159,6 +159,11 @@ 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，
+   * 且 reject 前会暂停旧源(ADR-137)，避免它在错误层下继续播放。
    */
   load(source: MediaSource): Promise<void>;
   /**

package/dist/index.d.mts

@@ -159,6 +159,11 @@ 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，
+   * 且 reject 前会暂停旧源(ADR-137)，避免它在错误层下继续播放。
    */
   load(source: MediaSource): Promise<void>;
   /**

package/dist/index.mjs

@@ -3149,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;
@@ -3161,6 +3168,7 @@ function createPlayer(options) {
 		}
 		const eventSession = sessionId;
 		notify(delivered);
+		if (isSourceFault(event, eventSession)) settlePendingLoad?.();
 		reportRecoveryFault(event, eventSession);
 	};
 	let playerRef = null;
@@ -4029,8 +4037,15 @@ function createPlayer(options) {
 		},
 		async load(source) {
 			if (destroyed) return;
+			const pauseBeforeReject = () => {
+				setPlayingIntent(false);
+				player.pause();
+			};
 			const parsedSource = MediaSourceSchema.safeParse(source);
-			if (!parsedSource.success) throwPlayerError("E_METHOD_NOT_SUPPORTED", `非法换源:${parsedSource.error.issues.map((i) => `${i.path.join(".") || "(根)"} ${i.message}`).join("; ")}`);
+			if (!parsedSource.success) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `非法换源:${parsedSource.error.issues.map((i) => `${i.path.join(".") || "(根)"} ${i.message}`).join("; ")}`);
+			}
 			const nextNormalized = normalizeSource(source);
 			const nextSessionId = newSessionId();
 			let nextRouted;
@@ -4041,11 +4056,18 @@ function createPlayer(options) {
 					event: "sourceroute",
 					payload: unsupportedRoutePayload(nextSessionId, nextNormalized, env)
 				});
+				pauseBeforeReject();
 				throw error;
 			}
-			if (nextRouted.kernel !== routed.kernel) throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源需要从 ${routed.kernel} 内核切到 ${nextRouted.kernel},运行时无法切换内核。请销毁当前 player 并用新的 source 重建。`);
+			if (nextRouted.kernel !== routed.kernel) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源需要从 ${routed.kernel} 内核切到 ${nextRouted.kernel},运行时无法切换内核。请销毁当前 player 并用新的 source 重建。`);
+			}
 			const constructionChanges = sourceConstructionChanges(normalized, nextNormalized);
-			if (constructionChanges.length > 0) throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源不能改变构造期 source 配置(${constructionChanges.join("、")})。播放器仍使用创建时的直播、HLS 与字幕插件配置。请销毁当前 player 并用新的 source 重建。`);
+			if (constructionChanges.length > 0) {
+				pauseBeforeReject();
+				throwPlayerError("E_METHOD_NOT_SUPPORTED", `换源不能改变构造期 source 配置(${constructionChanges.join("、")})。播放器仍使用创建时的直播、HLS 与字幕插件配置。请销毁当前 player 并用新的 source 重建。`);
+			}
 			const revision = ++loadRevision;
 			naturalProof?.abort();
 			recovery?.setSession(nextSessionId);
@@ -4070,7 +4092,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);
 		},
@@ -4094,6 +4124,7 @@ function createPlayer(options) {
 		*/
 		destroy() {
 			if (destroyed) return;
+			settlePendingLoad?.();
 			recovery?.destroy();
 			recoveryCleanup?.();
 			destroyed = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/player-core",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -33,7 +33,7 @@
     "xgplayer": "3.0.26",
     "hls.js": "1.6.19",
     "xgplayer-flv.js": "3.0.26",
-    "@video-lab/protocol": "4.1.1"
+    "@video-lab/protocol": "4.1.3"
   },
   "devDependencies": {
     "jsdom": "^24.0.0",