thunder-player-sdk/player.d.ts

Thunder Player SDK - A WebAssembly-based H.264 video player for web browsers

/**
 * Thunder Player SDK TypeScript Type Definitions
 * @version 1.0.2
 * @description 完整的TypeScript类型声明，支持IDE自动补全和类型检查
 */

// ============ 类型定义 ============

/**
 * 播放器状态枚举
 */
export enum PlayerState {
    /** 空闲状态 */
    Idle = 0,
    /** 播放中 */
    Playing = 1,
    /** 暂停中 */
    Pausing = 2,
    /** 跳转中 */
    Seeking = 3,
    /** 清理中 */
    Cleaning = 4
}

/**
 * SDK初始化参数
 */
export interface SDKAuthParams {
    /** 应用ID（必需） */
    appid: string;
    /** 用户ID（可选） */
    uid?: string;
    /** SDK序列号（必需） */
    sdk_sn: string;
    /** 认证服务器地址（可选，优先级最高） */
    authServer?: string;
}

/**
 * 播放结果
 */
export interface PlayResult {
    /** 错误码，0表示成功 */
    e: number;
    /** 错误信息 */
    m: string;
}

/**
 * 视频信息
 */
export interface VideoInfo {
    /** 视频宽度 */
    width: number;
    /** 视频高度 */
    height: number;
    /** 视频编码格式 */
    codec: string;
    /** 像素格式 */
    pixelFormat: string;
}

/**
 * 音频信息
 */
export interface AudioInfo {
    /** 音频编码格式 */
    codec: string;
    /** 音频声道数 */
    channels: number;
    /** 采样率 */
    sampleRate: number;
}

/**
 * 缓冲区信息
 */
export interface BufferInfo {
    /** 音频帧缓冲数量 */
    audioFrames: number;
    /** 视频帧缓冲数量 */
    videoFrames: number;
    /** 缓冲时长（秒） */
    bufferTime: number;
}

/**
 * 媒体信息
 */
export interface MediaInfo {
    /** 总时长（秒） */
    duration: number;
    /** 当前播放时间（秒） */
    currentTime: number;
    /** 播放进度（0-1） */
    progress: number;
    /** 视频信息 */
    video: VideoInfo;
    /** 音频信息 */
    audio: AudioInfo;
    /** 播放器状态字符串 */
    state: string;
    /** 缓冲区信息 */
    bufferInfo: BufferInfo;
}

/**
 * 时间更新事件数据
 */
export interface TimeUpdateEventData {
    /** 当前播放时间（秒） */
    currentTime: number;
    /** 总时长（秒） */
    duration: number;
    /** 播放进度（0-100） */
    progress: number;
}

/**
 * 元数据加载事件数据
 */
export interface LoadedMetadataEventData {
    /** 视频信息 */
    video: VideoInfo;
    /** 音频信息 */
    audio: AudioInfo;
    /** 总时长（秒） */
    duration: number;
}

/**
 * 错误事件数据
 */
export interface ErrorEventData {
    /** 错误码 */
    code: string;
    /** 错误消息 */
    message: string;
    /** 错误详情 */
    details?: any;
}

// ============ 事件类型定义 ============

/**
 * 播放器事件名称
 */
export type PlayerEventName =
    | 'play'              // 开始播放
    | 'pause'             // 暂停
    | 'resume'            // 恢复播放
    | 'stop'              // 停止
    | 'ended'             // 播放结束
    | 'timeupdate'        // 时间更新
    | 'loadedmetadata'    // 元数据加载完成
    | 'loadingstart'      // 开始加载
    | 'loadingend'        // 加载结束
    | 'error'             // 错误
    | 'statechange';      // 状态变化

/**
 * 事件数据映射表
 */
export interface PlayerEventMap {
    'play': {};
    'pause': {};
    'resume': {};
    'stop': {};
    'ended': {};
    'timeupdate': TimeUpdateEventData;
    'loadedmetadata': LoadedMetadataEventData;
    'loadingstart': {};
    'loadingend': {};
    'error': ErrorEventData;
    'statechange': { state: PlayerState };
}

/**
 * 事件回调函数类型
 */
export type EventCallback<T extends PlayerEventName> = (data: PlayerEventMap[T]) => void;

// ============ Player 类定义 ============

/**
 * Thunder Player SDK 主类
 *
 * @example
 * ```typescript
 * const player = new Player();
 *
 * // 初始化SDK
 * await player.initSDK({
 *   appid: 'your-app-id',
 *   sdk_sn: 'your-sdk-sn',
 *   authServer: 'https://your-auth-server.com'
 * });
 *
 * // 播放视频
 * const canvas = document.getElementById('video-canvas') as HTMLCanvasElement;
 * const result = player.play('https://example.com/video.ts', canvas);
 *
 * // 监听事件
 * player.on('timeupdate', (data) => {
 *   console.log(`当前播放时间: ${data.currentTime}秒`);
 * });
 * ```
 */
