更新记录

1.0.4（2026-04-19）

优化一对一通话。更新文档

1.0.3（2026-04-17）

更新安卓版

1.0.2（2026-04-16）

更新文档，优化一对一通话视图，增加音频设置

平台兼容性

uni-app(4.81)

RTC VolcEngine 组件

火山引擎实时音视频 SDK UTS 插件，支持 AI 语音通话、视频通话、字幕、录制等功能。

安装

将 rtc-volcengine 插件放入 uni_modules 目录。

基础用法

<template>
  <view class="container">
    <!-- RTC 组件，会自动创建本地和远端视频视图 -->
    <rtc-volcengine 
      ref="rtcRef" 
      @onEngineReady="onEngineReady"
      @onRoomStateChanged="onRoomStateChanged"
      @onUserJoined="onUserJoined"
      @onUserLeave="onUserLeave"
      @onAudioRouteChanged="onAudioRouteChanged"
      @onLog="onRTCLog"
      @onTokenWillExpire="handleTokenWillExpire"
    />

    <button @click="joinRoom">加入房间</button>
    <button @click="leaveRoom">离开房间</button>
    <button @click="interruptAI">打断AI</button>
    <button @click="toggleMute">静音/取消静音</button>
    <button @click="toggleSpeaker">扬声器/听筒</button>
    <button @click="switchCamera">切换摄像头</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      isMuted: false,
      isSpeaker: true
    }
  },
  methods: {
    // 初始化并加入房间
    joinRoom() {
      this.$refs.rtcRef.initEngine('YOUR_APP_ID', false)
    },

    // 引擎初始化完成回调
    onEngineReady(e) {
      const { success, message } = e.detail
      if (!success) return

      // 设置音频场景
      this.$refs.rtcRef.setAudioScenario(5)  // AI客户端
      this.$refs.rtcRef.setAnsMode(4)         // 自动降噪
      this.$refs.rtcRef.enablePlaybackDucking(true)
      this.$refs.rtcRef.enableVocalInstrumentBalance(true)
      this.$refs.rtcRef.enableAudioPropertiesReport(500)

      // 设置默认音频路由为扬声器
      this.$refs.rtcRef.setDefaultAudioRoute(3)
      this.$refs.rtcRef.setAudioRoute(-1)

      // 显示本地视频
      this.$refs.rtcRef.showLocalVideo()

      // 加入房间
      this.$refs.rtcRef.joinRoom(
        'ROOM_ID', 'USER_ID', 'TOKEN',
        true, true,    // 发布音频、发布视频
        true, true,    // 订阅音频、订阅视频
        true, true,    // 启动音频采集、启动视频采集
        19             // Call 通话模式
      )
    },

    // 房间状态变化
    onRoomStateChanged(e) {
      const { roomId, userId, state, extraInfo } = e.detail
      // state: 0=加入房间成功, !0=失败/异常退房/警告或错误
      if (state === 0) {
        console.log('加入房间成功')
      } else {
        console.log('房间异常, state=', state)
      }
    },

    // 远端用户加入 - 绑定远端视频
    onUserJoined(e) {
      const remoteUserId = e.detail.userId
      this.$refs.rtcRef.setupRemoteVideo(remoteUserId)
    },

    // 用户离开
    onUserLeave(e) {
      this.$refs.rtcRef.hideRemoteVideo()
    },

    // 离开房间
    leaveRoom() {
      this.$refs.rtcRef.hideLocalVideo()
      this.$refs.rtcRef.hideRemoteVideo()
      this.$refs.rtcRef.leaveRoom()
      this.$refs.rtcRef.destroyEngine()
    },

    // 打断AI说话
    interruptAI() {
      this.$refs.rtcRef.sendInterruptMessage('AI_BOT_ID')
    },

    // 静音/取消静音
    toggleMute() {
      this.isMuted = !this.isMuted
      this.$refs.rtcRef.muteAudioCapture(this.isMuted)
    },

    // 扬声器/听筒切换
    toggleSpeaker() {
      this.isSpeaker = !this.isSpeaker
      this.$refs.rtcRef.setDefaultAudioRoute(this.isSpeaker ? 3 : 2)
      this.$refs.rtcRef.setAudioRoute(-1)
    },

    // 切换摄像头
    switchCamera() {
      this.$refs.rtcRef.switchCamera()
    },

    // 音频路由变化回调
    onAudioRouteChanged(e) {
      const route = e.detail.route
      console.log('音频路由变化:', route)
    },

    // 原生日志回调
    onRTCLog(e) {
      console.log('[Native]', e.detail.message)
    },

    // Token 即将过期
    handleTokenWillExpire() {
      // 调用后端获取新 Token，然后更新
      this.$refs.rtcRef.updateToken(newToken)
    }
  },

  onUnload() {
    this.$refs.rtcRef.leaveRoom()
    this.$refs.rtcRef.destroyEngine()
  }
}
</script>

