Mediapro

API说明【纯传输层SDK】

API接口

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

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

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

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

void  SDTerminalP2P_Enviroment_Free ()

3、创建SDK对象

void*  SDTerminalP2P_Create();
参数：
返回值：对象指针，返回NULL表示失败。

4、销毁SDK对象

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

5、准备会话

BOOL  SDTerminalP2P_Online(
void* pTerminal,
const char* strLocalIp,
unsigned short shLocalPort,
const char* strRemoteIP, 
unsigned short shRemotePort, 
CLIENT_USER_TYPE_P2P eUserType);
参数：
@pTerminal，模块指针
@strLocalIp，绑定的本地IP地址;当设置为NULL或''时且strRemoteIP为NULL或''，内部将使用INADDR_ANY，交由操作系统选择一个网卡IP,多IP时系统选择不一定符合预期。当设置为NULL或''但strRemoteIP为有效值时，内部将根据strRemoteIP选择同网段网卡IP。
@shLocalPort，绑定的本地端口号，允许设置本地端口为0，由操作系统选择一个当前可用的端口。作为(服务端\播放端\接收端)使用时，需要指定本地监听的端口。
@strRemoteIP，远端IP地址。(服务端\播放端\接收端)上设置NULL或''即可，作为(服务端\播放端\接收端)时，一般是不知道（客户端\发送端)的IP和端口，内部将在收到远端数据后自动翻转IP和端口，从而获得可用于向远端发送数据的IP和端口。
@shRemotePort，远端端口号。(服务端\播放端\接收端)上设置远端端口号为0即可。
@eUserType，本客户端类型：收发一体、纯发送、纯接收，按需设置类型可以实现最小的资源开销。
返回值：返回大于等于0表示成功，返回负数则为失败，负数值为其错误码。

::: caution
当用户通过本参数指定了远端IP时，SDK仅会接收来自该IP的数据，丢弃来自其他IP的数据。
:::

6、结束会话

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

7、发送视频数据

void  SDTerminalP2P_SendVideoData(void* pTerminal, unsigned char *byBuf, unsigned int unLen, unsigned int unDts, BOOL bIsHevc);
参数：
@pTerminal，模块指针
@byBuf，码流存放区，一次传一帧带起始码的视频码流。内部将校验起始码合法性。
@unLen，码流长度。
@unDts, SDK默认使用内部时间戳模式，内部自动产生时间戳，此时本参数传入0即可。当用户调用SDTerminalP2P_SetUseInternalTimeStamp  API来指定外部时间戳模式时，在此传入外部时间戳。
@bIsHevc，当前码流是否为HEVC（H265）码流，是则设置为TRUE，H264码流设置为FALSE，请务必按实际情况准确设置。
返回值：无

8、发送音频数据

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

9、设置音视频传输参数

void SDTerminalP2P_SetTransParams(void* pTerminal, unsigned int unJitterBuffDelay, FEC_REDUN_TYPE_P2P eFecRedunMethod, unsigned int unFecRedunRatio, 
unsigned int unFecMinGroupSize, unsigned int unFecMaxGroupSize, BOOL bEnableAck);
参数：
@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。
@bEnableAck，是否启用ACK功能，当设置为TRUE时，走ACK模式。当设置为FALSE时走NACK模式。二者的区别见文档说明。建议设置为FALSE，使用NACK模式。
返回值：无

::: caution
本函数需要在Online之前调用。双方需要使用统一的ACK/NACK模式，通常建议使用NACK模式，即设置bEnableAck=FALSE
:::

10、设置自动冗余度模式下的冗余度上下限

void  SDTerminalP2P_SetAutoRedunMinMax(void* pTerminal, unsigned int unAutoRedunRatioMin, unsigned int unAutoRedunRatioMax);
参数：
@param pTerminal: 模块指针
@param unAutoRedunRatioMin: 自动冗余度下限。
@param unAutoRedunRatioMax: 自动冗余度上限。
返回值：无

::: tip
未调用本API指定自动冗余度上下限时，默认上下限为0~100
:::

11、获取当前SDK版本信息

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

12、获取当前丢包率数据

void SDTerminalP2P_GetVideoAudioUpDownLostRatio(void* pTerminal, 
float *pfVideoUpLostRatio, float *pfVideoDownLostRatio, 
float *pfAudioUpLostRatio, float *pfAudioDownLostRatio);
参数：
@pTerminal，模块指针
@pfVideoUpLostRatio，获取视频上行丢包率
@pfVideoDownLostRatio，获取视频下行丢包率
@pfAudioUpLostRatio，获取音频上行丢包率
@pfAudioDownLostRatio，获取音频下行丢包率
返回值：无
说明：上述值内部已经乘100.0转换为百分比

