Mediapro

API说明【纯传输层SDK】

API接口

所有API接口定义均位于SDTerminalMulticastSdk.h文件中。

1、系统环境初始化，仅需调用一次

void  SDTerminalMulticast_Enviroment_Init (const char * outputPath,  int outputLevel)
参数：
@param: outputPath：日志文件输出的目录，若目录不存在，SDK将自动创建，支持相对路径或绝对路径。日志对于问题定位非常重要，建议开启。
@param: outputLevel：日志输出的级别，只有等于或者高于该级别的日志会输出到文件，日志级别取值见LOG_OUTPUT_LEVEL_MULTICAST，有DEBUG、INFO、WARNING、ERROR、ALARM、FATAL、NONE几个级别可选，当指定为NONE时，将不会生成日志文件。

2、系统退出时调用一次反初始化

void  SDTerminalMulticast_Enviroment_Free()

3、创建SDK对象

void*  SDTerminalMulticast_Create();

4、销毁SDK对象

void  SDTerminalMulticast_Delete(void** ppTerminal);
参数：
@ ppTerminal，模块指针的指针
说明：使用者应该做好与其他API之间的互斥保护

5、准备会话

int  SDTerminalMulticast_Online(
void* pTerminal,
TERMINAL_TYPE_MULTICAST eUserType,
const char* strLocalIP,
const char* strMultiIp, 
unsigned short shMultiPort
);
参数：
@pTerminal，模块指针
@eUserType: 客户端类型，有组播发送端与组播接收端两种。
@strLocalIp，组播绑定的本地IP地址，当设置为NULL时，内部将使用INADDR_ANY，交由操作系统选择一个网卡IP。建议指定IP以防多IP时系统选择错误。
@strMultiIp，组播IP地址。
@shMultiPort，组播端口号，将使用本端口发送音频数据  使用本端口+2发送视频数据。
返回值：返回大于等于0表示成功，返回负数则为失败，负数值为其错误码。

6、结束会话

void  SDTerminalMulticast_Offline(void* pTerminal);
参数：
@pTerminal，模块指针
返回值：无

7、发送视频数据

void  SDTerminalMulticast_SendVideoData(void* pTerminal, unsigned char *byBuf, unsigned int unLen, unsigned int unDts, BOOL bIsHevc);
参数：
@pTerminal，模块指针
@byBuf，码流存放区。
@unLen，码流长度。
@unDts, SDK默认使用内部时间戳模式，内部自动产生时间戳，此时本参数传入0即可。当用户调用SDTerminalMulticast_SetUseInternalTimeStamp  API来指定外部时间戳模式时，在此传入外部时间戳。@bIsHevc，当前码流是否为HEVC（H265）码流，是则设置为TRUE，H264码流设置为FALSE，请务必按实际情况准确设置。
@ bIsHevc:传入码流是否为HEVC, H264时传入FALSE，请务必与实际情况相符。
返回值：无

::: tip
发送视频码流，一次传入一帧带起始码(0x 00 00 00 01或0x00 00 01)的码流。
:::

8、发送音频数据

void  SDTerminalMulticast_SendAudioData(void* pTerminal, unsigned char *byBuf, unsigned int unLen, unsigned int unDts);
参数：
@pTerminal，模块指针
@byBuf，码流存放区。
@unLen，码流长度。
@unDts, SDK默认使用内部时间戳模式，内部自动产生时间戳，此时本参数传入0即可。当用户调用SDTerminalMulticast_SetUseInternalTimeStamp  API来指定外部时间戳模式时，在此传入外部时间戳。
返回值：无

::: tip
向请求的位置发送音频码流，一次传一帧ADTS码流。内部将校验ADTS头合法性。
:::

9、设置音视频传输参数

void SDTerminalMulticast_SetTransParams(void* pTerminal, unsigned int unJitterBuffDelay, FEC_REDUN_TYPE_MULTICAST eFecRedunMethod, unsigned int unFecRedunRatio, 
unsigned int unFecMinGroupSize, unsigned int unFecMaxGroupSize, 
BOOL bEnableNack, 
unsigned short usNackPort);
参数：
@pTerminal，模块指针
@unJitterBuffDelay，本客户端接收码流时的内部缓存时间（毫秒）,范围0~600。设置为0时，将关闭内部接收JitterBuff功能，此时可以获得最低延时。
@eFecRedunMethod，为上行FEC冗余度方法，包括AUTO_REDUN自动冗余度、FIX_REDUN固定冗余度。自动冗余度将根据网络情况自行调整冗余。固定冗余度则全程使用固定值。
@unFecRedunRatio，上行冗余比率，比如设置为30，则表示使用30%冗余。自动冗余度时以该冗余度作为基础值，根据网络情况调整。 
@unFecMinGroupSize，为上行FEC分组的下限值，建议设置为16。
@unFecMaxGroupSize，为上行FEC分组的上限值，根据终端CPU能力而定，最大不超过72，越大FEC所消耗的CPU越高，抗丢包能力也越强，建议性能足够的设备上设置为64。
@bEnableNack，是否启用组播NACK功能，当设置为TRUE时启用。收发两端均开启时生效。
@usNackPort，当开启NACK功能时，组播发送端用于NACK信令、媒体传输的单播端口，收发双方保持设置一致时生效。
返回值：无

::: caution
本函数需在Online之前调用。
:::