事件回调列表

所有事件回调的数据在 e.detail 中获取。

方法列表

引擎管理

房间管理

音频控制

音频路由

音频路由值说明：

切换扬声器/听筒的正确方式：

// 切换到扬声器
this.$refs.rtcRef.setDefaultAudioRoute(3)  // 设默认路由为扬声器
this.$refs.rtcRef.setAudioRoute(-1)         // 切到默认路由

// 切换到听筒
this.$refs.rtcRef.setDefaultAudioRoute(2)  // 设默认路由为听筒
this.$refs.rtcRef.setAudioRoute(-1)         // 切到默认路由

注意：setAudioRoute 仅支持扬声器和默认路由，不能直接传入听筒(2)。切换听筒必须通过 setDefaultAudioRoute(2) + setAudioRoute(-1) 组合实现。

视频控制

消息发送

字幕

本地录制

joinRoom 参数说明

joinRoom(
  roomId,            // string - 房间ID
  userId,            // string - 用户ID
  token,             // string - Token
  publishAudio,      // boolean - 是否发布音频，默认 true
  publishVideo,      // boolean - 是否发布视频，默认 true
  subscribeAudio,    // boolean - 是否订阅音频，默认 true
  subscribeVideo,    // boolean - 是否订阅视频，默认 true
  startAudioCapture, // boolean - 是否启动音频采集，默认 true
  startVideoCapture, // boolean - 是否启动视频采集，默认 true
  roomProfile        // number - 房间模式，默认 0 (Communication)，进房后不可更改
)

注意：joinRoom 不支持回调参数，加入房间的结果通过 onRoomStateChanged 事件获取。当 state === 0 时表示加入成功，state !== 0 时表示失败或异常。

roomProfile 枚举值

典型场景示例

AI 语音通话 + 字幕 + 录制

<template>
  <rtc-volcengine 
    ref="rtcRef"
    @onEngineReady="onEngineReady"
    @onRoomStateChanged="onRoomStateChanged"
    @onUserJoined="onUserJoined"
    @onRemoteAudioProperties="onRemoteAudioProperties"
    @onSubtitleMessage="onSubtitleMessage"
    @onRoomBinaryMessage="onRoomBinaryMessage"
    @onTokenWillExpire="handleTokenWillExpire"
    @onRecordingState="onRecordingState"
    @onLog="onRTCLog"
  />
</template>

