功能介绍
本模块用于将设备端的音视频数据推送并存储在云端,回看时由观看端(如 App)从云端拉取数据。
使用流程
基本推流过程
iv_cs_get_balance_info //获取本地套餐信息(非必须)|iv_cs_init|iv_cs_push_stream_start_cb // 收到回调,开始推流|while(1) { iv_cs_push_stream }|iv_cs_push_stream_stop_cb // 收到回调,停止推流|iv_cs_exit
事件推流过程
iv_cs_get_balance_info //获取本地套餐信息(非必须)|iv_cs_init|iv_cs_event_start/iv_cs_event_start_ext // 用户触发事件|iv_cs_event_capture_picture_cb // SDK向用户请求获取事件截图|iv_cs_push_stream_start_cb // 收到回调,开始推流|while(1) { iv_cs_push_stream }|iv_cs_event_stop/iv_cs_event_stop_ext //用户停止事件|iv_cs_push_stream_stop_cb // 收到回调,停止推流|iv_cs_event_picture_result_cb // 截图使用完毕,用户回收截图资源|iv_cs_exit
基本流程
接口列表
该功能模块提供以下接口:
iv_cs_init():云存功能初始化。
iv_cs_exit():云存功能关闭。
iv_cs_push_stream():推送音、视频流。
int iv_cs_event_start()/iv_cs_event_start_ext():触发事件。
int iv_cs_event_stop()/iv_cs_event_stop_ext():停止事件。
int iv_cs_event_directly_report():触发即时事件上报。
int iv_cs_get_balance_info():获取云存套餐信息。
int iv_cs_set_trans_time():设置云存的传输超时时间。
int iv_cs_set_ai_process():设置云 AI 视频分析功能。
int iv_cs_get_ai_process():获取云 AI 视频分析功能。
用户需注册以下回调函数:
(*iv_cs_push_stream_start_cb)():音、视频流开始推流通知。
(*iv_cs_push_stream_stop_cb)():音、视频流停止推流通知。
(*iv_cs_event_capture_picture_cb)():获取事件截图。
(*iv_cs_event_picture_result_cb)():事件截图使用完毕通知。
(*iv_cs_event_report_result_cb)():事件上传状态通知。
(*iv_cs_notify_cb)():云存状态通知。
接口描述
iv_cs_init
功能描述
云存储模块初始化,注册相关回调,申请资源,需要模块时初始化调用。
函数原型
int iv_cs_init(iv_cs_init_parm_s *pstInitParm);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pstInitParm | iv_cs_init_parm_s * | 云存初始化参数结构体。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_exit
功能描述
云存储模块去初始化,释放资源。
函数原型
int iv_cs_exit(void);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
无 | 无 | 无 | 无 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_push_stream
功能描述
推送音视频流。
函数原型
int iv_cs_push_stream(iv_cm_stream_type_e eCsStreamType, void *pstCsPack);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
eCsStreamType | iv_cm_stream_type_e | 云存推流类型(音频/视频)。 | 输入 |
pstCsPack | void * | 云存推流的数据(音频 iv_cm_aenc_pack_s,视频 iv_cm_venc_pack_s)。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
使用说明
此接口禁止并行调用。
音频推荐使用 ADTS 的 AAC 裸流。
如使用 G711u、G711a、PCM 格式请在初始化时设置采样率、声道数等参数,对于这三种格式参数中
iv_cs_init_parm_s.av_fmt.u32SampleNumPerFrame
目前只支持1024采样点(双声道为2048采样点),双声道则左右声道交替存放(LRLRLRLR...
),以 PCM 为例:int16_t audio_data[1024]; // 单声道int16_t audio_data[2048]; // 双声道
视频支持 H.264 或 H.265 含 NALU 的 I帧、P帧裸流,不支持 B帧,其中I帧需包含 SPS、PPS 等数据,部分裸数据格式如下:
H264 I帧00 00 00 01 67 (...) 00 00 00 01 68 (...) 00 00 00 01 65 (...)H264 P帧00 00 00 01 41 (...)H265 I帧00 00 00 01 40 (...) 00 00 00 01 42 (...) 00 00 00 01 44 (...) 00 00 00 01 2A (...)H265 P帧00 00 00 01 02 (...)
iv_cs_event_directly_report
功能描述
用于触发一个事件并立即上报,事件编号的合法取值为1-16,事件编号的具体含义由用户定义。
该接口可传入事件对应图片信息上传至云服务器,如无图片信息 pic_addr 填 NULL,pic_len 填0。
函数执行成功事件及对应图片可上传成功,否则上报失败。
event_time_s 填0时 SDK 则使用系统时间。
未开通云存套餐的情况下可使用此接口上报只有图片的事件。
函数原型
int iv_cs_event_directly_report(int32_t event_id, uint32_t event_time_s, uint8_t *pic_addr,uint32_t pic_len)
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
event_id | int32_t | 事件编号。 | 输入 |
event_time_s | uint32_t | 事件触发 utc 时间,单位:秒。 | 输入 |
pic_addr | uint8_t * | 事件对应图片地址。 | 输入 |
event_id | int32_t | 事件对应图片长度。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_start
功能描述
用于触发一个事件,事件编号的合法取值为1-16,事件编号的具体含义由用户定义。
用户触发事件以后,SDK 调用 iv_cs_event_capture_picture_cb 向用户请求截图,同时会调用 iv_cs_push_stream_start_cb 通知用户开始推送音视频流。
截图上传完毕后 SDK 调用 iv_cs_event_picture_result_cb 通知用户图片上传结果。
需在上一事件停止后调用,且和 iv_cs_event_stop 成对调用。
适用于事件发生在调用该函数这一刻的情况。
函数原型
int iv_cs_event_start(int32_t event_id);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
user_event_id | int32_t | 事件编号 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_stop
功能描述
用于停止一个事件,事件编号的合法取值为1-16,事件编号的具体含义由用户定义。
用户停止事件以后,SDK 调用 iv_cs_push_stream_stop_cb 通知用户停止推送音视频流。
必须调用 iv_cs_event_start 后才可调,且和 iv_cs_event_start 成对调用。
函数原型
int iv_cs_event_stop(int32_t event_id);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
user_event_id | int32_t | 事件编号 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_start_ext
功能描述
用于触发一个事件,事件编号的合法取值为1-16,事件编号的具体含义由用户定义。
用户触发事件以后,SDK 调用 iv_cs_event_capture_picture_cb 向用户请求截图,同时会调用 iv_cs_push_stream_start_cb 通知用户开始推送音视频流。
截图上传完毕后SDK调用 iv_cs_event_picture_result_cb 通知用户图片上传结果。
适用于预录视频或补传视频的场景。
当 event_start_time_s 和 stream_start_time_s 小于 300 时,该值作为相对时间使用但不得小于0(小于零代表事件开始在未来,无意义),例如 event_start_time_s = 15 代表事件发生的时间是调用此函数前的15秒;大于 300 时作为绝对时间使用,即 UTC 时间。
event_start_time_s 和 stream_start_time_s 必须同为相对时间或同为绝对时间,不得混用。
event_start_time_s 和 stream_start_time_s 可以相同或不相同,可根据实际使用场景填写,例如 stream_start_time_s 填写 15 表示视频开始于调用此函数前的15秒,event_start_time_s 填写 0 表示事件发生于调用此函数的这一刻,这样就实现了预录视频还原完整事件经过的效果。
event_start_time_s 和 stream_start_time_s 作为绝对时间使用时,用户需尽量保证时间准确,以免云存录像时间出现太大偏差;使用过程中尽量避免向前校时,如果校时后的时间早于最后一段视频的结束时间可能导致已经上传的录像被覆盖。
函数原型
int iv_cs_event_start_ext(int32_t event_id, uint32_t event_start_time_s, uint32_t stream_start_time_s);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
user_event_id | int32_t | 事件编号。 | 输入 |
event_start_time_s | uint32_t | 事件开始的 utc 时间。 | 输入 |
stream_start_time_s | uint32_t | 事件对应视频开始的 utc 时间。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_stop_ext
功能描述
用于停止一个事件,事件编号的合法取值为1-16,事件编号的具体含义由用户定义。
用户停止事件以后,SDK 调用 iv_cs_push_stream_stop_cb 通知用户停止推送音视频流。
必须调用 iv_cs_event_start_ext 后才可调,且和iv_cs_event_start_ext 成对调用。
当 event_stop_time_s 或 stream_stop_time_s 小于 300 时,该值作为相对时间使用但不得小于0(小于零代表事件结束在未来,无意义),例如 event_stop_time_s = 15 代表事件结束的时间是调用此函数前的15秒;大于 300 时作为绝对时间使用,即 UTC 时间。
event_stop_time_s 和 stream_stop_time_s 必须同为相对时间或同为绝对时间,不得混用。
event_stop_time_s 和 stream_stop_time_s 作为绝对时间使用时,用户需尽量保证时间准确,以免云存录像时间出现太大偏差;使用过程中尽量避免向前校时,如果校时后的时间早于最后一段视频的结束时间可能导致已经上传的录像被覆盖。
函数原型
int iv_cs_event_stop_ext(int32_t event_id, uint32_t event_stop_time_s, uint32_t stream_stop_time_s);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
user_event_id | int32_t | 事件编号。 | 输入 |
event_stop_time_s | uint32_t | 事件结束的 utc 时间。 | 输入 |
stream_stop_time_s | uint32_t | 事件对应视频结束的 utc 时间。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_get_balance_info
功能描述
用于获取当前设备的云存的套餐信息。
当
timeout_s
大于0时,该接口为阻塞获取信息,直接从后台获取最新套餐信息,失败返回错误码IV_ERR_CS_QUERY_SERVICE_TIMEOUT
,成功返回IV_ERR_NONE
和套餐信息。当
timeout_s
等于0时,该接口为非阻塞接口,直接返回SDK
内的套餐缓存信息。当云存的套餐在后台发生变化后,正常情况下会及时更新到设备并缓存在 SDK 内,通过本接口直接查询 SDK 内缓存套餐信息效率更高。
接口可在设备上线后云存
SDK
未初始化前进行调用来获取套餐信息,云存 SDK 未初始化时采用轮询方式调用该接口,建议只在第一次调用时采用阻塞方式,后续的调用采用非阻塞方式,否则会引起带宽资源浪费。函数原型
int iv_cs_get_balance_info(iv_cs_balance_info_s *pstBalanceInfo, uint32_t timeout_s)
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pstBalanceInfo | iv_cs_balance_info_s | 云存套餐信息。 | 输出 |
timeout_s | uint32_t | 接口获取超时时间(单位:秒)。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_set_ai_process
功能描述
设置需要进行 AI 分析的事件 ID 以及 AI 分析的类型。
可以在云存初始化之后、云存退出前任意时刻调用,如需长期使能 AI,建议在云存初始化后进行设置,在云存退出前关闭,减少在事件触发时频繁开关。
函数原型
int iv_cs_set_ai_process(int32_t event_id, iv_cs_ai_type_e ai_type, void *args);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
event_id | int32_t | 需要进行 AI 分析的事件 ID。 | 输入 |
ai_type | iv_cs_ai_type_e | 需要进行 AI 分析的类型。 | 输入 |
arg | void * | 用户参数,暂未使用,填 NULL。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_get_ai_process
功能描述
获取某个事件的 AI 分析类型。
函数原型
int iv_cs_get_ai_process(int32_t event_id, iv_cs_ai_type_e *ai_type, void *args);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
event_id | int32_t | 需要读取的事件 ID。 | 输入 |
ai_type | iv_cs_ai_type_e * | 事件的 AI 分析类型。 | 输入 |
arg | void * | 用户参数,暂未使用,填 NULL。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_set_trans_time
功能描述
分别设置云存传输的上传和接收最大超时时间,单位毫秒,不能设置为0。
函数原型
int iv_cs_set_trans_time(uint32_t upload_timeout_ms, uint32_t reply_timeout_ms)
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
upload_timeout_ms | uint32_t | 上传最大超时时间,单位毫秒。 | 输入 |
reply_timeout_ms | uint32_t | 接口最大超时时间,单位毫秒。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_push_stream_start_cb
功能描述
开始推流回调,事件触发后、云存套餐开通后等情况会触发此回调,收到此回调后方可开始推流。
函数原型
int (*iv_cs_push_stream_stop_cb)(void);
参数说明
无
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_push_stream_stop_cb
功能描述
停止推流回调,事件结束、云存服务到期等情况会触发此回调,收到此回调后停止推流。
函数原型
int (*iv_cs_push_stream_start_cb)(void);
参数说明
无
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_capture_picture_cb
功能描述
抓图回调,建议非阻塞使用,仅支持 jpg 格式,返回时提供图片指针和大小,如果不需抓图请填 NULL 和0。
函数原型
int (*iv_cs_event_capture_picture_cb)(int32_t event_id, uint8_t **pic, int32_t *size);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
event_id | int32_t | 用户触发的事件 id,根据不同 id 可以上传对应事件的图片。 | 输入 |
pic | uint8_t ** | 指向保存截图的内存。 | 输出 |
size | int32_t * | 指向截图的大小。 | 输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_picture_result_cb
功能描述
上传图片结束回调,并通知上传结果。
每张抓图都会回调一次,在收到对应图片回调前不得回收图片资源,以免 SDK 上传图片失败。
函数原型
int (*iv_cs_event_picture_result_cb)(uint8_t **pic, iv_err_code_e err_code);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pic | uint8_t ** | 指向保存截图的内存,与 iv_cs_event_capture_picture_cb 的入参对应。 | 输入 |
err_code | iv_err_code_e | 上传图片的结果。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_event_report_result_cb
功能描述
用户事件上报结果回调,用户结束事件后事件上报的结果通过该回调通知。
函数原型
int (*iv_cs_event_report_result_cb)(iv_cs_event_result_info *pst_result_info);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pst_result_info | iv_cs_event_result_info * | 指向事件上报结果的信息。 | 输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
iv_cs_notify_cb
功能描述
云存消息通知回调,目前包括云存视频分段的上传情况通知、内部上传连接情况通知、内部发送缓存水位告警通知消息等。
notify_msg_type 为 IV_CS_AV_UPLOAD_STATE_MSG 时,pst_notify_data 使用联合体成员 iv_cs_upload_info_s。
notify_msg_type 为其余消息时,pst_notify_data 为 NULL。
函数原型
int (*iv_cs_notify_cb)(iv_cs_notify_msg_type_e notify_msg_type,iv_cs_notify_msg_data *pst_notify_data);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
notify_msg_type | iv_cs_notify_msg_type_e | 云存通知消息类型。 | 输入 |
pst_notify_data | iv_cs_notify_msg_data* | 云存通知消息数据。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败,对应相应错误码。 |
数据结构列表
云存模块涉及以下数据结构:
iv_cm_*:请参考音视频结构公共模块。
iv_cs_type_e:云存套餐类型枚举。
iv_cs_balance_info_s:云存套餐状态结构体。
iv_cs_ai_type_e:云 AI 分析的类型枚举。
iv_cs_event_report_opt_e:事件云存上传类型枚举。
iv_cs_upload_state_e:云存上传状态枚举。
iv_cs_upload_slice_info_s:云存某段视频上传状态结构体。
iv_cs_upload_info_s:云存视频上传状态结构体。
iv_cs_notify_msg_type_e:云存回调消息类型。
iv_cs_notify_msg_data:云存回调消息联合体。
iv_cs_event_result_info:云存事件上传结果结构体。
iv_cs_congestion_ctrl_s:云存水位控制结构体。
iv_cs_init_parm_s:云存模块初始化参数结构体。
数据结构描述
iv_cs_type_e
功能描述
云存套餐类型。
结构原型
typedef enum{CS_TYPE_NONE = 0,CS_TYPE_FULL_TIME = 1,CS_TYPE_EVENT = 2,} iv_cs_type_e;
参数说明
成员名称 | 描述 | 取值 |
CS_TYPE_NONE | 无套餐 | 0 |
CS_TYPE_FULL_TIME | 全时套餐 | 1 |
CS_TYPE_EVENT | 事件套餐 | 2 |
iv_cs_balance_info_s
功能描述
云存套餐结构体。
结构原型
typedef struct iv_cs_balance_s {int cs_switch;iv_cs_type_e cs_type;} iv_cs_balance_info_s;
参数说明
成员名称 | 描述 | 取值 |
cs_switch | 云存开关 | int |
cs_type | 云存套餐类型 | iv_cs_type_e |
iv_cs_ai_type_e
功能描述
云 AI 类型。
结构原型
typedef enum{CS_AI_TYPE_CLOSE = (uint32_t)0,CS_AI_TYPE_FALL_DETECT = (uint32_t)(1 << 0),} iv_cs_ai_type_e;
参数说明
成员名称 | 描述 | 取值 |
CS_AI_TYPE_CLOSE | 关闭云 AI。 | (uint32_t)0 |
CS_AI_TYPE_FALL_DETECT | 老人跌倒检测云 AI。 | (uint32_t)(1 << 0) |
iv_cs_event_report_opt_e
功能描述
事件云存上传类型枚举,用于告知 SDK 所有事件按视频事件处理或按图片事件处理,默认为0。
设置为 CS_EVENT_TS_REQ 时,至少成功上传一段视频 SDK 才认为这是一个完整事件。
设置为 CS_EVENT_PIC_REQ 时,成功上传截图后 SDK 才认为这是一个完整事件。
设置为 CS_EVENT_TS_OR_PIC_REQ 时,成功上传一段视频或成功上传截图 SDK 都认为这是一个完整事件。
例如:假设用户要求所有事件必须有视频,建议设置为 CS_EVENT_TS_REQ;假设用户只需上传事件截图不需上传视频,建议设置为 CS_EVENT_PIC_REQ。
结构原型
typedef enum cs_event_upload_options{CS_EVENT_TS_REQ = 0,CS_EVENT_PIC_REQ = 1,CS_EVENT_TS_OR_PIC_REQ = 2,} iv_cs_event_report_opt_e;
参数说明
成员名称 | 描述 | 取值 |
CS_EVENT_TS_REQ | 成功上传视频,图片可选上传。 | 0 |
CS_EVENT_PIC_REQ | 成功上传截图,视频可选上传。 | 1 |
CS_EVENT_TS_OR_PIC_REQ | 成功上传视频或图片。 | 2 |
iv_cs_upload_state_e
功能描述
视频是否上传成功。
结构原型
typedef enum{IV_CS_UPLOAD_OK = 0,IV_CS_UPLOAD_ERR = 1,} iv_cs_upload_state_e;
参数说明
成员名称 | 描述 | 取值 |
IV_CS_UPLOAD_OK | 上传成功 | 0 |
IV_CS_UPLOAD_ERR | 上传失败 | 1 |
iv_cs_upload_slice_info_s
功能描述
通知用户某段视频的上传状态。
用户可根据其中的 UTC 时间、PTS、帧序号等信息得知视频上传的状态。此结构体内记录的信息均为视频帧。一般而言只有 upload_size == total_size 且 state == IV_CS_UPLOAD_OK 才认为视频上传完全正常。
结构原型
typedef struct {uint64_t utc_sec_a;uint64_t utc_sec_b;uint64_t pts_ms_a;uint64_t pts_ms_b;uint32_t frame_seq_a;uint32_t frame_seq_b;uint32_t upload_size;uint32_t total_size;iv_cs_upload_state_e state;} iv_cs_upload_slice_info_s;
参数说明
成员名称 | 描述 | 取值 |
utc_sec_a | 本段视频开始的 UTC 时间(SDK 内部生成)。 | uint64_t |
utc_sec_b | 本段视频结束的 UTC 时间(SDK 内部生成)。 | uint64_t |
pts_ms_a | 本段视频第一帧的 PTS(来自 iv_cs_push_stream)。 | uint64_t |
pts_ms_b | 本段视频最后一帧的 PTS(来自 iv_cs_push_stream)。 | uint64_t |
frame_seq_a | 本段视频第一帧的序号(来自 iv_cs_push_stream)。 | uint32_t |
frame_seq_b | 本段视频最后一帧的序号(来自 iv_cs_push_stream)。 | uint32_t |
upload_size | 本段视频上传成功的大小(估算值)。 | uint32_t |
total_size | 本段视频总大小(精确值)。 | uint32_t |
state | 本段视频的上传状态(成功/失败)。 | iv_cs_upload_state_e |
iv_cs_upload_info_s
功能描述
通知用户视频的上传状态,由若干 iv_cs_upload_slice_info_s 组成。
结构原型
typedef struct {iv_cs_upload_slice_info_s slice_info[MAX_UPLOAD_INFO_NUM];int32_t num;} iv_cs_upload_info_s;
参数说明
成员名称 | 描述 | 取值 |
slice_info | 某段视频的上传状态。 | iv_cs_upload_slice_info_s |
num | slice_info 的数量。 | int32_t |
iv_cs_notify_msg_type_e
功能描述
云存回调消息类型。
结构原型
typedef enum cs_notify_type{IV_CS_AV_UPLOAD_CONNECT_FAIL = 0,IV_CS_AV_UPLOAD_CONNECT_RECOVER = 1,IV_CS_AV_UPLOAD_STATE_MSG = 2,IV_CS_AV_UPLOAD_WATERMARK_LOW = 3,IV_CS_AV_UPLOAD_WATERMARK_WARN = 4,IV_CS_AV_UPLOAD_WATERMARK_HIGH = 5,IV_CS_COS_SERVICE_WRONG = 6,IV_CS_MSG_BUTT} iv_cs_notify_msg_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_CS_AV_UPLOAD_CONNECT_FAIL | 云存服务器连接失败。 | 0 |
IV_CS_AV_UPLOAD_CONNECT_RECOVER | 云存服务器连接恢复。 | 1 |
IV_CS_AV_UPLOAD_STATE_MSG | 云存上传状态消息。 | 2 |
IV_CS_AV_UPLOAD_WATERMARK_LOW | 云存低水位告警。 | 3 |
IV_CS_AV_UPLOAD_WATERMARK_WARN | 云存中水位告警。 | 4 |
IV_CS_AV_UPLOAD_WATERMARK_HIGH | 云存高水位告警。 | 5 |
IV_CS_COS_SERVICE_WRONG | 云存服务不可用。 | 6 |
IV_CS_MSG_BUTT | - | - |
iv_cs_notify_msg_data
功能描述
iv_cs_notify_cb 回调携带的消息联合体。
结构原型
typedef union {iv_cs_upload_info_s *av_result_info;} iv_cs_notify_msg_data;
参数说明
成员名称 | 描述 | 取值 |
av_result_info | 视频上传的结果。 | iv_cs_upload_info_s |
iv_cs_event_result_info
功能描述
事件的上传结果。
结构原型
typedef struct {int32_t result_code;int32_t event_id;uint32_t start_time_s;uint32_t end_time_s;} iv_cs_event_result_info;
参数说明
成员名称 | 描述 | 取值 |
result_code | 上报结果。 | 0:失败,1:成功。 |
event_id | 事件序号。 | 1到16。 |
start_time_s | 事件开始时间,单位秒。 | UTC 时间戳。 |
end_time_s | 事件结束时间,单位秒。 | UTC 时间戳。 |
iv_cs_congestion_ctrl_s
功能描述
设置云存缓存水位告警相关参数。
结构原型
typedef struct {size_t low_mark;size_t warn_mark;size_t high_mark;int8_t enable;} iv_cs_congestion_ctrl_s;
参数说明
成员名称 | 描述 | 取值 |
low_mark | 设置触发告警的低水位值,单位字节。 | 不大于 u32MaxGopSize |
warn_mark | 设置触发告警的低水位值,单位字节。 | 不大于 u32MaxGopSize |
high_mark | 设置触发告警的低水位值,单位字节。 | 不大于 u32MaxGopSize |
enable | 设置是否开启水位值告警功能。 | 0:否,1:是 |
iv_cs_init_parm_s
功能描述
云存模块初始化参数结构体。
结构原型
typedef struct iv_cs_init_parm_s{uint32_t u32MaxGopSize;iv_cs_congestion_ctrl_s congestion_cfg;iv_cm_av_data_info_s av_fmt;iv_cs_event_report_opt_e event_report_opt;int (*iv_cs_push_stream_start_cb)(void);int (*iv_cs_push_stream_stop_cb)(void);void (*iv_cs_ai_service_notify_cb)(unsigned int ai_server_type, unsigned long long utc_expire);int (*iv_cs_event_capture_picture_cb)(int32_t event_id, uint8_t **pic, int32_t *size);int (*iv_cs_event_picture_result_cb)(uint8_t **pic, int32_t err_code);int (*iv_cs_event_report_result_cb)(iv_cs_event_result_info *pst_result_info);int (*iv_cs_notify_cb)(iv_cs_notify_msg_type_e notify_msg_type,iv_cs_notify_msg_data *pst_notify_data);}iv_cs_init_parm_s;
参数说明
成员名称 | 描述 | 取值 |
u32MaxGopSize | 云存缓存大小,单位字节,取值为4KB的整数倍。 | uint32_t |
congestion_cfg | 视频上传拥塞控制信息。 | iv_cs_congestion_ctrl_s |
av_fmt | 云存音视频格式(如果云存视频采用动态帧率,其中的 u32Framerate 请填0)。 | iv_cm_av_data_info_s |
event_report_opt | 事件上报选项设置。 | iv_cs_event_report_opt |
iv_cs_push_stream_start_cb | 开始推流回调(详细说明见上文)。 | 无 |
iv_cs_push_stream_stop_cb | 停止推流回调(详细说明见上文)。 | 无 |
iv_cs_ai_service_notify_cb | 云AI服务状态回调(暂未使用)。 | NULL |
iv_cs_event_capture_picture_cb | 获取事件截图回调(详细说明见上文)。 | 无 |
iv_cs_event_picture_result_cb | 图片上传结果回调(详细说明见上文)。 | 无 |
iv_cs_event_report_result_cb | 事件上报结果回调(详细说明见上文)。 | 无 |
iv_cs_notify_cb | 云存模块消息通知回调(详细说明见上文)。 | 无 |
注意事项
1. 云存开始推流送入的第一帧尽量保证为 IDR 帧,否则回放时可能导致花屏、解码失败等问题。
2. 云存可能因网络波动上传失败,使用过程请尽量保持网络状况良好。
3. u32MaxGopSize 取值推荐能保存一个 GOP 的视频和对应的音频,假设帧率为20fps,GOP 为80帧,经统计4秒的视频数据约700KB,音频约60KB,则 u32MaxGopSize 可以取 800KB。
4. u32MaxGopSize 如果设备内存紧张可以适当减小,如减小至原来的80%(上述为例即640KB),但不得小于一个I帧的大小,取值过小会导致云存上传更难以承受网络波动。
5. 用户可以在未收到 iv_cs_push_stream_stop_cb 回调的情况下主动停止推送云存录像,SDK 超过120秒未收到音视频数据会暂停云存录像。
6. 云存使用过程中禁止修改音视频格式,如格式发生变化,请调用 iv_cs_exit 关闭云存,再调用 iv_cs_init 重新初始化云存并设置新的音视频格式。
7. 云存功能内存开销计算:
输入 aac 格式音频:内存开销 = u32MaxGopSize + 100KB(SDK 内部数据)。
输入其他格式音频:内存开销 = u32MaxGopSize + 120KB(单声道)或 160KB(双声道)+ 100KB(SDK 内部数据)。
8. 事件云存触发建议事件至少持续3s及以上以保证视频片段、图片可及时上传,不会发生丢弃;否则可能会发生视频、图片上传失败,只上报事件触发消息等类似情况。
9. 单个事件持续时间建议不要超过1小时,尽量控制在10分钟以内,如果持续时间确实很长建议进行分割。
10. 事件云存支持并行事件,同一时刻允许触发多个不同事件,但不能触发多个相同事件。
11. 事件云存支持预录视频,网络良好的情况允许预录视频快速上传来追赶实时视频。
12. 并行事件只有第一个触发的事件支持预录视频,后续并行事件调用 iv_cs_event_start_ext(),stream_start_time_s 请填0或当前 UTC 时间;或直接调用 iv_cs_event_start()。
13. 如果没有套餐,全时云存不会触发推流通知, 此时推流也会返回错误码 IV_ERR_CS_APPLY_NO_SERVICE,需要用户定时检查套餐情况。
当全时云存套餐生效时,会触发开始推流通知,当无效时,会触发停止推流通知。
当事件云存套餐生效时,不会有通知,但此时调用事件云存的相关接口可以正常工作。
14. 事件支持无图片事件,当事件无图片时 SDK 不会调用 iv_cs_event_picture_result_cb 释放图片资源。
15. 事件云存强烈建议不要上传未来的视频,SDK 可以接受小幅度的时钟误差(建议正负1分钟以内)。系统时钟快于现实时间这种情况在使用中要特别注意,以免导致视频被覆盖。假设这样一个场景:现实时间为 09:00:00,设备端的系统时钟为09:00:40,此时触发了一个10秒的事件,并上传视频,即视频的时间为 09:00:40-09:00:50,之后设备开始校时,将时间修改为 09:00:10,在 09:00:30 触发了一个30秒的事件,并上传视频,即视频的时间为 09:00:30-09:01:00,此时第二个事件的视频会覆盖第一个事件的视频。
16. 云存消息通知回调 iv_cs_notify_cb 需要支持重入。
示例代码
// 云存推流while (run_flag){// 调用者主动推流,由调用者保证推送音视频帧的顺序与间隔,否则可能造成音视频不同步if(compare_time_stamp(frame_count_audio, audio_time_base, frame_count_video, video_time_base) <= 0){frame_count_audio += 1;get_aac_frame(audio_frame_buf, &audio_len);audio_pack.pu8Addr = audio_frame_buf;audio_pack.u32Len = audio_len;audio_pack.u64TimeStamp = (uint64_t)(frame_count_a * 1024 / 48.0);audio_pack.u32Seq = frame_count_a;iv_cs_push_stream(IV_CM_STREAM_TYPE_AUDIO, &audio_pack);}else{frame_count_video += 1;get_video_frame_h264(video_frame_buf, &video_len, &frame_type);video_pack.pu8Addr = video_frame_buf;video_pack.u32Len = video_len;video_pack.eFrameType = frame_type;video_pack.u64PTS = (uint64_t)(frame_count_v * 1000 / 25.0);video_pack.u32Seq = frame_count_v;iv_cs_push_stream(IV_CM_STREAM_TYPE_VIDEO, &video_pack);}sleep_ms(10);}
详细例程请参考
samples\\samples\\cloud_storage\\cloud_storage.c
及 samples\\samples\\
目录内的其他代码。