Mediapro

API说明【JAVA纯播放SDK】

API接口

SDK由如下三类API组成：

基础API接口，负责基础的TCP连接管理（如登录、下线）、音视频码流收发、底层回调反馈等。相关代码位于SDInterface.java
推送API接口，负责摄像头、麦克风的采集、音频3A、音视频压缩编码等处理。相关代码位于SDInterfaceCameraPublisher.java
播放API接口，负责播放远端音视频。相关代码位于SDInterfacePlayer.java

用户根据业务情况选择对应API调用。基础SDK包括所有类别客户端均需调用的基础功能，纯发送型客户端无需调用播放API，纯播放型客户端无需调用推送API。

图片1.png

基础API

1、系统初始化

系统初始化主要完成日志模块初始化、服务器IP地址配置，该API在整个系统中只需要调用一次即可。

int  SDsysinit(String strServerIp,  String strLogFileDir,  byte byLogFileLevel)
参数：
@strServerIp，指定服务器IP地址
@strLogFileDir，日志文件输出的目录，若目录不存在，SDK将自动创建，支持相对路径或绝对路径。
@byLogFileLevel，日志输出的级别，只有等于或者高于该级别的日志会输出到文件。级别定义位于Constant.java：
final byte LOG_LEVEL_DEBUG = 1;
        final byte LOG_LEVEL_INFO = 2;
        final byte LOG_LEVEL_WARN = 3;
        final byte LOG_LEVEL_ERROR = 4;
        final byte LOG_LEVEL_ALARM = 5;
        final byte LOG_LEVEL_FATAL = 6;
        final byte LOG_LEVEL_NONE = 7;
当指定为SD_LOG_LEVEL_NONE时，将不会生成日志文件。
返回值：返回0表示初始化成功，返回负数则为失败，负数值为其错误码。

2、系统反初始化

与 SDsysinit对应，系统退出前调用。

void SDsysexit()
参数：无
返回值：无

3、登录服务器

int  SDOnlineUser(int nRoomId,  int nUserId,  byte byUserType,  int nDomainId);
参数：
@nRoomId，表示当前客户端进入的房间号，要求非0
@nUserId，表示当前客户端使用的唯一用户ID，需要由用户自行保障唯一性。要求非0
@byUserType，表示客户端的类型，定义位于Constant.java：
        final byte USER_TYPE_OTHER = 0;         //保留未使用的类型
        final byte USER_TYPE_AV_SEND_RECV = 1;    //同时进行音视频发送和接收
        final byte USER_TYPE_AV_RECV_ONLY = 2;    //仅接收音视频
        final byte USER_TYPE_AV_SEND_ONLY = 3;    //仅发送音视频
用户根据自身业务选择合适的客户端类型，以获得资源的最低占用。
@unDomainId，域ID，默认为1，需与服务端沟通该值的设置。
返回值：返回0表示登录成功，返回负数则为失败，负数值为其错误码。

4、下线服务器

void  SDOfflineUser();
参数：无
返回值：无

5、请求上传音视频到指定位置

int  SDOnPosition(byte byPosition);
参数：
@byPosition，大于等于0，小于系统支持的最大“位置”数（默认最大数为6，可定制）。特殊值：当设置为255时表示由服务器分配当前空闲的位置。本函数调用成功后，客户端将自动停止接收自己位置的音视频流（不看自己）。
返回值：返回0表示请求发布成功，返回负数则为失败，负数值为其错误码。

::: caution
在Online成功后调用才能生效，纯播放端无需上下位置。
:::

6、请求从位置上下来

void  SDOffPosition();
参数：无
返回值：无
说明：对于当前在位置上的音视频发布者，SDOffPosition将从位置上下来并停止上行音视频数据，但它仍然保持在线状态并能接收其他位置的音视频流。本函数调用成功后，将自动恢复接收自己之前所在位置的音视频流（可能有其他客户端加入该位置）。

::: caution
说明：本接口在SDOnlineUser成功后调用。SDOfflineUser内部自带本API功能，因此客户端下线可以不用单独调用本API，直接调用SDOfflineUser即可。
:::

7、设置音视频下行掩码

void  SDSetAvDownMasks(int nAudioDownMask,  int nVideoDownMask);
通过设置音视频下行掩码，可以选择从服务器接收哪几个位置的音视频数据。每一个bit对应一个位置，最低位对应0号位置，最高位对应31号位置。比如希望接收某个index位置的音视频时，可以设置其对应bit设置为1，否则设置为0。
允许接收某个index位置的音视频时，可以设置为：
            UINT unMask = 0x1 << (index);
            unAudioDownChannelsMask |= unMask;
            unVideoDownChannelsMask |= unMask;