13、设置时间戳工作机制

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

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

14、设置发送端Smooth机制

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

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

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

void SDTerminalP2P_SetRecvRemoteVideoCallback(void* pTerminal, RecvP2PRemoteVideoFunc pfRecvRemoteVideoCallback, void* pObject)
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RecvP2PRemoteVideoFunc的定义如下：
void (*RecvP2PRemoteVideoFunc)(void* pObject, unsigned char* data, unsigned int unLen, unsigned int unPTS, VideoFrameInforP2P* pFrameInfo);
其中，VideoFrameInforP2P提供了当前帧以及当前流的重要信息：
typedef struct VideoFrameInforP2P
{
    unsigned int unWidth;
    unsigned int unHeight;
    unsigned int unFps;
    BOOL bPacketLost;
    BOOL bKeyFrame;
    BOOL bInfoUpdated;
    BOOL bIsHevc;
    unsigned char bySps[512];
    unsigned int unSpsSize;
    unsigned char byPps[512];
    unsigned int unPpsSize;
}VideoFrameInforP2P;

模块内部会获得当前码流的宽、高、帧率、VPS（HEVC时）、SPS、PPS告知外层，当其中某些参数发生变更时将置位bInfoUpdated以通知外层。
bPacketLost与bKeyFrame变量可用于外层实现丢帧冻结机制，bPacketLost表示当前帧是否接收完整，若网络丢包且FEC未能恢复时，该标志将置位。bKeyFrame表示当前帧是否为IDR关键帧。默认情况下内部已开启丢包冻结机制，外层可忽略bPacketLost与bKeyFrame。
当没有丢包发生时，本函数的输出与对方调用SDTerminalP2P_SendVideoData函数的输入完全一致。
返回值：无

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

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

void  SDTerminalP2P_SetRecvRemoteAudioCallback(void* pTerminal, RecvP2PRemoteAudioFunc pfRecvRemoteAudioCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。

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

17、设置远端请求IDR通知回调

void  SDTerminalP2P_SetRemoteIdrRequestNotifyCallback(void* pTerminal, P2PRemoteIdrRequestNotifyFunc pfRemoteIdrRequestNotifyCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfRemoteIdrRequestNotifyCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
P2PRemoteIdrRequestNotifyFunc的定义如下：
BOOL (*P2PRemoteIdrRequestNotifyFunc)(void* pObject);
当远端接收失败时，即会通过本回调通知本端，本端可以尽快编码IDR帧以避免远端长时间画面冻结。
返回值：无

::: caution
1、本函数在Online之前调用生效。
2、注意SDK内部是在网络接收线程中调用本回调，因此外层不应在回调中执行耗时操作，应尽快返回。
:::

18、设置码率自适应通知回调

void  SDTerminalP2P_SetAutoBitrateNotifyCallback(void* pTerminal, AUTO_BITRATE_TYPE_P2P eAutoBitrateMethod, P2PAutoBitrateNotifyFunc pfAutoBitrateNotifyCallback,void* pObject);
参数：
@pTerminal，模块指针
@eAutoBitrateMethod，码率自适应方法：P2P_AB_TYPE_DISABLE（关闭码率自适应，默认不调用本API时即关闭状态）、P2P_AB_TYPE_ADJUST_FRAME_FIRST（优先降低帧率，其次降低码率）、P2P_AB_TYPE_ADJUST_BITRATE_FIRST（优先降低码率，其次降低帧率）。
@pfAutoBitrateNotifyCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。

回调函数P2PAutoBitrateNotifyFunc的说明如下：
BOOL (*P2PAutoBitrateNotifyFunc)(void* pObject, BOOL bSelectOrDropFrame, unsigned int unFrameDropInterval, float fBitrateRatio);
当使用模块的码率自适应评估时，评估结果由本接口送出，外层负责具体的实施。
假设unFrameSelectOrDropInterval为N ，bSelectOrDropFrame为TRUE时，每N帧“取”一帧编码发送；为FALSE时，每N帧“丢”一帧。
比如bSelectOrDropFrame为FALSE，unFrameSelectOrDropInterval=2，表示每2帧丢1帧。
比如bSelectOrDropFrame为TRUE，unFrameSelectOrDropInterval=3，表示每3帧取1帧。
比如fBitrateRatio=0.8表示需要将码率降低为原始码率的0.8倍。
外层需同时响应帧率调整和码率调整，当外层执行了码率自适应动作时，本回调函数返回TRUE，否则返回FALSE。
返回值：无

::: caution
1、本函数在Online之前调用生效。
2、注意SDK内部是在网络接收线程中调用本回调，因此外层不应在回调中执行耗时操作，应尽快返回。
:::

最后修改时间： 2 年前