🎤 xfyun-sdk

🗣️ 科大讯飞语音识别（ASR）、语音合成（TTS）、翻译 Web SDK — 纯 TypeScript 编写的浏览器端语音解决方案，支持原生 JS、React、Vue 及微信小程序多端接入。

📑 目录

· 特性亮点
· 快速开始
· 架构设计
· 核心功能
  · ASR 语音识别
  · TTS 语音合成
  · Translator 翻译
· 完整示例
  · 原生 JavaScript
  · React Hooks
  · Vue 3 Composables
· API 参考
· 高级配置
· 框架集成
· 最佳实践
· 常见问题
· 更新日志

✨ 特性亮点

支持的功能矩阵

🚀 快速开始

安装

# npm
npm install xfyun-sdk

# pnpm
pnpm add xfyun-sdk

# yarn
yarn add xfyun-sdk

CDN 引入

<script src="https://cdn.jsdelivr.net/npm/xfyun-sdk/dist/index.umd.js"></script>
<script>
  const { XfyunASR, XfyunTTS, XfyunTranslator } = window.xfyunSdk;
</script>

讯飞 API 密钥获取

1. 访问 科大讯飞开放平台
2. 注册账号并登录
3. 创建应用 → 选择服务（语音听写 / 语音合成 / 翻译）
4. 在「应用管理」获取 AppID、APIKey、APISecret

⚠️ 安全提示：请勿将密钥直接硬编码在前端代码中。推荐通过环境变量或后端服务中转。

🏗️ 架构设计

┌─────────────────────────────────────────────────────────┐
│                        应用层                            │
│   React 组件  │  Vue 3 组合式  │  原生 JS  │  小程序    │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                      XfyunSDK Core                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  XfyunASR    │  │  XfyunTTS    │  │ XfyunTranslator │
│  │  语音识别    │  │  语音合成    │  │    翻译      │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ AudioCapturer │  │ AudioPlayer  │  │ WSManager    │  │
│  │  (麦克风采集) │  │  (音频播放)  │  │ (WebSocket)  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   VAD Engine │  │  Reconnector  │  │    Logger    │ │
│  │  (静音检测)  │  │  (自动重连)   │  │   (分级日志)  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │
              ┌────────────▼────────────┐
              │   讯飞 WebSocket API   │
              │  wss://iat-api.xfyun.cn │
              │  wss://tts-api.xfyun.cn │
              │  wss://itr-api.xfyun.cn │
              └─────────────────────────┘

🎤 ASR 语音识别

快速使用

import { XfyunASR } from 'xfyun-sdk';

const recognizer = new XfyunASR(
  {
    appId: import.meta.env.VITE_XFYUN_APP_ID,
    apiKey: import.meta.env.VITE_XFYUN_API_KEY,
    apiSecret: import.meta.env.VITE_XFYUN_API_SECRET,
    language: 'zh_cn',
    accent: 'mandarin',
    vadEos: 3000,
  },
  {
    onStart: () => console.log('🟢 识别已开始'),
    onStop: () => console.log('🔴 识别已停止'),
    onRecognitionResult: (text, isEnd) => {
      console.log(`📝 ${isEnd ? '[最终]' : '[中间]'} ${text}`);
    },
    onProcess: (volume) => {
      const bar = '█'.repeat(Math.round(volume * 10));
      console.log(`🔊 ${bar}`);
    },
    onError: (error) => console.error('❌ 错误:', error),
  }
);

recognizer.start();
recognizer.stop();
recognizer.destroy();

🔊 TTS 语音合成

快速使用

import { XfyunTTS } from 'xfyun-sdk';

const synthesizer = new XfyunTTS(
  {
    appId: import.meta.env.VITE_XFYUN_APP_ID,
    apiKey: import.meta.env.VITE_XFYUN_API_KEY,
    apiSecret: import.meta.env.VITE_XFYUN_API_SECRET,
    voice_name: 'xiaoyan',  // 青年女声
    speed: 50,               // 语速 0-100
    pitch: 50,               // 音调 0-100
    volume: 50,              // 音量 0-100
    audioFormat: 'mp3',      // mp3/wav/pcm
  },
  {
    onStart: () => console.log('🟢 合成开始'),
    onEnd: () => console.log('🔴 合成结束'),
    onAudioData: (audioData) => {
      // 流式音频数据
      console.log('收到音频:', audioData.byteLength, 'bytes');
    },
    onProgress: (current, total) => {
      console.log(`进度: ${current}/${total}`);
    },
    onError: (error) => console.error('❌ 错误:', error),
  }
);

