@wq-hook/volcano-react 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# @wq-hook/volcano-react
+
+火山引擎 ASR & TTS 的 React 封装库，提供了一套易用的 Hooks 和组件，帮助开发者快速在 React 应用中集成语音能力。
+
+## 安装
+
+```bash
+pnpm add @wq-hook/volcano-react
+```
+
+## 核心 Hooks
+
+### 1. `useMessageTTS`
+
+用于文本转语音（TTS）的高级 Hook，支持流式播放、自动缓存、降级策略和音频可视化。
+
+**特性**：
+- **流式合成**：利用 WebSocket 实现低延迟流式播放。
+- **多级缓存**：内置内存和 IndexedDB 缓存，相同的文本和参数不会重复请求。
+- **自动降级**：如果火山引擎服务不可用，自动降级到浏览器原生的 `SpeechSynthesis`。
+- **可视化支持**：提供 `getFrequencyData` 和 `getTimeDomainData` 方法用于绘制波形。
+
+**使用示例**：
+
+```tsx
+import { useMessageTTS } from '@wq-hook/volcano-react';
+
+const MyComponent = () => {
+  const { play, stop, isPlaying, isSynthesizing } = useMessageTTS({
+    ttsConfig: {
+      appid: 'YOUR_APPID',
+      token: 'YOUR_TOKEN',
+      uid: 'user-1'
+    },
+    audioParams: {
+      speaker: 'zh_female_vv_uranus_bigtts', // 发音人
+      speech_rate: 1.0, // 语速
+    }
+  });
+
+  return (
+    <div>
+      <button onClick={() => play("你好，这是一个测试文本。")}>播放</button>
+      <button onClick={stop}>停止</button>
+      {isPlaying && <p>正在播放...</p>}
+      {isSynthesizing && <p>正在合成...</p>}
+    </div>
+  );
+};
+```
+
+### 2. `useVolcanoASR`
+
+用于实时语音识别（ASR）的 Hook，支持麦克风录音并实时转换为文本。
+
+**使用示例**：
+
+```tsx
+import { useVolcanoASR } from '@wq-hook/volcano-react';
+
+const ASRComponent = () => {
+  const { start, stop, result, status } = useVolcanoASR({
+    config: {
+      appId: 'YOUR_APPID',
+      token: 'YOUR_TOKEN',
+      uid: 'user-1'
+    }
+  });
+
+  return (
+    <div>
+      <button onClick={start}>开始录音</button>
+      <button onClick={stop}>停止录音</button>
+      <p>状态: {status}</p>
+      <p>识别结果: {result}</p>
+    </div>
+  );
+};
+```
+
+## 组件
+
+### `AudioWaveVisualizer`
+
+一个用于显示音频波形的 Canvas 组件。
+
+```tsx
+import { AudioWaveVisualizer } from '@wq-hook/volcano-react';
+
+// 在使用 useMessageTTS 的组件中
+<AudioWaveVisualizer
+  width={300}
+  height={100}
+  barWidth={2}
+  gap={1}
+  barColor="#4F46E5"
+  getFrequencyData={getFrequencyData} // 来自 useMessageTTS
+/>
+```
+
+## 配置说明
+
+### UseTTSParams
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `ttsConfig` | `TTSConfig` | 火山引擎鉴权配置 (appid, token, etc.) |
+| `audioParams` | `AudioParams` | 音频参数 (speaker, speech_rate, etc.) |
+| `autoPlay` | `boolean` | 合成收到数据后是否自动播放，默认为 `true` |
+| `exclusive` | `boolean` | 是否互斥播放（播放时暂停其他实例），默认为 `true` |
+| `fallbackVoice` | `string` | 备用音色 ID，当主音色失败时尝试 |
+

package/dist/index.d.mts

