trtc-electron-sdk 13.3.801-alpha.2 → 13.3.801

package/liteav/extensions/MediaMixingManager/MediaMixingManager.d.ts

@@ -128,6 +128,7 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     private autoControlServer;
     private serverStatus;
     private serverMode;
+    private addMediaSourceTimers;
     private webRenderer;
     private pixelFormat;
     private pixelLength;
@@ -240,6 +241,14 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
      * @returns {Promise<void>}
      */
     addMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
+    /**
+     * Returns the per-sourceType timeout (ms) used by addMediaSource. The
+     * defaults are intentionally larger than the cpp-layer timeout in
+     * SourceManagerProxy so that, in the normal case, the cpp side resolves the
+     * promise first. This JS timer is the last-resort safety net in case the
+     * cpp side itself fails to emit any callback (older builds, ipc lost, etc.).
+     */
+    private getAddMediaSourceTimeoutMs;
     /**
      * 删除本地混流媒体源
      * @param mediaSource {TRTCMediaSource} - 媒体源信息

package/liteav/extensions/MediaMixingManager/MediaMixingManager.js

@@ -304,6 +304,12 @@ class TRTCMediaMixingManager {
         this.streamLayoutManager = null;
         this.serverStatus = TRTCMediaMixingServerStatus.Idle;
         this.serverMode = TRTCMediaMixingServerMode.Independent;
+        // Per-source timeout handles for addMediaSource. Keyed by the same promise
+        // key used in promiseStore. Used to guard against the case where the native
+        // cpp layer never emits SM_OnSourceInserted (e.g. internal OnlineVideoSource
+        // state machine stuck after a previous failure), which would otherwise leave
+        // the returned Promise pending forever and the UI stuck on "loading".
+        this.addMediaSourceTimers = new Map();
         this.webRenderer = null;
         this.pixelFormat = trtc_define_1.TRTCVideoPixelFormat.TRTCVideoPixelFormat_BGRA32;
         this.pixelLength = 4;
@@ -386,6 +392,10 @@ class TRTCMediaMixingManager {
             this.nodeMediaMixingPlugin = null;
             this.eventEmitter = null;
             this.promiseStore.destroy();
+            // Cancel any pending addMediaSource timeout timers to avoid late-firing
+            // callbacks touching a destroyed instance.
+            this.addMediaSourceTimers.forEach(timer => clearTimeout(timer));
+            this.addMediaSourceTimers.clear();
             this.paramsStore = null;
             this.trtcParamsStore = null;
         });
@@ -536,6 +546,58 @@ class TRTCMediaMixingManager {
                 var _a;
                 const key = `${promiseKeys.addMediaSource}-${newMediaSource.sourceType}-${newMediaSource.sourceId}`;
                 this.promiseStore.addPromise(key, resolve, reject);
+                // Arm a timeout safety net. The underlying cpp layer should normally
+                // call back via SM_OnSourceInserted, but for OnlineVideo / VideoFile we
+                // have observed the native MediaPlayer state machine getting stuck on
+                // the 2nd attempt after a previous network failure, with no callback
+                // ever emitted. Without this timer the returned Promise stays pending
+                // forever, freezing upstream UI (e.g. the "child view" loading state).
+                const timeoutMs = this.getAddMediaSourceTimeoutMs(newMediaSource.sourceType);
+                const timer = setTimeout(() => {
+                    try {
+                        // Defensive guard: destroy() may have been invoked while this
+                        // macrotask was already scheduled but before the clearTimeout()
+                        // loop in destroy() ran. In that case promiseStore / sourceList
+                        // are no longer in a consistent state, and any further side-
+                        // effect (e.g. ms.control = {}) could throw on undefined.
+                        if (!this.nodeMediaMixingPlugin || !this.promiseStore) {
+                            return;
+                        }
+                        // If the promise was already settled by the real callback, this is
+                        // a no-op because PromiseStore.rejectPromise returns false on
+                        // missing key.
+                        const rejected = this.promiseStore.rejectPromise(key, {
+                            code: types_1.TRTCMediaMixingErrorCode.InsertTimeout,
+                            message: 'addMediaSource timeout',
+                        });
+                        if (rejected) {
+                            logger_1.default.warn(`${this.logPrefix}addMediaSource timeout for sourceType:${newMediaSource.sourceType} sourceId:${newMediaSource.sourceId} timeoutMs:${timeoutMs}`);
+                            // Mark the source as failed so subsequent removeMediaSource can
+                            // take the fast (sync) path without waiting for cpp callbacks
+                            // again.
+                            const idx = this.findMediaSourceIndex({
+                                sourceId: newMediaSource.sourceId,
+                                sourceType: newMediaSource.sourceType,
+                            });
+                            if (idx !== -1) {
+                                const ms = this.sourceList[idx];
+                                if (ms) {
+                                    if (!ms.control) {
+                                        ms.control = {};
+                                    }
+                                    ms.control.isAddFailed = true;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        // Always clear our own timer slot, even if the rejection path
+                        // throws upstream. Without this, the Map would keep stale handles
+                        // alive until destroy().
+                        this.addMediaSourceTimers.delete(key);
+                    }
+                }, timeoutMs);
+                this.addMediaSourceTimers.set(key, timer);
                 this.nodeMediaMixingPlugin.addMediaSource(newMediaSource);
                 (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.addMedia({
                     id: `${newMediaSource.sourceType}__${newMediaSource.sourceId}`,
@@ -548,6 +610,23 @@ class TRTCMediaMixingManager {
             });
         });
     }
+    /**
+     * Returns the per-sourceType timeout (ms) used by addMediaSource. The
+     * defaults are intentionally larger than the cpp-layer timeout in
+     * SourceManagerProxy so that, in the normal case, the cpp side resolves the
+     * promise first. This JS timer is the last-resort safety net in case the
+     * cpp side itself fails to emit any callback (older builds, ipc lost, etc.).
+     */
+    getAddMediaSourceTimeoutMs(sourceType) {
+        switch (sourceType) {
+            case types_1.TRTCMediaSourceType.kOnlineVideo:
+                return 11000;
+            case types_1.TRTCMediaSourceType.kVideoFile:
+                return 6000;
+            default:
+                return 5000;
+        }
+    }
     /**
      * 删除本地混流媒体源
      * @param mediaSource {TRTCMediaSource} - 媒体源信息
@@ -1207,6 +1286,12 @@ class TRTCMediaMixingManager {
     onMediaSourceAdded(data) {
         var _a;
         const promiseKey = `${promiseKeys.addMediaSource}-${data.sourceType}-${data.sourceId}`;
+        // Real callback arrived: cancel the JS-side timeout safety net.
+        const timer = this.addMediaSourceTimers.get(promiseKey);
+        if (timer) {
+            clearTimeout(timer);
+            this.addMediaSourceTimers.delete(promiseKey);
+        }
         let flag = false;
         if (data.errCode === 0) {
             flag = this.promiseStore.resolvePromise(promiseKey, undefined);

package/liteav/extensions/MediaMixingManager/types.d.ts

@@ -13,7 +13,14 @@ export declare enum TRTCMediaMixingErrorCode {
     OnlineVideoConnectFailed = -10,
     OnlineVideoConnectionLost = -11,
     NoAvailableHevcDecoder = -12,
-    VideoFileNotExist = -13
+    VideoFileNotExist = -13,
+    /**
+     * SDK 兜底超时（addMediaSource 在 cpp / js 双层超时内未收到底层 onXxxStarted 回调）。
+     *
+     * 取一个远离 SDK 自然错误码区间（-1..-13）的值，便于上层稳定区分。
+     * 必须与 C++ 端 `kInsertTimeoutErrCode`（SourceManagerProxy）保持一致。
+     */
+    InsertTimeout = -9001
 }
 export declare enum TRTCMediaSourceType {
     kCamera = 0,

package/liteav/extensions/MediaMixingManager/types.js

@@ -17,6 +17,13 @@ var TRTCMediaMixingErrorCode;
     TRTCMediaMixingErrorCode[TRTCMediaMixingErrorCode["OnlineVideoConnectionLost"] = -11] = "OnlineVideoConnectionLost";
     TRTCMediaMixingErrorCode[TRTCMediaMixingErrorCode["NoAvailableHevcDecoder"] = -12] = "NoAvailableHevcDecoder";
     TRTCMediaMixingErrorCode[TRTCMediaMixingErrorCode["VideoFileNotExist"] = -13] = "VideoFileNotExist";
+    /**
+     * SDK 兜底超时（addMediaSource 在 cpp / js 双层超时内未收到底层 onXxxStarted 回调）。
+     *
+     * 取一个远离 SDK 自然错误码区间（-1..-13）的值，便于上层稳定区分。
+     * 必须与 C++ 端 `kInsertTimeoutErrCode`（SourceManagerProxy）保持一致。
+     */
+    TRTCMediaMixingErrorCode[TRTCMediaMixingErrorCode["InsertTimeout"] = -9001] = "InsertTimeout";
 })(TRTCMediaMixingErrorCode = exports.TRTCMediaMixingErrorCode || (exports.TRTCMediaMixingErrorCode = {}));
 var TRTCMediaSourceType;
 (function (TRTCMediaSourceType) {

package/liteav/trtc.d.ts

@@ -1167,7 +1167,6 @@ declare class TRTCCloud extends EventEmitter implements ITRTCCloud {
      * 该接口跟 startPublishing() 类似，但 startPublishCDNStream() 支持向非腾讯云的直播 CDN 转推。
      *
      * 注意：
-     * - 使用 startPublishing() 绑定腾讯云直播 CDN 不收取额外的费用。
      * - 使用 startPublishCDNStream() 绑定非腾讯云直播 CDN 需要收取转推费用，且需要通过工单联系我们开通。
      *
      * @param {TRTCPublishCDNParam} param - 转推参数

package/liteav/trtc.js

@@ -2097,7 +2097,6 @@ class TRTCCloud extends events_1.EventEmitter {
      * 该接口跟 startPublishing() 类似，但 startPublishCDNStream() 支持向非腾讯云的直播 CDN 转推。
      *
      * 注意：
-     * - 使用 startPublishing() 绑定腾讯云直播 CDN 不收取额外的费用。
      * - 使用 startPublishCDNStream() 绑定非腾讯云直播 CDN 需要收取转推费用，且需要通过工单联系我们开通。
      *
      * @param {TRTCPublishCDNParam} param - 转推参数

package/liteav/trtc_define.d.ts

@@ -1125,85 +1125,3 @@ export interface TRTCInitConfig {
     };
     isIPCMode?: boolean;
 }
-/**
- * @namespace TRTCVodPlayerEvent
- * @description 点播播放器（VOD Player）事件
- */
-export declare enum TRTCVodPlayerEvent {
-    /**
-     * @description 多媒体文件开始播放事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerStarted
-     * @param {Number} msLength 多媒体文件总长度，单位毫秒
-     */
-    onVodPlayerStarted = "onVodPlayerStarted",
-    /**
-     * @description 播放器就绪事件
-     *
-     * 调用 `preload()` 完成后触发，或 `switchSource()` 切换成功后触发。
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerLoaded
-     * @param {Number} durationMs 视频总时长，单位毫秒
-     * @param {Number} width 视频宽度（像素），纯音频文件时为 0
-     * @param {Number} height 视频高度（像素），纯音频文件时为 0
-     */
-    onVodPlayerLoaded = "onVodPlayerLoaded",
-    /**
-     * @description 多媒体文件播放进度改变事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerProgress
-     * @param {Number} msPos 多媒体文件当前播放进度，单位毫秒
-     */
-    onVodPlayerProgress = "onVodPlayerProgress",
-    /**
-     * @description 多媒体文件播放暂停事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerPaused
-     */
-    onVodPlayerPaused = "onVodPlayerPaused",
-    /**
-     * @description 多媒体文件播放恢复事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerResumed
-     */
-    onVodPlayerResumed = "onVodPlayerResumed",
-    /**
-     * @description 多媒体文件播放停止事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerStopped
-     * @param {Number} reason 停止原因
-     *  - 0:用户主动停止；
-     *  - 1:文件播放完；
-     *  - 2:视频断流。
-     */
-    onVodPlayerStopped = "onVodPlayerStopped",
-    /**
-     * @description 多媒体文件播放出错事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerError
-     * @param {Number} error 错误码
-     *  - -6001:未知错误；
-     *  - -6002:通用错误；
-     *  - -6003:解封装失败；
-     *  - -6005:解封装超时；
-     *  - -6006:视频解码错误；
-     *  - -6007:音频解码错误；
-     *  - -6009:视频渲染错误。
-     */
-    onVodPlayerError = "onVodPlayerError"
-}
-/**
- * 点播播放器事件监听器类型定义
- *
- * key 为 {@link TRTCVodPlayerEvent}，value 为该事件回调接收的参数元组。
- * 用于在 TS 层实现事件名到回调参数的精确类型映射，避免 any 滥用。
- */
-export interface TRTCVodPlayerEventMap {
-    [TRTCVodPlayerEvent.onVodPlayerStarted]: [msLength: number];
-    [TRTCVodPlayerEvent.onVodPlayerLoaded]: [durationMs: number, width: number, height: number];
-    [TRTCVodPlayerEvent.onVodPlayerProgress]: [msPos: number];
-    [TRTCVodPlayerEvent.onVodPlayerPaused]: [];
-    [TRTCVodPlayerEvent.onVodPlayerResumed]: [];
-    [TRTCVodPlayerEvent.onVodPlayerStopped]: [reason: number];
-    [TRTCVodPlayerEvent.onVodPlayerError]: [error: number];
-}

package/liteav/trtc_define.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TRTCTranscodingConfig = exports.TRTCPluginType = exports.TRTCVoiceChangerType = exports.TRTCVoiceReverbType = exports.TRTCPublishMode = exports.TRTCAudioRecordingContent = exports.TRTCMixInputType = exports.TRTCTranscodingConfigMode = exports.TRTCMixUser = exports.Rect = exports.TRTCSpeedTestResult = exports.TRTCSpeedTestParams = exports.TRTCVolumeInfo = exports.TRTCQualityInfo = exports.TRTCNetworkQosParam = exports.TRTCRenderParams = exports.TRTCVideoEncParam = exports.TRTCParams = exports.TRTCWaterMarkSrcType = exports.TRTCVideoEncodeComplexity = exports.TRTCVideoColorSpace = exports.TRTCVideoColorRange = exports.TRTCCameraCaptureMode = exports.TRTCDeviceType = exports.TRTCDeviceState = exports.TRTCLogLevel = exports.TRTCAudioFrame = exports.TRTCVideoFrame = exports.TRTCDeviceInfo = exports.TRTCScreenCaptureProperty = exports.TRTCScreenCaptureSourceInfo = exports.TRTCImageBuffer = exports.TRTCAudioQuality = exports.TRTCScreenCaptureSourceType = exports.TRTCAudioFrameFormat = exports.TRTCVideoQosPreference = exports.TRTCQosControlMode = exports.TRTCRoleType = exports.TRTCAppScene = exports.TRTCRecordType = exports.TRTCVideoMirrorType = exports.TRTCVideoBufferType = exports.TRTCVideoPixelFormat = exports.TRTCBeautyStyle = exports.TRTCVideoRotation = exports.TRTCVideoFillMode = exports.TRTCQuality = exports.TRTCVideoStreamType = exports.TRTCVideoResolutionMode = exports.TRTCVideoResolution = void 0;
-exports.TRTCVodPlayerEvent = exports.VideoBufferInfo = exports.TRTCSwitchRoomParam = exports.AudioMusicParam = exports.TRTCStatistics = exports.TRTCRemoteStatistics = exports.TRTCLocalStatistics = exports.TRTCAudioEffectParam = exports.TRTCAudioRecordingParams = exports.TRTCPublishCDNParam = void 0;
+exports.VideoBufferInfo = exports.TRTCSwitchRoomParam = exports.AudioMusicParam = exports.TRTCStatistics = exports.TRTCRemoteStatistics = exports.TRTCLocalStatistics = exports.TRTCAudioEffectParam = exports.TRTCAudioRecordingParams = exports.TRTCPublishCDNParam = void 0;
 const util_1 = require("./Renderer/util");
 /////////////////////////////////////////////////////////////////////////////////
 //
@@ -2032,76 +2032,3 @@ class VideoBufferInfo {
     }
 }
 exports.VideoBufferInfo = VideoBufferInfo;
-/////////////////////////////////////////////////////////////////////////////////
-//
-//                    TRTCVodPlayer 相关类型定义
-//
-/////////////////////////////////////////////////////////////////////////////////
-/**
- * @namespace TRTCVodPlayerEvent
- * @description 点播播放器（VOD Player）事件
- */
-var TRTCVodPlayerEvent;
-(function (TRTCVodPlayerEvent) {
-    /**
-     * @description 多媒体文件开始播放事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerStarted
-     * @param {Number} msLength 多媒体文件总长度，单位毫秒
-     */
-    TRTCVodPlayerEvent["onVodPlayerStarted"] = "onVodPlayerStarted";
-    /**
-     * @description 播放器就绪事件
-     *
-     * 调用 `preload()` 完成后触发，或 `switchSource()` 切换成功后触发。
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerLoaded
-     * @param {Number} durationMs 视频总时长，单位毫秒
-     * @param {Number} width 视频宽度（像素），纯音频文件时为 0
-     * @param {Number} height 视频高度（像素），纯音频文件时为 0
-     */
-    TRTCVodPlayerEvent["onVodPlayerLoaded"] = "onVodPlayerLoaded";
-    /**
-     * @description 多媒体文件播放进度改变事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerProgress
-     * @param {Number} msPos 多媒体文件当前播放进度，单位毫秒
-     */
-    TRTCVodPlayerEvent["onVodPlayerProgress"] = "onVodPlayerProgress";
-    /**
-     * @description 多媒体文件播放暂停事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerPaused
-     */
-    TRTCVodPlayerEvent["onVodPlayerPaused"] = "onVodPlayerPaused";
-    /**
-     * @description 多媒体文件播放恢复事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerResumed
-     */
-    TRTCVodPlayerEvent["onVodPlayerResumed"] = "onVodPlayerResumed";
-    /**
-     * @description 多媒体文件播放停止事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerStopped
-     * @param {Number} reason 停止原因
-     *  - 0:用户主动停止；
-     *  - 1:文件播放完；
-     *  - 2:视频断流。
-     */
-    TRTCVodPlayerEvent["onVodPlayerStopped"] = "onVodPlayerStopped";
-    /**
-     * @description 多媒体文件播放出错事件
-     *
-     * @event TRTCVodPlayerEvent#onVodPlayerError
-     * @param {Number} error 错误码
-     *  - -6001:未知错误；
-     *  - -6002:通用错误；
-     *  - -6003:解封装失败；
-     *  - -6005:解封装超时；
-     *  - -6006:视频解码错误；
-     *  - -6007:音频解码错误；
-     *  - -6009:视频渲染错误。
-     */
-    TRTCVodPlayerEvent["onVodPlayerError"] = "onVodPlayerError";
-})(TRTCVodPlayerEvent = exports.TRTCVodPlayerEvent || (exports.TRTCVodPlayerEvent = {}));

package/liteav/types.d.ts

@@ -1,5 +1,6 @@
 import TRTCMediaMixingManager, { TRTCMediaMixingService } from './extensions/MediaMixingManager';
-import { AudioMusicParam, Rect, TRTCAppScene, TRTCAudioQuality, TRTCBeautyStyle, TRTCDeviceType, TRTCLogLevel, TRTCAudioFrame, TRTCVideoFillMode, TRTCVideoRotation, TRTCVideoStreamType, TRTCWaterMarkSrcType, TRTCPluginType, TRTCPluginInfo, TRTCVideoProcessPluginOptions, TRTCMediaEncryptDecryptPluginOptions, TRTCAudioRecordingParams, TRTCScreenCaptureSourceInfo, TRTCScreenCaptureProperty, TRTCSpeedTestParams, TRTCRecordType, TRTCDeviceInfo, TRTCCameraCaptureParams, TRTCImageBuffer, TRTCInitConfig, TRTCAudioParallelParams, TRTCVoiceReverbType, TRTCVoiceChangerType, TRTCMusicPlayObserver, TRTCAudioFrameCallback, TRTCAudioProcessPluginOptions, TRTCPublishTarget, TRTCStreamEncoderParam, TRTCStreamMixingConfig, TRTCRenderParams, TRTCRoleType, TRTCSwitchRoomParam, TRTCVideoFrame, TRTCVideoPixelFormat, TRTCVideoBufferType, TRTCVodPlayerEventMap } from './trtc_define';
+import { AudioMusicParam, Rect, TRTCAppScene, TRTCAudioQuality, TRTCBeautyStyle, TRTCDeviceType, TRTCLogLevel, TRTCAudioFrame, TRTCVideoFillMode, TRTCVideoRotation, TRTCVideoStreamType, TRTCWaterMarkSrcType, TRTCPluginType, TRTCPluginInfo, TRTCVideoProcessPluginOptions, TRTCMediaEncryptDecryptPluginOptions, TRTCAudioRecordingParams, TRTCScreenCaptureSourceInfo, TRTCScreenCaptureProperty, TRTCSpeedTestParams, TRTCRecordType, TRTCDeviceInfo, TRTCCameraCaptureParams, TRTCImageBuffer, TRTCInitConfig, TRTCAudioParallelParams, TRTCVoiceReverbType, TRTCVoiceChangerType, TRTCMusicPlayObserver, TRTCAudioFrameCallback, TRTCAudioProcessPluginOptions, TRTCPublishTarget, TRTCStreamEncoderParam, TRTCStreamMixingConfig, TRTCRenderParams, TRTCRoleType, TRTCSwitchRoomParam, TRTCVideoFrame, TRTCVideoPixelFormat, TRTCVideoBufferType } from './trtc_define';
+import { TRTCVodPlayerEventMap } from './vod_player';
 export interface TRTCVideoRenderCallback {
     onRenderVideoFrame(userId: string, streamType: TRTCVideoStreamType, frame: TRTCVideoFrame): void;
 }

package/liteav/vod_player.d.ts

@@ -1,5 +1,87 @@
-import { TRTCVideoRotation, TRTCVideoFillMode, TRTCVodPlayerEventMap } from './trtc_define';
+import { TRTCVideoRotation, TRTCVideoFillMode } from './trtc_define';
 import { IVodPlayer } from './types';
+/**
+ * @namespace TRTCVodPlayerEvent
+ * @description 点播播放器（VOD Player）事件
+ */
+export declare enum TRTCVodPlayerEvent {
+    /**
+     * @description 多媒体文件开始播放事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerStarted
+     * @param {Number} msLength 多媒体文件总长度，单位毫秒
+     */
+    onVodPlayerStarted = "onVodPlayerStarted",
+    /**
+     * @description 播放器就绪事件
+     *
+     * 调用 `preload()` 完成后触发，或 `switchSource()` 切换成功后触发。
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerLoaded
+     * @param {Number} durationMs 视频总时长，单位毫秒
+     * @param {Number} width 视频宽度（像素），纯音频文件时为 0
+     * @param {Number} height 视频高度（像素），纯音频文件时为 0
+     */
+    onVodPlayerLoaded = "onVodPlayerLoaded",
+    /**
+     * @description 多媒体文件播放进度改变事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerProgress
+     * @param {Number} msPos 多媒体文件当前播放进度，单位毫秒
+     */
+    onVodPlayerProgress = "onVodPlayerProgress",
+    /**
+     * @description 多媒体文件播放暂停事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerPaused
+     */
+    onVodPlayerPaused = "onVodPlayerPaused",
+    /**
+     * @description 多媒体文件播放恢复事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerResumed
+     */
+    onVodPlayerResumed = "onVodPlayerResumed",
+    /**
+     * @description 多媒体文件播放停止事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerStopped
+     * @param {Number} reason 停止原因
+     *  - 0:用户主动停止；
+     *  - 1:文件播放完；
+     *  - 2:视频断流。
+     */
+    onVodPlayerStopped = "onVodPlayerStopped",
+    /**
+     * @description 多媒体文件播放出错事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerError
+     * @param {Number} error 错误码
+     *  - -6001:未知错误；
+     *  - -6002:通用错误；
+     *  - -6003:解封装失败；
+     *  - -6005:解封装超时；
+     *  - -6006:视频解码错误；
+     *  - -6007:音频解码错误；
+     *  - -6009:视频渲染错误。
+     */
+    onVodPlayerError = "onVodPlayerError"
+}
+/**
+ * 点播播放器事件监听器类型定义
+ *
+ * key 为 {@link TRTCVodPlayerEvent}，value 为该事件回调接收的参数元组。
+ * 用于在 TS 层实现事件名到回调参数的精确类型映射，避免 any 滥用。
+ */
+export interface TRTCVodPlayerEventMap {
+    [TRTCVodPlayerEvent.onVodPlayerStarted]: [msLength: number];
+    [TRTCVodPlayerEvent.onVodPlayerLoaded]: [durationMs: number, width: number, height: number];
+    [TRTCVodPlayerEvent.onVodPlayerProgress]: [msPos: number];
+    [TRTCVodPlayerEvent.onVodPlayerPaused]: [];
+    [TRTCVodPlayerEvent.onVodPlayerResumed]: [];
+    [TRTCVodPlayerEvent.onVodPlayerStopped]: [reason: number];
+    [TRTCVodPlayerEvent.onVodPlayerError]: [error: number];
+}
 /**
  *
  * 腾讯云点播播放器
@@ -125,8 +207,6 @@ export declare class TRTCVodPlayer implements IVodPlayer {
      * 重复调用会被忽略。
      *
      * @note 可以先调用 {@link preload} 预加载完成后再调用 start，也可以跳过 preload 直接调用 start。
-     * @note 从 SDK 10.7 版本开始，需要通过 TXLiveBase#setLicence 设置 Licence 后方可成功播放，
-     *       否则将播放失败（黑屏），全局仅设置一次即可。
      */
     start(): void;
     /**
@@ -154,14 +234,19 @@ export declare class TRTCVodPlayer implements IVodPlayer {
      */
     seek(msPos: number): void;
     /**
-     * 无缝切换当前播放的媒体文件
+     * 切换当前播放的媒体文件
+     *
+     * 底层实现等价于 `stop + 加载新源`，**切换后是否自动播放取决于切换前的状态**：
+     *   - 切换前在播放中：底层会自动 Started 新源，业务方无需再调 {@link start}；
+     *   - 切换前在暂停中：底层只 Loaded 新源不自动播放，业务方需在
+     *     {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 之后调 {@link start} 才会播。
      *
-     * 在后台预加载新的媒体源，待新源就绪后无缝切换，避免切换时出现黑屏。
-     * 切换成功后触发 {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 事件，携带新文件的媒体信息。
+     * 切换过程中会按顺序触发：
+     *   `onVodPlayerStopped` → `onVodPlayerLoaded`(新源信息) →
+     *   `onVodPlayerStarted`(仅"切换前在播放中"路径才会有)。
      *
      * @param newMediaFile - 新的媒体文件路径或 URL
      *
-     * @note 若当前处于暂停状态，切换后仍保持暂停并展示新文件第一帧。
      * @note 切换过程中调用 {@link stop} 会取消切换并停止当前播放。
      * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
      * @note 传入空串会被忽略并打 warn 日志（C++ 层亦有同等保护）。

package/liteav/vod_player.js

@@ -1,11 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRTCVodPlayer = void 0;
+exports.TRTCVodPlayer = exports.TRTCVodPlayerEvent = void 0;
 const events_1 = require("events");
 const trtc_define_1 = require("./trtc_define");
 const video_render_1 = require("./Live/video-render");
 const logger_1 = require("./logger");
 const NodeTRTCEngine = require('../build/Release/trtc_electron_sdk.node');
+/////////////////////////////////////////////////////////////////////////////////
+//
+//                    TRTCVodPlayer 相关类型定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+/**
+ * @namespace TRTCVodPlayerEvent
+ * @description 点播播放器（VOD Player）事件
+ */
+var TRTCVodPlayerEvent;
+(function (TRTCVodPlayerEvent) {
+    /**
+     * @description 多媒体文件开始播放事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerStarted
+     * @param {Number} msLength 多媒体文件总长度，单位毫秒
+     */
+    TRTCVodPlayerEvent["onVodPlayerStarted"] = "onVodPlayerStarted";
+    /**
+     * @description 播放器就绪事件
+     *
+     * 调用 `preload()` 完成后触发，或 `switchSource()` 切换成功后触发。
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerLoaded
+     * @param {Number} durationMs 视频总时长，单位毫秒
+     * @param {Number} width 视频宽度（像素），纯音频文件时为 0
+     * @param {Number} height 视频高度（像素），纯音频文件时为 0
+     */
+    TRTCVodPlayerEvent["onVodPlayerLoaded"] = "onVodPlayerLoaded";
+    /**
+     * @description 多媒体文件播放进度改变事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerProgress
+     * @param {Number} msPos 多媒体文件当前播放进度，单位毫秒
+     */
+    TRTCVodPlayerEvent["onVodPlayerProgress"] = "onVodPlayerProgress";
+    /**
+     * @description 多媒体文件播放暂停事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerPaused
+     */
+    TRTCVodPlayerEvent["onVodPlayerPaused"] = "onVodPlayerPaused";
+    /**
+     * @description 多媒体文件播放恢复事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerResumed
+     */
+    TRTCVodPlayerEvent["onVodPlayerResumed"] = "onVodPlayerResumed";
+    /**
+     * @description 多媒体文件播放停止事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerStopped
+     * @param {Number} reason 停止原因
+     *  - 0:用户主动停止；
+     *  - 1:文件播放完；
+     *  - 2:视频断流。
+     */
+    TRTCVodPlayerEvent["onVodPlayerStopped"] = "onVodPlayerStopped";
+    /**
+     * @description 多媒体文件播放出错事件
+     *
+     * @event TRTCVodPlayerEvent#onVodPlayerError
+     * @param {Number} error 错误码
+     *  - -6001:未知错误；
+     *  - -6002:通用错误；
+     *  - -6003:解封装失败；
+     *  - -6005:解封装超时；
+     *  - -6006:视频解码错误；
+     *  - -6007:音频解码错误；
+     *  - -6009:视频渲染错误。
+     */
+    TRTCVodPlayerEvent["onVodPlayerError"] = "onVodPlayerError";
+})(TRTCVodPlayerEvent = exports.TRTCVodPlayerEvent || (exports.TRTCVodPlayerEvent = {}));
 /**
  *
  * 腾讯云点播播放器
@@ -176,8 +249,6 @@ class TRTCVodPlayer {
      * 重复调用会被忽略。
      *
      * @note 可以先调用 {@link preload} 预加载完成后再调用 start，也可以跳过 preload 直接调用 start。
-     * @note 从 SDK 10.7 版本开始，需要通过 TXLiveBase#setLicence 设置 Licence 后方可成功播放，
-     *       否则将播放失败（黑屏），全局仅设置一次即可。
      */
     start() {
         var _a;
@@ -272,14 +343,19 @@ class TRTCVodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.seek(msPos);
     }
     /**
-     * 无缝切换当前播放的媒体文件
+     * 切换当前播放的媒体文件
+     *
+     * 底层实现等价于 `stop + 加载新源`，**切换后是否自动播放取决于切换前的状态**：
+     *   - 切换前在播放中：底层会自动 Started 新源，业务方无需再调 {@link start}；
+     *   - 切换前在暂停中：底层只 Loaded 新源不自动播放，业务方需在
+     *     {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 之后调 {@link start} 才会播。
      *
-     * 在后台预加载新的媒体源，待新源就绪后无缝切换，避免切换时出现黑屏。
-     * 切换成功后触发 {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 事件，携带新文件的媒体信息。
+     * 切换过程中会按顺序触发：
+     *   `onVodPlayerStopped` → `onVodPlayerLoaded`(新源信息) →
+     *   `onVodPlayerStarted`(仅"切换前在播放中"路径才会有)。
      *
      * @param newMediaFile - 新的媒体文件路径或 URL
      *
-     * @note 若当前处于暂停状态，切换后仍保持暂停并展示新文件第一帧。
      * @note 切换过程中调用 {@link stop} 会取消切换并停止当前播放。
      * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
      * @note 传入空串会被忽略并打 warn 日志（C++ 层亦有同等保护）。
@@ -621,29 +697,36 @@ class TRTCVodPlayer {
     _initEventCallback() {
         var _a;
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.setEventCallback((args) => {
-            switch (args[0]) {
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerStarted:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerStarted, args[1].msLength);
+            const event = args[0];
+            if ((event === TRTCVodPlayerEvent.onVodPlayerStopped || event === TRTCVodPlayerEvent.onVodPlayerError) && this.isStarted) {
+                this.isStarted = false;
+            }
+            switch (event) {
+                case TRTCVodPlayerEvent.onVodPlayerStarted:
+                    if (!this.isStarted) {
+                        this.isStarted = true;
+                    }
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerStarted, args[1].msLength);
                     break;
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerLoaded: {
+                case TRTCVodPlayerEvent.onVodPlayerLoaded: {
                     const data = args[1];
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerLoaded, data.durationMs, data.width, data.height);
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerLoaded, data.durationMs, data.width, data.height);
                     break;
                 }
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerProgress:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerProgress, args[1].msPos);
+                case TRTCVodPlayerEvent.onVodPlayerProgress:
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerProgress, args[1].msPos);
                     break;
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerPaused:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerPaused);
+                case TRTCVodPlayerEvent.onVodPlayerPaused:
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerPaused);
                     break;
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerResumed:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerResumed);
+                case TRTCVodPlayerEvent.onVodPlayerResumed:
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerResumed);
                     break;
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerStopped:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerStopped, args[1].reason);
+                case TRTCVodPlayerEvent.onVodPlayerStopped:
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerStopped, args[1].reason);
                     break;
-                case trtc_define_1.TRTCVodPlayerEvent.onVodPlayerError:
-                    this.fire(trtc_define_1.TRTCVodPlayerEvent.onVodPlayerError, args[1].error);
+                case TRTCVodPlayerEvent.onVodPlayerError:
+                    this.fire(TRTCVodPlayerEvent.onVodPlayerError, args[1].error);
                     break;
                 default: {
                     const exhaustiveCheck = args[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trtc-electron-sdk",
-  "version": "13.3.801-alpha.2",
+  "version": "13.3.801",
   "description": "trtc electron sdk",
   "main": "./liteav/index.js",
   "types": "./liteav/index.d.ts",