// 开始合成
synthesizer.start('你好，这是语音合成测试。');

// 停止合成
synthesizer.stop();

// 销毁实例
synthesizer.destroy();

TTS 发音人列表

更多发音人请参考 docs/api/TTS.md

🌐 Translator 翻译

文本翻译

import { XfyunTranslator } from 'xfyun-sdk';

// 方式一：静态方法（推荐）
const result = await XfyunTranslator.translateText(
  '你好，世界！',
  {
    appId: import.meta.env.VITE_XFYUN_APP_ID,
    apiKey: import.meta.env.VITE_XFYUN_API_KEY,
    apiSecret: import.meta.env.VITE_XFYUN_API_SECRET,
    from: 'cn',
    to: 'en',
  }
);

console.log(result.sourceText); // 你好，世界！
console.log(result.targetText); // Hello, World!

// 方式二：实例方法
const translator = new XfyunTranslator(
  {
    appId: 'your_app_id',
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret',
    type: 'text',
    from: 'en',
    to: 'ja',
  },
  {
    onResult: (result) => {
      console.log('翻译结果:', result.targetText);
    },
  }
);

translator.start('Hello, how are you?');

语音翻译（边说边译）

import { XfyunTranslator } from 'xfyun-sdk';

const translator = new XfyunTranslator(
  {
    appId: 'your_app_id',
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret',
    type: 'asr',           // 语音翻译模式
    from: 'cn',            // 源语言：中文
    to: 'en',              // 目标语言：英文
    domain: 'iner',        // 场景：日常对话
    vadEos: 5000,          // 静音检测超时
  },
  {
    onStart: () => console.log('翻译开始'),
    onResult: (result) => {
      console.log('源文:', result.sourceText);
      console.log('译文:', result.targetText);
      console.log('是否最终:', result.isFinal);
    },
    onEnd: () => console.log('翻译结束'),
  }
);

// 开始语音翻译
translator.start();

// 停止翻译
translator.stop();

// 销毁实例
translator.destroy();

支持的语言

📖 完整示例

原生 JavaScript（ASR + TTS + 翻译）

import { XfyunASR, XfyunTTS, XfyunTranslator } from 'xfyun-sdk';

// 配置
const config = {
  appId: 'your_app_id',
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
};

// ASR 实例
const asr = new XfyunASR(config, {
  onRecognitionResult: (text) => {
    console.log('识别:', text);
  },
});

// TTS 实例
const tts = new XfyunTTS({
  ...config,
  voice_name: 'xiaoyan',
  audioFormat: 'mp3',
}, {
  onAudioData: (data) => playAudio(data),
});

// 翻译实例
const translator = new XfyunTranslator({
  ...config,
  type: 'text',
  from: 'cn',
  to: 'en',
}, {
  onResult: (result) => {
    console.log('翻译:', result.targetText);
    tts.start(result.targetText);
  },
});

// 组合使用：识别 -> 翻译 -> 合成
asr.start();  // 开始识别

// 或者直接翻译文本
translator.start('今天天气真好！');

React Hooks（推荐）

import { useEffect, useRef, useState } from 'react';
import { XfyunASR, XfyunTTS, XfyunTranslator, XfyunASROptions } from 'xfyun-sdk';

// 语音识别 Hook
export function useSpeechRecognizer(options: Partial<XfyunASROptions>) {
  const recognizerRef = useRef<XfyunASR | null>(null);
  const [isListening, setIsListening] = useState(false);
  const [transcript, setTranscript] = useState('');

  useEffect(() => {
    recognizerRef.current = new XfyunASR(options as XfyunASROptions, {
      onStart: () => setIsListening(true),
      onStop: () => setIsListening(false),
      onRecognitionResult: (text, isEnd) => {
        setTranscript((prev) => (isEnd ? prev + text + '\n' : prev + text));
      },
    });
    return () => recognizerRef.current?.destroy();
  }, []);

  return {
    isListening,
    transcript,
    start: () => recognizerRef.current?.start(),
    stop: () => recognizerRef.current?.stop(),
  };
}

Vue 3 Composables（推荐）

