@wq-hook/ali-tts-streaming

阿里云 TTS 流式语音合成核心库 - 用于 React 应用的阿里云语音合成 Hook 和服务类。

特性

• ✅ 流式合成：支持 SSE 流式文本输入，实时语音合成
• ✅ 批量合成：一次性处理完整文本，自动分段发送
• ✅ 智能分段：实时文本分段，支持换行符、标点符号边界检测
• ✅ Markdown 格式化：自动清理 LLM 输出的 Markdown 语法，优化 TTS 朗读效果
• ✅ 音频播放：内置 PCM 音频播放器，自动队列管理
• ✅ TypeScript：完整的类型定义
• ✅ 零依赖：无运行时依赖，仅 peerDependencies

安装

pnpm add @wq-hook/ali-tts-streaming
# 或
npm install @wq-hook/ali-tts-streaming
# 或
yarn add @wq-hook/ali-tts-streaming

快速开始

使用 Hook（推荐）

import { useStreamingTTS } from '@wq-hook/ali-tts-streaming';

function App() {
  const { startBatch } = useStreamingTTS({
    auth: {
      appkey: 'your-appkey',
      token: 'your-token',
      region: 'cn-beijing',
    },
    audio: {
      voice: 'zhixiaoxia',
      format: 'pcm',
      sampleRate: 24000,
    },
    onSegmentComplete: (segment) => {
      console.log('分段完成:', segment);
    },
    onComplete: () => {
      console.log('合成完成');
    },
  });

  return (
    <button onClick={() => startBatch('你好，这是测试文本')}>
      开始合成
    </button>
  );
}

使用服务类

import { StreamingTTSService } from '@wq-hook/ali-tts-streaming';

const service = new StreamingTTSService({
  appkey: 'your-appkey',
  sampleRate: 24000,
});

// 配置 TTS 参数
service.setTTSConfig({
  token: 'your-token',
  region: 'cn-beijing',
  voice: 'zhixiaoxia',
  format: 'pcm',
  sampleRate: 24000,
});

// 批量合成
await service.startBatch('完整文本内容');

// 监听事件
service.on('segment:complete', ({ segment }) => {
  console.log('分段完成:', segment);
});

service.on('audio:received', ({ audio }) => {
  console.log('收到音频:', audio.byteLength, '字节');
});

API

useStreamingTTS

React Hook，提供流式和批量两种合成模式。

参数

interface UseStreamingTTSOptions {
  /** 认证配置 */
  auth: AuthConfig;
  /** 音频配置 */
  audio?: AudioConfig;
  /** 发送间隔（毫秒），默认 50ms */
  sendInterval?: number;
  /** Markdown 格式化配置（用于清理 LLM 输出的 Markdown 语法） */
  formatterConfig?: FormatterConfig;
  /** 分段完成回调 */
  onSegmentComplete?: (segment: TextSegment) => void;
  /** 音频接收回调 */
  onAudioReceived?: (audio: PCMData) => void;
  /** 完成回调 */
  onComplete?: () => void;
  /** 错误回调 */
  onError?: (error: Error) => void;
  /** 流式进度回调（用于更新 UI 显示 buffer） */
  onStreamProgress?: (data: { buffer: string; stats: { segmentCount: number; totalChars: number; bufferLength: number } }) => void;
}

返回值

interface UseStreamingTTSReturn {
  // SSE 流式模式 API
  /** 开始流式合成模式（用于 SSE 场景） */
  startStreaming: () => Promise<void>;
  /** 接收流式文本块 */
  onChunk: (chunk: string) => void;
  /** 标记流式输入结束 */
  complete: () => void;

  // 批量模式 API
  /** 批量合成模式（用于固定文本场景） */
  startBatch: (text: string, options?: BatchOptions) => Promise<void>;

  // 配置方法
  /** 设置发送间隔 */
  setSendInterval: (interval: number) => void;
  /** 设置 Markdown 格式化配置 */
  setFormatterConfig: (config: FormatterConfig) => void;
}

Markdown 格式化功能

本库内置了 Markdown 格式化器，用于清理 LLM 流式输出的 Markdown 语法，使其更适合 TTS 朗读。

默认行为

• 代码块：替换为「此处为一段代码」
• 表格：替换为「此处为一个表格」
• 行内语法：移除所有 Markdown 标记（粗体、斜体、链接、列表等）
• 标点补充：自动在段落末尾添加句号（如果没有结束标点）

使用示例

import { useStreamingTTS } from '@wq-hook/ali-tts-streaming';

function App() {
  const { startBatch } = useStreamingTTS({
    auth: { appkey: 'xxx', token: 'xxx', region: 'cn-beijing' },
    formatterConfig: {
      // 自定义代码块替换文本
      codeBlockReplacement: '跳过代码部分',
      // 自定义表格替换文本
      tableReplacement: '表格数据已省略',
      // 自定义替换规则
      customReplacements: [
        { pattern: /\{\{.*?\}\}/g, replacement: '变量' }
      ],
      // 是否自动补充句号（默认 true）
      autoAppendPeriod: true
    }
  });

  return (
    <button onClick={() => startBatch('# 标题\n\n这是**加粗**文字')}>
      开始合成
    </button>
  );
}

FormatterConfig 类型

interface FormatterConfig {
  /** 代码块替换文本（默认：「此处为一段代码」） */
  codeBlockReplacement?: string;
  /** 表格替换文本（默认：「此处为一个表格」） */
  tableReplacement?: string;
  /** 自定义替换规则（正则 -> 替换文本） */
  customReplacements?: Array<{ pattern: RegExp; replacement: string }>;
  /** 是否自动补充段落结束标点（默认：true） */
  autoAppendPeriod?: boolean;
  /** 自定义段落结束标点集合（默认：[。！？；、.!?;]） */
  sentenceEndPunctuation?: string;
}

文档发布内容

本包仅发布以下文件到 npm：

• dist/ - 编译后的代码（CommonJS + ESM + TypeScript 声明）
• README.md - 本文档
• LICENSE - MIT 许可证

不会发布：

• ❌ 源代码（src/）
• ❌ 测试代码
• ❌ 开发配置文件
• ❌ UI 组件

许可证

MIT