更新记录

1.0.8（2026-03-25）

优化代码

1.0.7（2026-03-25）

优化代码

1.0.6（2026-03-25）

更新demo

平台兼容性

uni-app(4.56)

xb-webrtc

xb-webrtc 是一个基于 UTS 的 uni-app 原生插件，用于在 App 端播放 WebRTC 视频流，并提供远端音频控制、数据通道控制、对讲、截图保存、分辨率切换等能力。

当前插件已经回到“播放器内部协商”模式：

• 页面层只传入 playUrl
• 插件内部会根据地址类型完成协商
• 多地址适配逻辑已收回插件目录

当前内置支持：

• 直接 HTTP SDP 接口
• 腾讯云 webrtc:// 拉流地址

适用平台

• uni-app App-Android
• uni-app App-iOS

对外导出

插件当前对外导出的核心类为：

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

推荐接入流程

推荐使用“页面只传地址，播放器内部协商”模式：

1. 页面创建播放器实例
2. 调用 setPlaybackOptions(enableAudio, enableDataChannel) 声明主/子播放器角色
3. 直接调用 start()
4. 插件内部根据 playUrl 类型完成信令请求和 offer/answer 协商
5. 协商成功后继续使用音频、截图、云台、分辨率、对讲等能力

最小示例：

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

const player = new WebRtcMonitorPlayer(playerId, playUrl)
player.setPlaybackOptions(true, true)
player.start()

说明：

• 页面层不需要自己维护不同类型地址的协商逻辑
• 地址适配公共逻辑已收口到 utssdk/index.uts
• Android / iOS 只保留各自的原生渲染、网络请求和平台能力实现

目录说明

当前插件目录里与播放链路最相关的文件如下：

• utssdk/interface.uts
  • 页面层可见接口声明
• utssdk/index.uts
  • 跨平台公共逻辑
  • 包括地址类型识别、腾讯 webrtc:// 辅助、基础信息提取、编解码解析、控制通道可用性判断
• utssdk/app-android/index.uts
  • Android 侧播放器实现
• utssdk/app-ios/index.uts
  • iOS 侧播放器实现

这样做的目的：

• 后续新增新的播放地址类型时，优先改 utssdk/index.uts 中的公共决策逻辑
• 平台差异仅保留在 Android / iOS 各自必须不同的实现层

构造函数

new WebRtcMonitorPlayer(playerId, url)

创建一个播放器实例。

参数：

• playerId: string
  • 播放器原生容器的唯一标识
• url: string
  • WebRTC 播放地址

说明：

• 构造函数只负责创建播放器实例和初始化原生资源
• 不会自动开始播放
• 推荐后续直接调用 start()
• url 会被实例保留，播放器内部会按地址类型选择协商方式
• 当前页面层应只关心 playUrl，不要再自己区分不同厂商的协商流程

实例方法

start(): void

开始播放。

行为：

• 初始化 WebRTC 连接
• 创建 PeerConnection
• 创建本地 offer
• 按 playUrl 类型自动完成 offer/answer 协商
• 收到远端流后开始渲染

说明：

• 这是当前推荐接入方式
• 页面层无需区分 webrtc:// 还是 HTTP SDP 地址
• 插件内部会根据地址类型自动走对应协商路径

内部当前支持的协商分支：

• plain-http
  • 直接把本地 offer 发到 HTTP SDP 接口
• tencent-webrtc
  • 先请求 signal_query
  • 再请求 /webrtc/v1/pullstream
  • 最后取回远端 answer SDP

prepareLocalOffer(onSuccess, onError): void

高级扩展接口：开始一次外部信令驱动的协商流程，并在本地 offer 生成完成后把 SDP 回传给页面层。

参数：

• onSuccess: (sdp: string) => void
  • 本地 offer SDP 生成成功后的回调
• onError: (message: string) => void
  • 本地协商初始化失败时的回调

行为：

• 清理旧连接
• 创建 PeerConnection
• 添加 recvonly transceiver
• 按当前配置决定是否创建 DataChannel
• 创建本地 offer
• 将本地 offer SDP 通过 onSuccess 回传

说明：

• 这是高级扩展能力，不是默认推荐方式
• 页面拿到本地 offer 后，应自行向业务服务端换取远端 answer
• 如果当前已处于 connecting，内部会忽略重复调用
• 只有在你明确要接入插件尚未内置的信令协议时，才建议使用这组接口

applyRemoteAnswerSdp(answerSdp): void

把页面层获取到的远端 answer SDP 回灌给播放器，完成 setRemoteDescription。

参数：

• answerSdp: string
  • 服务端返回的远端 answer SDP

说明：

• 通常和 prepareLocalOffer() 成对使用
• 如果 peerConnection 已释放，原生层会通过错误回调返回失败原因
• 远端流成功设置后，播放器会继续等待远端音视频轨并开始渲染

stop(): void

停止播放。

行为：

• 关闭当前 WebRTC 连接
• 停止数据通道和媒体流处理
• 保留播放器容器本身

说明：

• stop() 不等于 destroy()
• 停止后仍可以再次发起新的 prepareLocalOffer() 或 start()

destroy(): void

销毁播放器。

行为：

• 释放播放器相关原生资源
• 清理渲染器、连接、数据通道、对讲等状态

说明：

• 调用后当前实例不应继续复用
• 如需再次播放，建议重新创建实例

