API 描述
适用于 Windows/Linux 64 位系统。头文件引用 trro_remote.h,API 可参考头文件中接口注释。下面列举常用接口描述。
API 概览
初始化及销毁接口
函数列表 | 描述 |
使用 JSON 配置文件路径初始化SDK | |
使用 JSON 字符串初始化SDK | |
销毁 SDK |
现场设备查询接口
函数列表 | 描述 |
获取有会话权限的在线现场设备列表 | |
获取目标现场设备信息,需要有对应设备会话权限 |
视频操作接口
函数列表 | 描述 |
设置视频流渲染窗口 | |
连接视频流 (depreciated),请用新接口TRRO_connnectField | |
连接视频流(新) | |
关闭指定视频连接 | |
关闭所有视频连接 | |
更新视频渲染配置,可开启超分、夜视增强、旋转、镜像等 | |
更新现场设备目标视频流编码参数 | |
开启视频流转推 | |
关闭视频流转推 |
音视频输入输出接口
函数列表 | 描述 |
注册视频帧采集时间戳回调(depreciated),请用帧回调获取时间戳 | |
注册原始视频图像帧回调(默认YUVI420格式) | |
注册编码视频图像帧回调 | |
使用外部视频解码,打开会关闭原始视频图像回调,只回调编码视频帧。 | |
外部输入音频数据(PCM 数据) |
消息类接口
函数列表 | 描述 |
向现场设备发送控制数据 | |
监听现场设备发送来的数据 |
权限控制接口
函数列表 | 描述 |
请求控制权限 | |
注册现场设备权限状态回调 |
状态回调类接口
函数列表 | 描述 |
注册时延回调(depreciated),请用新接口AllLantencyCallback | |
注册时延回调(新) | |
注册信令服务连接状态回调 | |
注册视频流链接状态回调 | |
注册视频流传输状态回调(depreciated),请用新接口OnMediaStateInfo | |
注册视频流传输状态回调(新) | |
注册音频流传输状态回调 | |
注册连接的现场设备网络状态回调 |
音频控制接口
函数列表 | 描述 |
静音现场设备 |
诊断类接口
函数列表 | 描述 |
注册日志回调 | |
诊断视频流 | |
注册诊断信息回调接口 |
图像转换接口
函数列表 | 描述 |
I420转 ARGB |
软件信息接口
函数列表 | 描述 |
获取版本号 |
初始化接口
使用说明:可根据配置输入类型(文件/字符串),选择对应初始化接口初始化,只需使用一个。
使用 JSON 配置文件路径初始化
/** @name : TRRO_initJsonPath* @brief : SDK初始化,读取指定路径文件初始化, 接口为同步阻塞模式,等待信令连接成功后返回* @input : jsonPath JSON文件路径* @return : 成功 1 失败 <= 0*/int TRRO_initJsonPath(const char* jsonPath);
参数 | 含义 |
jsonPath | JSON 配置文件路径 |
返回值 | 成功:1 失败:<= 0 |
使用 json 字符串初始化
/** @name : TRRO_initJson* @brief : SDK初始化,读取输入JSON字符串初始化, 接口为同步阻塞模式,等待信令连接成功后返回* @input : json JSON 配置字符串* @return : 成功 1 失败 <= 0*/int TRRO_initJson(const char* json);
参数 | 含义 |
json | 配置信息 JSON 字符串 |
返回值 | 成功:1 失败:<= 0 |
销毁 SDK
使用说明:可通过该接口销毁 SDK,释放资源,可用于程序退出时需要主动释放底层资源场景(例如 C# 程序)。
//销毁SDKextern "C" TRRO_EXPORT void TRRO_destroy();
现场设备查询接口
获取在线现场设备列表
使用说明:可通过该接口获取到远端设备有会话权限的在线现场设备列表,可根据实际需要使用。当有权限的设备数量过多时,建议通过服务端 API 获取。
/** @name : TRRO_getGwList* @brief : 获取在线现场设备设备列表,接口为同步阻塞模式* @input : void* @return : JSON 字符串* {"ret":0,"msg":"suc","gateways":[{"deviceID":"xx","name":"xx","type":"gateway","status":"connected","streams":4,"timestamp":1682231838673,"version":"xx"}],"count":1}*/const char* TRRO_getGwList();
参数 | 含义 |
返回值 | 现场设备列表 JSON 字符串 { "ret":0, "msg":"suc", "gateways“:[ {"deviceID":"xx","name":"xx","type":"gateway","status":"connected","streams":4,"timestamp":1682231838673,"version":"xx"} ], "count":1 } |
获取在线现场设备信息
使用说明:获取目标现场设备信息,需要有对应设备会话权限。当设备不在线或无权限时返回 null。
/** @name : TRRO_getGwList* @brief : 获取对应网关的版本,接口为同步阻塞模式.* @input : gwid 设备id 公有云含projectID前缀,形式如ProjectId/FieldDeviceId* @return : json字符串, 使用方不需要释放指针, 获取到值后立即拷贝。* {"ret":0, "msg": "suc", "deviceID":"xx","name":"xx","type":"gateway","status":"connected","streams":4,"timestamp":1682231838673,"version":"xx","sdk_mode":"server2","ability":0,"licenseExpire":1745666980}*/extern "C" TRRO_EXPORT const char* TRRO_getGwInfo(const char* gwid);
参数 | 含义 |
gwid | 目标现场设备 ID,公有云形式例如 ProjectId/FieldDeviceId |
返回值 | 现场设备列表 JSON 字符串 { "ret":0, "msg":"suc", "deviceID":"xx", "name":"xx", "type":"gateway", "status":"connected", "streams":4, "timestamp":1682231838673, "version":"xx", "sdk_mode":"server2", "ability":0, "licenseExpire":1745666980 } |
视频操作接口
连接视频流(depreciated)
使用说明:可通过该接口对现场设备视频流进行连接。
/** @name : TRRO_connect* @brief : 发起视频连接,可多次调用连接不同流,异步模式,根据 onState 状态回调确认视频连接成功* @input : gwid 目标连接的现场设备 ID, 公有云传设备ID时需要带上projectid前缀,如projectid/fieldDeviceId* record_config:* 优先使用录制配置,当默认录制配置命名规则无法满足需求时使用,JSON 字符串,需要对每一路进行配置 eg:"{\\"file_names\\": [{\\"file\\":\\"test\\", \\"duration\\":15}, {\\"file\\":\\"test01\\", \\"duration\\":15}]}" ps:file 文件名 duration 分片时长单位秒* streams_num 要拉取现场设备视频流的个数, 与conn_fds和streams_num数组长度匹配, 值的范围 1 到 现场设备支持的device_streams数量* streams_id 现场设备视频流的 ID 数组, 现场设备视频流 ID 从0开始, 最大值为现场设备支持的 device_streams数量 -1* conn_fds conn_fd数组,conn_fd为接收视频流的句柄标识,自行编号,取值从0开始,最大值为 max_streams -1,max_streams在远端设备配置文件配置* @return : 成功 1 失败 <= 0*/int TRRO_connect(const char* gwid, const char* record_config, int streams_num, int* streams_id, int* conn_fds);
参数 | 含义 |
gwid | 现场设备 ID,公有云传设备 ID 时需要带上 projectid 前缀,例如 projectid/fieldDeviceId |
record_config | 视频录制配置,建议当默认录制配置无法满足需求时使用,JSON 字符串,需要对每一路进行配置,例如:
参数: file:文件名, 支持%D自动补充日期,%T自动补充时间 duration:切片时长(单位:秒) |
streams_num | 要连接视频流的数量 |
streams_id | 要连接的现场设备视频流 ID 数组 |
conn_fds | 接收视频流使用的接收视频流句柄数组 |
返回值 | 成功:1 失败:<= 0 |
连接视频流(new)
使用说明:可通过该接口对现场设备视频流进行连接,可支持跨 SDK 模式兼容拉流。打开兼容模式可能会影响秒开,建议在有明确需求时打开。
/** @name : TRRO_connectField* @brief : 发起视频连接,可多次调用连接不同流,异步模式,根据onState状态回调确认视频连接成功* @input : gwid 目标连接的现场设备ID,公有云传设备ID时需要带上projectid前缀,如projectid/fieldDeviceId* streams_num 要拉取现场设备视频流的个数, 与conn_fds和streams_num数组长度匹配, 值的范围 1 到 现场设备支持的device_streams数量* streams_id 现场设备视频流的ID数组, 现场设备视频流ID从0开始, 最大值为现场设备支持的device_streams数量 -1* conn_fds conn_fd数组,conn_fd为接收视频流的句柄标识,自行编号,取值从0开始,最大值为max_streams -1,max_streams在远端设备配置文件配置* compatible 是否开启版本兼容: 设置0,根据配置文件的“sdk_mode“字段来决定连接模式;设置为1,该接口会获取网关版本信息从而根据网关模式自动适配模式连接(由于需要获取版本信息会影响秒开)。默认值为0* record_config: 优先使用录制配置,当默认录制配置命名规则无法满足需求时使用,json字符串,需要对每一路进行配置 eg:"{\\"file_names\\": [{\\"file\\":\\"test\\", \\"duration\\":15}, {\\"file\\":\\"test01\\", \\"duration\\":15}]}"ps:file 文件名 duration 分片时长单位秒; 不使用时默认为NULL* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_connectField(const char* gwid, int streams_num, int* streams_id, int* conn_fds, int compatible = 0, const char* record_config = NULL);
参数 | 含义 |
gwid | 现场设备 ID,公有云传设备 ID 时需要带上 projectid 前缀,例如 projectid/fieldDeviceId |
streams_num | 要连接视频流的数量 |
streams_id | 要连接的现场设备视频流 ID 数组 |
conn_fds | 接收视频流使用的接收视频流句柄数组 |
compatible | 是否开启兼容模式, 0 不开启, 1开启。开启兼容模式,可跨 SDK 模式拉流,但会增加首帧延迟,建议有明确需求时使用。 |
record_config | 视频录制配置,建议当默认录制配置无法满足需求时使用,JSON 字符串,需要对每一路进行配置,例如:
参数: file:文件名, 支持%D自动补充日期,%T自动补充时间 duration:切片时长(单位:秒) |
返回值 | 成功:1 失败:<= 0 |
设置视频流渲染窗口
使用说明:可通过该接口设置渲染窗口,内部渲染时使用,外部渲染时设置空指针即可。
/** @name : TRRO_setWindows* @brief : 设置接收流句柄对应的显示窗口句柄* @input : conn_fds 接收视频流句柄数组* windows 显示窗口句柄数组, 显示窗口句柄为显示窗体的句柄/指针,如 Windows 平台的 HWND;* 外部渲染时,数组中的显示窗口句柄配置为 nullptr* num 设置显示窗口数量,与 conn_fds 和 windows 数组长度匹配* @return :void*/void TRRO_setWindows(int* conn_fds, WindowIdType * windows, int num);
参数 | 含义 |
conn_fds | 接收视频流句柄数组 |
windows | 显示窗口句柄数组,外部渲染时可设置为空指针数组 |
num | 与 conn_fds 和 windows 数组长度一致 |
关闭指定视频连接
使用说明:可通过该接口断开视频连接。
/** @name : TRRO_disconnect* @brief : 关闭conn_fds 对应的视频连接* @input : conn_fds 要关闭视频连接对应的视频接收句柄数组* fd_num conn_fd数组长度* @return : 成功 1 失败 <= 0*/int TRRO_disconnect(int* conn_fds, int fd_num);
参数 | 含义 |
conn_fd | 视频接收句柄数组 |
fd_num | 数组长度 |
返回值 | 成功 1 失败 <= 0 |
关闭所有视频连接
/** @name : TRRO_disconnectAll* @brief : 关闭所有视频连接* @input : void* @return : 成功 1 失败 <= 0*/int TRRO_disconnectAll();
更新视频流渲染配置
使用说明:设置接收流句柄对应的内部渲染模式, 仅内部渲染时使用。可设置拉伸模式、旋转、镜像、超分、夜视增强等功能
/** @name : TRRO_SetRenderConfig* @brief : 设置接收流句柄对应的内部渲染模式, 仅内部渲染时使用* @input : conn_fds 要设置渲染模式的接收视频流句柄数组* rotation 旋转角度 数组 rotation 为正顺时针旋转,rotation为负 逆时针旋转* scale 分辨率匹配模式数组 0 窗口拉伸, 1 保持原比例* config 预留渲染配置数组 0x00000XYZ X为1~2时开启夜视不同等级 推荐为2,Y为1时为开启超分模式,Z为1时为开启镜像渲染* num 配置的内部渲染流数量,与输入数组长度匹配* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_SetRenderConfig(int *conn_fds, int *rotation, int *scale, int *config, int num);
参数 | 含义 |
conn_fds | 要设置渲染模式的接收视频流句柄数组 |
rotation | 旋转角度,数组 rotation 为正顺时针旋转,rotation为负逆时针旋转, 缺省为0. |
scale | 分辨率匹配模式数组 0 窗口拉伸, 1 保持原比例, 缺省为0. |
config | 渲染配置数组,数组元素为32位int型,形如0x00000XYZ,缺省为0. X为1~3时开启夜视增强,对应不同强度,推荐强度为2,Y为1时为开启超分模式,Z为1时为开启镜像渲染; |
num | 配置的内部渲染流数量,与输入数组长度匹配 |
更新现场设备编码参数
使用说明:设置接收流句柄对应的内部渲染模式, 仅内部渲染时使用。
/** @name : TRRO_fieldDeviceEncodeConfig* @brief : 更新现场设备目标视频流编码参数* @input : gwid 现场设备id* streams_id 目标视频流编号* encode_config 待更新的编码参数,JSON 格式字符串,缺省字段将保持当前值不进行更新。 下面是更新支持的编码参数示意* {* "fps": 30,* "encode_width": 1920,* "encode_height": 1080,* "bps": 3000,* "min_fps": 30,* "min_bps": 1800,* "force_min": 0,* "min_width": 1920* }*/extern "C" TRRO_EXPORT int TRRO_fieldDeviceEncodeConfig(const char* gwid, int streams_id, const char* encode_config);
参数 | 含义 |
gwid | 现场设备 ID |
streams_id | 目标视频流编号 |
encode_config | 待更新的编码参数,JSON 格式字符串,缺省字段将保持当前值不进行更新。 下面是更新支持的编码参数示意 { "fps": 30, "encode_width": 1920, "encode_height": 1080, "bps": 3000, "min_fps": 30, "min_bps": 1800, "force_min": 0, "min_width": 1920 } |
开启视频流转推
使用说明:将对应视频接收句柄接收的视频流转推到指定RTMP URL的直播/存储服务。当远端对视频流disconnect时,会自动结束转推。
/** @name : TRRO_startMediaPush* @brief : 开启rtmp/rtsp转推,调用TRRO_stopMediaPush停止,当调用connect/disconnect函数后conn_fd连接的视频流发生切流或断开时,也会自动停止推流,需要重新start才能推流* @input : conn_fd 接收视频流的句柄标识* path 推流地址* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_startMediaPush(int conn_fd, const char* path);
参数 | 含义 |
conn_fd | 视频接收句柄 |
path | 视频流转推的目标 RTMP URL,以 rtmp://开头 |
停止视频流转推
使用说明:停止对应视频接收句柄接收的视频流转推。
/** @name : TRRO_stopMediaPush* @brief : 停止rtmp/rtsp转推* @input : conn_fd 接收视频流的句柄标识* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_stopMediaPush(int conn_fd);
参数 | 含义 |
conn_fd | 视频接收句柄 |
音视频输入输出接口
注册视频帧时间戳回调函数
使用说明:可通过该接口获取现场设备SDK采集当前远端接收到视频帧时的时间戳,对应现场设备steadyClock时钟。
extern "C" TRRO_EXPORT void TRRO_registerVideotimeCallback(void* context, TRRO_onVideotimeReport * callback);/** @name : TRRO_onVideotimeReport (depreciated)* @brief : 视频帧采集时间戳回调, 旧接口,建议使用 onAllLatencyReport 接口获取* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频来源现场设备 ID* conn_fd 对应视频流接收句柄* videotime 当前视频帧的现场设备采集时间戳* @return : void*/typedef void STD_CALL TRRO_onVideotimeReport(void* context, const char* gwid, int conn_fd, long long videotime);
视频原始图像回调
使用说明:可通过该接口获取现场设备发送的原始图像视频帧,默认为YUVI420格式。
注意:
请勿在回调线程长时间阻塞,若需要长时间处理建议转移到其他线程处理,否则会引起视频卡顿或延迟变大。
extern "C" TRRO_EXPORT void TRRO_registerRemoteFrameCallback(void* context, TRRO_onRemoteFrameData * callback, int frame_type = 0);/** @name : TRRO_onRemoteFrameData* @brief : 原始视频图像帧回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频帧的来源现场设备 ID* stream_id 视频帧的来源现场设备流 ID* conn_fd 接收视频流的句柄标识* data 视频图像帧数据,数据格式为YUVI420,可通过I4202ARGB接口转 ARGB* width 视频帧宽* height 视频帧高* videotime 当前视频帧的现场设备采集时间戳* @return : void*/typedef void STD_CALL TRRO_onRemoteFrameData(void* context, const char* gwid, int stream_id, int conn_fd, const char* data, int width, int height, long long videotime);
参数 | 含义 |
context | 上下文指针 |
gwid | 该视频图像来源的现场设备 ID |
stream_id | 该视频图像对应的现场设备视频流ID |
conn_fd | 该视频图像对应的远端设备视频流接收句柄 |
data | 视频图像数据 |
width | 视频图像宽 |
height | 视频图像高 |
videotime | 现场设备 SDK 采集该视频图像时的时间戳,对应 SteadClock 时钟 |
视频编码帧回调
使用说明:可通过该接口获取现场设备发送的编码视频帧。
注意:
请勿在回调线程长时间阻塞,若需要长时间处理建议转移到其他线程处理,否则会引起视频卡顿或延迟变大。
extern "C" TRRO_EXPORT void TRRO_registerRemoteEncodedFrameCallback(void* context, TRRO_onRemoteEncodedFrameData* callback);enum TrroCodec {Trro_H264 = 0,Trro_H265 = 1,Trro_AV1 = 2,};/** @name : TRRO_onRemoteEncodedFrameData* @brief : 编码视频图像帧回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频帧的来源现场设备 ID* stream_id 视频帧的来源现场设备流 ID* conn_fd 接收视频流的句柄标识* data 编码的视频图像帧数据* len 编码的视频图像帧的长度* trro_codec 编码的 codec 类型* is_key_frame 是否是关键帧* videotime 当前视频帧的现场设备采集时间戳* @return : void*/typedef void STD_CALL TRRO_onRemoteEncodedFrameData(void* context, const char* gwid, int stream_id, int conn_fd,const char* data, int len, TrroCodec trro_codec, bool is_key_frame,long long videotime);
参数 | 含义 |
context | 上下文指针 |
gwid | 该视频帧来源的现场设备 ID |
stream_id | 该视频帧对应的现场设备视频流ID |
conn_fd | 该视频帧对应的远端设备视频流接收句柄 |
data | 视频帧数据 |
len | 视频帧数据大小 |
TrroCodec | 视频帧编码格式 Trro_H264 = 0, Trro_H265 = 1, Trro_AV1 = 2, |
is_key_frame | 是否为关键帧,true 为关键帧, false不是关键帧; |
videotime | 现场设备 SDK 采集该视频帧时的时间戳,对应 SteadClock 时钟 |
视频编码帧回调
使用说明:可通过该接口获取现场设备发送的编码视频帧。
注意:
请勿在回调线程长时间阻塞,若需要长时间处理建议转移到其他线程处理,否则会引起视频卡顿或延迟变大。
extern "C" TRRO_EXPORT void TRRO_registerRemoteEncodedFrameCallback(void* context, TRRO_onRemoteEncodedFrameData* callback);enum TrroCodec {Trro_H264 = 0,Trro_H265 = 1,Trro_AV1 = 2,};/** @name : TRRO_onRemoteEncodedFrameData* @brief : 编码视频图像帧回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频帧的来源现场设备 ID* stream_id 视频帧的来源现场设备流 ID* conn_fd 接收视频流的句柄标识* data 编码的视频图像帧数据* len 编码的视频图像帧的长度* trro_codec 编码的 codec 类型* is_key_frame 是否是关键帧* videotime 当前视频帧的现场设备采集时间戳* @return : void*/typedef void STD_CALL TRRO_onRemoteEncodedFrameData(void* context, const char* gwid, int stream_id, int conn_fd,const char* data, int len, TrroCodec trro_codec, bool is_key_frame,long long videotime);
使用外部视频解码
使用说明:此接口用于关闭 SDK 内部视频解码,转而使用外部视频解码。
说明:
开启外部解码时,原始视频图像将不会回调,只会回调编码数据。
//是否使用外部解码(只针对视频)extern "C" TRRO_EXPORT int TRRO_useExternalDecoder(bool external);
参数 | 含义 |
external | true 使用外部解码 false 使用内部解码 |
输入外部音频流(PCM数据)
说明:
配置中需要“audio_external”节点值修改为1。
使用说明:此接口用于提供用户输入音频流进行传输,输入为 PCM 数据,16位采样。
/* @name TRRO_externAudioData(Experimental)* @brief 外部音频数据输入(pcm数据), 16位音频采样* @param[in] data 源数据* @param[in] data_size 数据大小* @param[in] channel 音频声道数* @param[in] sample_rate 音频采样率* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_externAudioData(const char* gwid, const char* data, int data_size, int channel, int sample_rate);
参数 | 含义 |
gwid | 要发送的现场设备 ID |
data | 音频流数据 |
data_size | 数据大小 |
channel | 声道数量 1:单声道 2:双声道 |
sample_rate | 采样频率,支持8k/16k/24k/32k/44.1k/48kHz等采样率, 例如48k采样率输入为48000 |
消息类接口
向现场设备发送控制数据
使用说明:可通过该接口给现场设备发送数据。目前限制单次发送数据大小700字节,频率限制100次/秒。发消息前需要拥有对应现场设备的 master 控制权限。
/** @name : TRRO_sendControlData* @brief : 向现场设备发送控制数据* @input : gwid 目标现场设备 ID* msg 发送消息,二进制透传* len 消息长度* qos 消息传输qos 0:不可靠传输 1:可靠传输* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_sendControlData(const char* gwid, const char* msg, int len, int qos = 0);
参数 | 含义 |
gwid | 现场设备 ID |
msg | 发送二进制数据 |
len | 消息长度 |
qos | 发送 qos: 0:不可靠传输 1:可靠传输 |
返回值 | 成功:1 失败:<= 0 |
注册现场设备消息回调函数
使用说明:可通过该接口接收现场设备发送的数据。
extern "C" TRRO_EXPORT void TRRO_registerReportDataCallback(void* context, TRRO_onReportData * callback);/** @name : TRRO_onReportData* @brief : 接收来自现场设备信息回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 消息来源现场设备 ID* msg 消息, 二进制透传* len 消息长度* qos 消息来源传输 qos, 0:不可靠传输, 1:可靠传输* @return : void*/typedef void STD_CALL TRRO_onReportData(void* context, const char* gwid, const char* msg, int len, int qos);
参数 | 含义 |
context | 上下文指针 |
gwid | 现场设备 ID |
msg | 接收的二进制数据 |
len | 消息长度 |
qos | 发送 qos: 0:不可靠传输 1:可靠传输 |
权限控制类接口
请求现场设备控制权限
使用说明:向现场设备请求控制权限,请求成功后才可向对应现场设备发送及接收控制数据。
//操控权限enum TrroPermission {kPermissionGuest = 0,kPermissionMaster = 1,};/** @name : TRRO_requestPermission* @brief : 向网关发出权限请求,网关会反馈TRRO_OnOperationPermissionState 更新权限* @input : gwid 目标设备 ID* permisson 参考结构体 TrroPermission* @return : 成功1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_requestPermission(const char* gwid, int permisson);
参数 | 含义 |
gwid | 目标现场设备 ID |
permisson | 控制权限 |
现场设备控制权限回调
extern "C" TRRO_EXPORT void TRRO_registerOnOperationPermissionState(void* context, TRRO_OnOperationPermissionState* callback);//操控权限enum TrroPermission {kPermissionGuest = 0,kPermissionMaster = 1,};/** #name : TRRO_OnOperationPermissionState* @brief : 回调现场设备操控权限状态通知* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* field_devid 来源现场设备 ID* self_permission 本设备当前的操控权限,参考 TrroPermission, 0 是 guest,只有观看权限, 1是 master,拥有完全控制权限* master_devid 拥有 master 权限的远端设备 ID* @return : void*/typedef void STD_CALL TRRO_OnOperationPermissionState(void* context, const char* field_devid, int self_permission, const char* master_devid);
参数 | 含义 |
context | 上下文指针 |
field_devid | 现场设备 ID |
self_permission | 自身对该现场设备拥有的控制权限级别 |
master_devid | 获得该现场设备 master 控制权的远端设备ID,空字符串代表没有远端设备获取了该现场设备的 master 控制权 |
状态回调类接口
延迟状态回调
使用说明:可用于监听视频延迟、控制延迟等延迟状态。
extern "C" TRRO_EXPORT void TRRO_registerLatencyCallback(void* context, TRRO_onLatencyReport * callback);extern "C" TRRO_EXPORT void TRRO_registerAllLatencyCallback(void* context, TRRO_onAllLatencyReport * callback);/** @name : TRRO_onLatencyReport (depreciated)* @brief : 视频时延回调, 旧接口,建议使用onAllLatencyReport接口获取* @input : context 回调上下文指针, 返回注册回调函数时传入的context* gwid 视频来源现场设备id* conn_fd 对应视频流接收句柄* latency 返回视频上行时延ms* @return : void*/typedef void STD_CALL TRRO_onLatencyReport(void* context, const char* gwid, int conn_fd, long long latency);/** @name : TRRO_onAllLatencyReport (Recommended)* @brief : 时延回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频来源现场设备 ID* conn_fd 对应视频流接收句柄* latency1 均值估计视频传输时延ms* latency2 均值估计视频传输时延ms* videotime 当前视频帧的现场设备采集时间戳* rcct 控制信道往返时延ms, 等于控制上行延迟+控制下行延迟* @return : void*/typedef void STD_CALL TRRO_onAllLatencyReport(void* context, const char* gwid, int conn_fd, long long latency1, long long latency2, long long videotime, int rcct);
参数 | 含义 |
context | 上下文指针 |
gwid | 视频流对应的现场设备 ID |
conn_fd | 视频流对应的远端设备接收句柄 |
latency1 | 采用均值估计的视频流传输延迟,单位 ms,估计误差与网络波动及上下行时延差值有关 |
latency | 均值估计视频传输时延,预留后续更新 |
videotime | 当前接收视频帧的现场设备采集时间戳 |
rcct | 控制消息通道往返时延 ms, 等于控制上行延迟+控制下行延迟 |
信令连接状态回调
使用说明:可用于监听与服务端信令连接的状态。
extern "C" TRRO_EXPORT int TRRO_registerSignalStateCallback(void *context, TRRO_onSignalState *callback);/*** SignalState 信令连接状态枚举*/enum SignalState {kTrroReady = 0, /**< 首次连接建立成功 */kTrroLost = 1, /**< 连接断开,内部会进行自动重连 */kTrroReup = 2, /**< 自动重连成功 */kTrroKickout = 3, /**< 被同名用户剔除 */kTrroAuthFailed = 4, /**< 用户名或者密码错误 */};/*** @name TRRO_onSignalState* @brief 信令连接状态回调* @param[in] context 上下文指针* @param[in] state 信令连接状态,参考枚举SignalState* @return void*/typedef void TRRO_onSignalState(void *context, SignalState state);
参数 | 含义 |
context | 上下文指针 |
SignalState | 信令连接状态 kTrroReady = 0, 首次连接建立成功 kTrroLost = 1, 连接断开,内部会进行自动重连 kTrroReup = 2, 自动重连成功 kTrroKickout = 3, 被同名用户剔除 kTrroAuthFailed = 4, 用户名或者密码错误 |
视频连接状态回调
使用说明:可用于监听拉取的视频流连接状态。
extern "C" TRRO_EXPORT void TRRO_registerOnState(void* context, TRRO_OnState * callback);//视频连接状态enum TrroState {kDisconnect = 0,kConnecting = 1,kConnected = 2,kDisconnecting = 3,};/** @name : TRRO_OnState* @brief : 视频流连接状态回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 视频帧的来源现场设备 ID* stream_id 视频帧的来源现场设备流 ID* conn_fd 接收视频流的句柄标识* state 视频流连接状态,对应 TrroState 状态* @return : void*/typedef void STD_CALL TRRO_OnState(void* context, const char* gwid, int stream_id, int conn_fd, int state);
参数 | 含义 |
context | 上下文指针 |
gwid | 视频流对应的现场设备ID |
stream_id | 视频流对应现场设备上的视频流ID |
conn_fd | 视频流对应的远端设备接收句柄 |
state | 视频连接状态 kDisconnect = 0, 视频连接断开 kConnecting = 1, 视频连接正在连接中 kConnected = 2, 视频连接成功 kDisconnecting = 3, 视频连接正在断开中 |
远端音视频传输状态回调函数
使用说明:可用于监听远端设备和现场设备的音视频流传输指标。
extern "C" TRRO_EXPORT void TRRO_registerOnMediaState(void* context, TRRO_OnMediaState * callback);extern "C" TRRO_EXPORT void TRRO_registerOnMediaStateInfo(void* context, TRRO_OnMediaStateInfo * callback);extern "C" TRRO_EXPORT void TRRO_registerOnAudioMediaStateInfo(void *context, TRRO_OnAudioMediaStateInfo * callback);/* TRRO_OnMediaStateInfo 使用该结构体 包含媒体传输的详细信息* fps 每秒帧数目* bps 每秒数据量* rtt UDP ping 网络往返时间* decd 解码耗时ms* jitter 接收抖动值* packets_lost 丢包率(0-255),丢包百分比 = packets_lost / 255 * 100%* packets_received 总接收数目* stun 穿网模式 0:host, 1:srflx, 2:prflx, 3:relay* 单位(%) 视频播放卡顿率 = 视频播放的累计卡顿时长 / 视频播放的总时长。* lag_k100 视频帧间隔超过100ms视为卡顿,并将其计入视频播放的累计卡顿时长,最终计算获得的卡顿率。* lag_k150 视频帧间隔超过150ms视为卡顿,并将其计入视频播放的累计卡顿时长,最终计算获得的卡顿率。* duration 视频播放的总时长*/struct TrroMediaState {int fps;int bps;int rtt;long long decd;int jitter;long long packets_lost;long long packets_received;int stun;double lag_k100;double lag_k150;long long duration;};/** @name : TRRO_OnMediaState(depreciated)* @brief : 视频流传输状态回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* conn_fd 接收视频流的句柄标识* fps 每秒帧数目* bps 每秒数据量* rtt UDP ping 网络往返时间* decd 解帧耗时ms* jitter 接收抖动值* packets_lost 丢包率(0-255),丢包百分比 = packets_lost / 255 * 100%* packets_received 总接收数目* stun 穿网模式 0:host, 1:srflx, 2:prflx, 3:relay* @return : void*/typedef void STD_CALL TRRO_OnMediaState(void* context, int conn_fd, int fps, int bps, int rtt, long long decd, int jitter,long long packets_lost, long long packets_received, int stun);/** @name : TRRO_OnMediaStateInfo(Recommended)* @brief : 视频流传输状态回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* conn_fd 接收视频流的句柄标识* mediastate 媒体相关的详细信息* @return : void*/typedef void STD_CALL TRRO_OnMediaStateInfo(void* context, int conn_fd, TrroMediaState mediastate);
参数 | 含义 |
context | 上下文指针 |
conn_fd | 视频流对应的远端设备接收句柄 |
TrroMediaState | 媒体状态结构体 fps: 帧率 bps: 码率,单位bps rtt:远端设备到服务器的网络rtt,单位ms jitter:远端设备到服务器的网络抖动 packets_lost:远端设备丢包率(0-255),丢包百分比=lost/255*100% packets_received: 接收到包数量 stun: stun连接模式 lag_k100:100ms卡顿率 lag_k150: 150ms卡顿率 duration: 视频持续时长,单位ms |
现场媒体传输状态回调
extern "C" TRRO_EXPORT void TRRO_registerFieldSideNetworkState(void* context, TRRO_onFieldSideMediaState * callback);/*** @name : TRRO_onFieldSideMediaState* @brief : field端网络状态信息,server模式时有意义* @input : context 上下文指针* gwid field端ID* stream_id field端流ID* fps field端推送帧率* bps field端推送码率* rtt field端封包来回时间* jitter field端抖动* lost field端丢包率(0-255), ,丢包百分比 = lost/255 * 100%* @return : void*/typedef void TRRO_onFieldSideMediaState(void* context, const char* gwid, int stream_id, int fps, int bps, int rtt, int jitter, int lost);
参数 | 含义 |
context | 上下文指针 |
gwid | 现场设备ID |
stream_id | 现场设备的视频流ID |
fps | 帧率 |
bps | 码率,单位 bps |
rtt | 现场设备到服务器的网络 rtt,单位 ms |
jitter | 现场设备到服务器的网络抖动 |
lost | 现场设备丢包率(0-255), ,丢包百分比 = lost/255 * 100% |
诊断类接口
诊断报告
extern "C" TRRO_EXPORT void TRRO_registerOnDiagReport(void* context, TRRO_OnDiagReport * callback);/** #name : TRRO_OnDiagReport* @brief : 诊断信息回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* gwid 发起诊断的目标现场设备 ID* type 1 成功 , < 0 相关错误信息* json 回调诊断详细信息 json 格式* @return : void*/typedef void STD_CALL TRRO_OnDiagReport(void* context, const char* gwid, int type, const char* json);
日志回调
使用说明:可用于监听 SDK 回调的日志内容。
extern "C" TRRO_EXPORT int TRRO_registerLogCallback(void* context, TRRO_OnLogData * callback);//日志等级enum TrroLogLevel {LOG_INFO = 1,LOG_WARNING = 2,LOG_ERROR = 3,};/** @name : TRRO_OnLogData* @brief : 日志回调* @input : context 回调上下文指针, 返回注册回调函数时传入的 context* msg 日志内容* level 日志级别,参考枚举 TrroLogLevel* @return : void*/typedef void STD_CALL TRRO_OnLogData(void* context, const char* msg, int level);
音频控制接口
静音现场设备
使用说明:将目标现场设备静音,仅支持 server 模式。
/** @name : TRRO_audioMute* @brief : Mute/unMute 目标现场设备的音频 仅 Server 模式* @input : gwid 目标现场设备 ID* mute true 静音, false 取消静音* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_audioMute(const char* gwid, bool mute);
参数 | 含义 |
gwid | 目标现场设备 ID |
mute | true:静音 false:取消静音 |
图像转换接口
I420转ARGB
使用说明:用于图像数据的格式转换,将 yuvi420格式转为 ARGB,支持分辨率 resize。
/** @name : TRRO_I4202ARGB* @brief : YUV I420 图像格式转 ARGB 图像格式,转换时带 resize 功能* @input : argb 存放输出A RGB 图像数据的指针,ARGB 的 int 表示: 0XFF(RR)(GG)(BB) , RR GG BB 为对应的 rgb 的值* yuvI420 输入 yuvI420 图像数据指针* src_width 输入图像宽度* src_height 输入图像高度* dst_width 输出图像宽度* dst_height 输出图像高度* @return : 成功 1 失败 <= 0*/extern "C" TRRO_EXPORT int TRRO_I4202ARGB(int* argb, char* yuvI420, int src_width, int src_height, int dst_width, int dst_height);
参数 | 含义 |
argb | 输出的 argb 数据 |
yuvI420 | 输入的 yuvi420格式数据 |
src_width | 输入图像宽度 |
src_height | 输入图像高度 |
dst_width | 输出图像宽度 |
dst_height | 输出图像高度 |
软件信息接口
获取版本号
//获取SDK版本号const char * TRRO_getVersion();