@wq-hook/volcano-react 1.0.1 → 1.0.3

package/dist/index.d.mts

@@ -212,6 +212,8 @@ interface UseMessageTTSParams {
     onPlayResume?: () => void;
     /** 播放结束回调 */
     onPlayEnd?: () => void;
+    /** 播放停止回调（用户主动停止时触发） */
+    onStop?: () => void;
     /** 播放错误回调 */
     onError?: (error: Error) => void;
     /** 互斥播放控制（默认：true） */
@@ -220,6 +222,7 @@ interface UseMessageTTSParams {
     fallbackVoice?: string;
     /** 可视化配置 */
     visualization?: VisualizationConfig;
+    streamId?: string;
 }
 interface VisualizationConfig {
     /** 是否开启可视化数据自动更新 */
@@ -260,11 +263,16 @@ interface UseMessageTTSReturn {
     getFrequencyData: () => Uint8Array;
     /** 获取音浪时域数据（用于可视化） */
     getTimeDomainData: () => Uint8Array;
+    /** 是否正在流式播放 */
+    isStreamActive: boolean;
+    streamState: StreamPlaybackState;
     /** 实时可视化数据（仅当 visualization.enabled 为 true 时更新） */
     visualizationData: VisualizationData;
+    /** 判断是否可以恢复播放（session 存在且未被停止） */
+    canResume: () => boolean;
 }
 
-declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, exclusive, fallbackVoice, visualization, }: UseMessageTTSParams): UseMessageTTSReturn;
+declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onStop, onError, fallbackVoice, visualization, streamId: externalStreamId, }: UseMessageTTSParams): UseMessageTTSReturn;
 
 /**
  * 流式文本分段
@@ -323,6 +331,7 @@ interface UseStreamTTSParams {
  * useStreamTTS 返回值
  */
 interface UseStreamTTSReturn {
+    streamId: string;
     /** WebSocket 是否已连接 */
     isConnected: boolean;
     /** 会话是否已启动 */
@@ -340,7 +349,7 @@ interface UseStreamTTSReturn {
     /** 播放进度（0-100） */
     progress: number;
     /** 建立 WebSocket 连接 */
-    connect: () => Promise<void>;
+    connect: () => Promise<string>;
     /** 接收流式文本块 */
     onMessage: (chunk: string) => void;
     /** 结束流式输入 */
@@ -376,51 +385,131 @@ interface SessionAudioCacheEntry {
     speed: number;
 }
 
+declare function useStreamTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, visualization, maxSegmentLength, }: UseStreamTTSParams): UseStreamTTSReturn;
+
 /**
- * 流式 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;
+interface StreamPlaybackState {
+    isPlaying: boolean;
+    isPaused: boolean;
+    isSynthesizing: boolean;
+    progress: number;
+    visualizationData: VisualizationData;
+    error: string | null;
+    isConnected: boolean;
+    isSessionStarted: boolean;
+    /**
+     * 流式输入是否已结束（finishStream 已调用）
+     * 用于区分流式合成中和流式合成完成后的状态
+     */
+    isStreamFinished: boolean;
+}
 /**
- * 获取 Session 音频缓存（供 useMessageTTS 使用）
- * @param instanceId - 实例 ID
+ * 播放会话配置
  */
-declare function getSessionAudioCache(instanceId: string): SessionAudioCacheEntry | undefined;
+interface PlaybackSessionConfig {
+    ttsConfig: TTSConfig;
+    audioParams?: AudioParams;
+    autoPlay?: boolean;
+    metricsCollector?: MetricsCollector;
+    visualization?: VisualizationConfig;
+    maxSegmentLength?: number;
+    onPlayStart?: () => void;
+    onPlayPause?: () => void;
+    onPlayResume?: () => void;
+    onPlayEnd?: () => void;
+    onError?: (error: Error) => void;
+}
 /**
- * 清除 Session 音频缓存
- * @param instanceId - 实例 ID
+ * 播放会话控制器
+ * 封装了 WebSocketMSE、Audio、可视化和状态管理
  */