<script>
export default {
  methods: {
    onEngineReady(e) {
      if (!e.detail.success) return

      // 设置 AI 语音场景
      this.$refs.rtcRef.setAudioScenario(5)  // AI客户端
      this.$refs.rtcRef.setAnsMode(4)        // 自动降噪
      this.$refs.rtcRef.enablePlaybackDucking(true)
      this.$refs.rtcRef.enableVocalInstrumentBalance(true)

      // 启用音量回调
      this.$refs.rtcRef.enableAudioPropertiesReport(200)

      // 设置默认音频路由为扬声器
      this.$refs.rtcRef.setDefaultAudioRoute(3)
      this.$refs.rtcRef.setAudioRoute(-1)

      // 加入房间（结果通过 onRoomStateChanged 事件获取）
      this.$refs.rtcRef.joinRoom(
        'ROOM_ID', 'USER_ID', 'TOKEN',
        true, false,   // 发布音频，不发布视频
        true, false,   // 订阅音频，不订阅视频
        true, false,   // 启动音频采集，不启动视频采集
        19             // Call 通话模式
      )
    },

    onRoomStateChanged(e) {
      const { state } = e.detail
      // state: 0=加入房间成功, !0=失败/异常
      if (state === 0) {
        // 加入成功后开启字幕
        this.$refs.rtcRef.startSubtitle(0, '')  // 识别模式
        // 开始录制
        this.$refs.rtcRef.startFileRecording('/path/to/save', 0, 1)  // 仅音频，MP4
      }
    },

    onUserJoined(e) {
      // 远端用户加入，绑定远端视频
      this.$refs.rtcRef.setupRemoteVideo(e.detail.userId)
    },

    onRemoteAudioProperties(e) {
      console.log(`远端 ${e.detail.userId} 音量: ${e.detail.volume}`)
    },

    onSubtitleMessage(e) {
      const { userId, text, definite } = e.detail
      console.log(`字幕 [${userId}]: ${text} (确定: ${definite})`)
    },

    onRoomBinaryMessage(e) {
      const { messageType, message, userId } = e.detail
      if (messageType === 'conversation') {
        console.log(`AI状态 [${userId}]: ${message}`)
      } else if (messageType === 'subtitle') {
        console.log(`字幕消息 [${userId}]: ${message}`)
      }
    },

    onRecordingState(e) {
      const { state, errorCode, filePath } = e.detail
      console.log(`录制状态: ${state}, 路径: ${filePath}`)
    },

    onRTCLog(e) {
      // 原生日志，可用于调试
      console.log('[Native]', e.detail.message)
    },

    // 打断 AI 说话
    interruptAI() {
      this.$refs.rtcRef.sendInterruptMessage('AI_USER_ID')
    },

    // 发送自定义消息给 AI
    sendCustomMessage() {
      const json = JSON.stringify({ type: 'command', action: 'pause' })
      this.$refs.rtcRef.sendUserBinaryMessage('AI_USER_ID', json)
    },

    // Token 过期处理
    handleTokenWillExpire() {
      // 调用后端获取新 Token
      const newToken = fetchNewToken()
      this.$refs.rtcRef.updateToken(newToken)
    }
  }
}
</script>

视频通话示例

<template>
  <rtc-volcengine 
    ref="rtcRef"
    style="width: 750rpx; height: 1000rpx;"
    @onEngineReady="onEngineReady"
    @onRoomStateChanged="onRoomStateChanged"
    @onUserJoined="onUserJoined"
    @onUserLeave="onUserLeave"
    @onAudioRouteChanged="onAudioRouteChanged"
  />
</template>

