@xmov/doubao-asr

豆包（字节跳动）实时语音识别 SDK，专为数字人电话场景优化。

特性

• 🎤 实时语音识别 - 支持实时音频流处理和识别
• 🔗 WebSocket 持续连接 - 保持连接活跃，高效的 gzip 压缩通信
• 🎯 句子级识别 - 提供句子开始、更新、结束事件
• 🔄 持续监听 - 识别完一句话后自动继续监听下一句，无需重启
• 🚫 手动停止 - 只有用户主动停止才关闭连接，忽略服务器完成信号
• 📱 数字人电话优化 - 针对电话对话场景的模型优化
• 💪 TypeScript 支持 - 完整的类型定义
• 🚀 开箱即用 - 简单的 API 设计
• 🛡️ 生产环境控制 - 可配置的生产环境禁用选项

安装

npm install @xmov/doubao-asr
# 或
pnpm add @xmov/doubao-asr

快速开始

基础用法

import { createDoubaoASR, DoubaoRecognizer } from '@xmov/doubao-asr'

// 创建并启动识别器
const recognizer = await createDoubaoASR(
  {
    wsUrl: 'wss://your-proxy-server.com/asr',
    appKey: 'your-app-key',
    accessKey: 'your-access-key'
  },
  {
    onRecognitionResultChange: (event) => {
      console.log('实时识别结果:', event.result.voice_text_str)
    },
    onSentenceEnd: (event) => {
      console.log('句子结束:', event.result.voice_text_str)
    },
    onError: (event) => {
      console.error('识别错误:', event.error)
    }
  }
)

// 停止识别
await recognizer.stop()

// 销毁资源
recognizer.destroy()

手动控制

import { DoubaoRecognizer } from '@xmov/doubao-asr'

const recognizer = new DoubaoRecognizer(
  {
    wsUrl: 'wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async',
    appKey: 'your-app-key',
    accessKey: 'your-access-key',
    engineModel: '16k_zh',
    sampleRate: 16000
  },
  {
    onRecognitionStart: () => {
      console.log('识别开始')
    },
    onSentenceBegin: (event) => {
      console.log('句子开始:', event.result.voice_text_str)
    },
    onRecognitionResultChange: (event) => {
      // 实时字幕更新
      updateSubtitle(event.result.voice_text_str)
    },
    onSentenceEnd: (event) => {
      // 句子完成，可以进行后续处理
      processFinalText(event.result.voice_text_str)
    },
    onRecognitionComplete: () => {
      console.log('识别完成')
    },
    onError: (event) => {
      console.error('错误:', event.error.message)
    }
  }
)

// 手动启动
await recognizer.start()

// 检查状态
console.log('当前状态:', recognizer.currentState)

配置选项

interface DoubaoASRConfig {
  /** WebSocket URL (代理或直接连接) */
  wsUrl?: string
  /** 应用Key (推荐使用) */
  appKey?: string
  /** 访问Key (推荐使用) */
  accessKey?: string
  /** 应用ID (向后兼容) */
  appId?: string
  /** Token (向后兼容) */
  token?: string
  /** 资源ID */
  resourceId?: string
  /** 连接ID */
  connectId?: string
  /** 采样率，默认 16000 */
  sampleRate?: number
  /** 引擎模型，默认 '16k_zh' */
  engineModel?: string
  /** VAD静音阈值(毫秒) */
  vadSilenceTime?: number
  /** 心跳间隔(毫秒) */
  keepAliveMs?: number
  /** 是否在生产环境禁用ASR */
  disableInProduction?: boolean
}

事件回调

interface DoubaoASRCallbacks {
  /** 错误回调 */
  onError?: (event: DoubaoErrorEvent) => void
  /** 识别开始回调 */
  onRecognitionStart?: (event: DoubaoRecognitionStartEvent) => void
  /** 识别结果变化回调 - 实时字幕更新 */
  onRecognitionResultChange?: (event: DoubaoRecognitionResultEvent) => void
  /** 识别完成回调 */
  onRecognitionComplete?: (event: DoubaoRecognitionCompleteEvent) => void
  /** 句子开始回调 */
  onSentenceBegin?: (event: DoubaoSentenceBeginEvent) => void
  /** 句子结束回调 - 最终文本 */
  onSentenceEnd?: (event: DoubaoSentenceEndEvent) => void
}

状态管理

识别器具有以下状态：

• IDLE - 空闲状态
• CONNECTING - 连接中
• CONNECTED - 已连接
• LISTENING - 监听中
• STOPPING - 停止中
• STOPPED - 已停止
• ERROR - 错误状态

import { RecognizerState } from '@xmov/doubao-asr'

console.log('当前状态:', recognizer.currentState)

if (recognizer.currentState === RecognizerState.LISTENING) {
  // 识别器正在监听
}

最佳实践

1. 错误处理

const recognizer = new DoubaoRecognizer(config, {
  onError: (event) => {
    console.error('ASR错误:', event.error.message)

    // 根据错误类型进行处理
    if (event.error.message.includes('网络')) {
      // 网络错误，可以尝试重连
      setTimeout(() => {
        recognizer.start().catch(console.error)
      }, 5000)
    }
  }
})

2. 资源管理

// 组件卸载时确保清理资源
useEffect(() => {
  return () => {
    recognizer.destroy()
  }
}, [])

3. 生产环境控制

const recognizer = new DoubaoRecognizer({
  // 在生产环境自动禁用 ASR
  disableInProduction: true,
  ...otherConfig
})

4. 实时字幕显示

let currentText = ''

const recognizer = new DoubaoRecognizer(config, {
  onSentenceBegin: () => {
    currentText = ''
  },
  onRecognitionResultChange: (event) => {
    // 实时更新字幕
    currentText = event.result.voice_text_str
    updateSubtitle(currentText)
  },
  onSentenceEnd: (event) => {
    // 句子完成，保存最终文本
    const finalText = event.result.voice_text_str
    saveFinalText(finalText)
    currentText = ''
  }
})

开发和构建

# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm typecheck

# 运行测试
pnpm test

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！