iOS API

最近更新时间:2025-09-23 10:21:51

我的收藏

API 描述

本文档为 iOS 平台 API, 适用于苹果 iOS 系统 iOS 12.0及以上版本,使用时请先在项目中配置引用 SDK 包。

CocoaPods 配置方式

1. 将 TRROControl.zip 解压至目标目录,解压后包含三个文件:LocalTrroSDK.podspec、rtc_engine.xcframework、TRROControl.framework。

2. 并在项目 podfile 文件中进行配置:
pod 'LocalTrroSDK', :path => './TRROControl'

原生 Xcode 工程配置方式

1. 将 rtc_engine、TRROControl 两个 framework 库拖入 Link Binary With Libraries 中。
2. 设置 rtc_engine、TRROControl 为 Embed & Sign,截图如下。
3. Other Linker Flags 中添加“-lc++ -lz -ObjC”三个选项。到此配置基本完成。

注意:
如果报 framework 找不到,则需配置 Build Settings 中的 Framework Search Paths

API 概览

TrroRemote

SDK 功能主入口。
注意:
方法都是同步阻塞模式,尽量放到子线程中执行。
API
描述
获取 TrroRemote 单例。
销毁 TrroRemote 单例。
设置 SDK 事件监听及回调队列。
使用配置参数启动 SDK。
使用 JSON 配置启动 SDK。
设置临时会话授权,用于连接现场设备临时会话身份验证。
getGwList
获取在线现场设备列表。
获取对应现场设备的信息。
连接现场设备单个视频流。
连接现场设备多个视频流。
切换解码方式。
true:外部解码。
false:内部解码(软解)。
关闭指定视频连接。
关闭所有视频连接。
给现场设备发送控制数据。
现场设备音频设置。
外部音频数据输入(PCM 数据),16位音频采样。
本地设备音频设置。
向网关发出权限请求。
获取 SDK 版本号。

sharedInstance

获取 TrroControl 单例。

+ (instancetype)sharedInstance;


destroySharedInstance

销毁 TrroControl 单例。
+ (void)destroySharedInstance;

setDelegate:delegateQueue

设置 SDK 事件监听及回调队列。
- (void)setDelegate:(id<TrroControlDelegate>)delegate
      delegateQueue:(dispatch_queue_t)delegateQueue;
参数
描述
delegate
回调代理实例。
delegateQueue
回调代理队列,默认为主队列。

setupWithOptions

使用 options 配置方式初始化控制端,接口为同步阻塞模式。
- (int)setupWithOptions:(TrroOptions *)trroOptions;
参数
描述
options
配置选项,选项说明参考 TrroOptions 说明。
@return
成功 1,失败 <= 0。

setupWithJson

使用 JSON 配置启动 SDK,接口为同步阻塞模式。
- (int)setupWithJson:(NSString *)jsonStr;
参数
描述
jsonStr
JSON 格式说明参见 代码示例
@return
回调:成功 1,失败 <= 0。

setSessionPermissionToken

设置临时会话授权,用于连接现场设备时的临时会话身份验证。返回值:成功1 失败<=0。
- (int)setSessionPermissionToken:(NSString *)signature gwid:(NSString *)gwid;
参数
描述
gwid
目标会话现场设备 ID。
signature
基于项目共享密钥签发的临时会话授权签名。

getGwList

获取在线现场设备的列表,接口为同步阻塞模式.
- (TrroGatewayList*)getGwList;
参数
描述
@return
回调网关列表,具体参见 TrroGateWayList

getGwInfoForGwid

获取对应网关的详细信息,接口为同步阻塞模式。
- (TrroGateway *)getGwInfoForGwid:(NSString *)gwid;
参数
描述
@return
回调网关列表,具体参见 TrroGateWay

connectToGwid:connectParam

连接1路视频流,接口为同步阻塞模式。
- (int)connectToGwid:(NSString *)gwid connectParam:(TrroConnectParam *)connectParam;
参数
描述
gwid
目标现场设备 ID。
connectParam
视频流配置信息,详细参见 TrroConnectParam
@return
成功:1,失败:<=0。

connectToGwid:connectParamList

发起视频连接,可多次调用连接不同流,接口为同步阻塞模式。
- (int)connectToGwid:(NSString *)gwid connectParamList:(NSArray<TrroConnectParam *> *)connectParamList;
参数
描述
gwid
目标现场设备 ID。
connectParamList
视频流配置信息数组,详细参见 TrroConnectParam
@return
成功:1,失败:<=0。

switchDecoder

