更新记录

1.0.9（2026-03-25）

修复bug

1.0.8（2026-03-25）

优化代码

1.0.7（2026-03-25）

修复bug

平台兼容性

uni-app x(4.56)

vee-webrtc

vee-webrtc 是一个 uni-app x UTS 组件插件，用于监控场景的 WebRTC 播放与控制，支持 Android / iOS。

版本

• 当前版本：1.0.7

功能概览

• WebRTC 拉流播放（主画面 / 子画面）
• 远端声音开关
• 对讲（DataChannel 上行音频）
• 云台控制（PTZ）
• 分辨率切换
• 截图保存到系统相册

插件职责

vee-webrtc 当前采用“插件负责媒体能力和地址协商，页面只传播放地址”的结构：

• 插件层负责：
  • 创建 PeerConnection
  • 根据播放地址类型选择对应 provider
  • 生成本地 offer
  • 请求远端 answer
  • 应用远端 answer
  • 视频渲染
  • 远端音频开关
  • 对讲、云台、分辨率、截图等控制能力
• 页面层负责：
  • 传入播放地址
  • 组织多画面和 UI 展示

这样做的目的很直接：不同厂商地址差异仍然由插件内部 provider 处理，页面不需要再维护协商分支。

快速接入

1. 页面模板

<template>
  <vee-webrtc class="player-view" @initElement="onPlayerElement"></vee-webrtc>
</template>

2. 创建播放器实例

import { WebRtcMonitorPlayer } from '@/uni_modules/vee-webrtc'

let player : WebRtcMonitorPlayer | null = null

const onPlayerElement = (element : UniNativeViewElement) => {
  const playUrl = 'https://xxx/index/api/webrtc?...'
  player = new WebRtcMonitorPlayer(element, playUrl)
  // 主画面建议：开启音频与数据通道
  player.setPlaybackOptions(true, true)
}

3. 开始播放

player?.start()

4. 获取流信息与能力

const streamInfo = player?.getStreamInfo()
const streamCapabilities = player?.getStreamCapabilities()

// 示例：
// streamInfo?.protocol
// streamInfo?.videoCodec
// streamCapabilities?.dataChannel

5. 常用控制

player?.stop()

// 声音
player?.setRemoteAudioEnabled(true)
player?.setRemoteAudioEnabled(false)

// 对讲
player?.startTalk(8000)   // 或 16000
player?.stopTalk()

// 云台 / 分辨率
player?.ptzDirectionControl(0) // 上，按设备协议填写命令
player?.changeResolution(2)    // 按设备协议填写分辨率值

// 截图
const result = player?.captureAndSaveToGallery() ?? ''

6. 推荐播放方式：页面只调用 start

当播放地址可能存在多种类型（如普通 https:// SDP 接口、webrtc:// 信令地址）时，页面无需关心地址差异，直接调用：

player?.start()

说明：

• 插件内部会根据 playUrl 自动选择地址 provider
• 当前已内置：
  • https://...
  • http://...
  • webrtc://...
• DataChannel 能力由插件根据地址类型自动判定
• 如需页面层完全接管协商，仍可继续使用：
  • prepareLocalOffer()
  • applyRemoteAnswerSdp()

地址适配结构

地址适配逻辑已收敛到插件跨平台入口：

• uni_modules/vee-webrtc/utssdk/index.uts
  • 统一维护多地址类型解析
  • 当前内置 https:// / http:// / webrtc://
  • 负责输出流信息与控制能力
• uni_modules/vee-webrtc/utssdk/interface.uts
  • 对外接口声明
• uni_modules/vee-webrtc/utssdk/app-android/index.uts
  • Android 原生实现
• uni_modules/vee-webrtc/utssdk/app-ios/index.uts
  • iOS 原生实现
• uni_modules/vee-webrtc/components/vee-webrtc/vee-webrtc.uvue
  • 组件包装层

当前支持的测试地址类型：

• https://...
• webrtc://...

测试地址配置入口：

• pages/index/webrtc_api.uts
• 通过 TEST_PLAY_URLS 统一维护测试流地址

如何扩展新的地址类型

如果后续要接入新的厂商地址，不建议继续改 index.uvue，也不建议把逻辑堆回插件里。推荐按下面的方式扩展：

1. 新建一个 provider 文件，例如：
   • 建议先在 uni_modules/vee-webrtc/utssdk/index.uts 内补充对应 provider
2. 实现 4 个函数：
   • canHandleXxx(playUrl)
   • getXxxCapabilities(playUrl)
   • buildXxxInfo(playUrl, answerSdp)
   • resolveXxx(playUrl, localOfferSdp)
3. 在 uni_modules/vee-webrtc/utssdk/index.uts 中注册 provider
4. 如需测试，直接把地址加到 TEST_PLAY_URLS

这样新增地址协议时，改动会被限制在插件公共层，不会影响页面主流程。

多画面推荐策略

• 主画面：setPlaybackOptions(true, true)
• 子画面：setPlaybackOptions(true, false)（保留音频轨，默认静音）
• 子画面建议额外调用一次 setRemoteAudioEnabled(false)，避免多路同时出声

API 说明

WebRtcMonitorPlayer 对外主要方法：

• start()：开始播放
• stop()：停止播放
• destroy()：销毁实例
• getStreamInfo()：获取当前流信息，返回 UTSJSONObject
• getStreamCapabilities()：获取当前流能力，返回 UTSJSONObject
• prepareLocalOffer(onSuccess, onError)：生成本地 offer SDP，供页面层自行换取 answer
• applyRemoteAnswerSdp(answerSdp)：应用页面层获取到的远端 answer SDP
• setPlaybackOptions(enableAudio, enableDataChannel)：设置音频接收与数据通道开关
• setRemoteAudioEnabled(enabled)：开启/关闭远端声音
• startTalk(sampleRate)：开始对讲，sampleRate 支持 8000/16000
• stopTalk()：停止对讲
• ptzDirectionControl(command)：发送云台控制命令
• changeResolution(value)：发送分辨率切换命令
• captureAndSaveToGallery()：截图并保存到相册

推荐调用顺序

页面层推荐顺序如下：

1. new WebRtcMonitorPlayer(element, playUrl)
2. setPlaybackOptions(enableAudio, enableDataChannel)
3. start()
4. 需要展示信息时读取：
   • getStreamInfo()
   • getStreamCapabilities()
5. 稳定播放后再启用：
   • setRemoteAudioEnabled(true/false)
   • startTalk(sampleRate)
   • ptzDirectionControl(command)
   • changeResolution(value)

权限与配置

Android

• 需声明麦克风权限：
  • <uses-permission android:name="android.permission.RECORD_AUDIO" />
• 对讲前建议先做运行时权限申请。

iOS

• 需在应用配置中提供麦克风与相册写入权限文案（如 NSMicrophoneUsageDescription、NSPhotoLibraryAddUsageDescription）。
• 截图首次会触发相册授权，授权后会自动保存。

常见问题

• 加密后编译报 Parse error：
  • 跨平台公共 UTS 代码应放在 utssdk/index.uts，不要把页面直接引用的逻辑拆到插件外部自定义目录。
• 对讲点击后失败：
  • 先确认 DataChannel 已连接（播放器已进入稳定播放状态后再开启对讲）。
  • 确认麦克风权限已授权。
• 截图保存失败：
  • iOS 自定义基座需包含相关媒体能力。
  • Android 请确认系统相册写入流程可用。

版本更新

• 详见 uni_modules/vee-webrtc/changelog.md

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS