car-eye 流媒体SDK

car-eye 流媒体SDK是car-eye 开源团队针对android IOS windows linux等各种平台下开发的流媒体推送库和播放库的提供的一系列应用API接口。分成car-eye pusher，player，FFMPEG, server 各个章节，为各种流媒体音视频应用提供了完整的解决方案。以下是详细的文档说明：

Car-eye RTSP client 库说明

1 RTSP库接口说明

关于本章

本章对RTSP拉取库的使用及各个接口函数进行了详细说明。

 

标题	内容
1.1 使用说明	使用本库的先提条件。
1.2 数据结构类型说明	本库中自定义的枚举类及结构体说明。
1.3 流拉取器接口说明	RTSP流拉取器接口的使用方法及详细说明。

 

 

1.1 使用说明

使用本库需要三部分文件：本库的引用头文件CarEyeRTSPClientAPI.h，运行动态库libCarEyeRtspClient.dll及开发使用的libCarEyeRtspClient.lib库。

注意：在使用本库时，必须要先调用CarEye_RtspActivate接口进行接口鉴权才能正常使用。

1.2 数据结构类型说明

本节中介绍本库中需要使用的几种自定义的数据类型。

1.2.1 视频编码类型定义

CarEye_VCodeType：该枚举类型定义了本库支持的视频编码类型，基本涵盖了实时流媒体领域中常见的几种格式。

1.2.2 音频编码类型定义

CarEye_ACodeType：该枚举类型定义了本库支持的音频编码类型，基本涵盖了实时流媒体领域中常见的几种格式。

1.2.3 推流信息媒体结构定义

CarEye_MediaInfo：该结构定义了本库中进行要拉流的媒体信息，结构成员说明见下表：

成员名	数据类型	成员说明
VCodec	CarEye_VCodeType	拉取的视频编码类型
Width	unsigned short	拉取的视频宽度分辨率
Height	unsigned short	拉取的视频高度分辨率
Fps	unsigned int	视频帧率
ACodec	CarEye_ACodeType	推流的音频编码类型
Channels	unsigned char	音频通道数
Samplerate	unsigned int	音频采样率
BitsPerSample	unsigned int	音频采样精度

表1 CarEye_MediaInfo结构说明

1.2.4 媒体帧信息结构定义

CarEye_RtspFrameInfo：该结构体定义了要拉取的媒体帧信息结构封装，结构成员说明见下表：

成员名	数据类型	成员说明
Codec	unsigned int	音频或视频编码格，参考CarEye_VCodeType与CarEye_ACodeType定义
FrameType	unsigned int	视频帧类型，如I、P、B等帧类型，参考CarEyeVideoFrameType定义
Fps	unsigned char	视频帧率
Width	unsigned short	拉取的视频宽度分辨率
Height	unsigned short	拉取的视频高度分辨率
Reserved1	unsigned int	保留字，如果该帧为关键帧则该字段为Sps长度加4字节
Reserved2	unsigned int	保留字，如果该帧为关键帧则该字段为Sps长度加4字节+Pps长度加4字节
Channels	unsigned char	音频通道数
Samplerate	unsigned int	音频采样率
BitsPerSample	unsigned int	音频采样精度
Length	unsigned int	音视频帧数据大小
USecond	unsigned int	时间戳中的微秒数部分
Second	unsigned int	时间戳中的秒数部分
Bitrate	float	比特率
Losspacket	Float	丢包率，暂时未用到

表2 CarEye_RtspFrameInfo结构说明

1.2.5 流拉取器数据回调函数定义

RTSPSourceCallBack：该回调函数类型定义了流拉取器状态变更时的通知结构，共三个参数，定义如下：

channelId：拉取器对应的通道号；

userPtr：用户开始拉流时传递的自定义数据；

frameType: 回调事件帧类型，定义参考CarEye_FrameFlag枚举类型；

pBuf: 根据帧类型定义的媒体数据；

frameInfo：当前帧的媒体信息；

1.3 流拉取器接口说明

1.3.1 创建一个RTSP实时流拉取器

说明：使用拉取器必须要使用本接口先创建一个拉取器才能正常使用，本接口创建的是实时流媒体拉取的拉取器。

函数名：CarEye_RtspCreate

返回值：返回0表示成功，其他表示失败

参数： handle：流拉取器对象句柄。

1.3.2 释放一个申请的RTSP拉取器

说明：在拉取器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加。

函数名：CarEye_RtspRelease

返回值：是否成功释放, 0释放成功

参数：handle：已申请的拉取器对象句柄。

1.3.3 使用指定拉取器拉取数据

说明：本接口将会从指定服务器中拉取流数据。