切换解码方式。
注意:
默认为 false,编码流和解码流都会通过 Delegate 回调,设置为 true 后,Delegate 只回调编码流。如果需要自行解码,需要设置为 true,避免 SDK 多余的软解操作。
- (int)switchDecoder:(BOOL)external;
参数
描述
external
是否自定义解码。
@return
成功:1 ,失败:<= 0。

disconnect

关闭 connFds 对应的视频连接。
- (int)disconnect:(NSArray<NSNumber *> *)connFds;
参数
描述
connFds
要关闭视频连接对应的视频接收句柄数组。
@return
成功:1 失败:<= 0。

disconnectAll

关闭所有视频连接。
- (int)disconnectAll;
参数
说明
@return
成功:1,失败:<=0。

sendControlMsg:qos:toGwid

 给现场设备发送控制数据。
- (int)sendControlMsg:(NSData *)msg qos:(int)qos toGwid:(NSString *)gwid;
参数
描述
msg
发送消息,二进制字节透传。
qos
消息传输 QoS。
0:不可靠传输。
1:可靠传输。
gwid
目标现场设备 ID。
@return
成功:1,失败:<=0。

audioMute:forGwid

Mute/unMute 目标现场设备的音频。
- (int)audioMute:(BOOL)mute forGwid:(NSString *)gwid;
参数
描述
mute
true:静音。
false:取消静音。
gwid
目标现场设备 ID。
@return
成功:1,失败:<=0。

externalAudioData:channel:sampleRate:forGwid

外部音频数据输入(PCM 数据), 16位音频采样,每次输入10ms数据。
- (int)externalAudioData:(NSData *)data
                 channel:(int)channel
              sampleRate:(int)sampleRate
                 forGwid:(NSString *)gwid;
参数
描述
data
音频 PCM 数据,16位音频采样,10ms数据。
channel
音频声道数。
sampleRate
音频采样率。
gwid
网关 ID。
@return
成功:1,失败:<= 0。

localAudioMute

本地设备音频设置。
- (void)localAudioMute:(BOOL)mute;
参数
描述
mute
true:静音。
false:取消静音。

requestPermission:forGwid

向网关发出权限请求。当有多个控制端时,为了可以成功发送消息(sendControlMsg),需要申请 master 权限。
- (int)requestPermission:(Trro_Permission)permission forGwid:(NSString *)gwid;
参数
描述
permission
权限枚举。
gwid
网关 ID。
@return
成功:1 失败:<= 0。

getVersion

获取 SDK 版本号。
- (NSString *)getVersion;

TrroOptions

配置初始化参数,字段说明参考:远端设备配置说明
publicModeWithDeviceId:projectId:password:deviceName:...
构造公有云模式参数。
+ (instancetype)publicModeWithDeviceId:(NSString *)deviceId projectId:(NSString *)projectId password:(NSString *)password deviceName:(NSString *)deviceName maxStreams:(int)maxStreamsaudioReceive:(BOOL)audioReceiveaudioExternal:(BOOL)audioExternallogEnable:(TrroLogEnable)logEnablelogOutputPath:(nullable NSString *)logOutputPath;
参数
描述
deviceId
设备 ID。用于注册到服务器的唯一编码。
projectId
工程 ID。
password
密码。
deviceName
设备名称,用于辨识设备信息。
maxStreams
设备连接的最大流数目。
audioReceive
是否接收网关端音频。
audioExternal
是否自定义音频输入,默认控制端不会输出声音,需要向网关端发送音频,需要将该值设为 true。
logEnable
是否开启日志。
logOutputPath
日志输出路径,默认路径:document/com.tencent.trro/
privateModeWithDeviceId:deviceStreams:deviceName:...
构造私有云模式参数。
+ (instancetype)privateModeWithDeviceId:(NSString *)deviceId deviceStreams:(int)deviceStreamsdeviceName:(NSString *)deviceNameserverIp:(NSString *)serverIpserverPort:(int)serverPort rtcServerIp:(NSString *)rtcServerIprtcServerPort:(int)rtcServerPortaudioReceive:(BOOL)audioReceiveaudioExternal:(BOOL)audioExternal
logOutputPath:(nullable NSString *)logOutputPath;
参数
描述
deviceId
设备 ID。用于注册到服务器的唯一编码。
deviceStreams
设备流数。
deviceName
设备名称,用于辨识设备信息。
serverIp
私有云 IP 地址。
serverPort
私有云 port。
rtcServerIp
私有云 rtc 服务器地址。
rtcServerPort
私有云 rtc port。
audioReceive
是否接收音频。
audioExternal
是否自定义音频输入,默认控制端不会输出声音,需要向网关端发送音频,需要将该值设为 true。
logEnable
是否开启日志。
logOutputPath
日志输出路径,默认路径:document/com.tencent.trro/

