本模块主要用于音视频监控,音视频对讲功能。
功能介绍
本模块主要实现音视频监控,音视频双向对讲功能。包含初始化音视频模块,注册监控对讲所需函数,SDK 主动发起开始停止对讲及数据接收,设备端实现监控对讲开始停止的具体操作,发送监控对讲的音视频数据,接收发起端音视频数据并进行播放;该模块是 IoT Video 的可选模块,需要在系统模块、物模型模块之后初始化。
使用流程
系统模块总流程
iv_avt_init //音视频传输模块初始化,注册回调|(音视频传输,接收信令,接收音频)|iv_avt_exit //音视频传输模块去初始化
音视频数据传输流程
iv_avt_get_av_enc_info_cb //获取音视频编码|iv_avt_start_real_play_cb //开始播放|while(1){iv_avt_send_stream} //推流|iv_avt_stop_real_play_cb //停止推流|停止调用iv_avt_send_stream
接收对向音频流程
iv_avt_start_recv_stream_cb //开始接收音频回调|iv_avt_recv_stream_cb //接收数据流,并进行解码播放|iv_avt_stop_recv_stream_cb //停止接收
接收信令
iv_avt_recv_command_cb //接收信令|处理信令 //处理信令
基本使用流程
接口列表
该功能模块提供以下接口:
接口 | 说明 |
音视频对讲模块初始化。 | |
音视频对讲模块去初始化。 | |
发送对讲音视频数据。 | |
获取发送流的实时状态。 | |
获取缓存中的实时数据量。 | |
设备端结束当前点播流。 | |
设备端主动发送数据到对端。 | |
获取设备的 peerinfo 信息。 |
用户需注册以下回调函数:
回调函数 | 说明 |
获取音视频编码参数信息。 | |
现场音视频开始播放回调。 | |
现场音视频停止播放回调。 | |
开始接收数据流回调。 | |
停止接收数据流回调。 | |
接收数据回调。 | |
监控时接收自定义数据并响应回调,已废弃。 | |
事件通知回调。 | |
接收信令回调。 | |
文件下载请求回调。 |
接口描述
iv_avt_init
功能描述
音视频对讲模块初始化。此接口在 SDK 初始化完成后调用,用于初始化音视频模块参数资源,云端发起的监控、回放处理函数,注册云端发过来的音视频数据接收函数。
函数原型
int iv_avt_init(const iv_avt_init_parm_s *pstInitParm);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pstInitParm | iv_avt_init_parm_s | 初始化参数。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_exit
功能描述
音视频对讲模块去初始化。本模块退出时调用,用于释放资源。
函数原型
int iv_avt_exit(void);
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
参数说明
无
iv_avt_send_stream
功能描述
发送对讲音视频数据。在监控请求发起时,设备端所有编码启动正常后,开始取流向请求端发送数据,注意不同清晰度视频请求时音频也需要同时发送。
函数原型
int iv_avt_send_stream(uint32_t visitor, uint32_t channel, iv_avt_video_res_type_e video_res_type,iv_avt_stream_type_e stream_type, void *p_stream);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
stream_type | iv_avt_stream_type_e | 音视频标识。 | 输入 |
pStream | void* | 每次发送的音视频数据内容。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
使用说明
iv_avt_start_real_play_cb
触发后,方可调用该接口发送数据流;其中 channel
, video_res_type
参数值,需要根据 iv_avt_start_real_play_cb
回调参数确定。
当发送的视频流为关键帧 (IDR),如有 SPS、PPS、VPS(H265) 时,需要将其与 IDR 帧放在一块内存地址中,并在 pStream
设置关键帧标志,pStream
在发送音频或视频数据时结构体类型不同,具体使用方式参考 demo
。iv_avt_get_send_stream_status
功能描述
获取视频流传输通道的发包统计数据如发送速率。
函数原型
int iv_avt_get_send_stream_status(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type,iv_p2p_send_stats_s *stream_send_status);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
stream_send_status | iv_p2p_send_stats_s | 音视频标识。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_get_send_stream_buf
功能描述
获取 p2p 缓存中实际数据量,用于自定义拥塞控制方式使用。
函数原型
size_t iv_avt_get_send_stream_buf(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
返回值
返回值 | 描述 |
size_t | 缓存中实时数据量的大小,单位 Byte。 |
iv_avt_send_finish_stream
功能描述
设备端结束当前发送的直播或者点播流。
函数原型
int iv_avt_send_finish_stream(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
使用说明
调用该接口设备端能够主动结束某一路视频流,可用于主动结束点播或者挂断的场景。
iv_avt_send_command
功能描述
设备端主动发送信令到对端。
函数原型
int iv_avt_send_command(uint32_t visitor, const char *msg, size_t msg_len, unsigned char *recv_buf,size_t *recv_len, uint32_t timeout_ms);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
msg | char* | 发送的消息内容。 | 输入 |
msg_len | size_t | 发送的消息长度。 | 输入 |
recv_buf | unsigned char* | 接收消息的缓存。 | 输出 |
recv_len | size_t* | 接收消息的长度。 | 输入输出 |
timeout_ms | uint32_t | 超时时间,单位 ms。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
使用说明
该调用为同步阻塞方式,如果设置了较短的超时时间,则在网络繁忙或不稳定时候,该消息可能会因为超时而被丢弃。
msg 传入的内存类型不做要求,可以是只读的,也可以是可读写的;msg 可以为任意格式字符或二进制数据,长度由 msg_len 提供,建议在16KB以内,否则会影响实时性。
recv_buf 必须是事先分配的足够大的内存用于存放对端回复的数据,recv_len 首先传入 recv_buf 最大的大小,接收到数据后会写入实际接收的数据大小。
该接口是一个同步阻塞接口,只能在直播或者回看期间调用,如果超时时间设置为0,SDK 内部会采用默认超时(7500ms左右)。
iv_avt_get_peerinfo
功能描述
获取 peerinfo 信息。
函数原型
const char *iv_avt_get_peerinfo(void);
参数说明
无
返回值
返回值 | 描述 |
peerinfo | peerinfo 的实际信息。 |
说明:
该接口为了及时获取最准确的 peerinfo,推荐
IV_AVT_EVENT_P2P_PEER_READY
事件回调中调用。iv_avt_get_av_enc_info_cb
功能描述
现场音视频开始播放回调。用于观看端发起现场监控时,SDK 回调设备端以取得此次监控通路的相应音视频信息。
函数原型
void (*iv_avt_get_av_enc_info_cb)(uint32_t visitor, uint32_t channel, iv_avt_video_res_type_e video_res_type,iv_cm_av_data_info_s *av_data_info);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
av_data_info | iv_cm_av_data_info_s * | 音视频数据信息。 | 输出 |
返回值
无
iv_avt_start_real_play_cb
功能描述
现场音视频开始播放回调。用于观看端发起现场监控时,SDK 回调通知设备端启动相关音视频业务。
函数原型
void (*iv_avt_start_real_play_cb)(uint32_t visitor, uint32_t channel, iv_avt_video_res_type_e video_res_type,void *args);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
args | void * | 当使用用户回放通道时,会传输些时间参数,暂未使用。 | 输入 |
返回值
无
注意:
当每次请求数据流时都会触发一次该回调,即使是不同的对端请求相同的 channel 和类型的数据流时,也会触发多次该回调,详细使用方法参照
demo
;visitor
表示对端的 ID,表明请求者的身份;channel
表示摄像头的 ID,针对单摄像头设备,该值为0;video_res_type
表示一个摄像头传输的视频流的类型(类似 IPC 的主码流,子码流概念),分辨率不强制一一对应。iv_avt_stop_real_play_cb
功能描述
现场音视频停止播放回调,用于观看端停止现场监控时,SDK 回调通知设备端关闭相关音视频业务。
函数原型
void (*iv_avt_stop_real_play_cb)(uint32_t visitor, uint32_t channel, iv_avt_video_res_type_e video_res_type);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | 视频流类型。 | 输入 |
返回值
无
注意:
当每次结束数据流时都会触发一次该回调,即使是不同的对端结束相同的 channel 和类型的数据流时,也会触发多次该回调,详细使用方法参照
demo
。iv_avt_start_recv_stream_cb
功能描述
通知设备开始接收对向数据流回调,并输出数据流的编码信息,当前版本支持音频。
函数原型
int (*iv_avt_start_recv_stream_cb)(uint32_t visitor, uint32_t channel, iv_cm_av_data_info_s *p_av_data_info);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
pstAvDataInfo | iv_cm_av_data_info_s * | 音视频解码信息参数。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_stop_recv_stream_cb
功能描述
通知设备停止接收对向数据流的回调。
函数原型
int (*iv_avt_stop_recv_stream_cb)(uint32_t visitor, uint32_t channel, iv_avt_stream_type_e stream_type);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
stream_type | iv_avt_stream_type_e | 音视频标识。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_recv_stream_cb
功能描述
接收对向的数据流回调。用于观看端向设备发送音视频数据时,设备端的接收数据回调,由用户实现对数据进行处理播放。
函数原型
int (*iv_avt_recv_stream_cb)(uint32_t visitor, uint32_t channel, iv_avt_stream_type_e stream_type, void *p_stream);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
stream_type | iv_avt_stream_type_e | 音视频标识。 | 输入 |
pStream | void * | 每次接收的音频数据内容。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_recv_user_data_cb
说明:
已废弃。
功能描述
监控过程中,由 App 发送的实时指令数据到设备,数据内容由用户自声明,可以作为控制 PTZ 命令等功能,设备端填写相应的返回值。该接口是一个同步接口,不要做延时太多的操作,已废弃,相关功能已转移至
iv_avt_recv_command_cb
回调的事件IV_AVT_COMMAND_USR_DATA
中。函数原型
void (*iv_avt_recv_user_data_cb)(uint32_t visitor,uint32_t channel, const char *src, uint32_t src_len,iv_cm_memory_s *dst);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
src | char * | 用户数据。 | 输入 |
src_len | uint32_t | 数据长度。 | 输入 |
dst | iv_cm_memory_s | 返回的数据地址和长度。 | 输出 |
返回值
无
iv_avt_notify_cb
功能描述
监控过程中,事件通知接口,用户在该回调中可以根据事件类型做相应的操作。当前版本主要是拥塞控制的事件回调。
函数原型
void (*iv_avt_notify_cb)(iv_avt_event_e event, uint32_t visitor, uint32_t channel,iv_avt_stream_type_e stream_type);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
event | iv_avt_event_e | 事件类型。 | 输入 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
stream_type | iv_avt_stream_type_e | 音视频流数据类型。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_avt_recv_command_cb
功能描述
接收信令处理回调。
函数原型
int (*iv_avt_recv_command_cb)(iv_avt_command_type_e command, uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type, void *args);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
command | iv_avt_command_type_e | 信令类型。 | 输入 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
video_res_type | iv_avt_video_res_type_e | stream 类型。 | 输入 |
args | void * | 信令参数。 | 输入输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
说明:
不同的 command,参数 args 不同,具体使用方式参照
iot_video_demo
,回调中切勿做耗时较长的操作。iv_avt_download_file_cb
功能描述
文件下载回调。
函数原型
int (*iv_avt_download_file_cb)(iv_avt_download_status_e status, uint32_t visitor,uint32_t channel, void *args);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
status | iv_avt_download_status_e | 下载状态。 | 输入 |
visitor | uint32_t | 访问者 ID。 | 输入 |
channel | uint32_t | 通道号。 | 输入 |
args | void * | 信令参数。 | 输入输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
说明:
不同的 status,参数 args 不同,具体使用方式参照
iot_video_demo
,回调中切勿做耗时较长的操作。数据结构列表
本模块提供以下数据结构:
iv_avt_stream_type_e:音视频数据类型枚举。
iv_avt_device_status_e:设备状态。
iv_avt_request_type_e:请求的类型。
iv_avt_video_res_e:视频清晰度枚举。
iv_avt_usr_data_parm_s:用户数据信令参数。
iv_avt_req_stream_param_s:请求流信令参数。
iv_avt_chn_name_param_s:通道名称参数。
iv_avt_event_e:事件类型枚举。
iv_avt_command_type_e:信令的类型枚举。
iv_avt_download_status_e:下载状态枚举。
iv_avt_p2p_log_level_e p2p:日志等级。
congestion_ctrl_s:拥塞控制信息。
p2p_keep_alive_s p2p:保活信息。
iv_p2p_send_stats_s p2p:发送流的状态。
p2p_init_params_s p2p:初始化参数。
local_net_info_s:局域网数据传输参数。
iv_avt_init_parm_s:音视频对讲初始化参数结构体。
数据结构描述
iv_avt_stream_type_e
功能描述
音视频数据类型枚举,包括音频和视频。
结构原型
typedef enum{IV_AVT_STREAM_TYPE_AUDIO = 0, /*audio*/IV_AVT_STREAM_TYPE_VIDEO = 1, /*video*/IV_AVT_STREAM_TYPE_AV = 2, /*audio+video*/IV_AVT_STREAM_TYPE_BUTT} iv_avt_stream_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_STREAM_TYPE_AUDIO | 音视 | 0 |
IV_AVT_STREAM_TYPE_VIDEO | 视频 | 1 |
IV_AVT_STREAM_TYPE_AV | 音频+视频 | 2 |
iv_avt_device_status_e
功能描述
对端(例如App、小程序)请求结果。
结构原型
typedef enum{IV_AVT_DEV_ACCEPT = 0, /* device accept app request */IV_AVT_DEV_REFUSE = 1, /* device refuse app request*/IV_AVT_DEV_STATUS_BUTT = 10} iv_avt_device_status_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_DEV_ACCEPT | 接受请求 | 0 |
IV_AVT_DEV_REFUSE | 拒绝请求 | 1 |
IV_AVT_DEV_STATUS_BUTT | 无效值 | 10 |
iv_avt_request_type_e
接口描述
请求的类型。
接口原型
typedef enum{IV_AVT_REQUEST_SEND_STREAM = 0, /* app request device to send stream */IV_AVT_REQUEST_RECV_STREAM = 1, /* app request device to receice stream, only support audio*/IV_AVT_REQUEST_BUTT} iv_avt_request_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_REQUEST_SEND_STREAM | 请求设备发送数据流。 | 0 |
IV_AVT_REQUEST_RECV_STREAM | 请求设备接收数据流。 | 1 |
IV_AVT_REQUEST_BUTT | 无效值。 | 10 |
使用说明
用于事件
IV_AVT_COMMAND_REQ_STREAM
。iv_avt_video_res_type_e
功能描述
视频流类型参数,用于区分视频流的类型,对具体对应的视频的分辨率用户自行决定,没有严格要求。
结构原型
typedef enum{IV_AVT_VIDEO_RES_FL = 0, // fluency streamIV_AVT_VIDEO_RES_SD = 1, // standard streamIV_AVT_VIDEO_RES_HD = 2, // high streamIV_AVT_VIDEO_RES_PB = 3, // playback streamIV_AVT_VIDEO_RES_BUTT} iv_avt_video_res_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_VIDEO_RES_FL | 流畅流 | 0 |
IV_AVT_VIDEO_RES_SD | 标清流 | 1 |
IV_AVT_VIDEO_RES_HD | 高清流 | 2 |
IV_AVT_VIDEO_RES_PB | 回放流 | 3 |
IV_AVT_VIDEO_RES_BUTT | 无效流 | 4 |
iv_avt_usr_data_parm_s
功能描述
用户数据信令的实际参数。
结构原型
typedef struct {char *src; // input datauint32_t src_len; // input data lengthiv_cm_memory_s dst; // output data} iv_avt_usr_data_parm_s;
参数说明
成员名称 | 描述 | 取值 |
src | 信令输入的数据 | - |
src_len | 参数的长度 | - |
dst | 信令返回的数据 | - |
注意事项
返回的数据地址
dst->buf
需要用户保证当前回调函数退出后,其生命周期仍然有效。为了避免内存泄露,用户不需要释放该地址,可以通过注册 dst->buf_free_fn
回调,IoT Video SDK
会在合适的时机调用dst->buf_free_fn
释放该地址,如果该地址不需要释放,则将 dst->buf_free_fn
置为NULL
。
用户返回的 dst->buf
地址必须是可读写的,SDK 内部可能会修改;如果返回 buf
为 NULL
或者 cmd_len
为0时,表示通道断开, App
侧会收到通道断开通知。iv_avt_req_stream_param_s
功能描述
IV_AVT_COMMAND_REQ_STREAM
事件对应的参数。结构原型
typedef struct {iv_avt_request_type_e request_type; // input dataiv_avt_device_status_e request_result; // output data} iv_avt_req_stream_param_s;
参数说明
成员名称 | 描述 | 取值 |
request_type | 请求的数据类型 | 输入数据。 |
request_result | 请求结果 | 输出数据,用户决定是否响应该请求。 |
iv_avt_chn_name_param_s
功能描述
IV_AVT_COMMAND_CHN_NAME
事件对应的参数。结构原型
typedef struct {iv_cm_memory_s name;uint8_t is_online;} iv_avt_chn_name_param_s;
参数说明
成员名称 | 描述 | 取值 |
name | 通道名称 | 输入数据。 |
is_online | 是否在线 | 0:离线。 1:在线。 |
注意事项
返回的数据地址
name->buf
需要用户保证当前回调函数退出后,其生命周期仍然有效。为了避免内存泄露,用户不需要释放该地址,可以通过注册 name->buf_free_fn
回调,IoT Video SDK
会在合适的时机调用dst->buf_free_fn
释放该地址,如果该地址不需要释放,则将 name->buf_free_fn
置为NULL
。
用户返回的 name->buf
地址必须是可读写的,SDK 内部可能会修改;如果返回 buf
为 NULL
或者 cmd_len
为0时,表示通道断开,App
侧会收到通道断开通知。
name
会被嵌入到 json 格式中,不能有不满足 json 的特殊字符,推荐使用大小写字母和数字的组合,避免使用特殊字符。iv_avt_event_e
功能描述
事件类型。
结构原型
typedef enum{IV_AVT_EVENT_P2P_PEER_READY = 0,IV_AVT_EVENT_P2P_PEER_CONNECT_FAIL = 1,IV_AVT_EVENT_P2P_PEER_ERROR = 2,IV_AVT_EVENT_P2P_PEER_ADDR_CHANGED = 3,IV_AVT_EVENT_P2P_WATERMARK_LOW = 4,IV_AVT_EVENT_P2P_WATERMARK_WARN = 5,IV_AVT_EVENT_P2P_WATERMARK_HIGH = 6,IV_AVT_EVENT_P2P_LOCAL_NET_READY = 7,IV_AVT_EVENT_P2P_BUTT} iv_avt_event_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_EVENT_P2P_PEER_READY | P2P 初始化完成通知。 | 0 |
IV_AVT_EVENT_P2P_PEER_CONNECT_FAIL | P2P 连接 STUN 服务器失败。 | 1 |
IV_AVT_EVENT_P2P_PEER_ERROR | 检测网络错误。 | 2 |
IV_AVT_EVENT_P2P_PEER_ADDR_CHANGED | P2P 地址方式变化。 | 3 |
IV_AVT_EVENT_P2P_WATERMARK_LOW | P2P 缓存数据低于最低值通知。 | 4 |
IV_AVT_EVENT_P2P_WATERMARK_WARN | P2P 缓存数据超过报警值通知。 | 5 |
IV_AVT_EVENT_P2P_WATERMARK_HIGH | P2P 缓存数据超过最大值通知。 | 6 |
IV_AVT_EVENT_P2P_LOCAL_NET_READY | P2P 局域网完成。 | 7 |
IV_AVT_EVENT_P2P_BUTT | 无效事件。 | 8 |
注意事项
出现
IV_AVT_EVENT_P2P_PEER_ADDR_CHANGED
事件,SDK 内部会进行重新协商,但此时 P2P 通道已断开,需要停止送入数据。
出现IV_AVT_EVENT_P2P_PEER_ERROR
或 IV_AVT_EVENT_P2P_PEER_CONNECT_FAIL
事件时,如果用户只需要局域网模式,就不用处理这两个事件,如果用户需要广域网通信,就需要用户手动重新初始化 SDK。
如果用户主动修改设备端 IP
地址,P2P 通道可能恢复较慢,受MQTT
保活时间影响,可以在IP
地址修改后直接重新初始化所有接口来加快P2P
通道恢复时间。iv_avt_command_type_e
功能描述
信令的类型。
结构原型
typedef enum{IV_AVT_COMMAND_USR_DATA = 0, // usr define data, for example ptzIV_AVT_COMMAND_REQ_STREAM = 1, // request stream (send or receive)IV_AVT_COMMAND_CHN_NAME = 2, // get channel nameIV_AVT_COMMAND_REQ_IFRAME = 3, // request I frame// playback commandIV_AVT_COMMAND_PLAYBACK_PAUSE, // pause playbackIV_AVT_COMMAND_PLAYBACK_RESUME, // resume playbackIV_AVT_COMMAND_PLAYBACK_QUERY_MONTH, // query record info of monthIV_AVT_COMMAND_PLAYBACK_QUERY_DAY, // query record info of dayIV_AVT_COMMAND_PLAYBACK_SEEK, // seek record positionIV_AVT_COMMAND_PLAYBACK_FF, // playback fast forward(快进)IV_AVT_COMMAND_PLAYBACK_SPEED, // playback speed(快放 or 慢放)IV_AVT_COMMAND_PLAYBACK_REWIND, // rewind record(倒放)IV_AVT_COMMAND_TYPE_BUTT} iv_avt_command_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_COMMAND_USR_DATA | 用户数据信令 | 0 |
IV_AVT_COMMAND_REQ_STREAM | 请求流信令 | 1 |
IV_AVT_COMMAND_CHN_NAME | 获取通道名称信令 | 2 |
IV_AVT_COMMAND_REQ_IFRAME | 请求I帧信令 | 3 |
IV_AVT_COMMAND_PLAYBACK_PAUSE | 暂停回放 | 4 |
IV_AVT_COMMAND_PLAYBACK_RESUME | 继续回放 | 5 |
IV_AVT_COMMAND_PLAYBACK_QUERY_MONTH | 按月查询录像 | 6 |
IV_AVT_COMMAND_PLAYBACK_QUERY_DAY | 按天查询录像 | 7 |
IV_AVT_COMMAND_PLAYBACK_SEEK | 移动播放位置 | 8 |
IV_AVT_COMMAND_PLAYBACK_FF | 快进 | 9 |
IV_AVT_COMMAND_PLAYBACK_SPEED | 设置播放速度 | 10 |
IV_AVT_COMMAND_PLAYBACK_REWIND | 倒放 | 11 |
IV_AVT_COMMAND_TYPE_BUTT | 信令的数量 | - |
注意事项
IV_AVT_COMMAND_CHN_NAME
仅在多摄像头设备时触发,根据system
模块初始化时参数max_channel_num
决定触发次数,每一次触发设置一个通道的名称,如果其中一次该信令的返回值不为 IV_ERR_NONE,则会停止后续触发,只有绑定了名称的channel
才能正常工作。iv_avt_download_status_e
功能描述
视频下载状态枚举,一般用于 App(或小程序)下载设备内的本地录像。
结构原型
typedef enum { IV_AVT_DOWNLOAD_STATUS_START, // start to download IV_AVT_DOWNLOAD_STATUS_RUNNING, IV_AVT_DOWNLOAD_STATUS_STOP, // stop to download IV_AVT_DOWNLOAD_STATUS_BUTT } iv_avt_download_status_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_DOWNLOAD_STATUS_START | 开始下载 | 0 |
IV_AVT_DOWNLOAD_STATUS_RUNNING | 下载中 | 1 |
IV_AVT_DOWNLOAD_STATUS_STOP | 停止下载 | 2 |
IV_AVT_DOWNLOAD_STATUS_BUTT | 无效状态 | - |
iv_avt_p2p_log_level_e
功能描述
日志等级。
结构原型
typedef enum{IV_AVT_P2P_LOG_DISABLE = 0,IV_AVT_P2P_LOG_ERROR = 1,IV_AVT_P2P_LOG_WARN = 2,IV_AVT_P2P_LOG_INFO = 3,IV_AVT_P2P_LOG_DEBUG = 4,IV_AVT_P2P_LOG_VERBOSE = 5} iv_avt_p2p_log_level_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_P2P_LOG_DISABLE | 关闭 p2p 日志。 | 0 |
IV_AVT_P2P_LOG_ERROR | 只打印 p2p 的 error 类型。 | 1 |
IV_AVT_P2P_LOG_WARN | 打印 p2p 的 error、 warning 类型。 | 2 |
IV_AVT_P2P_LOG_INFO | 打印 p2p 的 error、warning、info 类型。 | 3 |
IV_AVT_P2P_LOG_DEBUG | 打印 p2p 的 error、warning、info、debug。 | 4 |
IV_AVT_P2P_LOG_VERBOSE | 打印 p2p 的所有日志。 | 5 |
iv_avt_p2p_nic_type_e
功能描述
网卡类型。
结构原型
typedef enum{IV_AVT_P2P_NIC_NORMAL = 0,IV_AVT_P2P_NIC_NAT_EX = 1,} iv_avt_p2p_nic_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_P2P_NIC_NORMAL | 正常网卡。 | 0 |
IV_AVT_P2P_NIC_NAT_EX | 外挂 NAT 网卡。 | 1 |
iv_avt_p2p_tp_type_e
功能描述
P2P 网络传输方式。
结构原型
typedef enum{IV_AVT_P2P_UDP = 0,IV_AVT_P2P_TCP = 1,} iv_avt_p2p_tp_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_AVT_P2P_UDP | P2P 使用 UDP 协议。 | 0 |
IV_AVT_P2P_TCP | P2P 使用 TCP 协议。 | 1 |
congestion_ctrl_s
功能描述
拥塞控制参数。
结构原型
typedef struct {size_t low_mark;size_t warn_mark;size_t high_mark;bool enable;} congestion_ctrl_s;
参数说明
成员名称 | 描述 | 取值 |
low_mark | 缓存数据最低值,单位 Byte。 | - |
warn_mark | 缓存数据告警值,单位 Byte。 | - |
high_mark | 缓存数据最高值,单位 Byte。 | - |
enable | 拥塞控制使能。 | - |
使用说明
当
enable=0
时,无拥塞控制事件通知;当enable=1
时,用户需要设置low_mark
, warn_mark
, high_mark
值, IoT Video SDK
会根据网络环境和用户设置参数,触发相应的事件通知。当
IoT Video SDK
内部缓存的数据超过warn_mark
时,会触发一次IV_AVT_EVENT_P2P_WATERMARK_WARN
事件通知,表明缓存较多了,用户需要降低数据流的发送。当
IoT Video SDK
内部缓存的数据超过high_mark
时,会触发一次IV_AVT_EVENT_P2P_WATERMARK_HIGH
事件通知,表明内存缓存太多,网络环境太差,用户需要降低或停止数据流的发送。当
IoT Video SDK
内部缓存的数据恢复到low_mark
时,会触发一次IV_AVT_EVENT_P2P_WATERMARK_LOW
事件通知,表明内存缓存正常,用户可以正常发送数据了。p2p_keep_alive_s
功能描述
p2p 保活参数。
结构原型
typedef struct p2p_keep_alive_s {uint8_t time_inter_s;uint8_t max_attempt_num;} p2p_keep_alive_s;
参数说明
成员名称 | 描述 | 取值 |
time_inter_s | P2P 保活最大时间间隔,单位 s。 | 0表示关闭 p2p 保活功能。 |
max_attempt_num | P2P 保活最大尝试次数,最大10。 | 推荐3,0表示关闭 p2p 保活功能。 |
注意事项
p2p 保活通过与服务器之间进行通信,判断设备端网络状态是否发生变化,特别是设备端网络出现中断后再连接时,引起设备所在网络的拓扑结构的变化,如果网络拓扑发生变化,IoT Video SDK 内部会重新进行 p2p 协商,从而保证 p2p 通信正常。
time_inter_s
表示设备与服务器之间每次通信的最大时间间隔,设置的太大,设备网络断开到恢复的时间太短检测不到,可能会导致 p2p 通信失败,设置的太小,通信过于频繁占用资源较多,推荐设置5s到10s。
max_attempt_num
表示设备每次与服务器通信探测包数量,设置的太大,探测包太多影响设备的网络资源,设置的太少,网络差的情况下,判断不准确,推荐设置3。
time_inter_s
和 max_attempt_num
其中一个为0时,表示关闭 p2p 保活机制,在这种情况下 IoT Video SDK 内部会通过 system 模块中的 keep_alive_ms
(MQTT 保活时间)进行网络判断,该值较大,灵敏度不如 p2p 保活参数。iv_p2p_send_stats_s
接口描述
P2P 数据传输的状态。
结构原型
typedef struct {uint32_t inst_net_rate;uint32_t ave_sent_rate;uint64_t sum_sent_acked;uint32_t link_mode;} iv_p2p_send_stats_s;
参数说明
成员名称 | 描述 | 取值 |
inst_net_rate | 瞬时发送速率,随网速变化会有较大波动。 | 字节/秒 |
ave_sent_rate | 过去一秒内累计发送并得到对端确认的数据,即平均发送速率。 | 字节/秒 |
sum_sent_acked | 累计发送并得到对端确认的数据。 | 字节 |
link_mode | 当前 P2P 链路的连接模式:0 无效;1 直连;2 转发。 | 整数 |
p2p_init_params
接口描述
p2p 初始化时配置参数。
typedef struct {iv_avt_p2p_log_level_e log_level;const char *log_file_path;uint32_t log_file_size;uint32_t mtu_size;iv_avt_p2p_nic_type_e nic_type;uint32_t sender_interval_ms;uint32_t keepalive_interval_s;uint32_t access_retry_times;iv_avt_p2p_tp_type_e protocol;} p2p_init_params_s;
参数说明
成员名称 | 描述 | 取值 |
log_level | P2P 模块日志级别。 | iv_avt_p2p_log_level_e |
log_file_path | P2P 模块日志文件路径,若为 NULL 则输出到 stderr 或串口终端,建议配置在"/tmp"路径。 | char* |
log_file_size | P2P 模块日志文件大小限制,实际占用空间最大为该值两倍,SDK 会自动回滚。 | uint32_t |
mtu_size | P2P 模块 UDP MTU 大小。 | 范围 500-1460,若为0则采用默认值1460。 |
nic_type | 设备采用某些特殊的 NAT 网卡时需要进行设置。 | 一般置为0。 |
sender_interval_ms | 发送数据的 timer 间隔,默认为10毫秒,在码率较低且对功耗要求较高时可以适当改大。 | 一般置为0即为默认值。 |
keepalive_interval_s | P2P 与 STUN 服务器的保活间隔,默认为10秒。 | 一般置为0即为默认值。 |
access_retry_times | 连接 STUN 服务器的重试次数,默认为10,实际的重试次数为该值的3倍。 | 一般置为0即为默认值。 |
protocol | 一般置为0,当设备处于不支持 UDP 包的网络环境时,可以设置该参数为IV_AVT_P2P_TCP。 | 一般置为0即为默认值。 |
local_net_info_s
功能描述
局域网传输配置参数。
结构原型
typedef struct {int probe_port; //局域网探测的端口int trans_port; //局域网数据传输的端口char local_addr[64]; //设备在局域网的IP地址char *vendor_id; //厂商ID,用于区分不同厂商的设备char *device_id; //设备ID,用于区分设备} local_net_info_s;
参数说明
成员名称 | 描述 | 取值 |
probe_port | 探测监听端口,用于接收广播消息,设置为0表示关闭局域网功能。 | int |
trans_port | 局域网数据传输端口号,设置为0表示关闭局域网功能。 | int |
local_addr | 局域网地址。 | char |
vendor_id | 厂商 ID。 | char* |
device_id | 设备 ID。 | char* |
注意事项
probe_port
和trans_port
任意值为0,都表示关闭局域网通信功能。local_addr
设置当前设备的局域网地址,如192.168.0.22
等。vendor_id
表示厂商 ID,用于区分不同厂商,如果设置为 NULL,SDK 内部使用三元组信息中的ProductId
替代,同一类设备的vendor_id
相同,只能由大小写字母、数字、下划线组成,不能有特殊字符。device_id
表示设备 ID,用于区分不同设备,如果设置为 NULL,SDK 内部使用三元组信息中的DeviceName
替代,同一类设备的device_id
要保证唯一性,只能由大小写字母、数字、下划线组成,不能有特殊字符。iv_avt_init_parm_s
功能描述
音视频对讲初始化参数结构体。
结构原型
typedef struct iv_avt_init_parm_s {uint32_t max_frame_size;uint32_t max_connect_num;void (*iv_avt_get_av_enc_info_cb)(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type,iv_cm_av_data_info_s *av_data_info);void (*iv_avt_start_real_play_cb)(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type, void *args);void (*iv_avt_stop_real_play_cb)(uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type);int (*iv_avt_start_recv_stream_cb)(uint32_t visitor, uint32_t channel,iv_cm_av_data_info_s *p_av_data_info);int (*iv_avt_stop_recv_stream_cb)(uint32_t visitor, uint32_t channel,iv_avt_stream_type_e stream_type);int (*iv_avt_recv_stream_cb)(uint32_t visitor, uint32_t channel,iv_avt_stream_type_e stream_type, void *p_stream);/*已废弃,通过IV_AVT_COMMAND_USR_DATA实现*/void (*iv_avt_recv_user_data_cb)(uint32_t visitor, uint32_t channel, const char *src,uint32_t src_len, iv_cm_memory_s *dst);void (*iv_avt_notify_cb)(iv_avt_event_e event, uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type);int (*iv_avt_recv_command_cb)(iv_avt_command_type_e command, uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type, void *args);int (*iv_avt_download_file_cb)(iv_avt_download_status_e status, uint32_t visitor,uint32_t channel, void *args);congestion_ctrl_s congestion;p2p_keep_alive_s p2p_keep_alive;p2p_init_params_s p2p_init_params;local_net_info_s net_info;} iv_avt_init_parm_s;
参数说明
成员名称 | 描述 | 取值 |
max_frame_size | 发送数据的最大值,发送音视频或自定义数据时,保证每次数据的大小小于此值。 | 单位KB |
max_connect_num | 当前设备支持的最大连接数,即连接的 App 数量。 | 最大32 |
iv_avt_get_av_enc_info_cb | 获取设备编码信息回调。 | - |
iv_avt_start_real_play_cb | 现场监控开启回调。 | - |
iv_avt_stop_real_play_cb | 现场监控停止回调。 | - |
iv_avt_start_recv_stream_cb | 通知设备对音频开始的回调。 | - |
iv_avt_stop_recv_stream_cb | 通知设备对音频结束的回调。 | - |
iv_avt_recv_stream_cb | 接收观看端发来的音视频数据回调。 | - |
iv_avt_recv_user_data_cb | 已废弃。 | - |
iv_avt_notify_cb | 事件通知回调。 | - |
iv_avt_recv_command_cb | 接收信令通知回调。 | - |
iv_avt_download_file_cb | 下载本地录像通知回调。 | - |
congestion | 拥塞控制配置。 | - |
p2p_keep_alive | P2P 保活配置。 | - |
p2p_init_params | P2P 初始化参数。 | - |
net_info | 局域网配置(可选)。 | - |
注意:
所有回调切勿做耗时较长的操作。
注意事项
内存消耗统计方法
内存开销公式如下:
memory(KByte) = n * 2 * max_frame_size(KB) + 120KB
其中,n 是通道数量,max_frame_size 是设置的最大帧的大小。
示例代码
1. 对讲模块初始化
int av_talk_init(void){int ret = 0;iv_avt_init_parm_s stAvtInitParameters;memset(&stAvtInitParameters, 0, sizeof(iv_avt_init_parm_s));stAvtInitParameters.max_frame_size = 384; // 384kBstAvtInitParameters.max_connect_num = MAX_CONNECT_NUM; //stAvtInitParameters.congestion.enable = true;#ifdef USER_CONGESTION_CTRLstAvtInitParameters.congestion.low_mark = 0;stAvtInitParameters.congestion.warn_mark = 0;stAvtInitParameters.congestion.high_mark = 0;#elsestAvtInitParameters.congestion.low_mark = 200 * 1024;stAvtInitParameters.congestion.warn_mark = 400 * 1024;stAvtInitParameters.congestion.high_mark = 500 * 1024;#endifstAvtInitParameters.p2p_keep_alive.time_inter_s = 10;stAvtInitParameters.p2p_keep_alive.max_attempt_num = 4;stAvtInitParameters.iv_avt_get_av_enc_info_cb = av_talk_get_enc_info;stAvtInitParameters.iv_avt_start_real_play_cb = av_talk_start_real_play;stAvtInitParameters.iv_avt_stop_real_play_cb = av_talk_stop_real_play;stAvtInitParameters.iv_avt_start_recv_stream_cb = av_talk_start_recv_stream;stAvtInitParameters.iv_avt_recv_stream_cb = av_talk_recv_stream;stAvtInitParameters.iv_avt_stop_recv_stream_cb = av_talk_stop_recv_stream;stAvtInitParameters.iv_avt_notify_cb = av_talk_notify_process;stAvtInitParameters.iv_avt_recv_command_cb = av_talk_command_proc;stAvtInitParameters.p2p_init_params.log_level = IV_AVT_P2P_LOG_DEBUG;stAvtInitParameters.p2p_init_params.log_file_path = "/tmp";stAvtInitParameters.p2p_init_params.log_file_size = 1 * 1024 * 1024;ret = iv_avt_init(&stAvtInitParameters);if (ret < 0) {Log_e("iv_avt_init error:%d", ret);return ret;}return ret;}
2. 发送音视频数据
当
iv_avt_start_real_play_cb;
回调触发后, 可调用如下接口发送音视频数据:rc = iv_avt_send_stream(visitor, p_enc_handle->channel, p_enc_handle->video_res_type,IV_AVT_STREAM_TYPE_VIDEO, &v_stream);rc = iv_avt_send_stream(visitor, p_enc_handle->channel, p_enc_handle->video_res_type,IV_AVT_STREAM_TYPE_AUDIO, &a_stream);
3. 接收音视频数据
int av_talk_recv_stream(uint32_t visitor, uint32_t channel, iv_avt_stream_type_e stream_type,void *pStream){return qcloud_av_dec_play(visitor, channel, stream_type, pStream);}
4. 自定义数据收发
int av_talk_command_proc(iv_avt_command_type_e command, uint32_t visitor, uint32_t channel,iv_avt_video_res_type_e video_res_type, void *args){Log_d("command %d visitor %d channel %d stream %d args %p", command, visitor, channel,video_res_type, args);int rc = 0;switch (command) {case IV_AVT_COMMAND_USR_DATA: {iv_avt_usr_data_parm_s *usr_data = (iv_avt_usr_data_parm_s *)args;av_talk_recv_user_data(visitor, channel, usr_data->src, usr_data->src_len,&usr_data->dst);break;}case IV_AVT_COMMAND_REQ_STREAM: {iv_avt_req_stream_param_s *req_param = (iv_avt_req_stream_param_s *)args;Log_d("type %d\\n", req_param->request_type);req_param->request_result = IV_AVT_DEV_ACCEPT;break;}case IV_AVT_COMMAND_CHN_NAME: {iv_avt_chn_name_param_s *chn_name = (iv_avt_chn_name_param_s *)args;rc = av_talk_get_dev_name_proc(visitor, channel, &chn_name->name, &chn_name->is_online);break;}case IV_AVT_COMMAND_REQ_IFRAME: {Log_i("visitor need idr frame!");break;}default:break;}return rc;}
5. 对讲模块退出
int av_talk_exit(void){return iv_avt_exit();}