-declare function clearSessionAudioCache(instanceId: string): void;
+declare class PlaybackSession {
+    readonly id: string;
+    state: StreamPlaybackState;
+    private config;
+    private listeners;
+    private audio;
+    private audioContext;
+    private analyser;
+    private source;
+    private audioUrl;
+    private client;
+    private splitter;
+    private segmentQueue;
+    private isSending;
+    private isSessionStarting;
+    private streamText;
+    private sessionAudioBuffers;
+    private isStreamFinished;
+    private isSessionFinished;
+    private resolveAllSegmentsSent;
+    private animId;
+    private lastVisUpdate;
+    constructor(id: string, config: PlaybackSessionConfig);
+    /**
+     * 初始化 AudioContext（用于可视化）
+     */
+    private initAudioContext;
+    private setupAudioListeners;
+    /**
+     * 建立 WebSocket 连接
+     */
+    connect(): Promise<void>;
+    /**
+     * 发送流式文本
+     */
+    handleStreamChunk(chunk: string): void;
+    /**
+     * 结束流式输入
+     */
+    finishStream(): Promise<void>;
+    /**
+     * 处理非流式播放（直接播放整段文本）
+     */
+    play(text: string): Promise<void>;
+    private processQueue;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    seek(percentage: number): void;
+    private updateState;
+    subscribe(listener: (state: StreamPlaybackState) => void): () => boolean;
+    private notifyListeners;
+    private getFrequencyData;
+    private getTimeDomainData;
+    private startVisualizationLoop;
+    private stopVisualizationLoop;
+}
 /**
- * 根据文本查找匹配的 Session 缓存
- * @param streamText - 流式文本
- * @param voice - 音色
- * @param speed - 语速
+ * 流式播放管理器（单例）
  */
-declare function findSessionCacheByText(streamText: string, voice: string, speed: number): SessionAudioCacheEntry | undefined;
+declare class StreamPlaybackManagerImpl {
+    private sessions;
+    private activeStreamId;
+    /**
+     * 创建新的播放会话
+     */
+    createSession(id: string, config: PlaybackSessionConfig): PlaybackSession;
+    /**
+     * 获取会话
+     */
+    getSession(id: string): PlaybackSession | undefined;
+    /**
+     * 停止会话
+     */
+    stop(id: string): void;
+    /**
+     * 暂停会话
+     */
+    pause(id: string): void;
+    /**
+     * 恢复会话
+     */
+    resume(id: string): void;
+}
+declare const StreamPlaybackManager: StreamPlaybackManagerImpl;
 
 /**
  * 流式文本分段器
@@ -615,4 +704,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 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 };
+export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type SessionAudioCacheEntry, StreamPlaybackManager, type StreamPlaybackState, 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, splitTextByDelimiters, useMessageTTS, useStreamTTS, useVolcanoASR, useVolcanoTTS };

package/dist/index.d.ts

@@ -212,6 +212,8 @@ interface UseMessageTTSParams {
     onPlayResume?: () => void;
     /** 播放结束回调 */
     onPlayEnd?: () => void;
+    /** 播放停止回调（用户主动停止时触发） */
+    onStop?: () => void;
     /** 播放错误回调 */
     onError?: (error: Error) => void;
     /** 互斥播放控制（默认：true） */
@@ -220,6 +222,7 @@ interface UseMessageTTSParams {
     fallbackVoice?: string;
     /** 可视化配置 */
     visualization?: VisualizationConfig;
+    streamId?: string;
 }
 interface VisualizationConfig {
     /** 是否开启可视化数据自动更新 */
@@ -260,11 +263,16 @@ interface UseMessageTTSReturn {
     getFrequencyData: () => Uint8Array;
     /** 获取音浪时域数据（用于可视化） */
     getTimeDomainData: () => Uint8Array;
+    /** 是否正在流式播放 */
+    isStreamActive: boolean;
+    streamState: StreamPlaybackState;
     /** 实时可视化数据（仅当 visualization.enabled 为 true 时更新） */
     visualizationData: VisualizationData;
+    /** 判断是否可以恢复播放（session 存在且未被停止） */
+    canResume: () => boolean;
 }
 
-declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, exclusive, fallbackVoice, visualization, }: UseMessageTTSParams): UseMessageTTSReturn;
+declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onStop, onError, fallbackVoice, visualization, streamId: externalStreamId, }: UseMessageTTSParams): UseMessageTTSReturn;
 
 /**
  * 流式文本分段
@@ -323,6 +331,7 @@ interface UseStreamTTSParams {
  * useStreamTTS 返回值
  */
 interface UseStreamTTSReturn {
+    streamId: string;
     /** WebSocket 是否已连接 */
     isConnected: boolean;
     /** 会话是否已启动 */
@@ -340,7 +349,7 @@ interface UseStreamTTSReturn {
     /** 播放进度（0-100） */
     progress: number;
     /** 建立 WebSocket 连接 */
-    connect: () => Promise<void>;
+    connect: () => Promise<string>;
     /** 接收流式文本块 */
     onMessage: (chunk: string) => void;
     /** 结束流式输入 */
@@ -376,51 +385,131 @@ interface SessionAudioCacheEntry {
     speed: number;
 }
 
+declare function useStreamTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, visualization, maxSegmentLength, }: UseStreamTTSParams): UseStreamTTSReturn;
+
 /**
- * 流式 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;
+interface StreamPlaybackState {
+    isPlaying: boolean;
+    isPaused: boolean;
+    isSynthesizing: boolean;
+    progress: number;
+    visualizationData: VisualizationData;
+    error: string | null;
+    isConnected: boolean;
+    isSessionStarted: boolean;
+    /**
+     * 流式输入是否已结束（finishStream 已调用）
+     * 用于区分流式合成中和流式合成完成后的状态
+     */
+    isStreamFinished: boolean;
+}
 /**
- * 获取 Session 音频缓存（供 useMessageTTS 使用）
- * @param instanceId - 实例 ID
+ * 播放会话配置
  */