TrroConnectParam

属性
描述
streamId
现场设备视频流的 ID 数组, 现场设备视频流 ID 从0开始, 最大值为现场设备支持的 device_streams 数量 -1。
connFd
接收视频流的句柄标识,自行编号,取值从0开始。
videoView
用于视频流显示的控件。
renderConfig
本地渲染模式,如果自行管理渲染 view,则可忽略该字段。具体字段可参考 TrroRenderConfig

TrroRenderConfig

参数
描述
rotation
图像的顺时针旋转角度。{@link TrroVideoRotation}。
fillMode
画面填充模式。{@link TrroVideoFillMode}。
mirror
画面镜像模式。

TrroRemoteDelegate

SDK 事件监听接口。
API
描述
云端信令连接状态回调。
onError
错误信息回调。
网关帧时间戳回调。
时延回调。
接收来自现场设备信息回调。
已解码视频数据回调。
如果关闭 SDK 解码 [TrroRemote.sharedInstance switchDecoder:true],该回调不再回调。
编码视频数据回调。
若在该回调进行外部解码,建议关闭SDK解码[TrroRemote.sharedInstance switchDecoder:true]。
onState
视频流连接状态回调。
日志信息回调。
现场设备推流网络状态信息。
视频流接收传输状态回调。
onLogData
日志信息回调。
 

onSignalState

/**
* @param signalState 信令连接状态枚举
* 0 连接建立成功 1 连接断开,内部会进行自动重连 2 自动重连成功 3 被踢下线 4 用户名或者密码错误
*/
- (void)onSignalState:(int)signalState;

onError

/// 出错事件通知
///   - errorCode 错误码
///   - errorMsg 错误信息
- (void)onError:(NSInteger)errorCode errorMsg:(NSString *)errorMsg;

onVideoTimeReport

/// 网关帧时间戳回调
///   - windowId对应网关流id
///   - gwid    返回网关id
///   -videotime 网关帧时间戳
- (void)onVideoTimeReport:(NSString *)gwid connFd:(int)connFd videoTime:(long long)videoTime;

onAllLatencyReport

/// 时延回调
///   - gwid: 视频来源现场设备 ID。
///   - connFd: 对应视频流接收句柄
///   - latency1: 返回视频传输时延ms
///   - latency2: 返回视频+控制回环时延ms
///   - videotime: 当前视频帧的现场设备采集时间戳
///   - rcct: 控制信道往返时延ms
- (void)onAllLatencyReport:(NSString *)gwid
                    connFd:(int)connFd
                  latency1:(long long)latency1
                  latency2:(long long)latency2
                 videotime:(long long)videotime
                      rcct:(int)rcct;

onReportData

/// 接收来自现场设备信息回调
///   - gwid: 消息来源现场设备 ID。
///   - msg: 消息, 二进制字节透传
///   - len: 消息长度
///   - qos: 消息来源传输QoS, 0:不可靠传输, 1:可靠传输
- (void)onReportData:(NSString *)gwid msg:(NSData *)msg len:(int)len qos:(int)qos;

onRemoteFrameData

/**
 * 视频帧回调
 * stream_id  对应网关流id
 * conn_fd    接收视频流的句柄标识
 * data       视频帧数据
 * width      视频宽
 * height     视频高
 * videoTime  当前视频帧的现场设备采集时间戳
 */
- (void)onRemoteFrameData:(NSString *)gwid streamId:(int)streamId connFd:(int)connFd data:(NSData *)data width:(int)width height:(int)height videoTime:(long long)videoTime;

onRemoteEncodedFrame

/**
 * @param gwid 视频帧的来源现场设备 ID。
 * @param streamId 视频帧的来源现场设备流 ID
 * @param connFd 接收视频流的句柄标识
 * @param data 编码的视频图像帧数据
 * @param trroCodec 编码的codec类型
 * @param isKeyFrame 是否是关键帧
 * @param videoTime 当前视频帧时间戳(单调递增时间戳)
 */
- (void)onRemoteEncodedFrame:(NSString *)gwid streamId:(int)streamId connFd:(int)connFd data:(NSData *)data trroCodec:(TrroCodecType)trroCodec isKeyFrame:(BOOL)isKeyFrame videoTime:(long long)videoTime;

onState

/// 视频流连接状态回调
/// - Parameters:
///   - gwid: 视频帧的来源现场设备 ID。
///   - streamId: 视频帧的来源现场设备流 ID
///   - connFd: 接收视频流的句柄标识
///   - state: 视频流连接状态
- (void)onState:(NSString *)gwid streamId:(int)streamId connFd:(int)connFd state:(Trro_State)state;