<script>
export default {
  data() {
    return {
      isMuted: false,
      isVideoOff: false,
      isSpeaker: true
    }
  },
  methods: {
    onEngineReady(e) {
      if (!e.detail.success) return

      // 通话场景设置
      this.$refs.rtcRef.setAudioScenario(5)
      this.$refs.rtcRef.setAnsMode(4)
      this.$refs.rtcRef.enablePlaybackDucking(true)
      this.$refs.rtcRef.enableVocalInstrumentBalance(true)
      this.$refs.rtcRef.enableAudioPropertiesReport(500)

      // 默认扬声器
      this.$refs.rtcRef.setDefaultAudioRoute(3)
      this.$refs.rtcRef.setAudioRoute(-1)

      // 显示本地视频
      this.$refs.rtcRef.showLocalVideo()

      // 加入视频通话
      this.$refs.rtcRef.joinRoom(
        'ROOM_ID', 'USER_ID', 'TOKEN',
        true, true,    // 发布音频+视频
        true, true,    // 订阅音频+视频
        true, true,    // 启动音频+视频采集
        19             // Call 通话模式
      )
    },

    onRoomStateChanged(e) {
      if (e.detail.state === 0) {
        console.log('加入房间成功')
      }
    },

    onUserJoined(e) {
      // 绑定远端视频
      this.$refs.rtcRef.setupRemoteVideo(e.detail.userId)
    },

    onUserLeave(e) {
      this.$refs.rtcRef.hideRemoteVideo()
    },

    // 音频路由变化
    onAudioRouteChanged(e) {
      const routeMap = { '-1': '默认', '1': '有线耳机', '2': '听筒', '3': '扬声器', '4': '蓝牙耳机', '5': 'USB耳机' }
      this.isSpeaker = (String(e.detail.route) === '3')
    },

    // 控制方法
    toggleMute() {
      this.isMuted = !this.isMuted
      this.$refs.rtcRef.muteAudioCapture(this.isMuted)
    },

    toggleVideo() {
      this.isVideoOff = !this.isVideoOff
      this.$refs.rtcRef.enableLocalVideo(!this.isVideoOff)
      this.isVideoOff ? this.$refs.rtcRef.hideLocalVideo() : this.$refs.rtcRef.showLocalVideo()
    },

    switchCamera() {
      this.$refs.rtcRef.switchCamera()
    },

    toggleSpeaker() {
      this.isSpeaker = !this.isSpeaker
      this.$refs.rtcRef.setDefaultAudioRoute(this.isSpeaker ? 3 : 2)
      this.$refs.rtcRef.setAudioRoute(-1)
    },

    leaveRoom() {
      this.$refs.rtcRef.hideLocalVideo()
      this.$refs.rtcRef.hideRemoteVideo()
      this.$refs.rtcRef.leaveRoom()
      this.$refs.rtcRef.destroyEngine()
    }
  },

  onUnload() {
    this.$refs.rtcRef.leaveRoom()
    this.$refs.rtcRef.destroyEngine()
  }
}
</script>

Token 过期处理流程

1. 加入房间时传入 Token
   │
   ▼
2. 正常通话中...
   │
   ▼
3. Token 过期前 30 秒，触发 onTokenWillExpire 回调
   │
   ▼
4. 调用后端接口获取新 Token
   │
   ▼
5. 调用 updateToken(newToken) 更新 Token
   │
   ▼
6. 继续正常通话...

注意事项

1. 平台支持：支持 iOS 12+ 和 Android
2. 初始化顺序：必须先调用 initEngine，等待 onEngineReady 回调成功后才能调用其他方法
3. Token 有效期：建议设置合理的有效期，并在过期前通过 onTokenWillExpire 回调更新
4. 打断 AI：sendInterruptMessage 使用特殊的 ctrl+interrupt 二进制协议，内部已处理
5. 静音 vs 停用：muteAudioCapture(true) 静音但采集继续；enableLocalAudio(false) 完全停止采集
6. 录制：startFileRecording 的 type 和 fileType 可选，默认录制音视频 MP4
7. 内存管理：离开页面时务必调用 destroyEngine() 释放资源，组件卸载时会自动离开房间
8. 回调线程：所有回调已在内部切换到主线程，可直接操作 UI
9. joinRoom 回调：joinRoom 不支持传入 success/fail 回调参数，传入会导致 iOS 闪退。加入房间结果请通过 onRoomStateChanged 事件监听（state === 0 表示加入成功）
10. 音频路由：setAudioRoute 仅支持扬声器(3)和默认路由(-1)，切换听筒必须通过 setDefaultAudioRoute(2) + setAudioRoute(-1) 组合
11. 远端视频：调用 setupRemoteVideo(userId) 绑定远端视频后，Swift 端会在收到首帧解码时自动用正确的 streamId 重新绑定画布
12. 原生日志：Swift 端所有日志通过 onLog 事件回调返回，不在 Xcode 控制台打印
13. 大小窗切换：toggleVideoLayout 仅交换渲染目标，不改 LayoutParams，零布局开销，切换非常快
14. 视频朝向：setVideoOrientation 是 SDK 层面的视频帧朝向设置，影响整个 RTC 链路（采集→编码→传输→渲染），不是简单的 View 旋转
15. 头像占位：setRemoteAvatar 在远端未加入时显示头像占位，远端加入后自动隐藏；退出房间时头像会自动清除
16. 占位图片：setDummyCaptureImagePath 在摄像头关闭（stopVideoCapture）后开始推送静态图片，重新开启采集或传空字符串可停止