@@ -0,0 +1,358 @@
+import { WebsocketMSE } from '@wq-hook/volcano-sdk/tts';
+import React$1 from 'react';
+
+type ASRStatus = 'idle' | 'connecting' | 'recording' | 'error';
+interface ASRHookParams {
+    /** 应用 ID */
+    appId: string;
+    /** 访问令牌 */
+    token: string;
+}
+interface ASRHookReturn {
+    status: ASRStatus;
+    text: string;
+    error: string | null;
+    start: () => Promise<void>;
+    stop: () => void;
+}
+
+declare function useVolcanoASR(params: ASRHookParams): ASRHookReturn;
+
+/**
+ * useVTS Hook 类型定义
+ *
+ * 本文件定义了 useVTS Hook 所需的所有 TypeScript 类型接口
+ */
+
+/**
+ * TTS 实例类型
+ */
+type TTSInstance = typeof WebsocketMSE;
+/**
+ * TTS 配置接口
+ *
+ * @description 定义 TTS 服务的鉴权和配置信息
+ */
+interface TTSConfig {
+    /** 应用 ID */
+    appid: string;
+    /** JWT Token（需要从服务端获取） */
+    token: string;
+    /** 音色服务 ID（可选，克隆音色需要） */
+    resourceId?: string;
+    /** 命名空间（可选） */
+    namespace?: string;
+}
+/**
+ * useVolcanoTTS Hook 参数接口
+ *
+ * @description 定义 useVolcanoTTS Hook 的参数结构
+ */
+interface UseTTSParams {
+    /** TTS 配置 */
+    ttsConfig: TTSConfig;
+    /** 音频参数（可选） */
+    audioParams?: AudioParams;
+}
+/**
+ * 鉴权参数接口
+ *
+ * @description 定义 WebSocket 连接的鉴权参数
+ */
+interface AuthParams {
+    /** API 资源 ID */
+    api_resource_id?: string;
+    /** API 应用密钥 */
+    api_app_key?: string;
+    /** JWT Token，格式为 `Jwt; {token}` */
+    api_access_key?: string;
+}
+/**
+ * 音频参数接口
+ *
+ * @description 定义音频合成的参数配置
+ */
+interface AudioParams {
+    /** 发音人（如 zh_female_vv_uranus_bigtts） */
+    speaker?: string;
+    /** 音频格式（如 mp3, wav） */
+    format?: string;
+    /** 采样率（如 24000, 16000） */
+    sample_rate?: number;
+    /** 语速（可选） */
+    speech_rate?: number;
+    /** 音调（可选） */
+    pitch_rate?: number;
+    /** 音量（可选） */
+    loudness_rate?: number;
+}
+/**
+ * 消息状态类型
+ *
+ * @description 定义 TTS 消息的生命周期状态
+ */
+type MessageStatus = 'pending' | 'synthesizing' | 'playing' | 'completed' | 'error';
+/**
+ * TTS 消息接口
+ *
+ * @description 定义单条 TTS 消息的数据结构
+ */
+interface TTSMessage {
+    /** 消息唯一标识 */
+    id: string;
+    /** 文本内容 */
+    text: string;
+    /** 消息状态 */
+    status: MessageStatus;
+    /** MediaSource URL（可选） */
+    audioUrl?: string;
+    /** 错误信息（可选） */
+    error?: string;
+    /** TTS 实例（可选） */
+    instance?: ReturnType<typeof WebsocketMSE>;
+}
+/**
+ * Hook 配置选项接口
+ *
+ * @description 定义 useVTS Hook 的配置选项
+ */
+interface UseVTSOptions {
+    /** TTS 配置 */
+    tts: TTSConfig;
+    /** 音频参数 */
+    audio: AudioParams;
+    /** 模式：队列模式或并发模式 */
+    mode?: 'queue' | 'concurrent';
+    /** 是否自动播放 */
+    autoPlay?: boolean;
+    /** 最大并发数（仅并发模式有效） */
+    maxConcurrent?: number;
+    /** 消息开始回调 */
+    onMessageStart?: (id: string, text: string) => void;
+    /** 消息结束回调 */
+    onMessageEnd?: (id: string) => void;
+    /** 错误回调 */
+    onError?: (id: string, error: string) => void;
+}
+/**
+ * Hook 连接状态类型
+ *
+ * @description 定义 Hook 的连接状态
+ */
+type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'session-started' | 'error';
+/**
+ * Hook 返回类型
+ *
+ * @description 定义 useVTS Hook 的返回值
+ */
+interface UseVTSReturn {
+    /** 连接状态 */
+    status: ConnectionStatus;
+    /** 错误信息 */
+    error: string | null;
+    /** 当前播放的消息 ID */
+    currentMessageId?: string;
+    /** 连接方法，返回 audioUrl */
+    connect: () => Promise<string>;
+    /** 断开连接方法 */
+    disconnect: () => void;
+    /** 添加消息方法 */
+    addMessage: (id: string, text: string) => void;
+    /** 发送文本方法 */
+    sendText: (id: string, text: string) => void;
+    /** 结束会话方法 */
+    finishSession: () => void;
+    /** 播放音频方法（实现互斥播放） */
+    playAudio: (id: string, audioUrl: string) => void;
+    /** 配置选项 */
+    config: UseVTSOptions;
+}
+
+declare function useVolcanoTTS({ ttsConfig, audioParams, }: UseTTSParams): {
+    status: ConnectionStatus;
+    error: string | null;
+    connect: () => Promise<string>;
+    disconnect: () => void;
+    startSession: () => void;
+    finishSession: () => void;
+    sendText: (text: string) => Promise<void>;
+};
+
+interface TTSMetric {
+    name: 'tts_request' | 'tts_latency' | 'tts_cache_hit' | 'tts_error';
+    labels: {
+        voice?: string;
+        speed?: number;
+        text_length?: number;
+        error_code?: string;
+        stage?: 'synthesis' | 'first_packet' | 'playback';
+        [key: string]: any;
+    };
+    value: number;
+    timestamp: number;
+}
+interface MetricsCollector {
+    record(metric: TTSMetric): void;
+}
+
+interface UseMessageTTSParams {
+    /** TTS配置（与现有useVolcanoTTS保持一致） */
+    ttsConfig: TTSConfig;
+    /** 音频参数（可选） */
+    audioParams?: AudioParams;
+    /** 是否自动播放（默认：true） */
+    autoPlay?: boolean;
+    /** 指标收集器（可选） */
+    metricsCollector?: MetricsCollector;
+    /** 播放开始回调 */
+    onPlayStart?: () => void;
+    /** 播放暂停回调 */
+    onPlayPause?: () => void;
+    /** 播放恢复回调 */
+    onPlayResume?: () => void;
+    /** 播放结束回调 */
+    onPlayEnd?: () => void;
+    /** 播放错误回调 */
+    onError?: (error: Error) => void;
+    /** 互斥播放控制（默认：true） */
+    exclusive?: boolean;
+    /** 备用音色（可选，当主音色失败时尝试，再次失败则降级到离线语音） */
+    fallbackVoice?: string;
+    /** 可视化配置 */
+    visualization?: VisualizationConfig;
+}
+interface VisualizationConfig {
+    /** 是否开启可视化数据自动更新 */
+    enabled: boolean;
+    /** 更新频率（毫秒），默认跟随 requestAnimationFrame */
+    refreshInterval?: number;
+    /** FFT 大小，必须是 2 的幂次方，默认 256 */
+    fftSize?: number;
+}
+interface VisualizationData {
+    frequencyData: Uint8Array;
+    timeDomainData: Uint8Array;
+}
+interface UseMessageTTSReturn {
+    /** 播放状态 */
+    isPlaying: boolean;
+    /** 暂停状态 */
+    isPaused: boolean;
+    /** 设置播放进度（0-100） */
+    seek: (percentage: number) => void;
+    /** 是否正在合成 */
+    isSynthesizing: boolean;
+    /** 错误信息 */
+    error: string | null;
+    /** 播放进度（0-1） */
+    progress: number;
+    /** 播放文本方法 */
+    play: (text: string) => Promise<void>;
+    /** 暂停播放方法 */
+    pause: () => void;
+    /** 恢复播放方法 */
+    resume: () => void;
+    /** 停止播放方法 */
+    stop: () => void;
+    /** 切换播放/暂停方法 */
+    togglePlay: () => void;
+    /** 获取音浪频率数据（用于可视化） */
+    getFrequencyData: () => Uint8Array;
+    /** 获取音浪时域数据（用于可视化） */
+    getTimeDomainData: () => Uint8Array;
+    /** 实时可视化数据（仅当 visualization.enabled 为 true 时更新） */
+    visualizationData: VisualizationData;
+}
+
+declare function useMessageTTS({ ttsConfig, audioParams, autoPlay, metricsCollector, onPlayStart, onPlayPause, onPlayResume, onPlayEnd, onError, exclusive, fallbackVoice, visualization, }: UseMessageTTSParams): UseMessageTTSReturn;
+
+/**
+ * TextSplitter 类型声明
+ *
+ * @description
+ * TextSplitter 模块的所有类型定义，与实现代码分离
+ */
+/**
+ * 文本分段接口
+ *
+ * @description
+ * 定义分割后的文本段结构，用于处理长文本分段
+ */
+interface TextSegment {
+    /** 分段索引 */
+    index: number;
+    /** 分段内容 */
+    content: string;
+    /** 字符长度 */
+    length: number;
+    /** 是否已发送 */
+    sent?: boolean;
+    /** 发送时间戳 */
+    sentAt?: number;
+}
+
+/**
+ * 文本分段
+ */
+
+/**
+ * 智能分段文本 - 根据语义、标点符号进行分段，优化并行请求
+ *
+ * @param text - 原始文本
+ * @param minLength - 单段最小字符数（默认10，避免过碎）
+ * @param maxLength - 单段最大字符数（默认150，平衡并发请求）
+ * @returns 文本分段数组
+ */
+declare function splitTextByDelimiters(text: string, minLength?: number, maxLength?: number): TextSegment[];
+
+interface AudioWaveVisualizerProps {
+    /** 是否正在播放 */
+    isPlaying: boolean;
+    /** 是否暂停 */
+    isPaused: boolean;
+    /** 音频频率数据（来自Web Audio API） */
+    frequencyData?: Uint8Array;
+    /** 音频时域数据（来自Web Audio API） */
+    timeDomainData?: Uint8Array;
+    /** 波形样式：'bar' | 'line' | 'circle' | 'wave' */
+    style?: 'bar' | 'line' | 'circle' | 'wave';
+    /** 颜色主题（支持渐变） */
+    color?: string | [string, string];
+    /** 波形条数 */
+    bars?: number;
+    /** 高度（px） */
+    height?: number;
+    /** 宽度（px） */
+    width?: number;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    styleObj?: React.CSSProperties;
+}
+
+declare const AudioWaveVisualizer: React$1.FC<AudioWaveVisualizerProps>;
+
+interface AudioProgressBarProps {
+    /** 播放进度（0-100） */
+    progress: number;
+    /** 宽度（px 或百分比） */
+    width?: number | string;
+    /** 高度（px） */
+    height?: number;
+    /** 颜色主题（支持渐变） */
+    color?: string | [string, string];
+    /** 背景颜色 */
+    backgroundColor?: string;
+    /** 是否显示百分比文本 */
+    showText?: boolean;
+    /** 进度改变回调 */
+    onSeek?: (progress: number) => void;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+}
+
+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 };