函数名：CarEye_RtspStart

返回值：0启动成功，否则失败

参数：handle：已申请的拉取器对象句柄；

  channelId：用户指定为的通道号，回调函数的channelId形参即为该通道号；

  url：拉取网络流的URL地址；

  connType：连接类型，RTP数据是基于TCP或者UDP；

  mediaType：获取的媒体类型；

  userName：RTSP链接的用户名，无则输入NULL；

  password：RTSP链接的密码，无则输入NULL；

  userPtr：用户传入的自定义数据，回调函数的userPtr即为该数据；

  reCount：失败自动重连次数，1000表示失败后一直自动重连；

  outRtpPacket：为0回调函数输出完整的帧数据，为1回到输出RTP包数据；

  heartbeatType：心跳类型 0x00：不发送心跳、0x01：OPTIONS心跳、                     0x02：GET_PARAMETER心跳；

  verbosity：日志打印级别，0表示不输出。

1.3.4 关闭一个开启的RTSP流拉取器

说明：使用本接口可关闭一个已经启动的流拉取器。

函数名：CarEye_RtspStop

返回值：是否成功关闭, 0表示关闭成功。

参数：handle：已启动成功的拉取器对象句柄。

1.3.5 注册流拉取器的状态变更事件

说明：注册本事件可以通过回调函数获取拉取器获取的流数据。

函数名：CarEye_RtspEventRegister

返回值：无

参数：handle：已申请的拉取器对象句柄；

  callback：回调函数。

1 RTSP库接口说明

关于本章

本章对RTSP推流库的使用及各个接口函数进行了详细说明。

 

标题	内容
1.1 使用说明	使用本库的先提条件。
1.2 数据结构类型说明	本库中自定义的枚举类及结构体说明。
1.3 推流器接口说明	RTSP推流器接口的使用方法及详细说明。

 

 

Car-eye 推流器库说明

1.1 使用说明

使用本库需要三部分文件：本库的引用头文件CarEyeRtspAPI.h、CarEyeTypes.h，运行动态库libCarEyePusher.dll及开发使用的libCarEyePusher.lib库。

注意：在使用本库时，必须要先调用CarEyeRTSP_Register接口进行接口鉴权才能正常使用。

1.2 数据结构类型说明

本节中介绍的数据类型在CarEyeTypes.h中进行了定义。

1.2.1 推流库中错误码定义

CarEyeError：该枚举类型定义了本库接口在返回错误时的错误编码定义。

1.2.2 推流器的类型定义

CarEyePusherType：该枚举类型定义了推流库实现的四种推流器类型，分别是RTSP/RTMP方式推送实时流媒体或者推送本地MP4多媒体文件。

1.2.3 视频编码类型定义

CarEye_VCodeType：该枚举类型定义了本库支持的视频编码类型，基本涵盖了实时流媒体领域中常见的几种格式。

1.2.4 音频编码类型定义

CarEye_ACodeType：该枚举类型定义了本库支持的音频编码类型，基本涵盖了实时流媒体领域中常见的几种格式。

1.2.5 推流信息媒体结构定义

CarEye_MediaInfo：该结构定义了本库中进行要推流的媒体信息，结构成员说明见下表：

成员名	数据类型	成员说明
VideoCodec	CarEye_VCodeType	推流的视频编码类型
VideoFps	unsigned int	视频帧率，一般为25
AudioCodec	CarEye_ACodeType	推流的音频编码类型
AudioSamplerate	unsigned int	音频采样率, 录制人声一般为8000
AudioChannel	unsigned int	音频通道数
AudioBitsPerSample	unsigned int	音频采样精度

表1 CarEye_MediaInfo结构说明

1.2.6 媒体帧信息结构定义

CarEye_AV_Frame：该结构体定义了要推流的媒体帧信息结构封装，结构成员说明见下表：

成员名	数据类型	成员说明
FrameFlag	unsigned int	标识为视频帧或音频帧，取下面两个值： CAREYE_VFRAME_FLAG CAREYE_AFRAME_FLAG
FrameLen	unsigned int	帧的数据长度
VFrameType	unsigned int	视频帧类型，如I、P、B等 帧类型，定义参考 CarEyeVideoFrameType枚举类型定义
Buffer	unsigned char *	媒体数据存储区
Second	unsigned int	推流的时间戳秒数
USecond	unsigned int	推流的时间戳微秒值，非总微秒数, 与Second结合形成精确时间

表2 CarEye_AV_Frame结构说明

1.2.7 推流器状态变更回调函数定义

CarEyePusher_StateChanged：该回调函数类型定义了推流器状态变更时的通知结构，共三个参数，定义如下：