import { ref, onUnmounted } from 'vue';
import { XfyunTTS, type XfyunTTSOptions } from 'xfyun-sdk';

export function useSpeechSynthesizer(options: Partial<XfyunTTSOptions>) {
  const synthesizerRef = ref<XfyunTTS | null>(null);
  const isSynthesizing = ref(false);
  const audioChunks = ref<ArrayBuffer[]>([]);

  const init = () => {
    synthesizerRef.value = new XfyunTTS(
      options as XfyunTTSOptions,
      {
        onStart: () => (isSynthesizing.value = true),
        onEnd: () => (isSynthesizing.value = false),
        onAudioData: (data) => audioChunks.value.push(data),
      }
    );
  };

  const speak = (text: string) => synthesizerRef.value?.start(text);
  const stop = () => synthesizerRef.value?.stop();
  const destroy = () => synthesizerRef.value?.destroy();

  init();
  onUnmounted(destroy);

  return { isSynthesizing, audioChunks, speak, stop, destroy };
}

⚙️ API 参考

XfyunASROptions

XfyunTTSOptions

XfyunTranslatorOptions

BaseWebSocketClient（高级）

💡 高级用户：如果你需要扩展讯飞的其他 API，可以继承 BaseWebSocketClient 快速构建自定义客户端。

import { BaseWebSocketClient } from 'xfyun-sdk';

class MyCustomClient extends BaseWebSocketClient<MyState, MyOptions, MyHandlers> {
  // 1. 定义状态转换规则
  protected readonly STATE_TRANSITIONS: Record<MyState, MyState[]> = {
    'idle': ['connecting'],
    'connecting': ['connected', 'error'],
    'connected': ['processing', 'error'],
    'processing': ['stopped', 'error'],
    'stopped': ['idle'],
    'error': ['idle']
  };

  // 2. 实现抽象方法
  protected getModulePrefix(): string { return '[MyCustomClient]'; }
  protected getErrorCodePrefix(): number { return 40000; }
  protected generateAuthUrl(): string { /* ... */ }
  protected parseMessage(data: string | ArrayBuffer): void {
    // 处理消息
  }

  // 3. 使用基类提供的功能
  public start() {
    this.initWebSocket();  // 来自基类
  }
}

📊 架构设计

v1.5.0 新架构

┌─────────────────────────────────────────────────────────┐
│                        应用层                            │
│   React 组件  │  Vue 3 组合式  │  原生 JS  │  小程序    │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                      XfyunSDK Core                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │           BaseWebSocketClient (基类)              │  │
│  │  • WebSocket 连接管理 (ensureWebSocket, safeSend) │  │
│  │  • 定时器管理 (clearConnectingTimer, ...)         │  │
│  │  • 状态管理 (setState with validation)            │  │
│  │  • 错误处理 (handleError)                         │  │
│  └──────────────────────┬───────────────────────────┘  │
│         ┌───────────────┼───────────────┐              │
│         ▼               ▼               ▼              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  XfyunASR    │  │  XfyunTTS    │  │ XfyunTranslator │  │
│  │  语音识别    │  │  语音合成    │  │    翻译      │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ AudioCapturer │  │ AudioPlayer  │  │ WSManager    │  │
│  │  (麦克风采集) │  │  (音频播放)  │  │ (WebSocket)  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   VAD Engine │  │  Reconnector  │  │    Logger    │ │
│  │  (静音检测)  │  │  (自动重连)   │  │   (分级日志)  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │
              ┌────────────▼────────────┐
              │   讯飞 WebSocket API   │
              │  wss://iat-api.xfyun.cn │
              │  wss://tts-api.xfyun.cn │
              │  wss://itr-api.xfyun.cn │
              └─────────────────────────┘

设计优势

ASREventHandlers

RecognizerState 状态机

XfyunASR 公开方法

🔧 高级配置

热词识别（ASR）

const recognizer = new XfyunASR({
  // ...
  hotWords: ['xfyun-sdk', '科大讯飞', '语音识别'],
}, handlers);

TTS 多种音色

// 青年女声
const tts1 = new XfyunTTS({ voice_name: 'xiaoyan' }, handlers);

// 青年男声
const tts2 = new XfyunTTS({ voice_name: 'aisxiaofeng' }, handlers);

// 四川话
const tts3 = new XfyunTTS({ voice_name: 'aisjiuyuan' }, handlers);

