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。 | |
设置临时会话授权,用于连接现场设备临时会话身份验证。 | |
获取在线现场设备列表。 | |
获取对应现场设备的信息。 | |
连接现场设备单个视频流。 | |
连接现场设备多个视频流。 | |
切换解码方式。 true:外部解码。 false:内部解码(软解)。 | |
关闭指定视频连接。 | |
关闭所有视频连接。 | |
给现场设备发送控制数据。 | |
现场设备音频设置。 | |
外部音频数据输入(PCM 数据),16位音频采样。 | |
本地设备音频设置。 | |
向网关发出权限请求。 | |
获取 SDK 版本号。 |
sharedInstance
获取 TrroControl 单例。
+ (instancetype)sharedInstance;
destroySharedInstance
销毁 TrroControl 单例。
+ (void)destroySharedInstance;
setDelegate:delegateQueue
设置 SDK 事件监听及回调队列。
- (void)setDelegate:(id<TrroControlDelegate>)delegatedelegateQueue:(dispatch_queue_t)delegateQueue;
参数 | 描述 |
delegate | 回调代理实例。 |
delegateQueue | 回调代理队列,默认为主队列。 |
setupWithOptions
使用 options 配置方式初始化控制端,接口为同步阻塞模式。
- (int)setupWithOptions:(TrroOptions *)trroOptions;
参数 | 描述 |
options | |
@return | 成功 1,失败 <= 0。 |
setupWithJson
使用 JSON 配置启动 SDK,接口为同步阻塞模式。
- (int)setupWithJson:(NSString *)jsonStr;
参数 | 描述 |
jsonStr | |
@return | 回调:成功 1,失败 <= 0。 |
setSessionPermissionToken
设置临时会话授权,用于连接现场设备时的临时会话身份验证。返回值:成功1 失败<=0。
- (int)setSessionPermissionToken:(NSString *)signature gwid:(NSString *)gwid;
参数 | 描述 |
gwid | 目标会话现场设备 ID。 |
signature | 基于项目共享密钥签发的临时会话授权签名。 |
getGwList
获取在线现场设备的列表,接口为同步阻塞模式.
- (TrroGatewayList*)getGwList;
参数 | 描述 |
@return |
getGwInfoForGwid
获取对应网关的详细信息,接口为同步阻塞模式。
- (TrroGateway *)getGwInfoForGwid:(NSString *)gwid;
参数 | 描述 |
@return |
connectToGwid:connectParam
连接1路视频流,接口为同步阻塞模式。
- (int)connectToGwid:(NSString *)gwid connectParam:(TrroConnectParam *)connectParam;
参数 | 描述 |
gwid | 目标现场设备 ID。 |
connectParam | |
@return | 成功:1,失败:<=0。 |
connectToGwid:connectParamList
发起视频连接,可多次调用连接不同流,接口为同步阻塞模式。
- (int)connectToGwid:(NSString *)gwid connectParamList:(NSArray<TrroConnectParam *> *)connectParamList;
参数 | 描述 |
gwid | 目标现场设备 ID。 |
connectParamList | |
@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 *)datachannel:(int)channelsampleRate:(int)sampleRateforGwid:(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)audioExternallogOutputPath:(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 |
TrroRenderConfig
参数 | 描述 |
rotation | 图像的顺时针旋转角度。{@link TrroVideoRotation}。 |
fillMode | 画面填充模式。{@link TrroVideoFillMode}。 |
mirror | 画面镜像模式。 |
TrroRemoteDelegate
SDK 事件监听接口。
API | 描述 |
云端信令连接状态回调。 | |
错误信息回调。 | |
网关帧时间戳回调。 | |
时延回调。 | |
接收来自现场设备信息回调。 | |
已解码视频数据回调。 如果关闭 SDK 解码 [TrroRemote.sharedInstance switchDecoder:true],该回调不再回调。 | |
编码视频数据回调。 若在该回调进行外部解码,建议关闭SDK解码[TrroRemote.sharedInstance switchDecoder:true]。 | |
视频流连接状态回调。 | |
日志信息回调。 | |
现场设备推流网络状态信息。 | |
视频流接收传输状态回调。 | |
日志信息回调。 |
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 *)gwidconnFd:(int)connFdlatency1:(long long)latency1latency2:(long long)latency2videotime:(long long)videotimercct:(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 = [TrroOptionspublicModeWithDeviceId:self.settingData.deviceIdprojectId:@"xxxx"password:@"xxxx"deviceName:@"xxxx"maxStreams:4audioReceive:YESaudioExternal:YESlogEnable:TrroLogTrroDailylogOutputPath:nil];// result = 1 表示设置成功int result = [TrroRemote.sharedInstancesetupWithOptions: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];