channel：推流器对应的通道号；

state: 推流器当前的状态，定义参考CarEyeStateType枚举类型；

type: 该通道的推流器类型，定义参考1.2.2 推流器的类型定义

1.3 推流器接口说明

本节内容参见头文件CarEyeRtspAPI.h，还有一些简单的定义本文档就不做说明了，直接看代码注释即可。

1.3.1 创建一个RTSP实时推流器

说明：使用推流器必须要使用本接口先创建一个推流器才能正常使用，本接口创建的是实时流媒体推送的推流器。

函数名：CarEyeRTSP_StartPusher

返回值：创建成功返回大于等于0的推流器的通道号，小于0错误编号参考CarEyeError

参数： svrip：要推流的流媒体服务器IP地址或域名

port：要推流的流媒体服务器的端口号

name：推流链接的sdp名，拉取RTSP流的链接即为rtsp://svrip:port/name

mediaInfo：要推流的媒体信息，具体定义见1.2.5 推流信息媒体结构定义。

1.3.2 释放一个申请的RTSP推流器

说明：在推流器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加，本接口只用于释放CarEyeRTSP_StartPusher接口申请到的推流器。

函数名：CarEyeRTSP_StopPusher

返回值：是否成功关闭, 状态码参考CarEyeError

参数：channel：已启动的RTSP推流通道号。

1.3.3 获取指定通道编号的推流状态

说明：使用本接口可进行推流器的状态判断，是否已做好推流的准备，也就是与服务器已握手成功，可进行流媒体的推送。

函数名：CarEyeRTSP_PusherIsReady

返回值：0未做好准备, 非0做好准备

参数：channel：已启动的RTSP推流通道号。

1.3.4 使用指定通道推流器推送数据

说明：本接口会将输入的流媒体数据推送到服务器中。

函数名：CarEyeRTSP_PushData

返回值：是否推送成功, 状态码参考CarEyeError

参数：channel：已启动的RTSP推流通道号；

      frame：要推送的帧数据，详细定义见1.2.6 媒体帧信息结构定义。

1.3.1~1.3.4四节的接口即是RTSP推送实时媒体信息用到的全部接口，接下来讲述的为通过RTSP推送MP4文件的接口。

1.3.5 创建本地文件RTSP推流器

说明：本接口将会创建一个本地MP4文件推送的RTSP推流器，启动成功后接口内部会根据参数判断直接进行文件的推送，无需进行其他操作。

函数名：CarEyeRTSP_StartNativeFile

返回值：大于等于0: 启动的推流通道号 小于0错误编号参考CarEyeError

参数： svrip：要推流的流媒体服务器IP地址或域名

port：要推流的流媒体服务器的端口号

name：推流链接的sdp名，拉取RTSP流的链接即为rtsp://svrip:port/name

fileName: 要推流的本地文件路径 目前暂时支持MP4文件

startMs: 从本地媒体文件的该毫秒数位置开始推送

endMs: 推流结束的毫秒数 endMs必须大于startMs, 否则推流失败, 当两个参数都为0时推送全文件。

1.3.6 释放一个申请的RTSP本地文件推流器

说明：在推流器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加，本接口只用于释放CarEyeRTSP_StartNativeFile接口申请到的推流器。

函数名：CarEyeRTSP_StopNativeFile

返回值：是否成功关闭, 状态码参考CarEyeError

参数：channel：已启动的RTSP推流通道号。

1.3.7 注册推流器的状态变更事件

说明：注册本事件可以通过回调函数获取每个推流器通道的状态变更通知。

函数名：CarEyeRTSP_RegisterStateChangedEvent

返回值：无

参数：event：回调方法，类型定义见1.2.7 推流器状态变更回调函数定义。

Car-eye FFMPEG 多媒体库

使用本库需要三部分文件：本库的引用头文件CarEyeTypes.h，CarEyeDecoderAPI.h，CarEyeEncoderAPI.h，CarEyeOSDAPI.h、运行动态库libCarEyeMPEG.dll及开发使用的libCarEyeMPEG.lib库、FFMPEG的动态运行库。

注意：在使用本库时，必须要先调用CarEye_MPEG_Init接口进行初始化才能正常使用，该接口在CarEyeTypes.h头文件有进行了声明。

1.2 数据结构类型说明

本节中介绍的数据类型分别在CarEyeTypes.h、CarEyeDecoderAPI.h和CarEyeEncoderAPI.h三个文件中进行了定义。

1.2.1 媒体编码类型定义

CarEye_CodecType：该媒体类型定义了本库支持的音视频编码类型，基本涵盖了实时流媒体领域中常见的几种格式。