-declare function getSessionAudioCache(instanceId: string): SessionAudioCacheEntry | undefined;
+interface PlaybackSessionConfig {
+    ttsConfig: TTSConfig;
+    audioParams?: AudioParams;
+    autoPlay?: boolean;
+    metricsCollector?: MetricsCollector;
+    visualization?: VisualizationConfig;
+    maxSegmentLength?: number;
+    onPlayStart?: () => void;
+    onPlayPause?: () => void;
+    onPlayResume?: () => void;
+    onPlayEnd?: () => void;
+    onError?: (error: Error) => void;
+}
 /**
- * 清除 Session 音频缓存
- * @param instanceId - 实例 ID
+ * 播放会话控制器
+ * 封装了 WebSocketMSE、Audio、可视化和状态管理
  */
-declare function clearSessionAudioCache(instanceId: string): void;
+declare class PlaybackSession {
+    readonly id: string;
+    state: StreamPlaybackState;
+    private config;
+    private listeners;
+    private audio;
+    private audioContext;
+    private analyser;
+    private source;
+    private audioUrl;
+    private client;
+    private splitter;
+    private segmentQueue;
+    private isSending;
+    private isSessionStarting;
+    private streamText;
+    private sessionAudioBuffers;
+    private isStreamFinished;
+    private isSessionFinished;
+    private resolveAllSegmentsSent;
+    private animId;
+    private lastVisUpdate;
+    constructor(id: string, config: PlaybackSessionConfig);
+    /**
+     * 初始化 AudioContext（用于可视化）
+     */
+    private initAudioContext;
+    private setupAudioListeners;
+    /**
+     * 建立 WebSocket 连接
+     */
+    connect(): Promise<void>;
+    /**
+     * 发送流式文本
+     */
+    handleStreamChunk(chunk: string): void;
+    /**
+     * 结束流式输入
+     */
+    finishStream(): Promise<void>;
+    /**
+     * 处理非流式播放（直接播放整段文本）
+     */
+    play(text: string): Promise<void>;
+    private processQueue;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    seek(percentage: number): void;
+    private updateState;
+    subscribe(listener: (state: StreamPlaybackState) => void): () => boolean;
+    private notifyListeners;
+    private getFrequencyData;
+    private getTimeDomainData;
+    private startVisualizationLoop;
+    private stopVisualizationLoop;
+}
 /**
- * 根据文本查找匹配的 Session 缓存
- * @param streamText - 流式文本
- * @param voice - 音色
- * @param speed - 语速
+ * 流式播放管理器（单例）
  */
-declare function findSessionCacheByText(streamText: string, voice: string, speed: number): SessionAudioCacheEntry | undefined;
+declare class StreamPlaybackManagerImpl {
+    private sessions;
+    private activeStreamId;
+    /**
+     * 创建新的播放会话
+     */
+    createSession(id: string, config: PlaybackSessionConfig): PlaybackSession;
+    /**
+     * 获取会话
+     */
+    getSession(id: string): PlaybackSession | undefined;
+    /**
+     * 停止会话
+     */
+    stop(id: string): void;
+    /**
+     * 暂停会话
+     */
+    pause(id: string): void;
+    /**
+     * 恢复会话
+     */
+    resume(id: string): void;
+}
+declare const StreamPlaybackManager: StreamPlaybackManagerImpl;
 
 /**
  * 流式文本分段器
@@ -615,4 +704,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 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 };
+export { type ASRHookParams, type ASRHookReturn, type ASRStatus, type AudioParams, AudioProgressBar, type AudioProgressBarProps, AudioWaveVisualizer, type AudioWaveVisualizerProps, type AuthParams, type ConnectionStatus, type MessageStatus, type SessionAudioCacheEntry, StreamPlaybackManager, type StreamPlaybackState, 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, splitTextByDelimiters, useMessageTTS, useStreamTTS, useVolcanoASR, useVolcanoTTS };