@wq-hook/volcano-react 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -179,7 +179,7 @@ declare function useVolcanoTTS({ ttsConfig, audioParams, }: UseTTSParams): {
 };
 
 interface TTSMetric {
-    name: 'tts_request' | 'tts_latency' | 'tts_cache_hit' | 'tts_error';
+    name: 'tts_request' | 'tts_latency' | 'tts_cache_hit' | 'tts_error' | 'tts_synthesis_finished';
     labels: {
         voice?: string;
         speed?: number;
@@ -266,6 +266,266 @@ interface UseMessageTTSReturn {
 
 declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, exclusive, fallbackVoice, visualization, }: UseMessageTTSParams): UseMessageTTSReturn;
 
+/**
+ * 流式文本分段
+ */
+interface StreamTextSegment {
+    /** 分段索引 */
+    index: number;
+    /** 分段内容 */
+    content: string;
+    /** 分段长度 */
+    length: number;
+    /** 是否已发送 */
+    sent: boolean;
+}
+/**
+ * 流式文本分段器配置
+ */
+interface StreamingSplitOptions {
+    /** 单段最大字符数（默认150） */
+    maxLength?: number;
+    /** 单段最小字符数（默认10） */
+    minLength?: number;
+    /** 分段完成回调 */
+    onSegmentComplete?: (segment: StreamTextSegment) => void;
+    /** 所有分段完成回调 */
+    onAllComplete?: (segments: StreamTextSegment[]) => void;
+}
+/**
+ * useStreamTTS 参数
+ */
+interface UseStreamTTSParams {
+    /** TTS配置 */
+    ttsConfig: TTSConfig;
+    /** 音频参数 */
+    audioParams?: AudioParams;
+    /** 是否自动播放（默认：true） */
+    autoPlay?: boolean;
+    /** 指标收集器 */
+    metricsCollector?: MetricsCollector;
+    /** 播放开始回调 */
+    onPlayStart?: () => void;
+    /** 播放暂停回调 */
+    onPlayPause?: () => void;
+    /** 播放恢复回调 */
+    onPlayResume?: () => void;
+    /** 播放结束回调 */
+    onPlayEnd?: () => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+    /** 可视化配置 */
+    visualization?: VisualizationConfig;
+    /** 单段最大字符数（默认150） */
+    maxSegmentLength?: number;
+}
+/**
+ * useStreamTTS 返回值
+ */
+interface UseStreamTTSReturn {
+    /** WebSocket 是否已连接 */
+    isConnected: boolean;
+    /** 会话是否已启动 */
+    isSessionStarted: boolean;
+    /** 是否正在合成 */
+    isSynthesizing: boolean;
+    /** 是否正在播放 */
+    isPlaying: boolean;
+    /** 是否暂停 */
+    isPaused: boolean;
+    /** 错误信息 */
+    error: string | null;
+    /** 累计的流式文本（原始，未格式化） */
+    streamText: string;
+    /** 播放进度（0-100） */
+    progress: number;
+    /** 建立 WebSocket 连接 */
+    connect: () => Promise<void>;
+    /** 接收流式文本块 */
+    onMessage: (chunk: string) => void;
+    /** 结束流式输入 */
+    finishStream: () => Promise<void>;
+    /** 暂停播放 */
+    pause: () => void;
+    /** 恢复播放 */
+    resume: () => void;
+    /** 停止（断开连接，清理资源） */
+    stop: () => void;
+    /** 跳转到指定进度 */
+    seek: (percentage: number) => void;
+    /** 获取频率数据 */
+    getFrequencyData: () => Uint8Array;
+    /** 获取时域数据 */
+    getTimeDomainData: () => Uint8Array;
+    /** 可视化数据 */
+    visualizationData: VisualizationData;
+}
+/**
+ * Session 音频缓存条目
+ */
+interface SessionAudioCacheEntry {
+    /** 原始流式文本 */
+    streamText: string;
+    /** 音频数据 */
+    audioBuffers: ArrayBuffer[];
+    /** 缓存时间 */
+    timestamp: number;
+    /** 音色 */
+    voice: string;
+    /** 语速 */
+    speed: number;
+}
+
+/**
+ * 流式 TTS Hook
+ *
+ * 适用于 AI 对话实时语音合成场景：
+ * 1. connect() - 建立 WebSocket 连接
+ * 2. onMessage(chunk) - 接收 SSE 流式文本并实时分段合成
+ * 3. finishStream() - 结束流式输入，完成合成
+ *
+ * @example
+ * ```tsx
+ * const { connect, onMessage, finishStream, isPlaying } = useStreamTTS({
+ *   ttsConfig: { token, appid, resourceId },
+ *   audioParams: { speaker: "zh_female_tianmei" },
+ * });
+ *
+ * // SSE 事件处理
+ * useEffect(() => {
+ *   const eventSource = new EventSource("/api/chat");
+ *   eventSource.onopen = () => connect();
+ *   eventSource.onmessage = (e) => onMessage(e.data);
+ *   eventSource.onerror = async () => {
+ *     await finishStream();
+ *     eventSource.close();
+ *   };
+ * }, []);
+ * ```
+ */
+declare function useStreamTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, visualization, maxSegmentLength, }: UseStreamTTSParams): UseStreamTTSReturn;
+/**
+ * 获取 Session 音频缓存（供 useMessageTTS 使用）
+ * @param instanceId - 实例 ID
+ */
+declare function getSessionAudioCache(instanceId: string): SessionAudioCacheEntry | undefined;
+/**
+ * 清除 Session 音频缓存
+ * @param instanceId - 实例 ID
+ */
+declare function clearSessionAudioCache(instanceId: string): void;
+/**
+ * 根据文本查找匹配的 Session 缓存
+ * @param streamText - 流式文本
+ * @param voice - 音色
+ * @param speed - 语速
+ */
+declare function findSessionCacheByText(streamText: string, voice: string, speed: number): SessionAudioCacheEntry | undefined;
+
+/**
+ * 流式文本分段器
+ *
+ * 功能：
+ * - 接收流式文本输入（逐字符或逐 token）
+ * - 实时检测分段边界
+ * - 触发分段回调
+ *
+ * 分段规则：
+ * 1. 换行符 \n（立即分段，保持段落结构）
+ * 2. 字符数限制（智能拆分，优先在句子边界）
+ *
+ * @example
+ * ```ts
+ * const splitter = new StreamingTextSplitter({
+ *   maxLength: 150,
+ *   onSegmentComplete: (segment) => {
+ *     console.log('分段完成:', segment);
+ *   }
+ * });
+ *
+ * // 流式输入
+ * splitter.onChunk('Hello');
+ * splitter.onChunk(' ');
+ * splitter.onChunk('World');
+ * splitter.onChunk('\n'); // 触发分段
+ * splitter.complete();
+ * ```
+ */
+declare class StreamingTextSplitter {
+    /** 当前缓冲区 */
+    private buffer;
+    /** 分段索引计数器 */
+    private segmentIndex;
+    /** 已完成的分段列表 */
+    private segments;
+    /** 单段最大字符数 */
+    private readonly maxLength;
+    /** 单段最小字符数 */
+    private readonly minLength;
+    /** 分段完成回调 */
+    private readonly onSegmentComplete?;
+    /** 所有分段完成回调 */
+    private readonly onAllComplete?;
+    /** 是否已完成 */
+    private isCompleted;
+    constructor(options?: StreamingSplitOptions);
+    /**
+     * 接收流式文本块
+     * @param chunk - 文本块
+     */
+    onChunk(chunk: string): void;
+    /**
+     * 检测分段边界
+     * @param chunk - 最新接收的文本块
+     * @returns 是否应该分段
+     */
+    private detectBoundary;
+    /**
+     * 在句子边界强制拆分超长段落
+     */
+    private forceSplitAtSentenceBoundary;
+    /**
+     * 使用指定缓冲区内容刷新为分段
+     * @param bufferToFlush - 要分段的缓冲区内容
+     */
+    private flushSegmentWithBuffer;
+    /**
+     * 刷新当前缓冲区为分段
+     */
+    private flushSegment;
+    /**
+     * 拆分超长分段
+     * @param segment - 超长的分段
+     * @returns 拆分后的分段数组
+     */
+    private splitLongSegment;
+    /**
+     * 完成流式输入
+     * 处理剩余的缓冲区内容
+     */
+    complete(): void;
+    /**
+     * 重置分段器状态
+     */
+    reset(): void;
+    /**
+     * 获取当前缓冲区内容
+     */
+    getBuffer(): string;
+    /**
+     * 获取已分段的列表
+     */
+    getSegments(): StreamTextSegment[];
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        bufferLength: number;
+        segmentCount: number;
+        totalChars: number;
+    };
+}
+
 /**
  * TextSplitter 类型声明
  *
@@ -355,4 +615,4 @@ interface AudioProgressBarProps {
 
 declare const AudioProgressBar: React$1.FC<AudioProgressBarProps>;
 
-export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type TTSConfig, type TTSInstance, type TTSMessage, type TextSegment, type UseMessageTTSParams, type UseMessageTTSReturn, type UseTTSParams, type UseVTSOptions, type UseVTSReturn, type VisualizationConfig, type VisualizationData, splitTextByDelimiters, useMessageTTS, useVolcanoASR, useVolcanoTTS };
+export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type SessionAudioCacheEntry, type StreamTextSegment, type StreamingSplitOptions, StreamingTextSplitter, type TTSConfig, type TTSInstance, type TTSMessage, type TextSegment, type UseMessageTTSParams, type UseMessageTTSReturn, type UseStreamTTSParams, type UseStreamTTSReturn, type UseTTSParams, type UseVTSOptions, type UseVTSReturn, type VisualizationConfig, type VisualizationData, clearSessionAudioCache, findSessionCacheByText, getSessionAudioCache, splitTextByDelimiters, useMessageTTS, useStreamTTS, useVolcanoASR, useVolcanoTTS };

package/dist/index.d.ts

@@ -179,7 +179,7 @@ declare function useVolcanoTTS({ ttsConfig, audioParams, }: UseTTSParams): {
 };
 
 interface TTSMetric {
-    name: 'tts_request' | 'tts_latency' | 'tts_cache_hit' | 'tts_error';
+    name: 'tts_request' | 'tts_latency' | 'tts_cache_hit' | 'tts_error' | 'tts_synthesis_finished';
     labels: {
         voice?: string;
         speed?: number;
@@ -266,6 +266,266 @@ interface UseMessageTTSReturn {
 
 declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, exclusive, fallbackVoice, visualization, }: UseMessageTTSParams): UseMessageTTSReturn;
 
+/**
+ * 流式文本分段
+ */
+interface StreamTextSegment {
+    /** 分段索引 */
+    index: number;
+    /** 分段内容 */
+    content: string;
+    /** 分段长度 */
+    length: number;
+    /** 是否已发送 */
+    sent: boolean;
+}
+/**
+ * 流式文本分段器配置
+ */
+interface StreamingSplitOptions {
+    /** 单段最大字符数（默认150） */
+    maxLength?: number;
+    /** 单段最小字符数（默认10） */
+    minLength?: number;
+    /** 分段完成回调 */
+    onSegmentComplete?: (segment: StreamTextSegment) => void;
+    /** 所有分段完成回调 */
+    onAllComplete?: (segments: StreamTextSegment[]) => void;
+}
+/**
+ * useStreamTTS 参数
+ */
+interface UseStreamTTSParams {
+    /** TTS配置 */
+    ttsConfig: TTSConfig;
+    /** 音频参数 */
+    audioParams?: AudioParams;
+    /** 是否自动播放（默认：true） */
+    autoPlay?: boolean;
+    /** 指标收集器 */
+    metricsCollector?: MetricsCollector;
+    /** 播放开始回调 */
+    onPlayStart?: () => void;
+    /** 播放暂停回调 */
+    onPlayPause?: () => void;
+    /** 播放恢复回调 */
+    onPlayResume?: () => void;
+    /** 播放结束回调 */
+    onPlayEnd?: () => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+    /** 可视化配置 */
+    visualization?: VisualizationConfig;
+    /** 单段最大字符数（默认150） */
+    maxSegmentLength?: number;
+}
+/**
+ * useStreamTTS 返回值
+ */
+interface UseStreamTTSReturn {
+    /** WebSocket 是否已连接 */
+    isConnected: boolean;
+    /** 会话是否已启动 */
+    isSessionStarted: boolean;
+    /** 是否正在合成 */
+    isSynthesizing: boolean;
+    /** 是否正在播放 */
+    isPlaying: boolean;
+    /** 是否暂停 */
+    isPaused: boolean;
+    /** 错误信息 */
+    error: string | null;
+    /** 累计的流式文本（原始，未格式化） */
+    streamText: string;
+    /** 播放进度（0-100） */
+    progress: number;
+    /** 建立 WebSocket 连接 */
+    connect: () => Promise<void>;
+    /** 接收流式文本块 */
+    onMessage: (chunk: string) => void;
+    /** 结束流式输入 */
+    finishStream: () => Promise<void>;
+    /** 暂停播放 */
+    pause: () => void;
+    /** 恢复播放 */
+    resume: () => void;
+    /** 停止（断开连接，清理资源） */
+    stop: () => void;
+    /** 跳转到指定进度 */
+    seek: (percentage: number) => void;
+    /** 获取频率数据 */
+    getFrequencyData: () => Uint8Array;
+    /** 获取时域数据 */
+    getTimeDomainData: () => Uint8Array;
+    /** 可视化数据 */
+    visualizationData: VisualizationData;
+}
+/**
+ * Session 音频缓存条目
+ */
+interface SessionAudioCacheEntry {
+    /** 原始流式文本 */
+    streamText: string;
+    /** 音频数据 */
+    audioBuffers: ArrayBuffer[];
+    /** 缓存时间 */
+    timestamp: number;
+    /** 音色 */
+    voice: string;
+    /** 语速 */
+    speed: number;
+}
+
+/**
+ * 流式 TTS Hook
+ *
+ * 适用于 AI 对话实时语音合成场景：
+ * 1. connect() - 建立 WebSocket 连接
+ * 2. onMessage(chunk) - 接收 SSE 流式文本并实时分段合成
+ * 3. finishStream() - 结束流式输入，完成合成
+ *
+ * @example
+ * ```tsx
+ * const { connect, onMessage, finishStream, isPlaying } = useStreamTTS({
+ *   ttsConfig: { token, appid, resourceId },
+ *   audioParams: { speaker: "zh_female_tianmei" },
+ * });
+ *
+ * // SSE 事件处理
+ * useEffect(() => {
+ *   const eventSource = new EventSource("/api/chat");
+ *   eventSource.onopen = () => connect();
+ *   eventSource.onmessage = (e) => onMessage(e.data);
+ *   eventSource.onerror = async () => {
+ *     await finishStream();
+ *     eventSource.close();
+ *   };
+ * }, []);
+ * ```
+ */
+declare function useStreamTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, visualization, maxSegmentLength, }: UseStreamTTSParams): UseStreamTTSReturn;
+/**
+ * 获取 Session 音频缓存（供 useMessageTTS 使用）
+ * @param instanceId - 实例 ID
+ */
+declare function getSessionAudioCache(instanceId: string): SessionAudioCacheEntry | undefined;
+/**
+ * 清除 Session 音频缓存
+ * @param instanceId - 实例 ID
+ */
+declare function clearSessionAudioCache(instanceId: string): void;
+/**
+ * 根据文本查找匹配的 Session 缓存
+ * @param streamText - 流式文本
+ * @param voice - 音色
+ * @param speed - 语速
+ */
+declare function findSessionCacheByText(streamText: string, voice: string, speed: number): SessionAudioCacheEntry | undefined;
+
+/**
+ * 流式文本分段器
+ *
+ * 功能：
+ * - 接收流式文本输入（逐字符或逐 token）
+ * - 实时检测分段边界
+ * - 触发分段回调
+ *
+ * 分段规则：
+ * 1. 换行符 \n（立即分段，保持段落结构）
+ * 2. 字符数限制（智能拆分，优先在句子边界）
+ *
+ * @example
+ * ```ts
+ * const splitter = new StreamingTextSplitter({
+ *   maxLength: 150,
+ *   onSegmentComplete: (segment) => {
+ *     console.log('分段完成:', segment);
+ *   }
+ * });
+ *
+ * // 流式输入
+ * splitter.onChunk('Hello');
+ * splitter.onChunk(' ');
+ * splitter.onChunk('World');
+ * splitter.onChunk('\n'); // 触发分段
+ * splitter.complete();
+ * ```
+ */
+declare class StreamingTextSplitter {
+    /** 当前缓冲区 */
+    private buffer;
+    /** 分段索引计数器 */
+    private segmentIndex;
+    /** 已完成的分段列表 */
+    private segments;
+    /** 单段最大字符数 */
+    private readonly maxLength;
+    /** 单段最小字符数 */
+    private readonly minLength;
+    /** 分段完成回调 */
+    private readonly onSegmentComplete?;
+    /** 所有分段完成回调 */
+    private readonly onAllComplete?;
+    /** 是否已完成 */
+    private isCompleted;
+    constructor(options?: StreamingSplitOptions);
+    /**
+     * 接收流式文本块
+     * @param chunk - 文本块
+     */
+    onChunk(chunk: string): void;
+    /**
+     * 检测分段边界
+     * @param chunk - 最新接收的文本块
+     * @returns 是否应该分段
+     */
+    private detectBoundary;
+    /**
+     * 在句子边界强制拆分超长段落
+     */
+    private forceSplitAtSentenceBoundary;
+    /**
+     * 使用指定缓冲区内容刷新为分段
+     * @param bufferToFlush - 要分段的缓冲区内容
+     */
+    private flushSegmentWithBuffer;
+    /**
+     * 刷新当前缓冲区为分段
+     */
+    private flushSegment;
+    /**
+     * 拆分超长分段
+     * @param segment - 超长的分段
+     * @returns 拆分后的分段数组
+     */
+    private splitLongSegment;
+    /**
+     * 完成流式输入
+     * 处理剩余的缓冲区内容
+     */
+    complete(): void;
+    /**
+     * 重置分段器状态
+     */
+    reset(): void;
+    /**
+     * 获取当前缓冲区内容
+     */
+    getBuffer(): string;
+    /**
+     * 获取已分段的列表
+     */
+    getSegments(): StreamTextSegment[];
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        bufferLength: number;
+        segmentCount: number;
+        totalChars: number;
+    };
+}
+
 /**
  * TextSplitter 类型声明
  *
@@ -355,4 +615,4 @@ interface AudioProgressBarProps {
 
 declare const AudioProgressBar: React$1.FC<AudioProgressBarProps>;
 
-export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type TTSConfig, type TTSInstance, type TTSMessage, type TextSegment, type UseMessageTTSParams, type UseMessageTTSReturn, type UseTTSParams, type UseVTSOptions, type UseVTSReturn, type VisualizationConfig, type VisualizationData, splitTextByDelimiters, useMessageTTS, useVolcanoASR, useVolcanoTTS };
+export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type SessionAudioCacheEntry, type StreamTextSegment, type StreamingSplitOptions, StreamingTextSplitter, type TTSConfig, type TTSInstance, type TTSMessage, type TextSegment, type UseMessageTTSParams, type UseMessageTTSReturn, type UseStreamTTSParams, type UseStreamTTSReturn, type UseTTSParams, type UseVTSOptions, type UseVTSReturn, type VisualizationConfig, type VisualizationData, clearSessionAudioCache, findSessionCacheByText, getSessionAudioCache, splitTextByDelimiters, useMessageTTS, useStreamTTS, useVolcanoASR, useVolcanoTTS };