API 描述
适用于 Linux 64位系统。头文件引用 trro_field.h,API 可参考头文件中接口注释。下面列举常用接口描述。
注意:
标注为原子能力 API 的接口是不与 TRRO 实时互动业务关联的功能接口。该类接口可在SDK初始化后自由使用,方便客户复用 SDK 能力开发其他功能。
API 概览
初始化接口
函数列表 | 描述 |
使用 JSON 字符串初始化 | |
使用配置文件路径初始化 | |
使用配置路径及 license 路径初始化(私有化) | |
使用 JSON 字符串和 license 路径初始化(私有化) |
状态获取类接口
函数列表 | 描述 |
注册信令状态回调 | |
注册视频连接状态回调 | |
注册延迟状态回调 | |
注册视频媒体和网络状态回调 | |
注册音频媒体和网络状态回调 | |
注册外部编码建议信息回调(外部编码时使用) |
启停类接口
函数列表 | 描述 |
启动 SDK | |
停止 SDK |
音视频输入输出接口
函数列表 | 描述 |
输入外部源视频流 (图像数据) | |
注册视频采集数据回调函数 | |
输入外部源视频流(编码数据) | |
输入外部音频流(PCM 数据) |
相机采集接口 (原子能力API)
函数列表 | 描述 |
开始摄像头采集 | |
停止摄像头采集
|
消息类接口
函数列表 | 描述 |
向远端设备发送数据 | |
注册远端设备控制消息回调 |
权限控制类接口
函数列表 | 描述 |
注册远端设备操控权限请求通知回调 | |
设置远端设备操作权限 |
重配置接口
函数列表 | 描述 |
重配置现场设备视频流,仅支持重置 normal/combine/rtsp_enc 等扩展采集协议重配置 |
音频控制类接口
函数列表 | 描述 |
静音设置 | |
获取音频采集/播放设备数量 | |
获取音频采集/播放设备名称 | |
更改当前音频采集/播放设备 |
日志/错误信息类接口
函数列表 | 描述 |
注册日志回调函数 | |
注册错误事件回调 | |
错误码对应错误信息获取接口 |
视频录制接口(原子能力API)
函数列表 | 描述 |
启动录制 | |
发送录制数据 | |
切换录制文件 | |
结束录制 |
网络评估接口
函数列表 | 描述 |
测试网络质量是否满足视频传输要求,可用于启动时检查网络 |
获取软件信息
函数列表 | 描述 |
获取软件版本号 |
初始化接口
使用说明:可根据是否使用本地 license(公有云无需本地 license)以及配置输入类型(文件/字符串),选择对应的初始化接口进行初始化,只需使用一个。
使用 JSON 字符串初始化
使用说明:用户需确保 JSON 字符串格式正确,此接口用于 SDK 加载配置进行初始化。
/** @name : TRRO_initGwJson* @brief : 使用字符串初始化* @input : json_str 配置文件 JSON 字符串* @input : mode 0 同步模式,一直等待* -1 异步模式,初始化成功后通知TRRO_onSignalState* @return : 1 for success, other failed*/int TRRO_initGwJson(const char * json_str, int mode = 0);
参数 | 含义 |
json_str | 配置信息 JSON 字符串 |
mode | 返回模式 0:同步阻塞模式 1:异步模式 |
使用配置文件路径初始化
使用说明:用户需确保 JSON 配置文件格式正确,此接口用于 SDK 加载配置进行初始化。
/** @name : TRRO_initGwPath* @brief : 使用配置文件初始化* @input : cfg_path json配置文件路径名,e.g. "./config.json"* @input : mode 0 同步模式一直等待* -1 异步模式,初始化成功后TRRO_onSignalState信息* @return : 1 for success, other failed*/int TRRO_initGwPath(const char * cfg_path, int mode = 0);
参数 | 含义 |
cfg_path | 配置文件路径 |
mode | 返回模式 0:同步阻塞模式 1:异步模式 |
使用配置文件路径及 license 文件路径初始化
使用说明:用户需确保 JSON 配置文件格式正确,license 文件路径正常,此接口用于 SDK 加载配置进行初始化。
/** @name : TRRO_initGwPathWithLicense* @brief : 使用配置文件和本地license初始化* @input : cfg_path JSON 配置文件路径名,e.g. "./config.json"* @input : license_path license文件路径名,e.g. "./license.txt"* @input : mode 0 同步模式一直等待* -1 异步模式 初始化成功后通知TRRO_onSignalState* @return : 1 for success, other failed*/int TRRO_initGwPathWithLicense(const char * cfg_path, const char * license_path, int mode = 0);
参数 | 含义 |
cfg_path | 配置文件名 |
license_path | 本地 license 文件路径 |
mode | 返回模式 0:同步阻塞模式 1:异步模式 |
使用配置字符串和 license 文件路径初始化
使用说明:用户需确保 JSON 字符串和 license 内容格式正确,此接口用于 SDK 加载配置进行初始化。
/** @name : TRRO_initGwJsonWithLicense* @brief : 使用字符串和本地license初始化* @input : json_str 配置文件 JSON 字符串* @input : license_path license文件路径名,e.g. "./license.txt"* @input : mode 初始化模式* 0 同步模式一直等待* -1 异步模式, 初始化成功后通知TRRO_onSignalState* @return : 1 for success, other failed*/int TRRO_initGwJsonWithLicense(const char * json_str, const char * license_path, int mode = 0);
参数 | 含义 |
json_str | 配置文件 JSON 字符串 |
license_path | license 路径 |
mode | 返回模式。 0:同步阻塞模式 1:异步模式 |
状态获取类接口
使用说明:按需注册所需功能的回调接口。
注册信令状态回调(异步初始化回调)
使用说明:此接口用于注册信令状态回调接口,异步模式初始化时需使用,根据 Ready 状态判断初始化成功。
/** @name : TRRO_registerSignalStateCallback* @brief : 注册信令服务连接状态回调* @input : context 上下文指针callback 回调函数* @return : 1 for success, other failed*/int TRRO_registerSignalStateCallback(void *context, TRRO_onSignalState *callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
回调定义enum SignalState {kTrroReady = 0, /**< 连接建立成功 */kTrroLost = 1, /**< 连接断开,内部会进行自动重连 */kTrroReup = 2, /**< 自动重连成功 */kTrroKickout = 3,kTrroAuthFailed = 4, /**< 用户名或者密码错误 */};/** @name : TRRO_onSignalState* @brief : 信令连接状态回调* @input : context 上下文指针* state kTrroReady 连接建立成功* kTrroLost 连接断开,内部会进行自动重连* kTrroReup 自动重连成功* @return : void*/typedef void TRRO_onSignalState(void *context, SignalState state);
参数 | 含义 |
context | 回调上下文指针,返回注册时传入的 context |
state | 信令连接状态 |
注册视频连接状态回调
使用说明:此接口用于注册视频流连接状态回调,此接口可根据需求选择是否调用。
/*** @name TRRO_registerOnState* @brief 注册视频连接状态回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerOnState(void* context, TRRO_OnState * callback);
参数 | 含义 |
context | 上下文指针,回调时返回该上下文用于定位 |
callback | 回调函数 |
回调函数定义enum TrroState {kDisconnect = 0, /**< 断连 */kConnecting = 1, /**< 连接中 */kConnected = 2, /**< 已连接 */kDisconnecting = 3, /**< 已断连 */};/*** @name TRRO_onState* @brief 视频连接状态回调* @param[in] context 上下文指针* @param[in] stream_id 视频流id* @param[in] state TrroState连接状态* @return void*/typedef void TRRO_OnState(void* context, int stream_id, int state);
注册时延回调
使用说明:此接口用于在现场设备侧获取推流到拉流的视频数据处理延时,可按需选择使用。
/*** @name TRRO_registerLatencyCallback* @brief 注册时延回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerLatencyCallback(void *context, TRRO_onLatencyReport *callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
/*** @name TRRO_onLatencyReport* @brief 延迟信息回调* @param[in] context 上下文指针* @param[in] stream_id 流ID* @param[in] vcct 视频控制闭环时延, 等于视频上行延迟(不含采集)+控制下行延迟* @return void*/typedef void TRRO_onLatencyReport(void *context, int stream_id, int vcct);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
stream_id | 流 ID |
vcct | 视频控制闭环时延, 等于视频上行延迟(不含采集)+控制下行延迟 |
注册视频媒体状态回调
使用说明:此接口用于在现场设备获取已连接视频流的媒体状态,可按需选择使用。
/*** @name TRRO_registerMediaState* @brief 注册网络状态* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerMediaState(void* context, TRRO_onMediaState * callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 媒体状态回调函数 |
/*** @name TRRO_onMediaState* @brief 媒体传输状态回调* @param[in] context 回调上下文指针* @param[in] stream_id 流ID* @param[in] fps 每秒帧数目* @param[in] bps 每秒数据量* @param[in] rtt 封包来回时间* @param[in] lost 总丢包数目* @param[in] packets_send 总发送数目* @param[in] stun 穿网模式 0:host, 1:srflx, 2:prflx, 3:relay* @return void*/typedef void TRRO_onMediaState(void* context, int stream_id, int fps, int bps, int rtt, long long lost, long long packets_send, int stun);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
stream_id | 流 ID |
fps | 每秒帧数目 |
bps | 每秒数据量 |
rtt | 封包来回时间 |
lost | 总丢包数目 |
packets_send | 总发送数目 |
stun | 穿网模式 0:host 1:srflx 2:prflx 3:relay |
注册音频状态回调
使用说明:此接口用于在现场设备获取已连接音频流的媒体状态,可按需选择使用。
/*** @name TRRO_registerAudioMediaState* @brief 注册音频状态回调* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerAudioMediaState(void* context, TRRO_onMediaState * callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 媒体状态回调函数 |
注册编码建议信息回调
使用说明:此接口配合外部编码流输入数据接口共同使用,用户需可根据此接口的回调信息,对输入的编码流进行处理。
/*** @name TRRO_registerEncodeFrameInfoCallback* @brief 注册编码建议信息回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerEncodeFrameInfoCallback(void *context, TRRO_onEncodeFrameInfo *callback);
参数 | 含义 |
context | 上下文指针,回调时返回该上下文指针用于定位 |
callback | 回调函数 |
回调函数定义/*** @name TRRO_onEncodeFrameInfo* @brief 编码建议信息回调,适用于外部输入编码帧场景* @param[in] context 上下文指针* @param[in] stream_id 流ID* @param[in] type 回调类型, 0:强制关键帧请求 , 1 码率更新请求* @param[in] bitrate type为1时有效,表示建议输入的编码数据码率,单位kbps* @return void*/typedef void TRRO_onEncodeFrameInfo(void *context, int stream_id, int type, int bitrate);
参数 | 含义 |
context | 回调上下文指针,返回注册时传入的 context |
strem_id | 流 ID |
type | 回调类型 0:强制关键帧请求 1:码率更新请求 |
bitrate | 当 type 为1时有效,表示建议输入的编码数据码率,单位 kpbs |
启停类接口
启动接口
使用说明:此接口用于启动现场设备 SDK,初始化成功后方可调用,即同步模式初始化返回成功, 或者异步模式初始化 TRRO_onSignalState 通知连接 Ready。
/*** @name TRRO_start* @brief 启动音视频传输业务, 需要等待初始化成功后调用(同步模式init返回成功 或 异步模式初始化TRRO_onSignalState通知连接Read)* @param[in] void* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_start();
停止接口
使用说明:此接口用于停止现场设备 SDK。
/*** @name TRRO_stop* @brief 销毁SDK,释放sdk资源* @param[in] void* @return void*/extern "C" TRRO_EXPORT void TRRO_stop();
音视频输入输出接口
输入外部源视频流(图像数据)
使用说明:此接口用于提供用户输入视频的原始图像数据流,注意输入数据源需与配置文件中的流数目、流配置节点相匹配。
/*** @name TRRO_externalVideoData* @brief 外部图像输入接口* @param[in] stream_id 流ID* @param[in] data 消息体* @param[in] width 数据源宽* @param[in] height 数据源高* @param[in] type 数据源类型,当前支持Trro_ColorYUVI420 Trro_ColorJPEG Trro_ColorYUYV* @param[in] dataSize 数据大小,为0时会自动根据格式计算大小,发送JPEG等无特定大小数据时需指定* @param[in] text 图像要叠加字符串(experimental)* @param[in] point_x 叠加文字起始x坐标,最左侧为0 (experimental)* @param[in] point_y 叠加文字起始y坐标,最顶部为0 (experimental)* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_externalVideoData(int stream_id, const char * data, int width, int height, int type, int dataSize = 0, const char* text = "", int point_x = 0, int point_y = 0);
参数 | 含义 |
stream_id | 视频流 ID,从0开始,第2路为1,以此递增 |
data | 图像数据 |
width | 图像宽 |
height | 图像高 |
type | 图像类型 0:YUVI420 4:YUYV 5:JPEG,推荐 YUVI420 格式 |
dataSize | 图像数据大小,0为自动计算,发送 jpeg 等无固定大小图像格式需指定 |
text | 保留 |
point_x | 保留 |
point_y | 保留 |
注册视频采集数据回调函数
使用说明:此接口用于获取SDK内部采集的相机数据源,供上层业务使用。
/*** @name TRRO_registerVideoCaptureCallback* @brief 注册视频采集数据回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerVideoCaptureCallback(void* context, TRRO_onVideoCaptureData * callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
/*** @name TRRO_onVideoCaptureData* @brief 采集视频帧回调* @param[in] context 上下文指针,返回注册时传入的context* @param[in] data 视频数据* @param[in] width 宽* @param[in] height 高* @param[in] type 视频格式,0 YUV420, 4 YUYV* @param[in] stream_id 流号* @return void*/typedef void TRRO_onVideoCaptureData(void *context, const char* data, int width, int height, int type, int stream_id);
参数 | 含义 |
remote_devid | 设置权限的对端设备 ID |
data | 视频数据 |
width | 视频数据宽 |
height | 视频数据高 |
type | 视频格式: 0 YUV420 4 YUYV |
stream_id | 流号 |
输入外部源视频流(编码数据)
说明:
建议采用单 slice 编码, I 帧需要带 sps/pps。
使用说明:此接口用于提供用户输入已编码视频流进行传输,注意输入数据源需与配置文件中的流数目、流配置节点相匹配。输入视频流编码类型(例如 H264)需要与配置文件中对应流的 codec 一致,关键帧中包含 SPS/PPS 信息,同时配置文件中“protocol”节点值修改为“outenc”。
/*** @name TRRO_externalEncodeVideoData* @brief 外部编码流输入,编码流codec需要与配置codec一致* @param[in] stream_id 流ID* @param[in] data 消息体* @param[in] width 数据源宽* @param[in] height 数据源高* @param[in] size 数据大小* @param[in] type 数据源类型,参考FrameType* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_externalEncodeVideoData(int stream_id, const char * data, int width, int height, int size, FrameType type);
参数 | 含义 |
stream_id | 视频流 ID,从0开始,第2路为1,以此递增 |
data | 视频流数据 |
width | 视频款 |
height | 视频高 |
size | 视频帧大小 |
type | 编码类型 0:P 帧 1:I 帧(需包含 SPS/PPS 信息) |
输入外部音频流(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* data, int data_size, int channel, int sample_rate);
参数 | 含义 |
data | 音频流数据 |
data_size | 数据大小 |
channel | 声道数量 1:单声道 2:双声道 |
sample_rate | 采样频率,支持8k/16k/24k/32k/44.1k/48kHz等采样率, 例如48k采样率输入为48000 |
消息类接口
向远端设备发送数据
使用说明:此接口用于发送二进制数据到远端设备,配合远端设备 SDK 数据回调接口使用,此接口可根据需求选择是否调用。目前限制单次发送数据大小700字节,频率限制100次/秒。
/*** @name TRRO_sendControlData* @brief 向远端设备发送数据* @param[in] msg 消息体* @param[in] len 消息体长度* @param[in] qos 0:unreliable 1:reliable* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_sendControlData(const char* msg, int len, int qos = 0);
参数 | 含义 |
msg | 二进制消息内容 |
len | 消息长度 |
qos | 发送 qos 类型 0:非可靠传输 1:可靠传输 |
注册远端设备控制消息回调
使用说明:此接口用于注册远端设备 SDK 发送的控制数据回调函数,可根据需要实现。
/*** @name TRRO_registerControlDataCallback* @brief 注册远端设备消息回调函数* @param[in] context 上下文指针,回调时会返回该上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerControlDataCallback(void* context, TRRO_onControlData * callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该上下文指标用于定位 |
callback | 回调函数 |
回调函数定义/*** @name TRRO_onControlData* @brief 接收远端设备消息回调* @param[in] context 上下文指针,返回注册时传入的context* @param[in] controller_id 远端设备ID* @param[in] msg 消息体内容* @param[in] len 消息体长度* @param[in] qos 消息qos类型 0:unreliable, 1:reliable* @return void*/typedef void TRRO_onControlData(void *context, const char *controller_id, const char* msg, int len, int qos);
参数 | 含义 |
context | 回调上下文,返回注册时传入的 context |
controller_id | 远端设备 ID |
msg | 控制消息字符串 |
len | 字符串长度 |
qos | 消息 qos 类型 0:不可靠传输 1:可靠传输 |
权限控制类接口
注册远端设备操控权限请求通知回调
使用说明:此接口用于在现场设备接收权限控制请求,可按需选择使用。
/*** @name TRRO_registerOperationPermissionRequest* @brief 注册远端设备操控权限请求通知回调* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerOperationPermissionRequest(void *context, TRRO_onOperationPermissionRequest *callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
/*** @name TRRO_onOperationPermissionRequest* @brief 远端设备操控权限申请通知* @param[in] remote_devid 请求权限的remote deviceId* @param[in] permission 请求的权限,参考TrroPermission, 0: guest 只有观看权限, 1: master 完全控制权限* @return void*/typedef void TRRO_onOperationPermissionRequest(void* context, const char* remote_devid, int permission);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
remote_devid | 请求权限的 remote deviceId |
permission | 请求的权限,参见 TrroPermission 0:guest 只有观看权限 1:master 完全控制权限 |
设置远端设备操作权限
使用说明:此接口用于在改现场设备设置远端设备的操作权限。
/*** @name TRRO_setOperationPermission* @brief 设置远端设备操控权限,目前同时只能有一个远端设备有master权限,若已有远端设备是master权限,调用该接口设置master权限,会自动取消之前设备的master权限然后设置新设备;* @param[in] remote_devid 设置权限的对端设备id* @param[in] permission 参考 TrroPermission, 0 guest,只有观看权、1 master, 完全控制权限* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_setOperationPermission(const char* remote_devid, int permission);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
重配置接口
重置RTC配置
使用说明:重配置视频流配置
/*** @name TRRO_reinitRtc(Experimental)* @brief 重配置,当前仅支持重置normal/combine/rtsp_enc等扩展采集协议配置* @param[in] config 重配置 JSON 数据*/extern "C" TRRO_EXPORT int TRRO_reinitRtc(const char * config);
参数 | 含义 |
config | 重配置 JSON 数据 |
音频控制接口
设置静音
使用说明:关闭音频传输
/*** @name TRRO_audioMute(Experimental)* @brief Mute 拉流端的音频 仅Server模式* @param[in] userid 拉流端id* @param[in] mute 是否mute* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_audioMute(const char* userid, bool mute);
参数 | 含义 |
userid | 拉流端 ID |
mute | 是否 mute |
获取音频采集/播放设备数量
使用说明:获取音频采集/播放设备数量,可用于遍历音频设备名称
/*** MediaDeviceType 设备类型枚举*/enum MediaDeviceType {///麦克风类型设备MediaDeviceTypeMic = 0,///扬声器类型设备MediaDeviceTypeSpeaker = 1,};/*** @name TRRO_getDeviceCount(Experimental)* @brief 根据MediaDeviceType 查询音频设备的个数。* @param[in] type 音频设备类型* @return 设备个数*/extern "C" TRRO_EXPORT int TRRO_getDeviceCount(MediaDeviceType type);
参数 | 含义 |
MediaDeviceType | 音频设备类型,麦克风 MediaDeviceTypeMic ,扬声器 MediaDeviceTypeSpeaker |
查询音频设备名称
使用说明:查询音频采集/播放设备名称,可用于过滤目标音频设备
/*** @name TRRO_getDeviceName(Experimental)* @brief 根据MediaDeviceType 和 index查询设备名字。* @param[in] type 设备类型* @param[in] index 为设备索引,值为 [0, TRRO_getDeviceCount)* @return 设备名字,失败返回null*/extern "C" TRRO_EXPORT const char* TRRO_getDeviceName(MediaDeviceType type, int index);
参数 | 含义 |
MediaDeviceType | 音频设备类型,麦克风 MediaDeviceTypeMic ,扬声器 MediaDeviceTypeSpeaker |
index | 音频设备编号,值为 [0, TRRO_getDeviceCount) |
更改当前音频设备
使用说明:更改当前音频采集/播放设备。SDK启动时会根据配置选取默认音频设备,调用该接口可进行更改。
/*** @name TRRO_setCurrentDevice(Experimental)* @brief 根据MediaDeviceType 和 index设备当前采集或者播放设备。* @param[in] type 设备类型* @param[in] index 为设备索引,值为 [0, TRRO_getDeviceCount)* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_setCurrentDevice(MediaDeviceType type, int index);
参数 | 含义 |
MediaDeviceType | 音频设备类型,麦克风 MediaDeviceTypeMic ,扬声器 MediaDeviceTypeSpeaker |
index | 音频设备编号,值为 [0, TRRO_getDeviceCount) |
日志/错误信息类接口
注册日志回调函数
使用说明:此接口用于注册日志回调函数,供上层业务获取日志。
/*** @name TRRO_registerLogCallback* @brief 注册日志回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerLogCallback(void *context, TRRO_OnLogData *callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
/*** @name TRRO_OnLogData* @brief 日志回调* @param[in] context 上下文指针* @param[in] msg 日志内容* @param[in] level 日志级别,参考枚举TrroLogLevel* @return void*/typedef void TRRO_OnLogData(void *context, const char *msg, int level);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
msg | 日志内容 |
level | 日志级别,参考枚举 TrroLogLevel |
注册错误事件回调
使用说明:此接口用于注册错误事件回调,当推流端出现异常时触发回调,可按需选择使用。
/*** @name TRRO_registerOnErrorEvent* @brief 注册错误事件回调函数* @param[in] context 上下文指针* @param[in] callback 回调函数* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_registerOnErrorEvent(void* context, TRRO_OnErrorEvent * callback);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
callback | 回调函数 |
/*** @name TRRO_OnErrorEvent* @brief 错误信息回调* @param[in] context 上下文指针* @param[in] error_code 错误码 为负值* @param[in] error_msg 错误信息* @return void*/typedef void TRRO_OnErrorEvent(void* context, int error_code, const char* error_msg);
参数 | 含义 |
context | 上下文指针,回调时会返回该指针用于定位 |
error_code | 错误码 |
error_msg | 错误信息 |
错误信息查询
使用说明:查询错误码对应的错误信息。
/*** @name getErrorMsg* @brief 根据错误码,返回错误信息。* @param[in] errorCode 错误码* @return errorMsg 排查帮助信息*/extern "C" TRRO_EXPORT const char* getErrorMsg(int errorCode);
参数 | 含义 |
errorCode | 要查询的错误码,输入正负错误码均可以 |
errorMsg | 对应错误信息 |
录制类接口
启动录制
使用说明:创建视频录制器,用于现场设备本地录制视频流。
/*** @name TRRO_startRecorder(Experimental)* @brief 启动录制* @param[in] recorderID 录制ID (若想录制SDK采集流,id需设置成对应stream, config文件中stream_config需加上 “record_on”:1)* @param[in] format 录制格式:0 :264* @param[in] width 编码宽* @param[in] heigh 编码高* @param[in] jump 录制跳帧数(隔几帧录一帧)* @param[in] fps 编码帧率* @param[in] bps 码率* @param[in] filename 文件名* @param[in] config 录制选项(保留)* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_startRecorder(int recorderID, int format, int width, int heigh, int jump, int fps, int bps,const char* filename, const char* config);
参数 | 含义 |
recorderID | 录制 ID (若想录制SDK采集的视频流,ID 需设置成对应视频流 ID, 并在对应视频流的 stream_config 配置中加上 “record_on”:1,对应视频流数据会自动导入匹配 ID 的 recorder) |
format | 录制格式:0 :264 |
width | 编码宽 |
heigh | 编码高 |
jump | 录制跳帧数(隔几帧录一帧) |
fps | 编码帧率 |
bps | 码率 |
filename | 文件名 |
config | 录制选项(保留) |
发送录制数据
使用说明:输入要录制的视频数据。录制外部输入视频流时,配合 TRRO_startRecorder 接口和 TRRO_stopRecorder 接口使用。
/*** @name TRRO_sendRecordVideoData(Experimental)* @brief 发送录制数据* @param[in] recorderID 录制ID* @param[in] data 录制数据* @param[in] width 数据源宽* @param[in] height 数据源高* @param[in] size 录制数据大小* @param[in] format 视频源格式 1 yuv420 , 4 YUYV* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_sendRecordVideoData(int recorderID, const char* data, int width, int height, int format);
参数 | 含义 |
recorderID | 录制 ID |
data | 录制数据 |
width | 编码宽 |
heigh | 编码高 |
size | 录制数据大小 |
format | 编码帧率 |
bps | 视频源格式 1 yuv420 , 4 YUYV |
切换录制文件
使用说明:切换录制文件,配合录制功能使用。
/*** @name TRRO_switchRecorderFile(Experimental)* @brief 切换录制文件* @param[in] recorderID 录制ID* @param[in] filename 文件名* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_switchRecorderFile(int recorderID, const char* filename);
参数 | 含义 |
recorderID | 录制 ID |
filename | 切换后的录制文件名 |
结束录制
使用说明:停止录制,配合录制功能使用。
/*** @name Trro_TRRO_OnStatestopRecorder(Experimental)* @brief 停止录制* @param[in] recorderID 录制ID* @return 1 for success, other failed*/extern "C" TRRO_EXPORT int TRRO_stopRecorder(int recorderID);
参数 | 含义 |
recorderID | 录制 ID |
视频采集接口
开始采集
使用说明:用于采集相机数据并通过回调函数将相机数据回调给用户。
/*** @name TRRO_onVideoCaptureFrame* @brief 外部调用 TRRO_startVideoCapture 时的数据回调* @param[in] context 上下文指针* @param[in] capture_id 采集视频的当前源 ID* @param[in] data 采集的视频数据* @param[in] length 采集的视频数据长度* @param[in] width 采集的视频宽度* @param[in] height 采集的视频高度* @param[in] color_format 采集的视频格式* @return void*/typedef void TRRO_onVideoCaptureFrame(void *context, unsigned long long capture_id, const char* data, int length, int width, int height, TrroColor color_format);/*** @name TRRO_startVideoCapture* @brief 开始摄像头采集* @param[in] context 上下文* @param[in] url 采集路径,摄像头为/dev/video*, rtsp时是rtsp的地址* @param[in] protocol 当等于kV4L2_DMA或者kV4L2_MMAP时,为摄像头采集。当等于 kRTSP 时,为rtsp地址* @param[in] TrroColor 采集视频格式* @param[in] width 采集视频宽度* @param[in] height 采集视频高度* @param[in] fps 采集视频帧率* @param[in] callback 采集视频回调* @param[in, out] capture_id 采集流的唯一标识符(重复则返回错误),支持传入传出(当(*capture_id) > 0时才用传入值,为0则内部生成修改该值)* @return 开始采集失败则返回错误码,返回1表示成功*/extern "C" TRRO_EXPORT int TRRO_startVideoCapture(void *context, const char* url, VideoCaptureProtocol protocol, TrroColor color_format, int width, int height, int fps, TRRO_onVideoCaptureFrame callback, unsigned long long* capture_id);
参数 | 含义 |
context | 上下文指针,用于回调定位 |
url | 采集路径,摄像头为 /dev/video*, rtsp 时是 rtsp 的地址 |
protocol | kRTSP 为网络摄像头 rtsp 协议采集,kV4L2_MMAP 为 USB/GMSL 等摄像头 V4L2 协议采集,kV4L2_DMA 用于 nvidia jetson 平台 V4L2 采集 |
TrroColor | 采集视频格式,V4L2 协议为摄像头图像格式,RTSP 协议采集为目标回调格式 |
width | 采集视频宽度 |
height | 采集视频高度 |
fps | 采集视频帧率 |
callback | 采集视频回调 |
capture_id | 采集标识符,用于区分不同的采集,传入为指针形式,支持值指定或者自动生成(当(*capture_id)> 0时使用指定传入值,为0使用 sdk 自动生成值) |
停止采集
使用说明:用于采集相机数据并通过回调函数将相机数据回调给用户。
/*** @name TRRO_stopVideoCapture* @brief 停止摄像头采集* @param[in] capture_id 采集视频源 ID(不能为0)* @return 停止采集失败则返回错误码,返回1表示成功*/extern "C" TRRO_EXPORT int TRRO_stopVideoCapture(unsigned long long capture_id);
参数 | 含义 |
capture_id | 采集视频源 ID(不能为0) |
网络评估接口
开启网络评估
使用说明:用于评估网络质量是否满足视频传输要求,可用于业务启动前测试网络。该接口为阻塞函数,使用该接口时,SDK会主动推送视频流进行网络测试,并收集网络指标进行评估。如果SDK已在视频推流中,建议可直接通过媒体状态回调接口观察网络指标。
/*** @name TRRO_testNetworkQuality* @brief 评估网络状态 注意:此函数是阻塞函数* 如果网络未连接成功超时时间为10s 再加网络探测时间* @param[in] stream_ids 想要进行网络探测的流ID数组* @param[in] stream_size 想要进行网络探测的流ID数组的大小* @param[in] test_time 连接成功后的探测持续时间,test_time 最小2s,最大10s;** @return int 网络评估 0:无法评估网络,1:良好网络,2:较差网络,3:不可用网络*/extern "C" TRRO_EXPORT int TRRO_testNetworkQuality(int* stream_ids, int stream_size, int test_time);
参数 | 含义 |
stream_ids | 用于网络评估的视频流id数组 |
stream_size | 视频流 ID 数组大小 |
test_time | 探测时长,最小2秒,最大10秒 |
获取软件信息
获取软件版本号
使用说明:获取软件版本号。
/*** @name getSdkVersion* @brief 获取sdk版本信息* @param[in] void* @return version 版本号*/extern "C" TRRO_EXPORT const char* TRRO_getSdkVersion();