onMediaState

/// 视频流接收传输状态回调
/// - Parameters:
///   - connFd: 接收视频流的句柄标识
///   - fps: 每秒帧数目
///   - bps: 每秒数据量
///   - rtt: UDP ping网络往返时间
///   - decd: 解帧数目
///   - jitter: 接收抖动值
///   - packetsLost: 丢包率= Lost/255*100%
///   - packetsReceived: 总接收数目
///   - stun: 穿网模式 0:host, 1:srflx, 2:prflx, 3:relay
- (void)onMediaState:(int)connFd fps:(int)fps bps:(int)bps rtt:(int)rtt decd:(long long)decd jitter:(int)jitter packetsLost:(long long)packetsLost packetsReceived:(long long)packetsReceivedstun:(int)stun;

onFieldSideMediaState

/**
 * 推流端现场设备网络状态信息
 *
 * @param gwid field端ID
 * @param streamId field端流ID
 * @param fps field端推送帧率
 * @param bps field端推送码率
 * @param rtt field端封包来回时间
 * @param jitter field端抖动
 * @param lost field端丢包率 = lost/255*100%
 */
- (void)onFieldSideMediaState:(NSString *)gwid streamId:(int)streamId fps:(int)fps bps:(int)bps rtt:(int)rtt jitter:(int)jitter lost:(int)lost;

onAudioMediaStateInfo

/**
 * 视频流传输状态回调
 *
 * @param connFd 视频流传输状态回调
 * @param mediaState 媒体相关的详细信息
 */
- (void)onAudioMediaStateInfo:(int)connFd mediaState:(TrroMedia *)mediaState;

onLogData

/// 日志信息回调
/// - Parameters:
///   - msg: 日志内容
///   - level: 日志级别
- (void)onLogData:(NSString *)msg level:(TrroLog_Level)level;

TrroGateWayList

现场设备列表。
属性
描述
ret
0:获取成功。
msg
获取结果描述。
gateways
数组,在线设备列表。

TrroGateWay

现场设备。
属性
描述
ret
0:获取成功。
msg
获取结果描述。
deviceID
网关 ID。
name
设备名称。
type
设备类型。
status
设备状态。
streams
视频流数量。
timestamp
时间戳。
version
设备版本。
sdk_mode
网关 SDK 模式。
ability
网关能力。
licenseExpire
网关 license 过期时间。

TrroMedia

媒体传输的详细信息。
属性
描述
fps
每秒帧数。
bps
每秒数据量。
rtt
UDP ping网络往返时间。
decd
解码耗时 ms。
jitter
接收抖动值。
packetsLost
丢包率 = packetsLost / 255 * 100%。
packetsReceived
总接收数目。
stun
穿网模式 0:host, 1:srflx, 2:prflx, 3:relay
单位(%) 视频播放卡顿率 = 视频播放的累计卡顿时长 / 视频播放的总时长。
lagK100
视频帧间隔超过100ms视为卡顿,并将其计入视频播放的累计卡顿时长,最终计算获得的卡顿率。
lagK150
视频帧间隔超过150ms视为卡顿,并将其计入视频播放的累计卡顿时长,最终计算获得的卡顿率。
duration
视频播放的总时长。

示例代码

1. 事件回调监听设置
[TrroRemote.sharedInstance setDelegate:self delegateQueue:dispatch_get_main_queue()];
2. SDK 初始化。
TrroOptions *options = [TrroOptions
publicModeWithDeviceId:self.settingData.deviceId
             projectId:@"xxxx"
              password:@"xxxx"
            deviceName:@"xxxx"
            maxStreams:4
          audioReceive:YES
         audioExternal:YES
             logEnable:TrroLogTrroDaily
         logOutputPath:nil];
// result = 1 表示设置成功
int result = [TrroRemote.sharedInstance
setupWithOptions
:options];
3. 连接视频流。
TrroConnectParam *param1 = [TrroConnectParam new];
param1.videoView = holderView1;
param1.streamId = 0;
param1.connFd = 0;
param1.renderConfig = [TrroRenderConfig new];
param1.renderConfig.fillMode = TrroVideoFillMode_Fit;
 
TrroConnectParam *param2 = [TrroConnectParam new];
param2.videoView = holderView1;
param2.streamId = 1;
param2.connFd = 1;
param2.renderConfig = [TrroRenderConfig new];
param2.renderConfig.fillMode = TrroVideoFillMode_Fit;
 
// result = 1 表示拉取成功
int result = [TrroRemote.sharedInstance connectToGwid:self.gwid connectParamList:@[param1, param2]];
4. 资源释放。
[TrroRemote destroySharedInstance];