有奖捉虫:办公协同&微信生态&物联网文档专题 HOT
本模块主要用于音视频监控,音视频对讲功能。

功能介绍

本模块主要实现音视频监控,音视频双向对讲功能。包含初始化音视频模块,注册监控对讲所需函数,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 和类型的数据流时,也会触发多次该回调,详细使用方法参照demovisitor表示对端的 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 stream
IV_AVT_VIDEO_RES_SD = 1, // standard stream
IV_AVT_VIDEO_RES_HD = 2, // high stream
IV_AVT_VIDEO_RES_PB = 3, // playback stream

IV_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 data
uint32_t src_len; // input data length
iv_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 内部可能会修改;如果返回 bufNULL或者 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 data
iv_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 内部可能会修改;如果返回 bufNULL或者 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_ERRORIV_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 ptz
IV_AVT_COMMAND_REQ_STREAM = 1, // request stream (send or receive)
IV_AVT_COMMAND_CHN_NAME = 2, // get channel name
IV_AVT_COMMAND_REQ_IFRAME = 3, // request I frame

// playback command
IV_AVT_COMMAND_PLAYBACK_PAUSE, // pause playback
IV_AVT_COMMAND_PLAYBACK_RESUME, // resume playback
IV_AVT_COMMAND_PLAYBACK_QUERY_MONTH, // query record info of month
IV_AVT_COMMAND_PLAYBACK_QUERY_DAY, // query record info of day
IV_AVT_COMMAND_PLAYBACK_SEEK, // seek record position
IV_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_smax_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_porttrans_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; // 384kB
stAvtInitParameters.max_connect_num = MAX_CONNECT_NUM; //
stAvtInitParameters.congestion.enable = true;
#ifdef USER_CONGESTION_CTRL
stAvtInitParameters.congestion.low_mark = 0;
stAvtInitParameters.congestion.warn_mark = 0;
stAvtInitParameters.congestion.high_mark = 0;
#else
stAvtInitParameters.congestion.low_mark = 200 * 1024;
stAvtInitParameters.congestion.warn_mark = 400 * 1024;
stAvtInitParameters.congestion.high_mark = 500 * 1024;
#endif

stAvtInitParameters.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();
}