功能介绍
SDK 提供若干基础数据结构,供用户推送音视频流使用。
枚举说明
iv_cm_aenc_type_e
用于描述音频编码类型。
枚举原型
typedef enum{IV_CM_AENC_TYPE_PCM = 0,IV_CM_AENC_TYPE_G711A = 1,IV_CM_AENC_TYPE_G711U = 2,IV_CM_AENC_TYPE_G726 = 3, // 暂不支持IV_CM_AENC_TYPE_AAC = 4,IV_CM_AENC_TYPE_AMR = 5, // 暂不支持IV_CM_AENC_TYPE_ADPCMA = 6, // 暂不支持IV_CM_AENC_TYPE_BUTT} iv_cm_aenc_type_e;
iv_cm_aac_type_e
用于描述 AAC 音频编码类型。
枚举原型
typedef enum{IV_CM_AAC_TYPE_NONE = 0,IV_CM_AAC_TYPE_MAIN = 1,IV_CM_AAC_TYPE_LC = 2,IV_CM_AAC_TYPE_SSR = 3,IV_CM_AAC_TYPE_LTP = 4,IV_CM_AAC_TYPE_SBR = 5,IV_CM_AAC_TYPE_SCALCBLE = 6,IV_CM_AAC_TYPE_TWINVQ = 7,IV_CM_AAC_TYPE_CELP = 8,IV_CM_AAC_TYPE_HVXC = 9,IV_CM_AAC_TYPE_BUTT} iv_cm_aac_type_e;
iv_cm_aenc_sample_rate_e
用于描述音频采样率,仅 PCM 格式使用,其他格式无效。
枚举原型
typedef enum{IV_CM_AENC_SAMPLE_RATE_8000 = 8000, /* 8K samplerate*/IV_CM_AENC_SAMPLE_RATE_12000 = 12000, /* 12K samplerate*/IV_CM_AENC_SAMPLE_RATE_11025 = 11025, /* 11.025K samplerate*/IV_CM_AENC_SAMPLE_RATE_16000 = 16000, /* 16K samplerate*/IV_CM_AENC_SAMPLE_RATE_22050 = 22050, /* 22.050K samplerate*/IV_CM_AENC_SAMPLE_RATE_24000 = 24000, /* 24K samplerate*/IV_CM_AENC_SAMPLE_RATE_32000 = 32000, /* 32K samplerate*/IV_CM_AENC_SAMPLE_RATE_44100 = 44100, /* 44.1K samplerate*/IV_CM_AENC_SAMPLE_RATE_48000 = 48000, /* 48K samplerate*/IV_CM_AENC_SAMPLE_RATE_64000 = 64000, /* 64K samplerate*/IV_CM_AENC_SAMPLE_RATE_96000 = 96000, /* 96K samplerate*/IV_CM_AENC_SAMPLE_RATE_BUTT,} iv_cm_aenc_sample_rate_e;
iv_cm_aenc_bit_width_e
用于描述音频位宽,仅 PCM 格式使用,其他格式无效。
枚举原型
typedef enum{IV_CM_AENC_BIT_WIDTH_8 = 0, /* 8bit width */IV_CM_AENC_BIT_WIDTH_16 = 1, /* 16bit width*/IV_CM_AENC_BIT_WIDTH_24 = 2, /* 24bit width*/IV_CM_AENC_BIT_WIDTH_BUTT,} iv_cm_aenc_bit_width_e;
iv_cm_aenc_mode_e
用于描述音频声道数,仅 G711a、G711u、PCM 使用,其他格式无效。
枚举原型
typedef enum{IV_CM_AENC_MODE_MONO = 0, /*mono*/IV_CM_AENC_MODE_STEREO = 1, /*stereo*/IV_CM_AENC_MODE_BUTT} iv_cm_aenc_mode_e;
iv_cm_file_type_e
用于描述文件类型,用户可自行扩展。
枚举原型
typedef enum{IV_CM_FILE_TYPE_VIDEO = 0, /*video file*/IV_CM_FILE_TYPE_PIC = 1 /*pircture file*//*User expandable*/} iv_cm_file_type_e;
iv_cm_stream_type_e
用于描述媒体流的类型。
枚举原型
typedef enum{IV_CM_STREAM_TYPE_AUDIO = 0,IV_CM_STREAM_TYPE_VIDEO = 1,IV_CM_STREAM_TYPE_BUTT} iv_cm_stream_type_e;
iv_cm_venc_type_e
用于描述视频流的编码格式。
枚举原型
typedef enum{IV_CM_VENC_TYPE_H264 = 0, /*h264*/IV_CM_VENC_TYPE_H265 = 1, /*h265*/IV_CM_VENC_TYPE_BUTT} iv_cm_venc_type_e;
iv_cm_frame_type_e
用于描述视频帧的类型,暂不支持 B帧。
枚举原型
typedef enum{IV_CM_FRAME_TYPE_I = 0,IV_CM_FRAME_TYPE_P = 1,// IV_CM_FRAME_TYPE_B = 2, // not support yetIV_CM_FRAME_TYPE_BUTT} iv_cm_frame_type_e;
iv_cm_wifi_enc_type_e
用于描述 wifi 加密类型。
枚举原型
typedef enum{IV_CM_WIFI_ENC_TYPE_OPEN = 0, /*open wifi*/IV_CM_WIFI_ENC_TYPE_WEP = 1, /*wep wifi*/IV_CM_WIFI_ENC_TYPE_WPA = 2, /*wpa wifi*/IV_CM_WIFI_ENC_TYPE_BUTT} iv_cm_wifi_enc_type_e;
数据结构说明
iv_cm_aenc_pack_s
音频帧数据包。
结构原型
typedef struct iv_cm_aenc_pack_s {uint8_t *pu8Addr;uint32_t u32Len;uint64_t u64PTS;uint32_t u32Seq;} iv_cm_aenc_pack_s;
参数说明
成员名称 | 描述 | 取值 |
pu8Addr | 音频帧数据的地址。 | uint8_t * |
u32Len | 音频帧数据长度(字节)。 | uint32_t |
u64PTS | 音频帧数据时间戳,采用相对时间,可从0或 UTC 时间等任意时间基准开始计时,单位毫秒。 | uint64_t |
u32Seq | 音频帧数据包序号,每包+1。 | uint32_t |
iv_cm_aenc_stream_s
音频数据流,由1-8个音频帧数据包组成。
结构原型
typedef struct iv_cm_aenc_stream_s {iv_cm_aenc_pack_s *pstAencPack[8];uint32_t u32PackCount;} iv_cm_aenc_stream_s;
参数说明
成员名称 | 描述 | 取值 |
pstAencPack | 音频帧数据包的指针数组。 | iv_cm_aenc_pack_s * |
u32PackCount | 音频帧数据包个数。 | uint32_t |
iv_cm_venc_pack_s
视频帧数据包。
结构原型
typedef struct iv_cm_venc_pack_s {uint8_t *pu8Addr;uint32_t u32Len;uint64_t u64PTS;iv_cm_frame_type_e eFrameType;uint32_t u32Seq;} iv_cm_venc_pack_s;
参数说明
成员名称 | 描述 | 取值 |
pu8Addr | 视频帧数据的地址。 | uint8_t * |
u32Len | 视频帧数据长度(字节)。 | uint32_t |
u64PTS | 视频帧数据时间戳,采用相对时间,可从0或 UTC 时间等任意时间基准开始计时,单位毫秒。 | uint64_t |
eFrameType | 视频帧类型。 | iv_cm_frame_type_e |
u32Seq | 视频帧数据包序号,每包+1。 | uint32_t |
iv_cm_venc_stream_s
视频数据流,由1-8个视频帧数据包组成。
结构原型
typedef struct iv_cm_venc_stream_s {iv_cm_venc_pack_s *pstVencPack[8];uint32_t u32PackCount;} iv_cm_venc_stream_s;
参数说明
成员名称 | 描述 | 取值 |
pstVencPack | 视频帧数据包的指针数组。 | iv_cm_venc_pack_s * |
u32PackCount | 视频帧数据包个数。 | uint32_t |
iv_cm_avenc_stream_s
音视频数据流,由一个音频流和一个视频流组成。
结构原型
typedef struct iv_cm_avenc_stream_s {iv_cm_aenc_stream_s stAencStream;iv_cm_venc_stream_s stVencStream;} iv_cm_avenc_stream_s;
参数说明
成员名称 | 描述 | 取值 |
stAencStream | 音频流 | iv_cm_aenc_stream_s |
stVencStream | 视频流 | iv_cm_venc_stream_s |
iv_cm_av_data_info_s
用于描述音视频格式。
结构原型
typedef struct iv_cm_av_data_info_s {iv_cm_aenc_type_e eAudioType;iv_cm_aac_type_e u32AudioCodecOption;iv_cm_aenc_mode_e eAudioMode;iv_cm_aenc_bit_width_e eAudioBitWidth;iv_cm_aenc_sample_rate_e eAudioSampleRate;uint32_t u32SampleNumPerFrame;iv_cm_venc_type_e eVideoType;uint32_t u32VideoWidth;uint32_t u32VideoHeight;uint32_t u32Framerate;uint32_t u32Reserve[4];} iv_cm_av_data_info_s;
参数说明
成员名称 | 描述 | 取值 |
eAudioType | 音频编码类型。 | iv_cm_aenc_type_e |
u32AudioCodecOption | aac 编码类型,仅 AAC 使用,其他格式无效。 | iv_cm_aac_type_e |
eAudioMode | 音频声道数,仅 G711a、G711u、PCM 使用,其他格式无效。 | iv_cm_aenc_mode_e |
eAudioBitWidth | 音频位宽,仅 PCM 使用,其他格式无效。 | iv_cm_aenc_bit_width_e |
eAudioSampleRate | 音频采样率,仅 PCM 使用,其他格式无效。 | iv_cm_aenc_sample_rate_e |
u32SampleNumPerFrame | 音频每帧采样点数,仅 G711a、G711u、PCM 使用,其他格式无效(采样点数需乘以声道数,例如单声道1024点;双声道共2048点,即每声道1024点)。 | uint32_t |
eVideoType | 视频编码类型。 | iv_cm_venc_type_e |
u32VideoWidth | 视频宽度。 | uint32_t |
u32VideoHeight | 视频高度。 | uint32_t |
u32Framerate | 视频帧率,仅支持整数帧率。 | uint32_t |
u32Reserve | 保留。 | uint32_t |
iv_cm_memory_s
内存管理。
结构原型
typedef struct {uint8_t *buf; // buffer addresssize_t size; // buffer sizevoid (*buf_free_fn)(uint8_t *, size_t); // buffer free callback} iv_cm_memory_s;
参数说明
成员名称 | 描述 | 取值 |
buf | 内存地址。 | uint8_t * |
size | 内存大小。 | size_t |
buf_free_fn | 内存释放回调函数。 | void (*)(uint8_t *, size_t) |
iv_cm_time_fragment_s
时间段。
结构原型
typedef struct {uint32_t type; // not useduint64_t begin_time_s; // start timestamp in second of playback, unix timestampeuint64_t end_time_s; // end timestamp in second of playback, unix timestampe} iv_cm_time_fragment_s;
参数说明
成员名称 | 描述 | 取值 |
type | 类型,暂时未使用。 | uint32_t |
begin_time_s | 起始时间。 | 单位秒,UNIX 时间戳。 |
end_time_s | 结束时间。 | 单位秒,UNIX 时间戳。 |
iv_cm_pb_list_s
回放的录像列表。
结构原型
typedef struct {uint32_t count; // file count of the dayiv_cm_time_fragment_s file_list[0]; // play back file array} iv_cm_pb_list_s;
参数说明
成员名称 | 描述 | 取值 |
count | 录像的数量。 | uint32_t |
file_list | 录像实际时间段。 | iv_cm_time_fragment_s |
iv_cm_query_rd_by_month_s
按月查询录像结果。
结构原型
typedef struct {uint32_t year;uint32_t month;uint32_t type; // not useduint32_t day; // Use each bit for one day. For example day=0010 0000 1000 0000=8320 means// 8/14 day have playback data.} iv_cm_query_rd_by_month_s;
参数说明
成员名称 | 描述 | 取值 |
year | 年 | uint32_t |
month | 月 | 1到12 |
type | 类型,暂时未使用。 | uint32_t |
day | 有录像的天数,从低到高 bit 依次代表第几天。 | uint32_t |
iv_cm_query_rd_by_day_s
按月查询录像结果。
结构原型
typedef struct {iv_cm_time_fragment_s time_fragment;void (*free_fn)(void *ptr); // memory free callbackiv_cm_pb_list_s *rd_array;} iv_cm_query_rd_by_day_s;
参数说明
成员名称 | 描述 | 取值 |
iv_cm_time_fragment_s | 查询时间段。 | iv_cm_time_fragment_s |
free_fn | 查询结果释放函数。 | 函数指针 |
rd_array | 查询结果。 | iv_cm_pb_list_s * |
iv_cm_file_info_s
文件信息。
结构原型
typedef struct {iv_cm_file_type_e file_type; // file typechar file_name[MAX_FILE_NAME_LENGTH]; // file nameuint32_t file_size; // file size, unit Byteuint32_t begin_time_s; // start timestamp in second of playback, unix timestampeuint32_t end_time_s; // end timestamp in second of playback, unix timestampeiv_cm_memory_s extra_info; // user define information, json format} iv_cm_file_info_s;
参数说明
成员名称 | 描述 | 取值 |
file_type | 文件类型。 | iv_cm_file_type_e |
file_name | 文件名称。 | 字符串 |
file_size | 文件大小。 | uint32_t |
begin_time_s | 文件起始时间。 | uint32_t |
end_time_s | 文件结束时间。 | uint32_t |
extra_info | 文件自定义信息,json 格式。 | iv_cm_memory_s |
iv_cm_file_list_s
文件列表。
结构原型
typedef struct {uint32_t count; // file countiv_cm_file_info_s file_list[0]; // file list} iv_cm_file_list_s;
参数说明
成员名称 | 描述 | 取值 |
count | 文件数量 | uint32_t |
iv_cm_file_info_s | 文件信息 | iv_cm_file_info_s |
iv_cm_file_list_s
文件列表查询参数。
结构原型
typedef struct {iv_cm_time_fragment_s time_fragment;void (*free_fn)(void *ptr); // memory free callbackiv_cm_file_list_s *file_array;} iv_cm_query_file_list_s;
参数说明
成员名称 | 描述 | 取值 |
count | 文件数量 | uint32_t |
iv_cm_file_info_s | 文件信息 | iv_cm_file_info_s |
iv_cm_download_param_s
文件列表查询参数。
结构原型
typedef struct {char file_name[MAX_FILE_NAME_LENGTH]; // name of downloaded fileint file_offset; // offset of downloaded file} iv_cm_download_param_s;
参数说明
成员名称 | 描述 | 取值 |
file_name | 文件名 | char[] |
file_offset | 文件偏移 | int |
iv_cm_pb_seek_s
回放时滑动位置。
结构原型
typedef struct {uint64_t seek_time_ms;} iv_cm_pb_seek_s;
参数说明
成员名称 | 描述 | 取值 |
seek_time_ms | UNIX 时间戳,单位毫秒。 | uint64_t |
iv_cm_pb_ff_s
设置快进速度。
结构原型
typedef struct {uint32_t speed;} iv_cm_pb_ff_s;
参数说明
成员名称 | 描述 | 取值 |
speed | 0:正常播放 。 1:表示只发I帧。 2:表示I帧取2发一。 3:表示I帧取3发1。 | uint32_t |
iv_cm_pb_speed_s
设置快放或者慢放。
结构原型
typedef struct {uint32_t time_ms;} iv_cm_pb_speed_s;
参数说明
成员名称 | 描述 | 取值 |
time_ms | 表示 pts 的间隔,当大于正常 pts 时慢放,否则是快放。 | uint32_t |
iv_cm_pb_rewind_s
设置倒放。
结构原型
typedef struct {uint64_t begin_time_s; // end timestamp of rewinduint64_t end_time_s; // start timestamp of rewind} iv_cm_pb_rewind_s;
参数说明
成员名称 | 描述 | 取值 |
begin_time_s | 倒放的截止时间,UNIX 时间戳。 | uint64_t |
end_time_s | 倒放的起始时间,UNIX 时间戳。 | uint64_t |
注意事项
对于音视频数据的时间戳,请小心处理误差问题,否则可能因误差积累导致音视频不同步。
对于视频帧,假设帧率为30fps,即每帧33.3333毫秒,取整为33毫秒。不补偿时间戳为 0,33,66,99,132,165,198,补偿后时间戳为 0,33,67,100,133,167,200。
音频同理。
音频和视频的时间戳必须同时从0或同时从 UTC 时间等相同时间基准开始计时,不得一个从0计时,另一个从 UTC 计时,否则会导致音频无法播放等问题。
录像快进、倒放、快放和慢放状态时,音频需要特殊处理,可以不发送。