1.2.2YUV视频流类型定义

CarEye_AVType：该类型定义了本库支持的YUV视频流格式。

1.2.3 YUV视频流结构定义

CarEye_YUVFrame：该结构定义了本库中进行YUV数据传递的信息，结构成员说明见下表：

成员名	数据类型	成员说明
Y	unsigned char *	YUV数据中Y信道的数据
YSize	int	Y信道中数据的字节个数
U	unsigned char *	YUV数据中U信道的数据
USize	int	U信道中数据的字节个数
V	unsigned char *	YUV数据中V信道的数据
VSize	int	V信道中数据的字节个数

表1 CarEye_YUVFrame结构说明

1.2.4 水印信息结构定义

CarEye_OSDParam：该结构体定义了水印添加的参数信息，结构成员说明见下表：

成员名	数据类型	成员说明
Width	int	视频的宽度像素
Height	int	视频的高度像素
FramesPerSecond	int	视频帧率(FPS)
YUVType	CarEye_AVType	添加水印的YUV视频格式
X	int	水印起始位置的X轴坐标
Y	int	水印起始位置的Y轴坐标
FontSize	int	水印字体大小定义
FontColor	unsigned int	16进制的RGB颜色值，如绿色：0x00FF00
Transparency	float	透明度，0~1，0为全透明，1为不透明
SubTitle	char[1024]	要显示的水印字符，如果想要显示中文，则源代码文件必须保存为UTF-8无签名格式，否则会显示乱码。
FontName	char[64]	字体所在路径，如果字体文件在同目录下可使用”arial.ttf”这种格式，在Windows下调用系统字体可使用如下格式：”C\\\\:/Windows/Fonts/msyh.ttc”,示例是调用的系统的微软雅黑字体，可支持中文水印字体，有个别字体中文会乱码。

表2 CarEye_OSDParam结构说明

 

1.2.5 解码媒体帧信息结构定义

CarEye_FrameInfo：该结构体定义了本库解码需要的媒体信息数据，结构成员说明见下表：

成员名	数据类型	成员说明
VCodec	CarEye_CodecType	视频编码格式
ACodec	CarEye_CodecType	音频解码格式，无赋值CAREYE_CODEC_NONE
FramesPerSecond	unsigned char	视频帧率(FPS)
Width	unsigned short	视频的宽度像素
Height	unsigned short	视频的高度像素
VideoBitrate	unsigned int	视频码率，越高视频越清楚，相应体积也越大，如：4000K
SampleRate	unsigned int	音频采样率 如：44100
Channels	unsigned int	音频的通道数
BitsPerSample	unsigned int	音频采样精度16/8位等，库内部固定为16位
AudioBitrate	unsigned int	音频比特率，如：64K，越高声音越清楚，相应体积也越大

表3 CarEye_FrameInfo结构说明

1.2.6 编码媒体帧信息结构定义

CarEye_OriginalStream：该结构体定义了本库编码需要的媒体信息数据，结构成员说明见下表：

成员名	数据类型	成员说明
InVideoType	CarEye_AVType	视频YUV输入流格式
OutVideoType	CarEye_CodecType	期望编码后输出的视频流格式，不期望输出可设置为CAREYE_CODEC_NONE
OutAudioType	CarEye_CodecType	期望编码后输出的音频流格式，不期望输出可设置为CAREYE_CODEC_NONE
FramesPerSecond	unsigned char	视频帧率(FPS)，推荐如：25
Width	unsigned short	视频的宽度像素
Height	unsigned short	视频的高度像素
GopSize	int	一组图片中的图片数量，推荐值：10
MaxBFrames	int	非B帧之间的B帧的最大数量，推荐值：1
VideoBitrate	unsigned int	视频码率，越高视频越清楚，相应体积也越大 如：4000K
SampleRate	unsigned int	音频采样率 如：44100
AudioBitrate	unsigned int	音频比特率，如：64K，越高声音越清楚，相应体积也越大

表4 CarEye_OriginalStream结构说明

1.3 解码器接口说明

本节内容参见头文件CarEyeDecoderAPI.h

1.3.1 创建一个解码对象

说明：使用解码器必须要使用本接口先创建一个解码器才能正常使用。

函数名：CarEye_DecoderCreate

返回值：创建成功返回解码器的句柄，失败返回NULL

参数：aInfo：需要解码的媒体信息，具体定义见1.2.5 解码媒体帧信息结构定义。

1.3.2 释放一个申请的解码对象

说明：在解码器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加。

函数名：CarEye_DecoderRelease

返回值：无

