更新记录

1.0.1（2026-06-04） 下载此版本

项目初始化

平台兼容性

uni-app(5.07)

Voice2Text - 阿里云百炼实时语音转文字

基于阿里云 DashScope OpenAI Realtime API 的实时语音识别组件，支持微信小程序、H5、App 三端。

文件结构

voice2text/
├── index.js          # 核心类 Voice2Text，状态机管理、音频帧缓冲、结果处理
├── audio-handler.js  # 音频采集：小程序用 RecorderManager 帧模式，H5 用 Web Audio API
├── ws-client.js      # WebSocket 客户端：小程序用 uni.connectSocket，H5 用原生 WebSocket
├── protocol.js       # 消息协议：构建 session.update / audio.append 等消息，解析服务端响应
├── constants.js      # 常量：WS 地址、API Key、模型名、音频参数、状态枚举
└── README.md         # 本文件

基本用法

import { createVoice2Text } from '@/utils/audio-recg/voice2text'

// 创建实例
const v2t = createVoice2Text({
  onResult: (text, isFinal) => {
    console.log(isFinal ? '最终结果:' : '中间结果:', text)
  },
  onError: (err) => {
    console.error('识别错误:', err)
  },
  onEnd: () => {
    console.log('识别结束')
  },
  onStart: () => {
    console.log('录音已开始')
  },
  enableVad: true,  // 是否启用服务端 VAD（默认 true）
})

// 开始识别（自动连接 WebSocket + 开始录音）
await v2t.start()

// 停止识别，等待最终结果（最多等 timeout 毫秒）
const finalText = await v2t.stop(2000)

// 取消识别（不等待结果，直接断开）
v2t.cancel()

预连接模式

页面加载时提前建立 WebSocket 连接，用户按住按钮时可直接识别，减少首次延迟：

// 页面 onLoad 时静默预连接
v2tInstance.connect({ silent: true }).catch(() => {})

// 用户按住麦克风时直接 start（连接已就绪，无需等待）
await v2tInstance.start()

按住说话模式（推荐）

// touchstart
async onMicTouchStart() {
  this.voiceFingerDown = true
  await this.v2tInstance.start()
}

// touchend
async onMicTouchEnd() {
  this.voiceFingerDown = false
  const text = await this.v2tInstance.stop(2000)
  if (text.trim()) {
    // 发送识别结果
  }
}

// touchcancel（滑动取消）
onMicTouchCancel() {
  this.v2tInstance.cancel()
}

API

createVoice2Text(options)

创建实例。options 可选：

start(): Promise<void>

开始识别。内部流程：

1. 建立 WebSocket 连接
2. 发送 session.update 配置
3. 立即开始录音（缓存模式，连接就绪后回放）
4. 连接就绪后切换为实时推送

stop(timeout?: number): Promise<string>

停止识别。停止录音，等待服务端返回最终结果。

• timeout: 等待超时时间（ms），默认 2000
• 返回：最终识别文本

cancel(): void

取消识别，不等待结果，直接断开连接。

connect(options?: { silent?: boolean }): Promise<void>

预连接 WebSocket（不启动录音、不发送 session.update）。

• silent: 静默模式，连接失败不触发 onError

state: string

当前状态：idle | connecting | starting | recording | finishing | done | error

isRunning: boolean

是否正在识别（connecting / starting / recording / finishing）。

text: string

已累积的最终文本。

destroy(): void

销毁实例，释放所有资源。

平台差异

注意事项

• 需要用户授权麦克风权限
• 小程序需在 app.json 中配置 requiredPrivateInfos 和 permission
• WebSocket 连接使用阿里云 DashScope API Key，注意调用频率
• VAD 模式下服务端自动断句，非 VAD 模式需手动 commit