更新记录

1.0.0（2026-08-29）

· Android UTS 原生 PCM 流式采集（16kHz/16bit/单声道，100ms一帧） · H5 AudioContext 采集 + 16k 重采样 · 豆包 Seeduplex 全双工协议封装：流式字幕、流式音频、response.cancel 打断 · sayText 文本合成、session.update 热更新 · 静音保活、自动重连（最多 3 次） · 安全模式：rt-ticket HMAC 短期票据 + 服务端代理持 Key · 热词：不内置任何行业默认热词；config.hotwords 外部注入，文档附 5 个行业示例词表

平台兼容性

uni-app(3.8.3)

sm-doubao-realtime

豆包端到端实时语音全双工对话 · uni-app UTS 插件

10 分钟让你的 App/H5 拥有一个能随时被用户打断的语音 AI。

为什么用它，而不是自己接豆包

在 uni-app 里接豆包 Seeduplex（端到端全双工）会撞上 3 个每个开发者都会掉进去的坑，这个插件已经替你踩完并修好了：

额外顺手解决的问题：

• 快速停止/重启的旧线程竞态（按 sessionId 隔离）
• 麦克风权限未授予时的运行时弹窗申请（Android 6.0+）
• 服务端 VAD 阈值调好（1800ms 长停顿、nostream 二遍识别 definite 定稿）
• 模型对 sayText 文本的自发接话（AI 自己回答自己）已做防护窗拦截
• output_audio.done 在"所有分片真正播放完"才通知上层（WAV 写盘 / WebAudio 调度 / Renderjs 三条路径全部校准）

兼容性

UTS 付费插件仅支持 HBuilderX 云打包（不支持离线打包 / 安心打包），要求 HBuilderX ≥ 3.83。

快速接入（5 步跑通）

第 1 步：导入插件并开通豆包

• 导入本插件到 uni_modules/
• 在火山引擎控制台开通「豆包端到端实时语音」能力，拿到 API Key（X-Api-Key）
• 确认使用精品音色（Duplex 链路专属）：见下面 VOICE_MAP

第 2 步：部署代理服务（H5 必选、App 推荐走代理防 Key 泄露）

cd server
npm install ws
set DOUBAO_API_KEY=你的豆包Key
set PROXY_AUTH_SECRET=随便取一串长随机字符串，后面云函数要相同
set PROXY_PORT=9420
node realtime-proxy.js

线上部署（Nginx / uniCloud 云托管 / 任意 Node 主机）时配成 WSS，示例：

wss://your-domain.com/realtime  →  转发到代理内部端口 9420

详细部署 & Nginx 配置见 docs/deploy-proxy.md。

第 3 步：部署 rt-ticket 云函数

把 uniCloud-aliyun/cloudfunctions/rt-ticket/ 上传到你 uniCloud 空间，并在云函数控制台设置两个环境变量：

• REALTIME_TICKET_SECRET = 与上一步 PROXY_AUTH_SECRET 完全一致
• REALTIME_PROXY_URL = 上一步你的代理公网地址，如 wss://your-domain.com/realtime

第 4 步：拿票据 + 建立连接

<script>
import { RealtimeVoice, VOICE_MAP } from '@/uni_modules/sm-doubao-realtime/common/realtimeVoice.js'

export default {
  data() {
    return { rv: null, aiText: '', userText: '', customerSpeaking: false }
  },
  async mounted() {
    this.rv = new RealtimeVoice()

    // 事件订阅
    this.rv.onReady = () => console.log('会话建立完成')
    this.rv.onUserTextDelta = (t) => { this.userText = t }  // 用户字幕(流式)
    this.rv.onTextDelta = (t) => { this.aiText += t }       // AI字幕(打字机)
    this.rv.onAudioPlaying = () => { this.customerSpeaking = true }
    this.rv.onAudioDone = () => { this.customerSpeaking = false }
    this.rv.onError = (e) => console.error('语音错误', e)

    // 先调用云函数取票据(10分钟有效)
    const { result } = await uniCloud.callFunction({
      name: 'rt-ticket',
      data: { uid: '用户ID或匿名' }
    })
    if (result.errCode !== 0) throw new Error(result.errMsg)

    await this.rv.connect(result.ticket, {
      instructions: '你是一个亲切的AI语音助手，用简洁口语回答用户问题。',
      voice: VOICE_MAP.male,     // VOICE_MAP.female / VOICE_MAP.male 或直接写音色名
      speed: 0,                  // -12 ~ +12
      loudness: 0,               // -12 ~ +12
      proxyUrl: result.proxyUrl,
      // ASR 专业词表（可选）：大幅提升行业词识别准确率
      hotwords: [
        { word: '重疾险', weight: 14 },
        { word: '增额寿', weight: 14 }
      ],
      // 回复长度上限（建议 150-350 防太啰嗦）
      dialog: { max_tokens: 260 }
    })
  },

  methods: {
    // 按住说话 → 松手提交
    pressStart() { this.rv && this.rv.startCapture() },
    pressEnd()   { this.rv && this.rv.commitAudio() },
    // AI说话时用户要插嘴 —— 一键打断
    interrupt()  { this.rv && this.rv.cancelResponse() },
    // 让AI直接朗读一段文本(如开场白)
    sayHi()      { this.rv && this.rv.sayText('你好呀，我是你的AI助理，有什么可以帮您？') }
  },

  beforeUnmount() { this.rv && this.rv.close() }
}
</script>