停止接收某个index位置的音视频时，可以设置为：
            UINT unMask = 0x1 << (index);
            unMask = ~unMask;
            unAudioDownChannelsMask &= unMask;
            unVideoDownChannelsMask &= unMask;
SDSetAvDownMasks(unAudioDownChannelsMask,  unVideoDownChannelsMask);
当本客户端仅发送音视频，不接收音视频时，设置接收掩码为0即可。
参数：
@nAudioDownMask，控制音频接收的掩码。
@nVideoDownMask，控制视频接收的掩码。 
返回值：无

::: caution
请在Online成功后调用。
:::

8、设置音视频传输参数

void  SDSetTransParams(int nRedunMethod, int nRedunRatio, int nGroupSize, int nEnableNack, int nJitterBufTime);
参数：
@ nRedunMethod，上行冗余方法，0表示固定冗余度，1表示自动冗余度
@nRedunRatio，上行冗余比率，比如设置为30，则表示使用30%冗余。
@nGroupSize， 为上行FEC分组大小，512Kbps以下建议设置为8，512Kbps~1Mbps建议设置为16，1Mbps~2Mbps建议设置24，2Mbps以上建议设置28。
@nEnableNack，是否启用NACK功能，关于NACK请阅读相关文档，建议设置为1开启。
@nJitterBufTime，本客户端接收码流时的内部缓存时间初始值（毫秒）,范围0~600。设置为0时，将关闭内部接收JitterBuff功能。对延时无过高要求的场景下建议设置150ms。
返回值：无

::: caution
本函数需在SDOnlineUser之前调用，本API的使用若有疑问，请联系技术支持获得帮助。
:::

播放API

播放API定义位于SDInterfacePlayer.java中。一个APP中可以创建多个播放实例实现多路播放功能。

1、播放初始化

void  Init(Activity act, SurfaceViewRenderer surfaceView, boolean playAudioOnly, boolean playVideoOnly,  boolean  playAudioOnJava ,  int  decodeMode)
参数：
@ act，播放实例所在的Activity。
@ surfaceView，画面渲染的surface view。
@ playAudioOnly，是否仅播放音频。仅播放音频时surfaceView可设置为null
@ playVideoOnly，是否仅播放视频。
@ playAudioOnJava，是否在JAVA层播放远端音频，否则将在C层播放。在开启软件AEC时，必须在JAVA层播放远端音频。其他情况下即支持在C层播放，也支持在JAVA层播放。
@ decodeMode，解码模式， 0(软解码)  1(硬解码)  2(硬解码优先)
返回值：无

::: caution
说明：需要在调用基础API SDsysinit之后调用本API。
:::

2、播放反初始化

void Destroy()
参数：无
返回值：无

3、开始播放

void startPlay(int index,  int renderWidth,  int renderHeight, boolean renderKeepRatio) 
参数：
@ index，播放的音视频“位置”索引。
@ renderWidth，画面渲染窗口的宽度。
@ renderHeight，画面渲染窗口的高度。
@ renderKeepRatio，是否保持宽高比渲染
返回值：无

::: caution
说明：无需提供精确的renderWidth和renderHeight，只需要二者比率与surfaceView宽高比一致即可。当然若能获得精确宽高最佳。
:::

4、停止播放

void stopPlay() 
参数：无
返回值：无

反馈回调

底层SDK对外提供了状态反馈，外层通过Handler对回调进行处理。绝大部分的回调仅做信息通知使用，外层可仅做信息展示用途。具体描述如下：

1、SYS_NOTIFY_RECON_START
因为网络原因，SDK与服务器断开连接，并自动开始重连。外层无需处理本消息，亦可界面提示用户。
2、SYS_NOTIFY_RECON_SUCCESS
因为网络原因，SDK与服务器断开连接，并自动重连成功。外层无需处理本消息，亦可界面提示用户。
3、SYS_NOTIFY_ONPOSITION
提示某个用户开始进入到某个“位置”发布音视频流。外层无需处理本消息，亦可界面提示用户。
4、SYS_NOTIFY_OFFPOSITION
提示某个用户离开其发布“位置”。外层无需处理本消息，亦可界面提示用户。
5、SYS_NOTIFY_EXIT_KICKED
提示当前用户的账号在其他位置登录，本用户被顶下去，外层需要结束播放并提示用户。用户应该避免使用重复UID的情况。

最后修改时间： 1 年前