setPlaybackOptions(enableAudio, enableDataChannel): void

设置当前播放器的播放能力。

参数：

• enableAudio: boolean
  • 是否启用远端音频接收
• enableDataChannel: boolean
  • 是否启用数据通道

典型用途：

• 主播放器：setPlaybackOptions(true, true)
• 子播放器：setPlaybackOptions(false, false)
• 纯播放型流：setPlaybackOptions(true, false) 或 setPlaybackOptions(false, false)

说明：

• 数据通道相关能力依赖 enableDataChannel = true
• 声音相关能力依赖 enableAudio = true
• 建议在发起协商前调用该方法
• 插件内部还会结合播放地址类型再做一次能力收敛
  • 例如腾讯 webrtc:// 拉流默认不启用控制通道相关能力

getStreamBasicInfoJson(): string

获取播放器当前基础流信息，返回 JSON 字符串。

返回示例：

{
  "protocol": "WebRTC",
  "host": "global-lebtest-play.myqcloud.com",
  "videoCodec": "H264",
  "audioCodec": "OPUS",
  "controlChannel": "关闭"
}

说明：

• 推荐页面层自行 JSON.parse(...) 后使用
• videoCodec / audioCodec 在协商完成前可能是 未知
• 当前之所以返回字符串而不是对象，是为了规避部分 Android 场景下的对象桥接问题

getStreamCapabilitiesJson(): string

获取当前播放地址与实例配置共同决定的能力信息，返回 JSON 字符串。

返回示例：

{
  "dataChannel": false,
  "talk": false,
  "ptz": false,
  "resolution": false
}

说明：

• 页面可据此决定是否显示云台、分辨率、对讲等按钮
• 推荐页面层自行 JSON.parse(...) 后使用

setRemoteAudioEnabled(enabled): boolean

设置远端声音开关。

参数：

• enabled: boolean
  • true 开启声音
  • false 关闭声音

返回值：

• true
  • 已成功应用到当前远端音频流
• false
  • 当前没有可用远端音频流，或播放器未启用音频

说明：

• 如果流尚未到达，原生层会先记录状态，待远端音频轨可用后再应用
• 如果播放器本身未启用音频，该方法会返回 false

ptzDirectionControl(command): boolean

发送云台控制命令。

参数：

• command: number
  • 具体命令码由设备协议决定

返回值：

• true
  • 命令已通过数据通道发送成功
• false
  • 数据通道未就绪或发送失败

说明：

• 该方法依赖数据通道已建立
• 也依赖业务信令链路本身支持 m=application / DataChannel
• 通常用于上、下、左、右及停止命令发送

changeResolution(value): boolean

切换设备分辨率。

参数：

• value: number
  • 分辨率值由设备协议决定

返回值：

• true
  • 命令已发送成功
• false
  • 数据通道未就绪或发送失败

说明：

• 该方法本质上也是通过数据通道向设备发送控制指令

captureAndSaveToGallery(): string

截图并保存到系统相册。

返回值：

• 成功时返回保存结果字符串
• 失败时返回空字符串，或由原生层抛出异常

说明：

• Android 侧通过原生截图并写入系统相册
• iOS 侧通过原生截图并写入系统相册
• 最终是否成功取决于系统权限状态
• 与数据通道是否启用无关

startTalk(sampleRate): boolean

开始对讲。

参数：

• sampleRate: number
  • 目标采样率，通常使用 8000 或 16000

返回值：

• true
  • 对讲流程已开始或授权流程已发起
• false
  • 对讲启动失败

说明：

• 依赖数据通道可用
• 依赖麦克风权限已授权
• 原生层会负责采集音频、编码并通过数据通道发送
• 如果当前流类型不支持数据通道，对讲能力也不可用

stopTalk(): boolean

停止对讲。

返回值：

• true
  • 对讲已停止，或当前本就未在对讲
• false
  • 停止失败

实例回调属性

onStateChanged?: (state) => void

播放器状态变化回调。

状态值：

• 0：idle
• 1：connecting
• 2：playing
• 3：reconnecting
• 4：error

onErrorCallback?: (message) => void

播放器错误回调。

参数：

• message: string
  • 原生层返回的错误文本

说明：

• 这两个回调属性保留给 UTS 页面或高级接入场景使用
• 如果页面是普通 ts/js 脚本，建议优先使用 start() + JSON 字符串 getter 的方式
• 原因是部分 Android 场景下，函数属性桥接稳定性不如普通方法调用

注意事项

• start() 是当前推荐接入方式
• 默认应由插件内部根据 playUrl 类型完成协商
• prepareLocalOffer() + applyRemoteAnswerSdp() 仅在你确实需要自定义信令时再使用
• start()、ptzDirectionControl()、changeResolution()、startTalk() 等能力依赖底层连接状态
• setRemoteAudioEnabled() 仅在播放器启用音频时有效
• ptzDirectionControl()、changeResolution()、startTalk() 依赖数据通道启用
• 不是所有 WebRTC 播放地址都支持数据通道；对这类地址应关闭 enableDataChannel
• stop() 用于停止连接，destroy() 用于彻底释放实例
• 多播放器场景下，建议只给主播放器开启音频和数据通道
• 如果页面需要展示真实 视频格式/音频格式，推荐通过 getStreamBasicInfoJson() 拉取，不要依赖对象桥接

开发文档

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