第 5 步：Android 云打包勾选权限

• 打包时会自动合入麦克风权限（RECORD_AUDIO）
• 首次启动用户授权即可，插件会弹系统权限框

更完整的「示例工程 ZIP」请在插件市场本页下载。

核心 API

new RealtimeVoice()

无参数。用事件和 connect 配置。

connect(ticket, config, attemptIndex?) => Promise

• ticket（必填）：rt-ticket 云函数返回的 10 分钟 HMAC 票据
• config.instructions：AI 人设提示词（豆包 LLM 指令）
• config.voice：音色名，Duplex 链路专属精品音色，常见：

  const VOICE_MAP = {
  female: 'zh_female_vv_jupiter_bigtts',
  male:   'zh_male_yunzhou_jupiter_bigtts'
  }

  也可直接传豆包控制台里的精品音色字符串。注意不能用普通 TTS 音色名（后者 duplex 不报错但没声音）。

• config.gender：快捷选 'female' | 'male'（和 voice 二选一）
• config.speed / config.loudness：语速/响度 -12~+12
• config.hotwords：ASR 热词 { word, weight }[]，提升行业词识别
• config.asr / config.tts / config.dialog：按豆包 S2S StartSessionPayload 原字段透传，覆盖默认值
• config.proxyUrl：wss 代理地址
• attemptIndex（可选）：当前第几次重试，用于内部连接超时分级（1→7s / 2→12s / 3→18s）

事件回调（赋值即可）

操作方法

票据/代理安全模型

用户 App/H5                rt-ticket 云函数              realtime-proxy (你的服务器)            豆包官方
  │                            │                               │                          │
  │  ① callFunction(rt-ticket) │                               │                          │
  │───────────────────────────>│  ② 读环境变量：               │                          │
  │                            │     REALTIME_TICKET_SECRET    │                          │
  │                            │     REALTIME_PROXY_URL        │                          │
  │                            │  签 ticket = uid.expire.hmac  │                          │
  │<───────────────────────────┤                               │                          │
  │  ③ ws.connect(proxy?ticket)│                               │                          │
  │──────────────────────────────────────────────────────────>│  ④ 校验 hmac & 有效期      │
  │                            │                               │  加 X-Api-Key(服务端持)    │
  │                            │                               │─────────────────────────>│
  │                            │                               │                         WS
  │<══════════════════════════双向音频&文字═══════════════════>│<══════════════════════════>│

任何情况下豆包 API Key 都不进入客户端。

常见问题 FAQ

Q1：为什么 App 运行自定义基座上 PCM 采集每 100ms 还弹一个 toast？ A：那是 UTS 付费插件的免费试用水印（每次启动），买了正式授权后绑定 appid 云打包就没了，不是 bug。

Q2：连上了但 started/done 正常，就是听不到声音？ A：99% 是音色用错了：你用的是火山独立 TTS 音色名，它不属于 Duplex 链路，后者要选「精品音色」。用本插件导出的 VOICE_MAP 即可。

Q3：H5 本地调试连不上代理？ A：先 node server/realtime-proxy.js 起本地 9420 端口；再检查浏览器是否允许了本地页面的麦克风权限（https 或 localhost 才能用 getUserMedia）。

Q4：App 端用 WAV 兜底播分片，切换间隙明显？ A：默认已启用「三播放器流水线 + 双预载 + 首片小缓冲快速起播」，如仍有明显间隙可在页面用 renderjs 模式（把 rv.audioOut = 'render' 并在 WebView 侧处理 rv.onAudioChunk(base64PCM) 的 WebAudio 播放），延迟更低。示例工程里有现成封装。

Q5：iOS 现在能用吗？ A：v1.0 只支持 Android + H5，iOS UTS 采集层暂无开发计划（不承诺后续版本）；iOS 用户可通过 Safari 访问 H5 版本使用。

更新日志

v1.0.0（首版）

• Android：UTS 原生 PCM 流式采集，@UTSJS.keepAlive 保活每帧回调；权限弹窗；sessionId 防竞态
• H5：AudioContext + ScriptProcessor + 16k 重采样
• 豆包 Seeduplex 全双工协议封装：session.create/update、流式字幕、流式音频、response.cancel 打断
• sayText 文本合成（含自发回复音频/文字防护）
• 安全模型：rt-ticket HMAC 票据 + realtime-proxy（服务端持 Key）
• 静音保活：无输入 200ms 推 200ms 静音，防服务端断开 AudioServerNoAudioInputTooLongError
• 重连：最多 3 次，指数退避

售后与定制

• 售后：评论区公开提问，工作日 24 小时内回复；严重 Bug（影响正常通话）3 个工作日内修复
• 定制开发：行业词表预置、特定客户人设模板、iOS 提前接入、音色定制、与 uni-im/自有 IM 对接等，留言或私信联系作者报价

（本插件不含豆包官方 API 使用费，需在火山引擎控制台自行开通与计费。）