参数：aDecoder：已申请并想释放的解码器。

1.3.3 获取解码后YUV视频所占用的字节数

说明：由于解码后的YUV数据字节数是固定的，所以提供该接口方便开发者申请内存。

函数名：CarEye_GetYUVSize

返回值：解码后YUV数据的字节个数，小于0说明获取失败

参数：aDecoder：已申请成功的解码器。

1.3.4 解码视频数据

说明：本接口会将输入的视频流解码为YUV420视频数据。

函数名：CarEye_DecoderYUV420

返回值：小于表示解码失败，大于0为解码后YUV420的字节个数，等于0表示参数无效

参数：aDecoder：已申请成功的解码器；

      aFilter：水印编码器，已弃用，直接传入NULL即可；

      aBytes：要解码的视频流；

      aSize：要解码的视频流字节个数；

      aYuv：解码成功后输出的YUV420数据，该参数传递方向为向外输出。

1.3.5 解码音频数据

说明：本接口会将输入的音频流解码为PCM音频数据。

函数名：CarEye_DecoderPCM

返回值：小于表示解码失败，大于0为解码后PCM的字节个数，等于0表示参数无效

参数：aDecoder：已申请成功的解码器；

      aBytes：要解码的音频流；

      aSize：要解码的音频流字节个数；

      aPcm：解码成功后输出的PCM数据，该参数传递方向为向外输出。

1.4 编码器接口说明

本接内容参见头文件CarEyeEncoderAPI.h

1.4.1 创建一个编码对象

说明：使用编码器必须要使用本接口先创建一个编码器才能正常使用。

函数名：CarEye_EncoderCreate

返回值：创建成功返回编码器的句柄，失败返回NULL

参数：aInfo：需要编码的媒体信息，具体定义见1.2.6 编码媒体帧信息结构定义。

1.4.2 释放一个编码对象

说明：在编码器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加。

函数名：CarEye_EncoderRelease

返回值：无

参数：aEncoder：已申请并想释放的编码器。

1.4.3 编码视频数据

说明：将输入的YUV数据编码为设定好的视频数据输出。

函数名：CarEye_EncoderYUV

返回值：小于表示编码失败，大于0为编码后视频数据的字节个数，等于0表示参数无效

参数：aEncoder：已申请成功的编码器；

      aYuv：要进行编码的YUV数据；

      aBytes：编码后的视频流，该参数传递方向为向外输出。

1.4.4 获取音频编码时接收的最大字节数

说明：防止一次解码的音频数据过大，提供该接口方便开发者申请内存。

函数名：CarEye_GetPcmMaxSize

返回值：PCM缓冲区的最大字节个数

参数：aEncoder：已申请成功的编码器。

1.4.5 编码音频数据

说明：将输入的PCM数据编码为设定好的音频数据输出。

函数名：CarEye_EncoderPCM

返回值：小于表示编码失败，大于0为编码后视频数据的字节个数，等于0表示参数无效

参数：aEncoder：已申请成功的编码器；

      aPcm：要进行编码的PCM数据；

      aSize：要编码PCM数据字节个数；

      aPts：当前编码帧的序号；

      aBytes：编码后的音频流，该参数传递方向为向外输出。

1.5 水印编码器接口说明

本接内容参见头文件CarEyeOSDAPI.h

1.5.1 创建一个水印编码对象

说明：使用编码器必须要使用本接口先创建一个编码器才能正常使用。

函数名：CarEye_OSD_Create

返回值：创建成功返回编码器的句柄，失败返回NULL

参数：aParam：需要添加水印的媒体信息，具体定义见1.2.4 水印信息结构定义。

1.5.2 进行水印添加

说明：本接口对输入的YUV数据进行水印添加操作。

函数名：CarEye_OSD_Encode

返回值：成功返回0，其他为失败

参数：aFilter：申请成功的水印编码器；

      aFrame：要添加水印的YUV数据，该参数方向为输入输出双向，经过本接口调用后 该参数值即为添加水印的YUV数据，结构定义见1.2.3YUV视频流结构定义；

      txtoverlay：水印文字内容，增加该参数值可实时修改水印内容。

1.5.3 释放一个水印编码对象

说明：在编码器使用完后一定要使用本接口进行释放，防止申请过多不释放造成内存增加。

函数名：CarEye_OSD_Release

返回值：无

参数：aFilter：已申请并想释放的水印编码器。

car-eye开源官方网址：www.car-eye.cn   

car-eye 流媒体平台网址：www.liveoss.com    

car-eye 技术官方邮箱: [email protected]    
car-eye技术交流QQ群: 590411159     

CopyRight©  car-eye 开源团队 2018