// 童声
const tts4 = new XfyunTTS({ voice_name: 'aisxiaowawa' }, handlers);

指数退避重连

const recognizer = new XfyunASR({
  enableReconnect: true,
  reconnectAttempts: 5,
  reconnectInterval: 1000,
}, handlers);

💥 常见问题

Q: 麦克风权限被拒绝？

在用户交互（点击按钮）后调用 .start()，避免浏览器自动播放策略拦截。

Q: 识别结果为空？

1. 检查控制台日志（logLevel: 'debug'）
2. 确认 appId / apiKey / apiSecret 正确
3. 检查网络代理是否拦截 WebSocket
4. 确认讯飞应用已开通对应服务
5. 在 HTTPS 或 localhost 环境下测试

Q: TTS 音频如何播放？

synthesizer.onAudioData = async (audioData) => {
  const blob = new Blob([audioData], { type: synthesizer.getMimeType() });
  const url = URL.createObjectURL(blob);
  const audio = new Audio(url);
  await audio.play();
};

Q: React/Vue 组件内存泄漏？

// React
useEffect(() => {
  const recognizer = new XfyunASR(options, handlers);
  return () => recognizer.destroy();
}, []);

// Vue 3
import { onUnmounted } from 'vue';
onUnmounted(() => recognizer?.destroy());

📄 许可证

本项目基于 MIT License 开源。

🛡️ 质量保证

代码质量指标

安全特性

测试与验证

• ✅ 零编译错误: TypeScript 编译 100% 通过
• ✅ 零运行时破坏: 所有重构保持功能一致
• ✅ 向后兼容: API 完全向后兼容，无破坏性变更

📝 更新日志

v1.2.0 (2026-04-20)

测试覆盖率提升 🎉

• recognizer.ts: 测试覆盖率从38.2%提升至58.1% (+19.9%)
• translator.ts: 测试覆盖率从32.94%提升至53.2% (+20.3%)
• 总体覆盖率: 达到51.8%，超过jest.config.js设置的50%阈值

关键修复

• ✅ 资源泄漏修复: connectingTimer清理机制
• ✅ 栈溢出修复: arrayBufferToBase64分块处理优化
• ✅ TTS连接超时回退机制增强
• ✅ WebSocket集成测试完善

新增测试文件

• xfyuws-integration.spec.ts: WebSocket流程集成测试
• recognizer-event.spec.ts: 事件处理回调测试
• translator-error.spec.ts: 错误处理测试
• recognizer-close.spec.ts: close事件处理测试
• translator-open.spec.ts: open事件处理测试
• recognizer-message.spec.ts: message条件分支测试
• translator-close.spec.ts: close事件处理测试
• recognizer-state.spec.ts: 状态管理测试
• translator-boundary.spec.ts: 异步边界测试
• comprehensive-coverage.spec.ts: 综合测试套件
• recognizer-remaining-coverage.spec.ts: 剩余覆盖率覆盖测试
• translator-remaining-coverage.spec.ts: 剩余覆盖率覆盖测试
• resource-leak-prevention.spec.ts: 资源泄漏预防测试

质量保证

• 所有123个测试通过 ✅
• TypeScript编译检查通过 ✅
• ESLint代码规范检查通过 ✅
• 覆盖率阈值: jest.config.js设置50%，实际达到51.8% ✅

v1.3.0 (2026-03-28)

新增：

• ✨ examples/vue-demo/ 完整 Vue 3 + Vite 示例项目
• ✨ useSpeechRecognizer Vue 3 组合式函数（composable）
• ✨ SpeechRecognizer.vue 单文件组件（含音量条/状态徽章/动画）
• ✨ XfyunTTS 语音合成支持
• ✨ XfyunTranslator 翻译功能（文本翻译 + 语音翻译）
• ✨ 多种 TTS 音色（40+ 发音人）
• ✨ TTS 流式音频数据回调
• ✨ 支持 mp3/wav/pcm 音频格式
• ✨ 16 种语言翻译支持

优化：

• ⚡️ README 全面专业化设计（架构图、最佳实践、框架集成）
• ⚡️ CI workflow 切换为 pnpm
• ⚡️ 添加 npm 下载量 + CI + 覆盖率 Badge

文档：

• 📚 新增 docs/api/TTS.md / Translator.md API 文档
• 📚 新增 E2E 测试和性能测试

⭐ Star · Bug Report · Pull Request