10、获取当前SDK版本信息

UINT SDTerminalP2P_GetVersion(void* pTerminal);
参数：
@pTerminal，模块指针
返回值：获得当前SDK的版本信息

11、获取当前丢包率数据

void SDTerminalMulticast_GetVideoAudioUpDownLostRatio(void* pTerminal, 
float *pfVideoUpLostRatio, float *pfVideoDownLostRatio, 
float *pfAudioUpLostRatio, float *pfAudioDownLostRatio);
参数：
@pTerminal，模块指针
@pfVideoUpLostRatio，获取视频上行丢包率
@pfVideoDownLostRatio，获取视频下行丢包率
@pfAudioUpLostRatio，获取音频上行丢包率
@pfAudioDownLostRatio，获取音频下行丢包率
返回值：无

::: caution
上述值内部已经乘100.0转换为百分比，因为组播为单向1对多，仅对接收方统计下行丢包率
:::

12、设置时间戳工作机制

void  SDTerminalMulticast_SetUseInternalTimeStamp(void* pTerminal,      
BOOL bUseInternalTimestamp);
@pTerminal，模块指针
@bUseInternalTimestamp，是否采用内部时间戳模式，TRUE-内部，FALSE-外部。默认情况下未调用本API时，系统采用内部时间戳模式，此时将在每次调用Send接口时自动产生时间戳。当用户需要使用外部时间戳时，需调用本API指定FALSE。
返回值：无

::: caution
本函数需在Online之前调用。不调用本函数时，默认使用内部时间戳模式。
:::

13、设置发送端Smooth机制

void  SDTerminalMulticast_SetVideoFrameRateForSmoother(void* pTerminal,      
unsigned int unFrameRate);
@pTerminal，模块指针
@unFrameRate，设置视频帧率信息，该值将作为内部发送时Smoother处理的参考。注意该帧率要符合实际帧率,可以高于实际帧率，但不能低于实际帧率，否则将导致发送速度不足，触发内部自行关闭Smooth功能。
返回值：无

::: caution
本函数需在Online之前调用。未调用本函数时，默认关闭smooth处理。
:::

回调输出相关API接口

接收的远端音视频数据均通过回调函数的方式通知外层，SDK提供了相关的回调函数设置接口。

1、设置视频数据接收回调

void SDTerminalMulticast_SetRecvRemoteVideoCallback(void* pTerminal, 
     RecvMulticastRemoteVideoFunc pfRecvRemoteVideoCallback, void* pObject)
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RecvMulticastRemoteVideoFunc的定义如下：
void (*RecvMulticastRemoteVideoFunc)(void* pObject, unsigned char* data, unsigned int unLen, unsigned int unPTS, VideoFrameInforMulticast* pFrameInfo);
其中，VideoFrameInforMulticas提供了当前帧以及当前流的重要信息：
typedef struct VideoFrameInforMulticast
{
    unsigned int unWidth;
    unsigned int unHeight;
    unsigned int unFps;
    BOOL bPacketLost;
    BOOL bKeyFrame;
    BOOL bInfoUpdated;
    BOOL bIsHevc;
    unsigned char byVps[512];
    unsigned int unVpsSize;
    unsigned char bySps[512];
    unsigned int unSpsSize;
    unsigned char byPps[512];
    unsigned int unPpsSize;
} VideoFrameInforMulticast;
模块内部会获得当前码流的宽、高、帧率、VPS（HEVC时）、SPS、PPS告知外层，当其中某些参数发生变更时将置位bInfoUpdated以通知外层。
bPacketLost与bKeyFrame变量可用于外层实现丢帧冻结机制，bPacketLost表示当前帧是否接收完整，若网络丢包且FEC未能恢复时，该标志将置位。bKeyFrame表示当前帧是否为IDR关键帧。默认情况下内部已开启丢包冻结机制，外层可忽略bPacketLost与bKeyFrame。
当没有丢包发生时，本函数的输出与对方调用SDTerminalMulticast_SendVideoData函数的输入完全一致。
返回值：无

::: caution
SDK内部将在独立于网络接收线程之外的线程中调用本接口，所以外层可以将相对耗时的操作（比如解码）放置在此回调中。
:::

2、设置音频数据接收回调

void  SDTerminalMulticast_SetRecvRemoteAudioCallback(void* pTerminal, RecvMulticastRemoteAudioFunc pfRecvRemoteAudioCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RecvMulticastRemoteAudioFunc的定义如下：
void (*RecvMulticastRemoteAudioFunc)(void* pObject, unsigned char* data, unsigned int unLen, unsigned int unPTS, AudioFrameInforMulticast* pFrameInfo);
其中，AudioFrameInforMulticast提供了当前帧以及当前流的重要信息：
typedef struct AudioFrameInforMulticast
{
    unsigned int unCodecType;
    unsigned int unSampleRate;
    unsigned int unChannelNum;
    unsigned int unFrameNo;
    BOOL bInfoUpdated;
} AudioFrameInforMulticast;
音频帧为ADTS格式，其每个包头部均附带了采样率、通道数、编码格式（目前固定0-AAC）等信息。
返回值：无

::: caution
SDK内部将在独立于网络接收线程之外的线程中调用本接口，所以外层可以将相对耗时的操作（比如解码）放置在此回调中。
:::

最后修改时间： 1 年前