trtc-electron-sdk 13.3.800-alpha.1 → 13.3.800-alpha.2

package/README.md

@@ -11,13 +11,13 @@ Tencent Real-Time Communication (TRTC) is a set of low-latency, high-quality rea
 - ⬆️ [Publishing to CSS CDN](https://www.tencentcloud.com/document/product/647/47858#)
 
 ## 💻 Environment Support
-- 🍎 Support macOS x64 and arm64（**Electron 11+**）
-- ⚙️ Support Windows ia32 and x64
+- 🍎 macOS **11.0 (Big Sur)** and above, x64 and arm64 (**Electron 11+**)
+- 🪟 Windows 7 SP1 and above, ia32 and x64
 - 🌈 Electron: 8.5.0 and above
 
-|    macOS     |   Windows   |    Electron    |
-| :----------: | :---------: | :------------: |
-| x64 \| arm64 | ia32 \| x64 | 8.5.0 and above |
+|         macOS          |   Windows   |    Electron    |
+| :--------------------: | :---------: | :------------: |
+| 11.0+ (x64 \| arm64)   | ia32 \| x64 | 8.5.0 and above |
 
 
 ## ⏬ Install

package/liteav/index.d.ts

@@ -1,6 +1,7 @@
 export * from './trtc_define';
 export * from './trtc_code';
 export * from './vod_player';
+export { VodPlayerEvents, VodPlayerEventMap, IVodPlayer } from './types';
 export * from './extensions/DeviceManager';
 export * from './extensions/AudioEffectManager';
 export * from './extensions/MediaMixingManager';

package/liteav/index.js

@@ -13,9 +13,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VodPlayerEvents = void 0;
 __exportStar(require("./trtc_define"), exports);
 __exportStar(require("./trtc_code"), exports);
 __exportStar(require("./vod_player"), exports);
+var types_1 = require("./types");
+Object.defineProperty(exports, "VodPlayerEvents", { enumerable: true, get: function () { return types_1.VodPlayerEvents; } });
 __exportStar(require("./extensions/DeviceManager"), exports);
 __exportStar(require("./extensions/AudioEffectManager"), exports);
 __exportStar(require("./extensions/MediaMixingManager"), exports);

package/liteav/types.d.ts

@@ -1,8 +1,53 @@
 import TRTCMediaMixingManager, { TRTCMediaMixingService } from './extensions/MediaMixingManager';
-import { AudioMusicParam, Rect, TRTCAppScene, TRTCAudioQuality, TRTCBeautyStyle, TRTCDeviceType, TRTCLogLevel, TRTCAudioFrame, 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 { 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';
 export interface TRTCVideoRenderCallback {
     onRenderVideoFrame(userId: string, streamType: TRTCVideoStreamType, frame: TRTCVideoFrame): void;
 }
+export declare enum VodPlayerEvents {
+    onVodPlayerStarted = "onVodPlayerStarted",
+    onVodPlayerLoaded = "onVodPlayerLoaded",
+    onVodPlayerProgress = "onVodPlayerProgress",
+    onVodPlayerPaused = "onVodPlayerPaused",
+    onVodPlayerResumed = "onVodPlayerResumed",
+    onVodPlayerStopped = "onVodPlayerStopped",
+    onVodPlayerError = "onVodPlayerError"
+}
+export interface VodPlayerEventMap {
+    [VodPlayerEvents.onVodPlayerStarted]: [msLength: number];
+    [VodPlayerEvents.onVodPlayerLoaded]: [durationMs: number, width: number, height: number];
+    [VodPlayerEvents.onVodPlayerProgress]: [msPos: number];
+    [VodPlayerEvents.onVodPlayerPaused]: [];
+    [VodPlayerEvents.onVodPlayerResumed]: [];
+    [VodPlayerEvents.onVodPlayerStopped]: [reason: number];
+    [VodPlayerEvents.onVodPlayerError]: [error: number];
+}
+export interface IVodPlayer {
+    on<K extends keyof VodPlayerEventMap>(event: K, listener: (...args: VodPlayerEventMap[K]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    off<K extends keyof VodPlayerEventMap>(event: K, listener: (...args: VodPlayerEventMap[K]) => void): this;
+    off(event: string | symbol, listener: (...args: any[]) => void): this;
+    setView(view: HTMLElement | null): void;
+    setRenderRotation(rotation: TRTCVideoRotation): void;
+    setFillMode(mode: TRTCVideoFillMode): void;
+    setMirror(mirror: boolean): void;
+    preload(): void;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    seek(msPos: number): void;
+    switchSource(newMediaFile: string): void;
+    stop(): void;
+    getDuration(): number;
+    getWidth(): number;
+    getHeight(): number;
+    mute(mute: boolean): void;
+    setVolume(volume: number): void;
+    publishVideo(): void;
+    publishAudio(): void;
+    unpublishVideo(): void;
+    unpublishAudio(): void;
+    destroy(): void;
+}
 export interface ITRTCCloud {
     createSubCloud(config?: TRTCInitConfig): ITRTCCloud | null;
     enterRoom(params: any, scene: TRTCAppScene): void;

package/liteav/types.js

@@ -1,2 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VodPlayerEvents = void 0;
+var VodPlayerEvents;
+(function (VodPlayerEvents) {
+    VodPlayerEvents["onVodPlayerStarted"] = "onVodPlayerStarted";
+    VodPlayerEvents["onVodPlayerLoaded"] = "onVodPlayerLoaded";
+    VodPlayerEvents["onVodPlayerProgress"] = "onVodPlayerProgress";
+    VodPlayerEvents["onVodPlayerPaused"] = "onVodPlayerPaused";
+    VodPlayerEvents["onVodPlayerResumed"] = "onVodPlayerResumed";
+    VodPlayerEvents["onVodPlayerStopped"] = "onVodPlayerStopped";
+    VodPlayerEvents["onVodPlayerError"] = "onVodPlayerError";
+})(VodPlayerEvents = exports.VodPlayerEvents || (exports.VodPlayerEvents = {}));

package/liteav/vod_player.d.ts

@@ -1,34 +1,5 @@
 import { TRTCVideoRotation, TRTCVideoFillMode } from './trtc_define';
-/**
- * VodPlayer 播放器事件枚举
- */
-export declare enum VodPlayerEvents {
-    /** 播放开始，参数：msLength（总时长，毫秒） */
-    onVodPlayerStarted = "onVodPlayerStarted",
-    /** 播放进度更新，参数：msPos（当前进度，毫秒） */
-    onVodPlayerProgress = "onVodPlayerProgress",
-    /** 播放暂停 */
-    onVodPlayerPaused = "onVodPlayerPaused",
-    /** 播放恢复 */
-    onVodPlayerResumed = "onVodPlayerResumed",
-    /** 播放停止，参数：reason（0=用户主动停止，1=文件播放完，2=视频断流） */
-    onVodPlayerStopped = "onVodPlayerStopped",
-    /** 播放错误，参数：error（错误码） */
-    onVodPlayerError = "onVodPlayerError"
-}
-/**
- * VodPlayer 事件与回调参数的类型映射
- *
- * 用于 on/off 方法的类型约束，使事件名和回调参数在编译期匹配。
- */
-export interface VodPlayerEventMap {
-    [VodPlayerEvents.onVodPlayerStarted]: [msLength: number];
-    [VodPlayerEvents.onVodPlayerProgress]: [msPos: number];
-    [VodPlayerEvents.onVodPlayerPaused]: [];
-    [VodPlayerEvents.onVodPlayerResumed]: [];
-    [VodPlayerEvents.onVodPlayerStopped]: [reason: number];
-    [VodPlayerEvents.onVodPlayerError]: [error: number];
-}
+import { IVodPlayer, VodPlayerEventMap } from './types';
 /**
  *
  * 腾讯云点播播放器
@@ -51,21 +22,29 @@ export interface VodPlayerEventMap {
  * // 使用完毕后销毁
  * VodPlayer.releaseVodPlayer(player);
  */
-export declare class VodPlayer {
+export declare class VodPlayer implements IVodPlayer {
+    /** `_dataRenderCallback` 中允许连续重置 video buffer 的最大次数，超过后退化为周期日志 */
+    private static readonly MAX_BUFFER_RETRY;
+    /** 重试上限达到后，每隔多少帧打一次 warn 日志（按 30fps 估算 ≈ 2 秒一次） */
+    private static readonly BUFFER_RETRY_LOG_INTERVAL;
     private nativeVodPlayer;
     private videoRender;
     private mediaFilePath;
-    private repeat;
     private isStarted;
     private isDestroyed;
+    private isRenderPrepared;
+    /** 数据回调中连续 setVideoBuffer 失败次数（用于 _dataRenderCallback 退避策略） */
+    private _setBufferRetryCount;
     private logger;
     private eventEmitter;
     /**
      * 创建 VodPlayer 实例
      *
-     * @param mediaFilePath - 媒体文件路径（本地路径或在线 URL）
+     * @param mediaFilePath - 媒体文件路径（本地绝对路径或在线 URL），必填且必须是非空字符串
      * @param repeat - 是否循环播放，默认 false
      * @returns VodPlayer 实例
+     *
+     * @throws {TypeError} 当 `mediaFilePath` 不是非空字符串时抛出
      */
     static createVodPlayer(mediaFilePath: string, repeat?: boolean): VodPlayer;
     /**
@@ -100,61 +79,120 @@ export declare class VodPlayer {
     /**
      * 设置视频渲染的 DOM 容器
      *
-     * @param view - HTML 元素，用于承载视频画面
+     * @param view - HTML 元素，用于承载视频画面；传 `null` 时仅解除当前 view 关联，
+     *               播放/渲染管线不受影响（可后续再次 `setView(newDom)` 切换容器）。
+     *
+     * @note 若调用方需要彻底停止渲染，请使用 {@link stop} 或 {@link destroy}。
      */
     setView(view: HTMLElement | null): void;
+    /**
+     * 预加载多媒体文件
+     *
+     * 预加载完成后会触发 {@link VodPlayerEvents.onVodPlayerLoaded} 事件，事件参数携带
+     * 媒体信息（时长、宽高）；同时 C++ 层会产生首帧并推送到 JS 层的视频渲染管线，
+     * 在 view 上展示首帧画面。
+     *
+     * @example
+     * player.on(VodPlayerEvents.onVodPlayerLoaded, (durationMs, width, height) => {
+     *   console.log('预加载完成:', durationMs, width, height);
+     *   player.start();
+     * });
+     * player.preload();
+     *
+     * @note 可以先调用 preload 再调用 {@link start} 播放，也可以不调用 preload 直接调用 {@link start}。
+     * @note 若已经调用过 {@link start}，再调用 preload 将无效。
+     */
+    preload(): void;
     /**
      * 开始播放
      *
+     * 支持的视频格式：mp4、mkv、mov。
+     * 支持的音频格式：opus、aac。
+     *
+     * 重复调用会被忽略。
+     *
+     * @note 可以先调用 {@link preload} 预加载完成后再调用 start，也可以跳过 preload 直接调用 start。
+     * @note 从 SDK 10.7 版本开始，需要通过 TXLiveBase#setLicence 设置 Licence 后方可成功播放，
+     *       否则将播放失败（黑屏），全局仅设置一次即可。
      */
     start(): void;
     /**
      * 停止播放
-     *
      */
     stop(): void;
     /**
      * 暂停播放
+     *
+     * @note 仅在 {@link start} 之后调用才有效；未播放时调用会被忽略并打 warn 日志。
      */
     pause(): void;
     /**
      * 恢复播放
+     *
+     * @note 仅在 {@link start} 之后调用才有效；未播放时调用会被忽略并打 warn 日志。
      */
     resume(): void;
     /**
-     * 跳转到指定播放位置
+     * 跳转到指定播放位置（seek）
      *
      * @param msPos - 目标位置，单位毫秒
+     *
+     * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
      */
     seek(msPos: number): void;
     /**
-     * 获取媒体文件总时长
+     * 无缝切换当前播放的媒体文件
+     *
+     * 在后台预加载新的媒体源，待新源就绪后无缝切换，避免切换时出现黑屏。
+     * 切换成功后触发 {@link VodPlayerEvents.onVodPlayerLoaded} 事件，携带新文件的媒体信息。
+     *
+     * @param newMediaFile - 新的媒体文件路径或 URL
+     *
+     * @note 若当前处于暂停状态，切换后仍保持暂停并展示新文件第一帧。
+     * @note 切换过程中调用 {@link stop} 会取消切换并停止当前播放。
+     * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
+     * @note 传入空串会被忽略并打 warn 日志（C++ 层亦有同等保护）。
+     */
+    switchSource(newMediaFile: string): void;
+    /**
+     * 获取视频总时长
+     *
+     * @returns 总时长，单位毫秒；播放器已销毁时返回 0。
      *
-     * @returns 总时长，单位毫秒
+     * @note 跨平台口径已统一为 `int64_t`（即使 Windows x64 下底层 `long` 是 32 位，
+     *       binding 层也会显式扩到 64 位避免 ~49 天回绕）；JS `number` 安全整数上限 2^53，
+     *       业务上点播时长不会触及。
      */
     getDuration(): number;
     /**
      * 获取视频宽度
      *
-     * @returns 视频宽度（像素）
+     * @returns 视频宽度（像素）；纯音频文件或播放器已销毁时返回 0
      */
     getWidth(): number;
     /**
      * 获取视频高度
      *
-     * @returns 视频高度（像素）
+     * @returns 视频高度（像素）；纯音频文件或播放器已销毁时返回 0
      */
     getHeight(): number;
     /**
-     * 设置画面旋转角度
+     * 设置画面顺时针旋转角度
      *
-     * @param rotation - 旋转角度，参考 TRTCVideoRotation 枚举
+     * 仅对窗口渲染模式生效。
+     *
+     * @param rotation - 旋转角度，参考 {@link TRTCVideoRotation} 枚举，
+     *                   支持 TRTCVideoRotation0 / 90 / 180 / 270，默认 TRTCVideoRotation0
      */
     setRenderRotation(rotation: TRTCVideoRotation): void;
     /**
      * 设置画面填充模式
      *
-     * @param mode - 填充模式，参考 TRTCVideoFillMode 枚举
+     * 仅对窗口渲染模式生效。
+     *
+     * @param mode - 填充模式，参考 {@link TRTCVideoFillMode} 枚举：
+     *   - Fill：画面填满窗口，可能被拉伸或裁剪
+     *   - Fit：画面按比例适配窗口，可能出现黑边（默认值）
      */
     setFillMode(mode: TRTCVideoFillMode): void;
     /**
@@ -172,28 +210,32 @@ export declare class VodPlayer {
     /**
      * 设置播放音量
      *
-     * @param volume - 音量大小，取值范围 0-100
+     * @param volume - 音量大小，取值范围 [0, 150]，100 为原始音量，默认值 100
      */
     setVolume(volume: number): void;
     /**
-     * 开始推送视频流到 TRTC
+     * 向已关联的 TRTC 实例推送视频流
+     *
+     * @note 推流前播放器需已关联到 TRTC 实例（内部由 {@link start} 自动处理）。
      */
     publishVideo(): void;
     /**
-     * 开始推送音频流到 TRTC
+     * 向已关联的 TRTC 实例推送音频流
+     *
+     * @note 绑定后音频播放由 TRTC 接管。
      */
     publishAudio(): void;
     /**
-     * 停止推送视频流到 TRTC
+     * 停止向已关联的 TRTC 实例推送视频流
      */
     unpublishVideo(): void;
     /**
-     * 停止推送音频流到 TRTC
+     * 停止向已关联的 TRTC 实例推送音频流
      */
     unpublishAudio(): void;
     /**
      * @private
-     * 将点播播放器关联到 TRTC 实例（用于推流）
+     * 将点播播放器关联到 TRTC 实例（用于辅助流推流，绑定后音频播放由 TRTC 接管）
      */
     private attachTRTC;
     /**
@@ -201,9 +243,15 @@ export declare class VodPlayer {
      * 将点播播放器从 TRTC 实例分离
      */
     private detachTRTC;
+    /**
+     * 类型安全地发射事件，参数类型由 `VodPlayerEventMap` 推导。
+     * 通过 `setImmediate` 让 emit 异步化，避免在 N-API 回调栈中触发用户代码。
+     */
     private fire;
     private _createVideoRender;
     private _destroyVideoRender;
+    private _prepareRender;
+    private _teardownRender;
     private _setVideoRenderBuffer;
     private _addDataRenderCallback;
     private _removeDataRenderCallback;

package/liteav/vod_player.js

@@ -1,29 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VodPlayer = exports.VodPlayerEvents = void 0;
+exports.VodPlayer = 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 types_1 = require("./types");
 const NodeTRTCEngine = require('../build/Release/trtc_electron_sdk.node');
-/**
- * VodPlayer 播放器事件枚举
- */
-var VodPlayerEvents;
-(function (VodPlayerEvents) {
-    /** 播放开始，参数：msLength（总时长，毫秒） */
-    VodPlayerEvents["onVodPlayerStarted"] = "onVodPlayerStarted";
-    /** 播放进度更新，参数：msPos（当前进度，毫秒） */
-    VodPlayerEvents["onVodPlayerProgress"] = "onVodPlayerProgress";
-    /** 播放暂停 */
-    VodPlayerEvents["onVodPlayerPaused"] = "onVodPlayerPaused";
-    /** 播放恢复 */
-    VodPlayerEvents["onVodPlayerResumed"] = "onVodPlayerResumed";
-    /** 播放停止，参数：reason（0=用户主动停止，1=文件播放完，2=视频断流） */
-    VodPlayerEvents["onVodPlayerStopped"] = "onVodPlayerStopped";
-    /** 播放错误，参数：error（错误码） */
-    VodPlayerEvents["onVodPlayerError"] = "onVodPlayerError";
-})(VodPlayerEvents = exports.VodPlayerEvents || (exports.VodPlayerEvents = {}));
 /**
  *
  * 腾讯云点播播放器
@@ -54,9 +37,10 @@ class VodPlayer {
         this._dataRenderCallback = this._dataRenderCallback.bind(this);
         this.nativeVodPlayer = new NodeTRTCEngine.NodeVodPlayer(mediaFilePath, repeat);
         this.mediaFilePath = mediaFilePath;
-        this.repeat = repeat;
         this.isStarted = false;
         this.isDestroyed = false;
+        this.isRenderPrepared = false;
+        this._setBufferRetryCount = 0;
         this.videoRender = null;
         this._createVideoRender();
         this._initEventCallback();
@@ -65,11 +49,17 @@ class VodPlayer {
     /**
      * 创建 VodPlayer 实例
      *
-     * @param mediaFilePath - 媒体文件路径（本地路径或在线 URL）
+     * @param mediaFilePath - 媒体文件路径（本地绝对路径或在线 URL），必填且必须是非空字符串
      * @param repeat - 是否循环播放，默认 false
      * @returns VodPlayer 实例
+     *
+     * @throws {TypeError} 当 `mediaFilePath` 不是非空字符串时抛出
      */
     static createVodPlayer(mediaFilePath, repeat = false) {
+        if (typeof mediaFilePath !== 'string' || mediaFilePath.length === 0) {
+            // 空串或非字符串透传到 C++ 后 createTXVodPlayer 行为未定义，提前抛错让调用方立刻发现
+            throw new TypeError(`VodPlayer.createVodPlayer: mediaFilePath must be a non-empty string, got: ${JSON.stringify(mediaFilePath)}`);
+        }
         return new VodPlayer(mediaFilePath, repeat);
     }
     /**
@@ -112,23 +102,72 @@ class VodPlayer {
     /**
      * 设置视频渲染的 DOM 容器
      *
-     * @param view - HTML 元素，用于承载视频画面
+     * @param view - HTML 元素，用于承载视频画面；传 `null` 时仅解除当前 view 关联，
+     *               播放/渲染管线不受影响（可后续再次 `setView(newDom)` 切换容器）。
+     *
+     * @note 若调用方需要彻底停止渲染，请使用 {@link stop} 或 {@link destroy}。
      */
     setView(view) {
-        var _a;
+        var _a, _b;
         if (this.isDestroyed) {
             this.logger.warn('setView: player already destroyed');
             return;
         }
+        if (view === null) {
+            // 仅解除 view 关联，不下发 destroyRender / removeDataRenderCallback
+            // 否则后续 setView(newDom) 还需要重建整条渲染管线
+            this.logger.info('setView: view is null, detach current view');
+            (_a = this.videoRender) === null || _a === void 0 ? void 0 : _a.setRenderView(null);
+            return;
+        }
         this.logger.info(`setView view: ${view}`);
-        (_a = this.videoRender) === null || _a === void 0 ? void 0 : _a.setRenderView(view);
+        (_b = this.videoRender) === null || _b === void 0 ? void 0 : _b.setRenderView(view);
+    }
+    /**
+     * 预加载多媒体文件
+     *
+     * 预加载完成后会触发 {@link VodPlayerEvents.onVodPlayerLoaded} 事件，事件参数携带
+     * 媒体信息（时长、宽高）；同时 C++ 层会产生首帧并推送到 JS 层的视频渲染管线，
+     * 在 view 上展示首帧画面。
+     *
+     * @example
+     * player.on(VodPlayerEvents.onVodPlayerLoaded, (durationMs, width, height) => {
+     *   console.log('预加载完成:', durationMs, width, height);
+     *   player.start();
+     * });
+     * player.preload();
+     *
+     * @note 可以先调用 preload 再调用 {@link start} 播放，也可以不调用 preload 直接调用 {@link start}。
+     * @note 若已经调用过 {@link start}，再调用 preload 将无效。
+     */
+    preload() {
+        var _a;
+        if (this.isDestroyed) {
+            this.logger.warn('preload: player already destroyed');
+            return;
+        }
+        if (this.isStarted) {
+            this.logger.warn('preload: already started, ignored');
+            return;
+        }
+        this.logger.info(`preload mediaFile: ${this.mediaFilePath}`);
+        this._prepareRender();
+        (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.preload();
     }
     /**
      * 开始播放
      *
+     * 支持的视频格式：mp4、mkv、mov。
+     * 支持的音频格式：opus、aac。
+     *
+     * 重复调用会被忽略。
+     *
+     * @note 可以先调用 {@link preload} 预加载完成后再调用 start，也可以跳过 preload 直接调用 start。
+     * @note 从 SDK 10.7 版本开始，需要通过 TXLiveBase#setLicence 设置 Licence 后方可成功播放，
+     *       否则将播放失败（黑屏），全局仅设置一次即可。
      */
     start() {
-        var _a, _b;
+        var _a;
         if (this.isDestroyed) {
             this.logger.warn('start: player already destroyed');
             return;
@@ -138,35 +177,35 @@ class VodPlayer {
             this.logger.warn('start: already started, ignored');
             return;
         }
-        (_a = this.videoRender) === null || _a === void 0 ? void 0 : _a.createRender();
-        this._setVideoRenderBuffer();
-        this._addDataRenderCallback();
+        this._prepareRender();
         this.attachTRTC();
-        (_b = this.nativeVodPlayer) === null || _b === void 0 ? void 0 : _b.start();
+        (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.start();
         this.isStarted = true;
     }
     /**
      * 停止播放
-     *
      */
     stop() {
-        var _a, _b;
+        var _a;
         if (this.isDestroyed) {
             this.logger.warn('stop: player already destroyed');
             return;
         }
         this.logger.info('stop');
-        if (!this.isStarted) {
+        if (!this.isStarted && !this.isRenderPrepared) {
             return;
         }
-        this.isStarted = false;
-        (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.stop();
-        this.detachTRTC();
-        (_b = this.videoRender) === null || _b === void 0 ? void 0 : _b.destroyRender();
-        this._removeDataRenderCallback();
+        if (this.isStarted) {
+            this.isStarted = false;
+            (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.stop();
+            this.detachTRTC();
+        }
+        this._teardownRender();
     }
     /**
      * 暂停播放
+     *
+     * @note 仅在 {@link start} 之后调用才有效；未播放时调用会被忽略并打 warn 日志。
      */
     pause() {
         var _a;
@@ -174,11 +213,17 @@ class VodPlayer {
             this.logger.warn('pause: player already destroyed');
             return;
         }
+        if (!this.isStarted) {
+            this.logger.warn('pause: player not started, ignored');
+            return;
+        }
         this.logger.info('pause');
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.pause();
     }
     /**
      * 恢复播放
+     *
+     * @note 仅在 {@link start} 之后调用才有效；未播放时调用会被忽略并打 warn 日志。
      */
     resume() {
         var _a;
@@ -186,13 +231,19 @@ class VodPlayer {
             this.logger.warn('resume: player already destroyed');
             return;
         }
+        if (!this.isStarted) {
+            this.logger.warn('resume: player not started, ignored');
+            return;
+        }
         this.logger.info('resume');
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.resume();
     }
     /**
-     * 跳转到指定播放位置
+     * 跳转到指定播放位置（seek）
      *
      * @param msPos - 目标位置，单位毫秒
+     *
+     * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
      */
     seek(msPos) {
         var _a;
@@ -200,13 +251,54 @@ class VodPlayer {
             this.logger.warn('seek: player already destroyed');
             return;
         }
+        if (!this.isStarted && !this.isRenderPrepared) {
+            this.logger.warn(`seek: player not preloaded or started, ignored (msPos=${msPos})`);
+            return;
+        }
         this.logger.info(`seek msPos: ${msPos}`);
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.seek(msPos);
     }
     /**
-     * 获取媒体文件总时长
+     * 无缝切换当前播放的媒体文件
+     *
+     * 在后台预加载新的媒体源，待新源就绪后无缝切换，避免切换时出现黑屏。
+     * 切换成功后触发 {@link VodPlayerEvents.onVodPlayerLoaded} 事件，携带新文件的媒体信息。
+     *
+     * @param newMediaFile - 新的媒体文件路径或 URL
+     *
+     * @note 若当前处于暂停状态，切换后仍保持暂停并展示新文件第一帧。
+     * @note 切换过程中调用 {@link stop} 会取消切换并停止当前播放。
+     * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
+     * @note 传入空串会被忽略并打 warn 日志（C++ 层亦有同等保护）。
+     */
+    switchSource(newMediaFile) {
+        var _a;
+        if (this.isDestroyed) {
+            this.logger.warn('switchSource: player already destroyed');
+            return;
+        }
+        if (!newMediaFile) {
+            this.logger.warn('switchSource: newMediaFile is empty, ignored');
+            return;
+        }
+        if (!this.isStarted && !this.isRenderPrepared) {
+            this.logger.warn(`switchSource: player not preloaded or started, ignored (newMediaFile=${newMediaFile})`);
+            return;
+        }
+        this.logger.info(`switchSource newMediaFile: ${newMediaFile}`);
+        this.mediaFilePath = newMediaFile;
+        // 切换源后如果出现 buffer 尺寸变化，需要让 _dataRenderCallback 退避计数重置
+        this._setBufferRetryCount = 0;
+        (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.switchSource(newMediaFile);
+    }
+    /**
+     * 获取视频总时长
+     *
+     * @returns 总时长，单位毫秒；播放器已销毁时返回 0。
      *
-     * @returns 总时长，单位毫秒
+     * @note 跨平台口径已统一为 `int64_t`（即使 Windows x64 下底层 `long` 是 32 位，
+     *       binding 层也会显式扩到 64 位避免 ~49 天回绕）；JS `number` 安全整数上限 2^53，
+     *       业务上点播时长不会触及。
      */
     getDuration() {
         var _a, _b;
@@ -219,7 +311,7 @@ class VodPlayer {
     /**
      * 获取视频宽度
      *
-     * @returns 视频宽度（像素）
+     * @returns 视频宽度（像素）；纯音频文件或播放器已销毁时返回 0
      */
     getWidth() {
         var _a, _b;
@@ -232,7 +324,7 @@ class VodPlayer {
     /**
      * 获取视频高度
      *
-     * @returns 视频高度（像素）
+     * @returns 视频高度（像素）；纯音频文件或播放器已销毁时返回 0
      */
     getHeight() {
         var _a, _b;
@@ -243,9 +335,12 @@ class VodPlayer {
         return (_b = (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.getHeight()) !== null && _b !== void 0 ? _b : 0;
     }
     /**
-     * 设置画面旋转角度
+     * 设置画面顺时针旋转角度
+     *
+     * 仅对窗口渲染模式生效。
      *
-     * @param rotation - 旋转角度，参考 TRTCVideoRotation 枚举
+     * @param rotation - 旋转角度，参考 {@link TRTCVideoRotation} 枚举，
+     *                   支持 TRTCVideoRotation0 / 90 / 180 / 270，默认 TRTCVideoRotation0
      */
     setRenderRotation(rotation) {
         var _a;
@@ -259,7 +354,11 @@ class VodPlayer {
     /**
      * 设置画面填充模式
      *
-     * @param mode - 填充模式，参考 TRTCVideoFillMode 枚举
+     * 仅对窗口渲染模式生效。
+     *
+     * @param mode - 填充模式，参考 {@link TRTCVideoFillMode} 枚举：
+     *   - Fill：画面填满窗口，可能被拉伸或裁剪
+     *   - Fit：画面按比例适配窗口，可能出现黑边（默认值）
      */
     setFillMode(mode) {
         var _a, _b;
@@ -302,7 +401,7 @@ class VodPlayer {
     /**
      * 设置播放音量
      *
-     * @param volume - 音量大小，取值范围 0-100
+     * @param volume - 音量大小，取值范围 [0, 150]，100 为原始音量，默认值 100
      */
     setVolume(volume) {
         var _a;
@@ -314,7 +413,9 @@ class VodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.setVolume(volume);
     }
     /**
-     * 开始推送视频流到 TRTC
+     * 向已关联的 TRTC 实例推送视频流
+     *
+     * @note 推流前播放器需已关联到 TRTC 实例（内部由 {@link start} 自动处理）。
      */
     publishVideo() {
         var _a;
@@ -326,7 +427,9 @@ class VodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.publishVideo();
     }
     /**
-     * 开始推送音频流到 TRTC
+     * 向已关联的 TRTC 实例推送音频流
+     *
+     * @note 绑定后音频播放由 TRTC 接管。
      */
     publishAudio() {
         var _a;
@@ -338,7 +441,7 @@ class VodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.publishAudio();
     }
     /**
-     * 停止推送视频流到 TRTC
+     * 停止向已关联的 TRTC 实例推送视频流
      */
     unpublishVideo() {
         var _a;
@@ -350,7 +453,7 @@ class VodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.unpublishVideo();
     }
     /**
-     * 停止推送音频流到 TRTC
+     * 停止向已关联的 TRTC 实例推送音频流
      */
     unpublishAudio() {
         var _a;
@@ -364,7 +467,7 @@ class VodPlayer {
     // ─── 内部方法 ───────────────────────────────────────────────
     /**
      * @private
-     * 将点播播放器关联到 TRTC 实例（用于推流）
+     * 将点播播放器关联到 TRTC 实例（用于辅助流推流，绑定后音频播放由 TRTC 接管）
      */
     attachTRTC() {
         var _a;
@@ -388,6 +491,10 @@ class VodPlayer {
         this.logger.info('detachTRTC');
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.detachTRTC();
     }
+    /**
+     * 类型安全地发射事件，参数类型由 `VodPlayerEventMap` 推导。
+     * 通过 `setImmediate` 让 emit 异步化，避免在 N-API 回调栈中触发用户代码。
+     */
     fire(event, ...args) {
         setImmediate(() => {
             this.eventEmitter.emit(event, ...args);
@@ -401,11 +508,32 @@ class VodPlayer {
         this.videoRender.setVideoPixelFormat(trtc_define_1.TRTCVideoPixelFormat.TRTCVideoPixelFormat_BGRA32);
     }
     _destroyVideoRender() {
+        this._teardownRender();
         if (this.videoRender) {
             this.videoRender.destroy();
             this.videoRender = null;
         }
+    }
+    _prepareRender() {
+        var _a;
+        if (this.isRenderPrepared) {
+            return;
+        }
+        (_a = this.videoRender) === null || _a === void 0 ? void 0 : _a.createRender();
+        this._setVideoRenderBuffer();
+        this._addDataRenderCallback();
+        this.isRenderPrepared = true;
+        this._setBufferRetryCount = 0;
+    }
+    _teardownRender() {
+        var _a;
+        if (!this.isRenderPrepared) {
+            return;
+        }
+        (_a = this.videoRender) === null || _a === void 0 ? void 0 : _a.destroyRender();
         this._removeDataRenderCallback();
+        this.isRenderPrepared = false;
+        this._setBufferRetryCount = 0;
     }
     _setVideoRenderBuffer() {
         var _a;
@@ -424,47 +552,69 @@ class VodPlayer {
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.setDataCallback(null);
     }
     _dataRenderCallback(args) {
-        if (this.videoRender) {
-            const [userId, type, width, height, timestamp, rotation, valid, bufferId] = args;
-            const result = this.videoRender.renderVideoData(userId, type, width, height, timestamp, rotation, valid, bufferId);
-            if (!result) {
-                this.logger.info(`_dataRenderCallback: renderVideoData returned false, re-setting video buffer`);
-                this._setVideoRenderBuffer();
+        if (!this.videoRender) {
+            this.logger.warn('_dataRenderCallback: videoRender is null, frame dropped');
+            return;
+        }
+        const [userId, type, width, height, timestamp, rotation, valid, bufferId] = args;
+        const result = this.videoRender.renderVideoData(userId, type, width, height, timestamp, rotation, valid, bufferId);
+        if (result) {
+            // 渲染成功，重置重试计数，避免长期累计后误触发降级
+            if (this._setBufferRetryCount !== 0) {
+                this._setBufferRetryCount = 0;
             }
+            return;
         }
-        else {
-            this.logger.warn('_dataRenderCallback: videoRender is null, frame dropped');
+        // renderVideoData 返回 false 通常意味着 buffer 尺寸 / 格式不匹配，需要重新 setVideoBuffer。
+        // 但若底层持续失败（例如尺寸一直对不上），不能每帧都重置 buffer——30fps 下每秒会触发 30 次
+        // 跨 N-API 调用，引发明显性能抖动。这里加重试上限：前 N 次正常重置，超过后退避到周期性日志。
+        this._setBufferRetryCount += 1;
+        if (this._setBufferRetryCount <= VodPlayer.MAX_BUFFER_RETRY) {
+            this.logger.info(`_dataRenderCallback: renderVideoData returned false (retry ${this._setBufferRetryCount}/${VodPlayer.MAX_BUFFER_RETRY}), re-setting video buffer`);
+            this._setVideoRenderBuffer();
+        }
+        else if (this._setBufferRetryCount % VodPlayer.BUFFER_RETRY_LOG_INTERVAL === 0) {
+            this.logger.warn(`_dataRenderCallback: renderVideoData keeps failing for ${this._setBufferRetryCount} frames, giving up frame`);
         }
     }
     _initEventCallback() {
         var _a;
         (_a = this.nativeVodPlayer) === null || _a === void 0 ? void 0 : _a.setEventCallback((args) => {
-            const key = args[0];
-            const data = args[1];
-            switch (key) {
-                case VodPlayerEvents.onVodPlayerStarted:
-                    this.fire(VodPlayerEvents.onVodPlayerStarted, data.msLength);
+            switch (args[0]) {
+                case types_1.VodPlayerEvents.onVodPlayerStarted:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerStarted, args[1].msLength);
+                    break;
+                case types_1.VodPlayerEvents.onVodPlayerLoaded: {
+                    const data = args[1];
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerLoaded, data.durationMs, data.width, data.height);
                     break;
-                case VodPlayerEvents.onVodPlayerProgress:
-                    this.fire(VodPlayerEvents.onVodPlayerProgress, data.msPos);
+                }
+                case types_1.VodPlayerEvents.onVodPlayerProgress:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerProgress, args[1].msPos);
                     break;
-                case VodPlayerEvents.onVodPlayerPaused:
-                    this.fire(VodPlayerEvents.onVodPlayerPaused);
+                case types_1.VodPlayerEvents.onVodPlayerPaused:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerPaused);
                     break;
-                case VodPlayerEvents.onVodPlayerResumed:
-                    this.fire(VodPlayerEvents.onVodPlayerResumed);
+                case types_1.VodPlayerEvents.onVodPlayerResumed:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerResumed);
                     break;
-                case VodPlayerEvents.onVodPlayerStopped:
-                    this.fire(VodPlayerEvents.onVodPlayerStopped, data.reason);
+                case types_1.VodPlayerEvents.onVodPlayerStopped:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerStopped, args[1].reason);
                     break;
-                case VodPlayerEvents.onVodPlayerError:
-                    this.fire(VodPlayerEvents.onVodPlayerError, data.error);
+                case types_1.VodPlayerEvents.onVodPlayerError:
+                    this.fire(types_1.VodPlayerEvents.onVodPlayerError, args[1].error);
                     break;
-                default:
-                    this.logger.warn(`unknown vod player event: ${key}`);
+                default: {
+                    const exhaustiveCheck = args[0];
+                    this.logger.warn(`unknown vod player event: ${String(exhaustiveCheck)}`);
                     break;
+                }
             }
         });
     }
 }
 exports.VodPlayer = VodPlayer;
+/** `_dataRenderCallback` 中允许连续重置 video buffer 的最大次数，超过后退化为周期日志 */
+VodPlayer.MAX_BUFFER_RETRY = 3;
+/** 重试上限达到后，每隔多少帧打一次 warn 日志（按 30fps 估算 ≈ 2 秒一次） */
+VodPlayer.BUFFER_RETRY_LOG_INTERVAL = 60;

package/package.json

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