API说明【JAVA摄像头互动SDK】
API接口
SDK由如下三类API组成：
- 基础API接口，负责基础的TCP连接管理（如登录、下线）、音视频码流收发、底层回调反馈等。相关代码位于SDInterface.java
- 推送API接口，负责摄像头、麦克风的采集、音频3A、音视频压缩编码等处理。相关代码位于SDInterfaceCameraPublisher.java
- 播放API接口，负责播放远端音视频。相关代码位于SDInterfacePlayer.java
用户根据业务情况选择对应API调用。基础SDK包括所有类别客户端均需调用的基础功能，纯发送型客户端无需调用播放API，纯播放型客户端无需调用推送API。
基础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定义位于SDInterfaceCameraPublisher.java中。SDK通过单实例方式调用推送API，形式如下：SDInterfaceCameraPublisher.Inst().API()。一个APP中只允许有一个推送实例。
1、推送初始化
void Init(SDInterface interface, SurfaceView view, boolean sendAudioOnly, boolean sendVideoOnly, SDAudio3AConfig audio3AConfig)
参数：
@ interface，基础API对象
@ view，用于本地摄像头视频渲染的view
@ sendAudioOnly，是否仅发送音频，为true时表示纯音频发送模式，此时参数view可设置为null，不进行视频采集和编码。
@ sendVideoOnly，是否仅发送视频，为true时表示纯视频发送模式，不进行音频采集和编码。
@ audio3AConfig，音频3A设置，可选择开启或关闭AEC\ANS\AGC，也可选择采用软件3A或硬件3A（需设备支持，否则无效）。
返回值：无
::: caution
说明：需要在调用基础API SDsysinit之后调用本API。
:::
2、推送反初始化
void Destroy()
参数：无
返回值：无
3、设置摄像头采集参数
boolean setPreviewParams(int cameraType, int previewOrientation, int width, int height)
参数：
@cameraType，采用前置摄像头还是后置摄像头，取值范围：
Camera.CameraInfo.CAMERA_FACING_FRONT
Camera.CameraInfo.CAMERA_FACING_BACK
@ previewOrientation，摄像头垂直模式还是水平模式，取值范围：
Configuration.ORIENTATION_PORTRAIT
Configuration.ORIENTATION_LANDSCAPE
@ width，请求采集的宽度。
@ height，请求采集的高度。
返回值：true成功，false失败
::: caution
说明：本API必须在Start接口之前调用
:::
4、设置视频编码参数
boolean setVideoEncParams(int bitrate, int frameRate , int width, int height)
参数：
@ bitrate，视频编码的码率，注意单位为bps。
@ framerate，视频编码的帧率，如30表示30fps。
@ width，视频编码的宽度。
@ height，视频编码的高度。
返回值：true成功，false失败
::: caution
当采集宽高与编码宽高不等时，内部将自行缩放处理。当二者宽高比不一致时，将剪裁到编码宽高比。未调用本API时将默认按640X360编码
:::
5、设置视频编码类型（硬编码、软编码）
void setToHardwareEncoder()
void setToSoftwareEncoder()
参数：
返回值：
::: caution
使用软编码或硬编码，默认将优先使用硬编码，硬编码创建失败时自动切为软编码。硬编码功耗低、高分辨率性能充足，但码率波动大，对网络产生压力较大。软编码码率控制相对平稳。高分辨率时建议使用硬编码，低分辨率时使用软编码。
:::
6、设置音频采集编码参数
boolean setAudioEncParams(int channelNum, int samplerate)
参数：
@ channelNum，音频编码的声道数，1为单声道，2为立体声。
@ samplerate，音频编码的采样率，比如32000。
返回值：true成功，false失败
::: caution
说明：未调用本API指定时，默认使用44100HZ，2声道。
:::
7、开始推送音视频流
boolean startPublish()
参数：无
返回值：true成功，false失败
::: caution
说明：需在已经登录的状态下调用，否则将不会生效。调用本API后内部将启动音视频的采集、编码、发送。
:::
8、停止推送
boolean stopPublish()
参数：无
返回值：true成功，false失败
9、切换前后置摄像头
boolean changeCameraFace ()
参数：
返回值：true成功，false失败
::: caution
说明：过程中动态切换摄像头类型，若当前为前置摄像头，调用本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)
参数：
@ index，播放的音视频“位置”索引。
@ renderWidth，画面渲染窗口的宽度。
@ renderHeight，画面渲染窗口的高度。
返回值：无
::: 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 年前
API接口
基础API
1、系统初始化
2、系统反初始化
3、登录服务器
4、下线服务器
5、请求上传音视频到指定位置
6、请求从位置上下来
7、设置音视频下行掩码
8、设置音视频传输参数
推送API
1、推送初始化
2、推送反初始化
3、设置摄像头采集参数
4、设置视频编码参数
5、设置视频编码类型（硬编码、软编码）
6、设置音频采集编码参数
7、开始推送音视频流
8、停止推送
9、切换前后置摄像头
播放API
1、播放初始化
2、播放反初始化
3、开始播放
4、停止播放
反馈回调