import * as react from 'react'; /** * 音频帧数据类型 */ type AudioFramePayload = ArrayBuffer | Uint8Array | Int16Array; /** * 音频配置常量 */ declare const AUDIO_CONFIG: { /** 默认采样率 */ readonly DEFAULT_SAMPLE_RATE: 16000; /** 默认声道数 */ readonly DEFAULT_CHANNELS: 1; /** 默认位深度 */ readonly DEFAULT_BIT_DEPTH: 16; /** 推荐帧大小(40ms) */ readonly RECOMMENDED_FRAME_SIZE: 1280; /** 缓冲区大小 */ readonly BUFFER_SIZE: 512; /** 重采样阈值 */ readonly RESAMPLE_THRESHOLD: 0.1; }; /** * 音频处理性能优化配置 */ declare const AUDIO_PERFORMANCE: { /** 是否启用Web Workers */ readonly ENABLE_WORKER: boolean; /** 批处理大小 */ readonly BATCH_SIZE: 10; /** 缓存大小 */ readonly CACHE_SIZE: 100; /** 是否启用音频压缩 */ readonly ENABLE_COMPRESSION: true; }; /** * 校验音频规格是否符合 16kHz/单声道/16bit */ declare function validateAudioSpec(params: { sampleRate: number; channels?: number; bitDepth?: number; }): boolean; /** * 将任意采样率/声道的 Float32 PCM 重采样到 16k 单声道,并返回 Int16 PCM * - 优先通过 OfflineAudioContext 高质量重采样 * - 回退到简易线性插值重采样 */ declare function resampleTo16kMono(float32Input: Float32Array, inputSampleRate: number, channels?: number): Promise; /** * 音频处理缓存 */ declare class AudioCache { private cache; private maxSize; set(key: string, value: Float32Array): void; get(key: string): Float32Array | undefined; clear(): void; } /** * 音频批处理器 */ declare class AudioBatchProcessor { private batch; private batchSize; private callback; constructor(callback: (data: Float32Array[]) => void); add(data: Float32Array): void; flush(): void; } /** * 获取音频缓存实例 */ declare function getAudioCache(): AudioCache; /** * 创建音频批处理器 */ declare function createAudioBatchProcessor(callback: (data: Float32Array[]) => void): AudioBatchProcessor; /** * 将音频帧转换为Base64编码 * * @param buffer 音频帧数据 * @returns Base64编码的字符串 */ declare function toBase64(buffer: AudioFramePayload): string; /** * 将Int16数组转换为Float32数组 * * @param int16 Int16数组 * @returns Float32数组 */ declare function int16ToFloat32(int16: Int16Array): Float32Array; /** * 将字节数组转换为Int16数组 * * @param bytes 字节数组 * @returns Int16数组 */ declare function bytesToInt16(bytes: Uint8Array): Int16Array; /** * 将Float32数组转换为Int16数组 * * @param float32 Float32数组 * @returns Int16数组 */ declare function float32ToInt16(float32: ArrayLike): Int16Array; /** * 计算音频RMS(均方根)值(优化版本) * * @param samples 音频样本数组 * @returns RMS值 */ declare function calculateRMS(samples: ArrayLike): number; /** * 计算音频电平(0-100) * * @param samples 音频样本数组 * @returns 电平值(0-100) */ declare function calculateLevel(samples: ArrayLike): number; /** * 获取共享的AudioContext实例 * * @param sampleRate 采样率,默认16000 * @returns AudioContext实例 */ declare function getSharedAudioContext(sampleRate?: number): AudioContext; /** * 释放共享的AudioContext实例 */ declare function releaseSharedAudioContext(): void; /** * 获取AudioContext引用计数 */ declare function getAudioContextRefCount(): number; /** * 暂停共享的AudioContext */ declare function suspendSharedAudioContext(): Promise; /** * 恢复共享的AudioContext */ declare function resumeSharedAudioContext(): Promise; /** * 创建AudioWorkletNode处理器 * * @param audioCtx AudioContext实例 * @param onAudioData 音频数据回调函数 * @returns Promise */ declare function createAudioWorkletProcessor(audioCtx: AudioContext, onAudioData: (data: Float32Array) => void, workletBaseUrl?: string): Promise; /** * 创建ScriptProcessorNode处理器(兼容性回退) * * @param audioCtx AudioContext实例 * @param onAudioData 音频数据回调函数 * @returns ScriptProcessorNode */ declare function createScriptProcessor(audioCtx: AudioContext, onAudioData: (data: Float32Array) => void): ScriptProcessorNode; /** * 错误严重程度枚举 */ declare enum ErrorSeverity { LOW = "low", MEDIUM = "medium", HIGH = "high", CRITICAL = "critical" } /** * 错误类型枚举 */ declare enum ErrorType { NETWORK = "network", AUTHENTICATION = "authentication", PARAMETER = "parameter", AUDIO = "audio", WEBSOCKET = "websocket", UNKNOWN = "unknown" } /** * 增强的错误信息接口 */ interface XfyunError { code: number; message: string; severity: ErrorSeverity; type: ErrorType; retryable: boolean; timestamp: number; context?: Record | undefined; } /** * 映射讯飞错误码为友好的错误消息 * * @param code 错误码 * @param message 原始错误消息 * @returns 友好的错误消息 */ declare function mapXfyunError(code?: number, message?: string): string; /** * 检查是否为可重试的错误 * * @param code 错误码 * @returns 是否可重试 */ declare function isRetryableError(code?: number): boolean; /** * 获取错误严重程度 * * @param code 错误码 * @returns 错误严重程度 */ declare function getErrorSeverity(code?: number): ErrorSeverity; /** * 获取错误类型 * * @param code 错误码 * @returns 错误类型 */ declare function getErrorType(code?: number): ErrorType; /** * 创建增强的错误对象 * * @param code 错误码 * @param message 原始错误消息 * @param context 错误上下文 * @returns 增强的错误对象 */ declare function createXfyunError(code: number, message?: string, context?: Record): XfyunError; /** * 错误恢复策略 */ interface ErrorRecoveryStrategy { maxRetries: number; retryDelay: number; backoffMultiplier: number; maxRetryDelay: number; } /** * 默认错误恢复策略 */ declare const DEFAULT_RECOVERY_STRATEGY: ErrorRecoveryStrategy; /** * 计算重试延迟 * * @param attempt 当前尝试次数 * @param strategy 恢复策略 * @returns 延迟时间(毫秒) */ declare function calculateRetryDelay(attempt: number, strategy?: ErrorRecoveryStrategy): number; /** * 生成可读的错误日志上下文 */ declare function formatErrorContext(ctx?: Record): string; /** * 讯飞客户端基础配置接口 */ interface BaseXfyunClientOptions { /** 后端服务基础地址 */ serverBase?: string; /** 获取认证码的方法 */ getAuthCode?: () => string; /** 错误回调 */ onError?: (message: string, sid?: string) => void; /** 统一日志回调(可用于上报) */ onLog?: (level: 'info' | 'warn' | 'error', payload: Record) => void; } /** * 讯飞客户端基础类 * * 提供所有讯飞客户端的通用功能: * - 统一的错误处理 * - 统一的签名获取 * - 统一的状态管理 * * @template T 具体的客户端选项类型 */ declare abstract class BaseXfyunClient { protected readonly serverBase: string; protected readonly options: T; error: string | null; protected lastContext: Record | null; protected sessionId: string; constructor(options?: T); /** * 获取签名信息 * * @param type 签名类型 (iat|tts|rtasr|dts/create|dts/query) * @returns 签名响应数据 * @throws Error 获取签名失败时抛出异常 */ protected getSignature(type: string): Promise; /** * 统一错误处理 * * @param message 错误消息 * @param sid 会话ID(可选) */ protected handleError(message: string, sid?: string, context?: Record): void; /** * 处理讯飞API错误码 * * @param code 错误码 * @param message 原始错误消息 * @param sid 会话ID(可选) * @returns 处理后的错误消息 */ protected processXfyunError(code?: number, message?: string, sid?: string, extra?: Record): string; /** * 重置客户端状态 */ reset(): void; /** * 关闭客户端连接 * * 子类可以重写此方法来实现具体的关闭逻辑 */ close(): void; } /** * 基础Hook状态类型 */ type BaseHookStatus = "idle" | "connecting" | "open" | "closing" | "closed" | "error"; /** * 基础Hook选项 */ interface BaseHookOptions extends BaseXfyunClientOptions { /** 是否自动清理资源 */ autoCleanup?: boolean; } /** * 基础讯飞Hook * * 提供所有讯飞Hook的通用功能: * - 统一的状态管理 * - 统一的错误处理 * - 统一的资源清理 * * @template T 具体的客户端类型 * @template O 具体的选项类型 */ declare function useBaseXfyun, O extends BaseHookOptions = BaseHookOptions>(createClient: (options?: O) => T, options?: O): { status: BaseHookStatus; error: string | null; reset: () => void; close: () => void; ensureClient: () => T; clientRef: react.RefObject; }; /** * IAT业务参数配置 */ interface IatBusiness { /** 语种,默认为 zh_cn */ language?: string; /** 业务领域,固定为 iat */ domain?: string; /** 方言/口音(中文场景),默认 mandarin */ accent?: string; /** 静音断句阈值(毫秒),默认 2000 */ vad_eos?: number; /** 动态修正开关,默认 "wpgs" */ dwa?: string; /** 是否返回标点(1/0),默认 1 */ ptt?: 0 | 1; /** 返回字级别信息 */ vinfo?: 0 | 1; /** 返回结果格式(plain/json 等) */ rst?: string; /** 返回结果语言 */ rlang?: string; /** 产品类型 */ pd?: string; /** 产品引擎 */ pd_engine?: string; /** 候选结果数量 */ nbest?: number; /** 候选词数量 */ wbest?: number; } /** * IAT客户端选项 */ interface IatClientOptions extends BaseXfyunClientOptions { /** IAT业务参数配置 */ business?: IatBusiness; /** 识别增量文本回调 */ onResult?: (text: string, isFinal: boolean) => void; /** 原始消息回调(调试用) */ onMessage?: (msg: any) => void; /** 连接打开回调(包含 sid) */ onOpen?: (sid?: string) => void; /** 连接关闭回调 */ onClose?: (code?: number, reason?: string) => void; /** 心跳间隔(毫秒),0表示禁用 */ heartbeatMs?: number; /** 输入采样率(用于自动重采样判断) */ inputSampleRate?: number; /** 输入声道数(默认1) */ inputChannels?: number; /** 是否自动重采样到16k单声道(默认false) */ autoResample?: boolean; /** 最大重试次数(默认3) */ maxRetries?: number; /** 重连退避策略(可选,不传使用默认) */ retryStrategy?: ErrorRecoveryStrategy; /** 是否启用语言/方言与URL匹配校验(默认true) */ enableLangCheck?: boolean; } /** * 科大讯飞语音听写(IAT)客户端 * * 支持实时语音转文字功能,特点: * - WebSocket实时连接 * - 支持动态修正 * - 支持增量识别结果 * - 自动断句处理 * * 使用示例: * ```typescript * const client = new IatClient({ * serverBase: 'http://localhost:8083', * business: { language: 'zh_cn', vad_eos: 2000 }, * onResult: (text, isFinal) => console.log(text, isFinal) * }); * await client.open(); * client.sendFrame(audioData, false); * ``` */ declare class IatClient extends BaseXfyunClient { private ws; status: "idle" | "connecting" | "open" | "closing" | "closed"; private resultTemp; private resultMap; private maxResultWindow; private lastSnSeen; private appId; private sid; private heartbeatTimer; private visibilityHandler?; private pausedByPageHidden; private retryCount; constructor(options?: IatClientOptions); /** * 建立IAT WebSocket连接并发送首帧 * * 首帧内容: * - common.app_id: 来自后端签名返回 * - business: 语言/断句/标点/动态修正等配置 * - data: { status:0, format:'audio/L16;rate=16000', encoding:'raw' } * * @throws Error 连接失败时抛出异常 */ open(): Promise; /** * 处理识别结果 * * @param result 识别结果数据 */ private processRecognitionResult; /** * 调试/测试专用:注入一条识别结果并走内部重建逻辑 * 不建立网络连接即可验证动态修正与乱序容错 */ debugProcessRecognitionResult(result: any): void; /** * 发送音频帧 * * @param frame 音频帧数据 * @param isLast 是否为最后一帧 */ sendFrame(frame: AudioFramePayload, isLast: boolean): void; /** * 重置客户端状态 */ reset(): void; /** * 关闭WebSocket连接 */ close(): void; } /** * IAT Hook选项 */ interface IatOptions extends BaseXfyunClientOptions { /** IAT业务参数配置 */ business?: IatBusiness; /** 识别增量文本回调 */ onResult?: (text: string, isFinal: boolean) => void; /** 原始消息回调(调试用) */ onMessage?: (msg: any) => void; /** 连接打开回调(包含 sid) */ onOpen?: (sid?: string) => void; /** 连接关闭回调 */ onClose?: (code?: number, reason?: string) => void; /** 心跳间隔(毫秒),0表示禁用 */ heartbeatMs?: number; /** 最大重试次数(默认3) */ maxRetries?: number; /** 重连退避策略(可选,不传使用默认) */ retryStrategy?: ErrorRecoveryStrategy; } /** * 科大讯飞语音听写(IAT) Hook * * 支持实时语音转文字功能,特点: * - WebSocket实时连接 * - 支持动态修正 * - 支持增量识别结果 * - 自动断句处理 * * 使用示例: * ```typescript * const { status, error, open, sendFrame, close, reset } = useIat({ * serverBase: 'http://localhost:8083', * business: { language: 'zh_cn', vad_eos: 2000 }, * onResult: (text, isFinal) => console.log(text, isFinal) * }); * * await open(); * sendFrame(audioData, false); * ``` */ declare function useIat(options?: IatOptions): { status: BaseHookStatus; error: string | null; open: () => Promise; sendFrame: (frame: AudioFramePayload, isLast: boolean) => void; close: () => void; reset: () => void; }; /** * TTS业务参数配置 */ interface TtsBusiness { /** 音频编码,默认 "raw" */ aue?: string; /** 发音人,默认 "x4_yezi" */ vcn?: string; /** 语速(0-100),默认 50 */ speed?: number; /** 音量(0-100),默认 50 */ volume?: number; /** 音调(0-100),默认 50 */ pitch?: number; /** 数字发音风格(按官方枚举/数值) */ rdn?: number | string; /** 文本编码(默认 utf8,可覆盖) */ tte?: string; /** 音频封装格式(默认 audio/L16;rate=16000,可覆盖) */ auf?: string; /** 音库领域(如通用/教育等) */ ent?: string; } /** * TTS客户端选项 */ interface TtsClientOptions extends BaseXfyunClientOptions { /** TTS业务参数配置 */ business?: TtsBusiness; /** 音量电平回调(0-100) */ onLevel?: (level: number) => void; /** MP3音频块回调 */ onMp3Chunk?: (bytes: Uint8Array) => void; /** 合成完成回调 */ onComplete?: () => void; /** 是否由SDK内置自动播放(PCM走WebAudio,MP3走MSE),默认 true */ autoplay?: boolean; /** MP3 播放策略:"mse" | "none",默认 "mse"(仅当 autoplay=true 且 aue=mp3 生效) */ mp3Playback?: "mse" | "none"; /** 自动播放被策略阻止时,是否绑定一次性手势触发以恢复播放(默认 true) */ autoplayGesture?: boolean; } /** * 科大讯飞语音合成(TTS)客户端 * * 支持文字转语音功能,特点: * - WebSocket实时连接 * - 支持多种音频格式(PCM/MP3) * - 实时音频播放 * - 音量电平监控 * * 使用示例: * ```typescript * const client = new TtsClient({ * serverBase: 'http://localhost:8083', * business: { aue: 'raw', vcn: 'x4_yezi', speed: 50 }, * onLevel: (level) => console.log('音量:', level) * }); * await client.speak('你好世界'); * ``` */ declare class TtsClient extends BaseXfyunClient { private ws; status: "idle" | "connecting" | "open" | "playing" | "closed" | "error"; private audioCtx; private pcmQueue; private pcmProcessing; private pcmPaused; private pcmCurrentSource; private pcmScheduleAheadSec; private pcmCursorTime; private pcmPlaybackComplete; private mse; private mseAudioEl; private mseSourceBuffer; private mseQueue; private mseAppending; constructor(options?: TtsClientOptions); /** * 发起TTS合成并实时播放 * * @param text 待合成的文本 * @throws Error 合成失败时抛出异常 */ speak(text: string): Promise; /** * 处理音频数据 * * @param audio Base64编码的音频数据 */ private processAudioData; /** * 停止TTS合成并关闭客户端 */ close(): void; /** * 强制重新创建客户端(用于参数更新) */ forceRecreate(): void; /** * 重置客户端状态 */ reset(): void; /** 音频数据回调,由上层设置 */ onAudio?: (pcmBytes: Uint8Array) => void; private enqueuePcm; private playPcmQueue; /** * 调度播放完成检查(延迟检查确保音频播放完成) */ private schedulePlaybackCompleteCheck; /** * 检查播放是否完成并触发onComplete回调 */ private checkPlaybackComplete; private ensureMse; private enqueueMp3; private flushMseQueue; private teardownPlayback; /** * 主动请求触发一次自动播放(适用于外部在用户手势中调用) */ requestAutoplay(): void; /** 暂停PCM播放(仅影响内置PCM播放) */ pause(): void; /** 恢复PCM播放 */ resume(): void; /** 停止播放并清空队列 */ stop(): void; } /** * TTS Hook选项 */ interface TtsOptions extends BaseXfyunClientOptions { /** TTS业务参数配置 */ business?: TtsBusiness; /** 音量电平回调(0-100) */ onLevel?: (level: number) => void; /** MP3音频块回调 */ onMp3Chunk?: (bytes: Uint8Array) => void; /** 合成完成回调 */ onComplete?: () => void; } /** * 科大讯飞语音合成(TTS) Hook * * 支持文字转语音功能,特点: * - WebSocket实时连接 * - 支持多种音频格式(PCM/MP3) * - 实时音频播放 * - 音量电平监控 * * 使用示例: * ```typescript * const { status, error, speak, stop } = useTts({ * serverBase: 'http://localhost:8083', * business: { aue: 'raw', vcn: 'x4_yezi', speed: 50 }, * onLevel: (level) => console.log('音量:', level) * }); * * await speak('你好世界'); * ``` */ declare function useTts(options?: TtsOptions): { status: BaseHookStatus; error: string | null; speak: (text: string) => Promise; stop: () => void; forceRecreate: () => void; }; /** * RTASR业务参数配置 */ interface RtasrBusiness { /** 语种,默认为 zh_cn */ language?: string; /** 业务领域,固定为 rtasr */ domain?: string; /** 方言/口音(中文场景),默认 mandarin */ accent?: string; /** 静音断句阈值(毫秒),默认 2000 */ vad_eos?: number; /** 动态修正开关,默认 "wpgs" */ dwa?: string; /** 是否返回标点(1/0),默认 1 */ ptt?: 0 | 1; /** 产品类型,默认 "edu" */ pd?: string; /** 产品引擎 */ pd_engine?: string; /** 结果语言 */ rlang?: string; /** 候选结果数量 */ nbest?: number; /** 候选词数量 */ wbest?: number; } /** * RTASR客户端选项 */ interface RtasrClientOptions extends BaseXfyunClientOptions { /** RTASR业务参数配置 */ business?: RtasrBusiness; /** 识别增量文本回调 */ onResult?: (text: string, isFinal: boolean) => void; /** 原始消息回调(调试用) */ onMessage?: (msg: any) => void; /** 连接打开回调(包含 sid) */ onOpen?: (sid?: string) => void; /** 连接关闭回调 */ onClose?: (code?: number, reason?: string) => void; /** 心跳间隔(毫秒),0表示禁用 */ heartbeatMs?: number; /** 最大重试次数(默认3) */ maxRetries?: number; /** 重连退避策略(可选,不传使用默认) */ retryStrategy?: ErrorRecoveryStrategy; /** 输入采样率(用于自动重采样判断) */ inputSampleRate?: number; /** 输入声道数(默认1) */ inputChannels?: number; /** 是否自动重采样到16k单声道(默认false) */ autoResample?: boolean; } /** * 科大讯飞实时语音转写(RTASR)客户端 * * 支持长时间语音转文字功能,特点: * - WebSocket实时连接 * - 支持连续音频流识别 * - 自动重连机制 * - 支持动态修正 * * 使用示例: * ```typescript * const client = new RtasrClient({ * serverBase: 'http://localhost:8083', * business: { language: 'zh_cn', domain: 'rtasr' }, * onResult: (text, isFinal) => console.log(text, isFinal) * }); * await client.open(); * client.sendFrame(audioData, false); * ``` */ declare class RtasrClient extends BaseXfyunClient { private ws; status: "idle" | "connecting" | "open" | "closing" | "closed"; private resultTemp; private resultArray; private appId; private sid; private started; private pendingFrames; private lastMessageTime; private lastAudioTime; private messageCheckTimer; private audioTimeoutTimer; private heartbeatTimer; private retryCount; private ended; private sentEnd; private visibilityHandler?; private pausedByPageHidden; constructor(options?: RtasrClientOptions); /** * 清理现有连接,确保完全关闭 */ private cleanupExistingConnection; /** * 建立RTASR WebSocket连接并发送首帧 * * @throws Error 连接失败时抛出异常 */ open(): Promise; /** * 处理识别结果 * * @param msg 消息数据 */ private processRecognitionResult; /** * 发送音频帧 * * @param frame 音频帧数据 * @param isLast 是否为最后一帧 */ sendFrame(frame: ArrayBuffer, isLast: boolean): void; /** * 冲刷等待队列 */ private flushPendingFrames; /** * 重置客户端状态 */ reset(): void; /** * 关闭WebSocket连接 */ close(): void; } /** * RTASR Hook选项 */ interface RtasrOptions extends BaseXfyunClientOptions { /** RTASR业务参数配置 */ business?: RtasrBusiness; /** 识别增量文本回调 */ onResult?: (text: string, isFinal: boolean) => void; /** 原始消息回调(调试用) */ onMessage?: (msg: any) => void; /** 连接打开回调(包含 sid) */ onOpen?: (sid?: string) => void; /** 连接关闭回调 */ onClose?: (code?: number, reason?: string) => void; /** 心跳间隔(毫秒),0表示禁用 */ heartbeatMs?: number; /** 最大重试次数(默认3) */ maxRetries?: number; /** 重连退避策略(可选,不传使用默认) */ retryStrategy?: ErrorRecoveryStrategy; } /** * 科大讯飞实时语音转写(RTASR) Hook * * 支持长时间语音转文字功能,特点: * - WebSocket实时连接 * - 支持连续音频流识别 * - 自动重连机制 * - 支持动态修正 * * 使用示例: * ```typescript * const { status, error, open, sendFrame, close, reset } = useRtasr({ * serverBase: 'http://localhost:8083', * business: { language: 'zh_cn', domain: 'rtasr' }, * onResult: (text, isFinal) => console.log(text, isFinal) * }); * * await open(); * sendFrame(audioData, false); * ``` */ declare function useRtasr(options?: RtasrOptions): { status: BaseHookStatus; error: string | null; open: () => Promise; sendFrame: (frame: ArrayBuffer, isLast: boolean) => void; close: () => void; reset: () => void; client: RtasrClient | null; }; /** * DTS发音人配置 */ declare const DTS_VOICES: { readonly x4_yeting: { readonly name: "希涵"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "游戏影视解说"; }; readonly x4_guanyijie: { readonly name: "关山-专题"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "专题片纪录片"; }; readonly x4_pengfei: { readonly name: "小鹏"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "新闻播报"; }; readonly x4_qianxue: { readonly name: "千雪"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "阅读听书"; }; readonly x4_lingbosong: { readonly name: "聆伯松-老年男声"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "阅读听书"; }; readonly x4_xiuying: { readonly name: "秀英-老年女声"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "阅读听书"; }; readonly x4_mingge: { readonly name: "明哥"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "阅读听书"; }; readonly x4_doudou: { readonly name: "豆豆"; readonly gender: "男"; readonly language: "中文/男童"; readonly style: "阅读听书"; }; readonly x4_lingxiaoshan_profnews: { readonly name: "聆小珊"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "新闻播报"; }; readonly x4_xiaoguo: { readonly name: "小果"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "新闻播报"; }; readonly x4_xiaozhong: { readonly name: "小忠"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "新闻播报"; }; readonly x4_yezi: { readonly name: "小露"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "通用场景"; }; readonly x4_chaoge: { readonly name: "超哥"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "新闻播报"; }; readonly x4_feidie: { readonly name: "飞碟哥"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "游戏影视解说"; }; readonly x4_lingfeihao_upbeatads: { readonly name: "聆飞皓-广告"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "直播广告"; }; readonly x4_wangqianqian: { readonly name: "嘉欣"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "直播广告"; }; readonly x4_lingxiaozhen_eclives: { readonly name: "聆小臻"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "直播广告"; }; readonly x4_EnUs_Catherine_profnews: { readonly name: "Catherine"; readonly gender: "女"; readonly language: "英语"; readonly style: "专业新闻"; }; readonly x5_lingfeizhe: { readonly name: "灵飞哲"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "通用场景"; }; readonly x5_lingxiaoxue: { readonly name: "灵小雪"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "通用场景"; }; readonly x4_lingfeihong_document: { readonly name: "聆飞红-文档"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "文档阅读"; }; readonly x4_lingfeichen_assist: { readonly name: "聆飞晨-助手"; readonly gender: "男"; readonly language: "中文/普通话"; readonly style: "智能助手"; }; readonly x4_lingxiaoqi_assist: { readonly name: "聆小七-助手"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "智能助手"; }; readonly x4_lingfeihong_document_n: { readonly name: "聆飞红-文档N"; readonly gender: "女"; readonly language: "中文/普通话"; readonly style: "文档阅读"; }; }; /** * DTS业务参数配置 */ interface DtsBusiness { /** 音频编码,默认 "raw" */ aue?: string; /** 发音人,默认 "x4_mingge" */ vcn?: 'x4_yeting' | 'x4_guanyijie' | 'x4_pengfei' | 'x4_qianxue' | 'x4_lingbosong' | 'x4_xiuying' | 'x4_mingge' | 'x4_doudou' | 'x4_lingxiaoshan_profnews' | 'x4_xiaoguo' | 'x4_xiaozhong' | 'x4_yezi' | 'x4_chaoge' | 'x4_feidie' | 'x4_lingfeihao_upbeatads' | 'x4_wangqianqian' | 'x4_lingxiaozhen_eclives' | 'x4_EnUs_Catherine_profnews' | 'x5_lingfeizhe' | 'x5_lingxiaoxue' | 'x4_lingfeihong_document' | 'x4_lingfeichen_assist' | 'x4_lingxiaoqi_assist' | 'x4_lingfeihong_document_n'; /** 语速(0-100),默认 50 */ speed?: number; /** 音量(0-100),默认 50 */ volume?: number; /** 音调(0-100),默认 50 */ pitch?: number; /** 背景音(0-100),默认 0 */ bgs?: number; /** 文本处理类型,默认 0 */ ttp?: number; } /** * DTS客户端选项 */ interface DtsClientOptions extends BaseXfyunClientOptions { /** 后端服务基础地址(必需) */ serverBase: string; /** 获取认证码的方法(必需) */ getAuthCode: () => string; /** DTS业务参数配置 */ business?: DtsBusiness; /** 任务创建回调 */ onTaskCreated?: (taskId: string) => void; /** 任务完成回调 */ onTaskCompleted?: (result: any) => void; /** 任务轮询超时时间(毫秒,默认 10 分钟) */ pollTimeoutMs?: number; /** 任务轮询最大次数(默认 300 次) */ maxPollTimes?: number; } /** * 科大讯飞长文本语音合成(DTS)客户端 * * 支持长文本语音合成功能,特点: * - HTTP API调用 * - 支持10万字左右的长文本 * - 异步任务处理 * - 任务状态查询 * * 使用示例: * ```typescript * const client = new DtsClient({ * serverBase: 'http://localhost:8083', * business: { aue: 'raw', vcn: 'x4_mingge', speed: 50 }, * onTaskCreated: (taskId) => console.log('任务ID:', taskId) * }); * const taskId = await client.createTask('很长的文本...'); * const result = await client.waitForTask(taskId); * ``` */ declare class DtsClient extends BaseXfyunClient { constructor(options?: DtsClientOptions); /** * 创建DTS任务 * * @param text 待合成的文本 * @param business 业务参数(可选,会覆盖默认配置) * @returns 任务ID * @throws Error 创建失败时抛出异常 */ createTask(text: string, business?: DtsBusiness): Promise; /** * 查询DTS任务状态 * * @param taskId 任务ID * @returns 任务状态数据 * @throws Error 查询失败时抛出异常 */ queryTask(taskId: string): Promise; /** * 轮询查询任务直到完成 * * @param taskId 任务ID * @param intervalMs 轮询间隔(毫秒),默认2000 * @returns 任务完成后的结果数据 * @throws Error 任务失败或查询异常时抛出异常 */ waitForTask(taskId: string, intervalMs?: number): Promise; /** * 下载任务结果产物 * - 支持片段数组或单一直链 */ downloadResult(taskId: string, format?: string): Promise; /** * 关闭DTS客户端 * * DTS客户端使用HTTP API,无需特殊关闭逻辑 */ close(): void; } /** * DTS Hook选项 */ interface DtsOptions extends DtsClientOptions { } /** * DTS Hook状态类型 */ type DtsStatus = "idle" | "creating" | "querying" | "completed" | "error"; /** * 科大讯飞长文本语音合成(DTS) Hook * * 支持长文本语音合成功能,特点: * - HTTP API调用 * - 支持10万字左右的长文本 * - 异步任务处理 * - 任务状态查询 * * 使用示例: * ```typescript * const { status, error, taskId, result, createTask, waitForTask } = useDts({ * serverBase: 'http://localhost:8083', * business: { aue: 'raw', vcn: 'x4_mingge', speed: 50 }, * onTaskCreated: (taskId) => console.log('任务ID:', taskId) * }); * * const taskId = await createTask('很长的文本...'); * const result = await waitForTask(taskId); * ``` */ declare function useDts(options?: DtsOptions): { status: DtsStatus; error: string | null; taskId: string | null; result: any; createTask: (text: string, business?: DtsBusiness) => Promise; queryTask: (taskId: string) => Promise; waitForTask: (taskId: string, intervalMs?: number) => Promise; reset: () => void; }; /** * useIatRecorder 选项 * - client: IatClient 实例(需外部创建与配置) * - vadThreshold: 本地音量阈值(0-100),用于粗略静音门限显示/控制 * - frameMs: 发送给服务端的帧长(毫秒),默认 40ms(约 640 samples @16kHz) */ interface UseIatRecorderOptions { client: IatClient; vadThreshold?: number; frameMs?: number; } /** * 基于浏览器麦克风的 IAT 录音 Hook。 * - 内部通过 WebAudio 的 ScriptProcessor 聚合帧,并以 16bit PCM 发送给 IatClient * - 提供 recording/level 状态与 start/stop 控制方法 */ declare function useIatRecorder(options: UseIatRecorderOptions): { recording: boolean; level: number; start: () => Promise; stop: () => void; }; /** * useRtasrStream 选项 * - client: RtasrClient 实例 * - frameMs: 帧长(毫秒),默认 40ms */ interface UseRtasrStreamOptions { client: RtasrClient; frameMs?: number; } /** * 使用浏览器麦克风流向 RTASR 发送音频数据的 Hook。 * - 内部以 ScriptProcessor 聚合帧并转换为 Int16 PCM,通过 WebSocket 发送 * - 提供 streaming 状态与 start/stop 控制 */ declare function useRtasrStream(options: UseRtasrStreamOptions): { streaming: boolean; start: () => Promise; stop: () => void; }; /** * useTtsPlayer 选项 * - client: TtsClient 实例 */ interface UseTtsPlayerOptions { client: TtsClient; } /** * TTS 播放控制 Hook。 * - 封装 speak/pause/resume/stop 控制 * - 暴露播放状态与音量电平 level(0-100) */ declare function useTtsPlayer({ client }: UseTtsPlayerOptions): { status: "closed" | "error" | "idle" | "connecting" | "open" | "playing"; level: number; speak: (text: string) => Promise; pause: () => void; resume: () => void; stop: () => void; requestAutoplay: () => void; }; type StreamingTtsStatus = "idle" | "connecting" | "open" | "synthesizing" | "playing" | "paused" | "closed" | "error"; /** * StreamingTts 客户端配置 */ interface StreamingTtsOptions extends BaseXfyunClientOptions { /** * 业务参数(发送到服务端的合成参数) */ business: { /** 音频编码格式,例如 'raw'(PCM)或 'mp3' */ aue?: string; /** 发音人,示例:'x4_yezi' */ vcn?: string; /** 语速,0-100,默认 50 */ speed?: number; /** 音量,0-100,默认 50(服务端合成音量) */ volume?: number; /** 音调,0-100,默认 50 */ pitch?: number; /** 文本编码,通常为 'utf8' */ tte?: string; /** 采样率及格式,示例:'audio/L16;rate=16000' */ auf?: string; /** 随机数(部分场景使用) */ rdn?: number; /** 引擎类型(部分场景使用) */ ent?: string; }; /** * 文本接收回调 * @param text 已追加的原始文本片段 */ onTextReceived?: (text: string) => void; /** * 音频接收回调 * @param audio 原始音频字节(PCM: 16bit 小端,MP3: 二进制分片) */ onAudioReceived?: (audio: Uint8Array) => void; /** * 播放状态回调 * @param isPlaying 是否处于播放中 */ onPlaying?: (isPlaying: boolean) => void; /** 合成与播放整体完成回调(连接关闭且缓冲播放完毕后触发) */ onComplete?: () => void; /** * 错误回调 * @param error 具有人类可读信息的错误字符串 */ onError?: (error: string) => void; /** * 日志回调 * @param level 日志级别:'info' | 'warn' | 'error' * @param payload 任意结构化日志载荷 */ onLog?: (level: 'info' | 'warn' | 'error', payload: any) => void; /** WebSocket 连接建立回调(readyState=OPEN) */ onOpen?: () => void; /** WebSocket 连接关闭回调(包括正常关闭与异常关闭) */ onClose?: () => void; /** * 客户端状态变化回调 * @param status 当前状态 */ onStatusChange?: (status: StreamingTtsStatus) => void; /** 是否自动播放(MP3/MSE 需在可用时尝试自动播放) */ autoplay?: boolean; /** MP3 播放方式:'mse' 优先 MediaSource,'blob' 走 URL.createObjectURL */ mp3Playback?: 'mse' | 'blob'; /** 保活间隔毫秒,默认 30000 */ keepAliveIntervalMs?: number; /** 空闲时(无文本/未结束)也发送保活,默认 false */ keepAliveWhenIdle?: boolean; /** PCM 播放前瞻秒数,默认 0.08 */ audioScheduleAheadSec?: number; /** 在最后一次 appendText 之后,若无新输入则在该毫秒后自动 endText */ autoEndAfterMs?: number; /** 最小日志级别过滤,默认 'info' */ logLevel?: 'info' | 'warn' | 'error'; /** * 启动重试策略 * - maxRetries: 最大重试次数(默认 0) * - initialDelayMs: 初始延迟(默认 500) * - factor: 退避乘数(默认 1.8) */ retry?: { maxRetries?: number; initialDelayMs?: number; factor?: number; }; } /** * 流式语音合成客户端 * * - 支持流式文本输入与实时音频播放(PCM/MP3) * - 单连接复用,提供暂停、恢复、停止控制 * - 事件与日志回调丰富,便于生产观测 */ declare class StreamingTtsClient extends BaseXfyunClient { private ws; status: StreamingTtsStatus; private textBuffer; private textEnded; sessionId: string; private appId; private keepAliveInterval; private closing; private inactivityTimer; private audioCtx; private pcmQueue; private pcmProcessing; private pcmPaused; private pcmCurrentSource; private pcmScheduleAheadSec; private pcmCursorTime; private pcmPlaybackComplete; private gainNode; private mse; private mseAudioEl; private mseSourceBuffer; private mseQueue; private mseAppending; private blobAudioEl; private blobChunks; constructor(options: StreamingTtsOptions); /** * 写日志,遵循 logLevel 最小级别过滤 * @param level 日志级别 * @param payload 结构化日志内容 */ private log; /** * 统一更新状态并派发 onStatusChange 回调 * @param next 下一个状态 */ private updateStatus; /** * UTF-8 安全的 Base64 编码 * @param text 原始字符串 * @returns Base64 字符串 */ private encodeBase64Utf8; /** * 设置本地播放音量(0.0 - 1.0) * @param volume 音量值 */ setLocalVolume(volume: number): void; /** * 重置自动结束计时器(用于 autoEndAfterMs) */ private resetInactivityTimer; /** * 开始流式合成,建立 WebSocket 连接并预热播放资源 * @returns Promise,在连接建立或失败后决议 */ start(): Promise; /** * 建立 WebSocket 并绑定事件 * @returns Promise,在 onopen 时 resolve,若连接未能打开则 reject */ private openWebSocket; /** * 追加文本片段(status=1) * @param text 文本片段 */ appendText(text: string): void; /** * 结束文本输入(status=2) */ endText(): void; /** * 暂停播放(仅在 playing 状态有效) */ pause(): void; /** * 恢复播放(仅在 paused 状态有效) */ resume(): void; /** * 停止合成与播放,复位到 idle */ stop(): void; /** * 关闭连接并释放音频相关资源 */ close(): void; /** 获取当前状态 */ getStatus(): StreamingTtsStatus; /** 是否处于连接态(open/synthesizing/playing/paused) */ isConnected(): boolean; /** 是否处于播放态 */ isPlaying(): boolean; /** * 启动连接保活机制 */ private startKeepAlive; /** 停止连接保活 */ private stopKeepAlive; /** * 发送保活数据(status=0) */ private sendKeepAliveData; /** * 构建业务参数(含默认值与可选项) * @returns 业务参数对象 */ private buildBusinessParams; /** 根据业务配置将音频交给对应处理器 */ private processAudioData; /** * 处理 PCM 音频(16-bit 小端)并推入播放队列 * @param audio Base64 字符串形式的音频数据 */ private processPcmAudio; /** * 处理 MP3 音频:优先 MSE,失败则 blob 兜底 * @param audio Base64 字符串形式的 MP3 数据分片 */ private processMp3Audio; /** * 批量调度 PCM 队列,提高连贯性并降低卡顿 */ private playPcmQueue; /** 触发播放完成检查的定时流程 */ private schedulePlaybackCompleteCheck; /** * 在连接 closed 且缓冲播放完毕时触发完成回调 */ private checkPlaybackComplete; /** * 初始化 MSE 播放器,不支持时自动降级为 blob */ private ensureMse; /** * 初始化 blob 播放器 */ private ensureBlobAudio; /** * 刷新 MSE 队列,采用一次性 updateend 监听避免重复注册 */ private flushMseQueue; /** * 统一处理讯飞错误 */ protected processXfyunError(code?: number, message?: string, _sid?: string, _extra?: Record): string; /** * 设置错误状态并分发错误回调与日志 * @param message 错误详情 */ protected handleError(message: string): void; /** * 重置内部状态与资源,供 start 前或 stop/close 使用 */ reset(): void; } /** * useStreamingTts 选项 * 继承底层客户端选项(屏蔽底层回调以便由 Hook 转发)。 */ interface UseStreamingTtsOptions extends Omit { onTextReceived?: (text: string) => void; onAudioReceived?: (audio: Uint8Array) => void; onPlaying?: (isPlaying: boolean) => void; onComplete?: () => void; onError?: (error: string) => void; onLog?: (level: 'info' | 'warn' | 'error', payload: any) => void; } /** * useStreamingTts 返回结果 */ interface UseStreamingTtsResult { status: 'idle' | 'connecting' | 'open' | 'synthesizing' | 'playing' | 'paused' | 'closed' | 'error'; isConnected: boolean; isPlaying: boolean; error: string | null; start: () => Promise; appendText: (text: string) => void; endText: () => void; pause: () => void; resume: () => void; stop: () => void; close: () => void; setLocalVolume: (v: number) => void; currentText: string; totalTextLength: number; } /** * React Hook:流式语音合成 * - 负责实例化 `StreamingTtsClient` 并通过回调事件驱动 React 状态 * - 暴露便捷控制方法与本地音量控制 * @param options Hook 配置,可覆盖客户端选项并接收 Hook 级别回调 * @returns Hook 返回的状态、控制方法与文本统计 */ declare function useStreamingTts(options?: UseStreamingTtsOptions): UseStreamingTtsResult; /** * RTASR连接池管理器 * * 提供连接复用和管理功能,支持多次调用 */ declare class RtasrConnectionPool { private static instance; private connections; private connectionOptions; private constructor(); /** * 获取单例实例 */ static getInstance(): RtasrConnectionPool; /** * 生成连接键 */ private generateKey; /** * 获取或创建连接 */ getConnection(options: RtasrClientOptions): Promise; /** * 关闭指定连接 */ closeConnection(options: RtasrClientOptions): void; /** * 关闭所有连接 */ closeAllConnections(): void; /** * 获取连接状态 */ getConnectionStatus(options: RtasrClientOptions): 'none' | 'connecting' | 'open' | 'closed' | 'closing' | 'idle'; /** * 获取连接数量 */ getConnectionCount(): number; /** * 清理无效连接 */ cleanupInvalidConnections(): void; } /** * 获取RTASR连接池实例 */ declare function getRtasrConnectionPool(): RtasrConnectionPool; export { AUDIO_CONFIG, AUDIO_PERFORMANCE, type AudioFramePayload, type BaseHookOptions, type BaseHookStatus, BaseXfyunClient, type BaseXfyunClientOptions, DEFAULT_RECOVERY_STRATEGY, DTS_VOICES, type DtsBusiness, DtsClient, type DtsClientOptions, type DtsOptions, type DtsStatus, type ErrorRecoveryStrategy, ErrorSeverity, ErrorType, type IatBusiness, IatClient, type IatClientOptions, type IatOptions, type RtasrBusiness, RtasrClient, type RtasrClientOptions, RtasrConnectionPool, type RtasrOptions, StreamingTtsClient, type StreamingTtsOptions, type StreamingTtsStatus, type TtsBusiness, TtsClient, type TtsClientOptions, type TtsOptions, type UseIatRecorderOptions, type UseRtasrStreamOptions, type UseStreamingTtsOptions, type UseStreamingTtsResult, type UseTtsPlayerOptions, type XfyunError, bytesToInt16, calculateLevel, calculateRMS, calculateRetryDelay, createAudioBatchProcessor, createAudioWorkletProcessor, createScriptProcessor, createXfyunError, float32ToInt16, formatErrorContext, getAudioCache, getAudioContextRefCount, getErrorSeverity, getErrorType, getRtasrConnectionPool, getSharedAudioContext, int16ToFloat32, isRetryableError, mapXfyunError, releaseSharedAudioContext, resampleTo16kMono, resumeSharedAudioContext, suspendSharedAudioContext, toBase64, useBaseXfyun, useDts, useIat, useIatRecorder, useRtasr, useRtasrStream, useStreamingTts, useTts, useTtsPlayer, validateAudioSpec };