sur-voice

流式语音转文字组件库，基于 HiVoice WebSocket ASR，支持 Web、uni-app H5、小程序、APP。

安装

npm install sur-voice
# 或
pnpm add sur-voice

平台接入

Web（Vue 3）

<script setup>
import { surVoice } from 'sur-voice'
</script>

<template>
  <surVoice
    app-key="YOUR_APP_KEY"
    secret="YOUR_SECRET"
    @update:inputText="onText"
  />
</template>

按需注册：

import { createApp } from 'vue'
import SurVoice, { install } from 'sur-voice'

const app = createApp(App)
install(app) // 全局注册 <SurVoice />

uni-app（H5 / 微信小程序 / APP）

在 pages.json 或组件中直接引用源码组件（uni-app 会自行编译）：

<script setup>
import SurVoice from 'sur-voice/uni'
</script>

<template>
  <SurVoice
    app-key="YOUR_APP_KEY"
    secret="YOUR_SECRET"
    @update:inputText="onText"
  />
</template>

小程序注意事项：

1. 在 manifest.json → 微信小程序 → 权限中开启录音权限
2. 需在后台配置 wss://ws-osasr.hivoice.cn 为合法 socket 域名
3. 录音使用 PCM 16kHz 帧回调，需基础库支持 RecorderManager.onFrameRecorded

仅使用核心 SDK（自定义 UI）

import { AsrClient } from 'sur-voice/core'
import { createWebSocket, createWebRecorder } from 'sur-voice'

// 小程序 / APP
import { createUniSocket, createUniRecorder } from 'sur-voice/uni-entry'

const client = new AsrClient({
  config: { appKey: '...', secret: '...' },
  createSocket: createWebSocket, // 或 createUniSocket
  useBlobSend: true,             // Web: true，小程序: false
  callbacks: {
    onText: (text, partial) => console.log(text),
    onStatus: (status) => console.log(status),
  },
})

const recorder = createWebRecorder((chunk) => {
  client.enqueueChunk(chunk)
})

await recorder.ready()
client.connect()
recorder.start()

// 停止
recorder.stop()
client.finish()

Props

| 属性 | 类型 | 说明 | |------|------|------| | appKey | string | HiVoice 应用 Key | | secret | string | HiVoice 应用 Secret |

事件

| 事件 | 参数 | 说明 | |------|------|------| | update:inputText | string | 识别文本实时更新 |

插槽

| 插槽 | 作用域 | 说明 | |------|--------|------| | start-record | { start, stop, recording, textLoading, inputText } | 自定义开始录音按钮 | | stop-record | 同上 | 自定义停止录音按钮 |

包结构

sur-voice
├── dist/sur-voice.es.js   # Web 入口（ESM）
├── dist/sur-voice.cjs.js  # Web 入口（CJS）
├── dist/core.es.js        # 纯 ASR 核心（无 UI）
├── src/components/uni/    # uni-app 组件源码
└── src/core/              # 平台无关 ASR 逻辑

安全建议

secret 不应长期暴露在前端。生产环境建议由后端签发短期 token，前端仅持有临时凭证。

License

MIT