export class Player {
    // ============ 构造和初始化 ============

    /**
     * 创建播放器实例
     */
    constructor();

    /**
     * 初始化SDK环境（必须在播放前调用）
     * @param authParams 认证参数
     * @returns Promise，初始化成功返回true
     * @throws 如果认证参数无效
     */
    initSDK(authParams: SDKAuthParams): Promise<boolean>;

    /**
     * 检查SDK是否已初始化
     * @returns SDK是否已初始化
     */
    isSDKInitialized(): boolean;

    // ============ 播放控制 ============

    /**
     * 播放视频
     * @param url 视频URL（支持 .ts .ls .uls .mls 格式）
     * @param canvas Canvas元素用于视频渲染
     * @param callback 可选的回调函数（已废弃，建议使用事件监听）
     * @returns 播放结果
     */
    play(url: string, canvas: HTMLCanvasElement, callback?: Function): PlayResult;

    /**
     * 暂停播放
     */
    pause(): void;

    /**
     * 恢复播放（暂停后）
     * @param fromSeek 是否来自跳转操作
     */
    resume(fromSeek?: boolean): void;

    /**
     * 停止播放
     */
    stop(): Promise<void>;

    /**
     * 跳转到指定时间
     * @param timeMs 目标时间（毫秒）
     */
    seekTo(timeMs: number): void;

    // ============ 音量控制 ============

    /**
     * 设置音量
     * @param volume 音量值（0.0 - 1.0）
     */
    setVolume(volume: number): void;

    /**
     * 获取当前音量
     * @returns 音量值（0.0 - 1.0）
     */
    getVolume(): number;

    // ============ 播放速度控制 ============

    /**
     * 设置播放速度
     * @param speed 播放速度倍率（0.1 - 10.0，1.0为正常速度）
     */
    setPlaybackSpeed(speed: number): void;

    /**
     * 获取当前播放速度
     * @returns 播放速度倍率
     */
    getPlaybackSpeed(): number;

    // ============ 状态和信息获取 ============

    /**
     * 获取播放器状态
     * @returns 播放器状态码
     */
    getState(): PlayerState;

    /**
     * 获取当前播放时间
     * @returns 当前时间（秒）
     */
    getCurrentTime(): number;

    /**
     * 获取视频总时长
     * @returns 总时长（秒）
     */
    getDuration(): number;

    /**
     * 获取播放进度
     * @returns 进度值（0.0 - 1.0）
     */
    getProgress(): number;

    /**
     * 获取下载缓存进度
     * @returns 缓存进度（0.0 - 1.0）
     */
    getDownloadProgress(): number;

    /**
     * 获取完整的媒体信息
     * @returns 媒体信息对象
     */
    getMediaInfo(): MediaInfo;

    /**
     * 获取缓冲区信息
     * @returns 缓冲区信息
     */
    getBufferInfo(): BufferInfo;

    /**
     * 获取当前FPS
     * @returns FPS值
     */
    getCurrentFps(): number;

    /**
     * 获取SDK版本号
     * @returns 版本号字符串
     */
    getVersion(): string;

    // ============ 事件系统 ============

    /**
     * 注册事件监听器
     * @param eventName 事件名称
     * @param callback 回调函数
     * @returns 播放器实例（支持链式调用）
     */
    on<T extends PlayerEventName>(eventName: T, callback: EventCallback<T>): this;

    /**
     * 移除事件监听器
     * @param eventName 事件名称
     * @param callback 要移除的回调函数（可选，不传则移除该事件的所有监听器）
     * @returns 播放器实例（支持链式调用）
     */
    off<T extends PlayerEventName>(eventName: T, callback?: EventCallback<T>): this;

    // ============ 资源管理 ============

    /**
     * 销毁播放器实例，释放所有资源
     * 推荐在页面卸载或不再需要播放器时调用
     */
    destroy(): void;

    // ============ 高级功能 ============

    /**
     * 启用/禁用自动页面可见性处理
     * @param enabled 是否启用
     * @returns 播放器实例（支持链式调用）
     */
    enableAutoVisibilityHandling(enabled: boolean): this;

    /**
     * 切换音轨
     */
    switchAudioTrack(): void;

    /**
     * 全屏播放
     */
    fullscreen(): void;
}

// ============ 默认导出 ============

export default Player;

// ============ 全局类型扩展（如果通过script标签引入） ============

declare global {
    interface Window {
        Player: typeof Player;
        THUNDER_AUTH_SERVER?: string;
        THUNDER_CONFIG?: {
            authServer?: string;
            apiTimeout?: number;
            retryCount?: number;
            logLevel?: 'debug' | 'info' | 'warn' | 'error';
            enableDebug?: boolean;
        };
    }
}