trtc-electron-sdk/liteav/vod_player.d.ts

trtc electron sdk

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];
}
/**
 *
 * 腾讯云点播播放器
 *
 * 用于播放本地或在线的音视频文件，支持视频渲染、音量控制、
 * 进度控制、TRTC 推流等功能。
 *
 * @version v13.3.800
 *
 * @example
 * import { TRTCVodPlayer, TRTCVodPlayerEvent } from 'trtc-electron-sdk';
 *
 * const player = TRTCVodPlayer.createVodPlayer('/path/to/video.mp4', false);
 * player.on(TRTCVodPlayerEvent.onVodPlayerStarted, (msLength) => {
 *   console.log('播放开始，总时长:', msLength);
 * });
 * player.setView(document.getElementById('video-container')!);
 * player.start();
 *
 * // 使用完毕后销毁
 * TRTCVodPlayer.releaseVodPlayer(player);
 */
export declare class TRTCVodPlayer implements IVodPlayer {
    private static readonly MAX_BUFFER_RETRY;
    private static readonly BUFFER_RETRY_LOG_INTERVAL;
    private nativeVodPlayer;
    private videoRender;
    private mediaFilePath;
    private isStarted;
    private isDestroyed;
    private isRenderPrepared;
    private _setBufferRetryCount;
    private logger;
    private eventEmitter;
    /**
     * 当前 native 构建是否启用了 VOD 播放器。
     *
     * 这是一次性的"构建期能力探测"——`NodeTRTCEngine.NodeVodPlayer` 是
     * 加载 .node 时绑定，运行期不会变化，因此结果可在模块加载时缓存为常量。
     *
     * 通过 {@link isSupported} 对外暴露访问入口。
     */
    private static readonly VOD_SUPPORTED;
    /**
     * 判断当前 native 构建是否启用了 VOD 播放器
     *
     * C++ 侧 VOD 模块为条件编译（`TRTC_VOD_PLAYER` 宏），未启用时 `NodeTRTCEngine.NodeVodPlayer`
     * 不存在。调用方在 {@link createVodPlayer} 前应先用本方法探测，否则会拿到一个
     * `Error: [TRTCVodPlayer][ERR_NO_VOD_SUPPORT] ...` 异常。
     *
     * @returns true 表示当前构建支持 VOD；false 表示未启用
     */
    static isSupported(): boolean;
    /**
     * 创建 TRTCVodPlayer 实例
     *
     * @param mediaFilePath - 媒体文件路径（本地绝对路径或在线 URL），必填且必须是非空字符串
     * @param repeat - 是否循环播放，默认 false
     * @returns TRTCVodPlayer 实例
     *
     * @throws {Error} 当前 native 构建未启用 VOD 时抛出，错误信息以
     *                 `[TRTCVodPlayer][ERR_NO_VOD_SUPPORT]` 起始，便于日志聚合与告警
     *                 （请先用 {@link isSupported} 探测）
     * @throws {TypeError} 当 `mediaFilePath` 不是非空字符串时抛出
     */
    static createVodPlayer(mediaFilePath: string, repeat?: boolean): TRTCVodPlayer;
    /**
     * 销毁 TRTCVodPlayer 实例，释放相关资源
     *
     * @param player - 待销毁的 TRTCVodPlayer 实例
     */
    static releaseVodPlayer(player: TRTCVodPlayer): void;
    private constructor();
    /**
     * 监听 TRTCVodPlayer 事件
     *
     * @param event - 事件名称，参考 {@link TRTCVodPlayerEvent}
     * @param listener - 事件回调函数，参数类型根据事件自动推导
     */
    on<K extends keyof TRTCVodPlayerEventMap>(event: K, listener: (...args: TRTCVodPlayerEventMap[K]) => void): this;
    on(event: string | symbol, listener: (...args: any[]) => void): this;
    /**
     * 取消监听 TRTCVodPlayer 事件
     *
     * @param event - 事件名称
     * @param listener - 事件回调函数
     */
    off<K extends keyof TRTCVodPlayerEventMap>(event: K, listener: (...args: TRTCVodPlayerEventMap[K]) => void): this;
    off(event: string | symbol, listener: (...args: any[]) => void): this;
    /**
     * 设置视频渲染的 DOM 容器
     *
     * @param view - HTML 元素，用于承载视频画面；传 `null` 时仅解除当前 view 关联，
     *               播放/渲染管线不受影响（可后续再次 `setView(newDom)` 切换容器）。
     *
     * @note 若调用方需要彻底停止渲染，请使用 {@link stop} 或 {@link destroy}。
     */
    setView(view: HTMLElement | null): void;
    /**
     * 预加载多媒体文件
     *
     * 预加载完成后会触发 {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 事件，事件参数携带
     * 媒体信息（时长、宽高）；同时 C++ 层会产生首帧并推送到 JS 层的视频渲染管线，
     * 在 view 上展示首帧画面。
     *
     * @example
     * player.on(TRTCVodPlayerEvent.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。
     */
    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;
    /**
     * 切换当前播放的媒体文件
     *
     * 底层实现等价于 `stop + 加载新源`，**切换后是否自动播放取决于切换前的状态**：
     *   - 切换前在播放中：底层会自动 Started 新源，业务方无需再调 {@link start}；
     *   - 切换前在暂停中：底层只 Loaded 新源不自动播放，业务方需在
     *     {@link TRTCVodPlayerEvent.onVodPlayerLoaded} 之后调 {@link start} 才会播。
     *
     * 切换过程中会按顺序触发：
     *   `onVodPlayerStopped` → `onVodPlayerLoaded`(新源信息) →
     *   `onVodPlayerStarted`(仅"切换前在播放中"路径才会有)。
     *
     * @param newMediaFile - 新的媒体文件路径或 URL
     *
     * @note 切换过程中调用 {@link stop} 会取消切换并停止当前播放。
     * @note 调用前必须先 {@link preload} 或 {@link start}，否则会被忽略并打 warn 日志。
     * @note 传入空串会被忽略并打 warn 日志（C++ 层亦有同等保护）。
     */
    switchSource(newMediaFile: string): void;
    /**
     * 获取视频总时长
     *
     * @returns 总时长，单位毫秒；播放器已销毁时返回 0。
     *
     * @note 跨平台口径已统一为 `int64_t`（即使 Windows x64 下底层 `long` 是 32 位，
     *       binding 层也会显式扩到 64 位避免 ~49 天回绕）；JS `number` 安全整数上限 2^53，
     *       业务上点播时长不会触及。
     */
    getDuration(): number;
    /**
     * 获取视频宽度
     *
     * @returns 视频宽度（像素）；纯音频文件或播放器已销毁时返回 0
     */
    getWidth(): number;
    /**
     * 获取视频高度
     *
     * @returns 视频高度（像素）；纯音频文件或播放器已销毁时返回 0
     */
    getHeight(): number;
    /**
     * 设置画面顺时针旋转角度
     *
     * 仅对窗口渲染模式生效。
     *
     * @param rotation - 旋转角度，参考 {@link TRTCVideoRotation} 枚举，
     *                   支持 TRTCVideoRotation0 / 90 / 180 / 270，默认 TRTCVideoRotation0
     */
    setRenderRotation(rotation: TRTCVideoRotation): void;
    /**
     * 设置画面填充模式
     *
     * 仅对窗口渲染模式生效。
     *
     * @param mode - 填充模式，参考 {@link TRTCVideoFillMode} 枚举：
     *   - Fill：画面填满窗口，可能被拉伸或裁剪
     *   - Fit：画面按比例适配窗口，可能出现黑边（默认值）
     */
    setFillMode(mode: TRTCVideoFillMode): void;
    /**
     * 设置画面镜像
     *
     * @param mirror - 是否镜像
     */
    setMirror(mirror: boolean): void;
    /**
     * 静音 / 取消静音
     *
     * @param mute - 是否静音
     */
    mute(mute: boolean): void;
    /**
     * 设置播放音量
     *
     * @param volume - 音量大小，取值范围 [0, 150]，100 为原始音量，默认值 100
     */
    setVolume(volume: number): void;
    /**
     * 向已关联的 TRTC 实例推送视频流
     *
     * @note 推流前播放器需已关联到 TRTC 实例（内部由 {@link start} 自动处理）。
     */
    publishVideo(): void;
    /**
     * 向已关联的 TRTC 实例推送音频流
     *
     * @note 绑定后音频播放由 TRTC 接管。
     */
    publishAudio(): void;
    /**
     * 停止向已关联的 TRTC 实例推送视频流
     */
    unpublishVideo(): void;
    /**
     * 停止向已关联的 TRTC 实例推送音频流
     */
    unpublishAudio(): void;
    /**
     * @private
     * 销毁播放器，释放所有资源
     *
     * 包括：解绑事件监听、停止播放、销毁渲染器、清理 native 回调。
     *
     * 注意：调用本方法后不再向业务方派发任何事件。即便 `stop()` 内部会异步触发
     * `onVodPlayerStopped`，该事件也不会送达，因为监听器已在第一步被清空。
     * 这是 `releaseVodPlayer` 的自然语义（资源释放后不再产生副作用）。
     */
    private _destroy;
    /**
     * @private
     * 将点播播放器关联到 TRTC 实例（用于辅助流推流，绑定后音频播放由 TRTC 接管）
     */
    private attachTRTC;
    /**
     * @private
     * 将点播播放器从 TRTC 实例分离
     */
    private detachTRTC;
    /**
     * @private
     * 类型安全地发射事件，参数类型由 `TRTCVodPlayerEventMap` 推导。
     * 通过 `setImmediate` 让 emit 异步化，避免在 N-API 回调栈中触发用户代码。
     */
    private fire;
    private _createVideoRender;
    private _destroyVideoRender;
    private _prepareRender;
    private _teardownRender;
    private _setVideoRenderBuffer;
    private _addDataRenderCallback;
    private _removeDataRenderCallback;
    private _dataRenderCallback;
    private _initEventCallback;
}