mstf-kit/dist/types/utils/audioPlayer.d.ts

一个现代化的 JavaScript/TypeScript 工具库，提供了丰富的常用工具函数

/**
 * 音频播放器工具
 * 支持背景播放和UI渲染模式
 */
/**
 * Vue3 ref类型 (简化版)
 */
interface Ref<T> {
    value: T;
}
/**
 * 播放器状态
 */
export type PlayerState = 'idle' | 'loading' | 'playing' | 'paused' | 'ended' | 'error' | 'destroyed';
/**
 * 音频播放器选项
 */
export interface AudioPlayerOptions {
    /**
     * 是否渲染UI界面
     * - true: 创建播放器UI并渲染到指定容器
     * - false: 仅背景播放，不创建UI (默认)
     */
    renderUI?: boolean;
    /**
     * 播放器容器元素、选择器或Vue3 ref
     * 仅当 renderUI 为 true 时有效
     */
    container?: HTMLElement | string | Ref<HTMLElement>;
    /** 播放器宽度 */
    width?: string;
    /** 播放器高度 */
    height?: string;
    /**
     * 播放器主题
     * - 'default': 默认主题
     * - 'dark': 暗色主题
     * - 'minimal': 简约主题
     */
    theme?: 'default' | 'dark' | 'minimal';
    /**
     * 是否显示音频可视化
     * 仅当 renderUI 为 true 时有效
     */
    showVisualization?: boolean;
    /**
     * 可视化类型
     * - 'waveform': 波形图
     * - 'bars': 频谱柱状图
     * - 'circle': 圆形频谱图
     */
    visualizationType?: 'waveform' | 'bars' | 'circle';
    /**
     * 是否自动播放
     * 注意：现代浏览器可能会阻止自动播放
     */
    autoplay?: boolean;
    /** 是否循环播放 */
    loop?: boolean;
    /** 播放速率 (0.5-2.0) */
    playbackRate?: number;
    /** 初始音量 (0-1) */
    volume?: number;
    /** 指定音频上下文采样率 (Hz) */
    sampleRate?: number;
    /** 播放开始回调 */
    onPlay?: () => void;
    /** 播放暂停回调 */
    onPause?: () => void;
    /** 播放结束回调 */
    onEnded?: () => void;
    /** 播放进度回调 */
    onTimeUpdate?: (currentTime: number, duration: number) => void;
    /** 音量变化回调 */
    onVolumeChange?: (volume: number, muted: boolean) => void;
    /** 错误回调 */
    onError?: (error: Error) => void;
}
/**
 * 音频播放器接口
 */
export interface AudioPlayer {
    /** 加载音频 */
    load(source: string | Blob | File): Promise<void>;
    /** 播放 */
    play(): Promise<void>;
    /** 暂停 */
    pause(): void;
    /** 停止播放（重置到开始） */
    stop(): void;
    /** 跳转到指定时间（秒） */
    seek(time: number): void;
    /** 设置音量 (0-1) */
    setVolume(volume: number): void;
    /** 设置播放速率 (0.5-2.0) */
    setPlaybackRate(rate: number): void;
    /** 静音/取消静音 */
    toggleMute(): void;
    /** 获取当前播放状态 */
    getState(): PlayerState;
    /** 获取当前播放时间（秒） */
    getCurrentTime(): number;
    /** 获取音频总时长（秒） */
    getDuration(): number;
    /** 获取音量 (0-1) */
    getVolume(): number;
    /** 是否静音 */
    isMuted(): boolean;
    /** 获取播放进度 (0-1) */
    getProgress(): number;
    /** 是否正在播放 */
    isPlaying(): boolean;
    /** 销毁播放器，释放资源 */
    destroy(): void;
}
/**
 * 创建音频播放器
 * @param options 播放器选项
 * @returns 音频播放器对象
 * @example
 * ```typescript
 * // 创建背景播放器（无UI）
 * const backgroundPlayer = createAudioPlayer();
 * await backgroundPlayer.load('https://example.com/audio.mp3');
 * await backgroundPlayer.play();
 *
 * // 创建带UI的播放器
 * const uiPlayer = createAudioPlayer({
 *   renderUI: true,
 *   container: '#player-container',
 *   theme: 'dark',
 *   showVisualization: true,
 *   visualizationType: 'bars'
 * });
 *
 * await uiPlayer.load(audioBlob);
 * uiPlayer.setVolume(0.8);
 * await uiPlayer.play();
 * ```
 */
export declare function createAudioPlayer(options?: AudioPlayerOptions): AudioPlayer;
/**
 * 简易播放音频Blob的方法（仅背景播放）
 * @param blob 音频Blob对象
 * @param options 播放选项
 * @returns 音频播放器对象
 */
export declare function playAudio(blob: Blob | string, options?: Partial<Pick<AudioPlayerOptions, 'autoplay' | 'loop' | 'volume' | 'onEnded'>>): Promise<AudioPlayer>;
export {};