maple-rtc 音视频SDK集成文档 - android

简介：

maple-rtc 为蓝蘑云推出的实时音视频会议系统，包括了实时音频，视频，变声，美颜等功能，适用于娱乐，游戏，教育等实时音视频场景中；

一：下载SDK

1.1 Android音视频SDK

maple-rtc android sdk 目录结构如下：

1.2 android音视频demo源码下载

演示的android 音视频maple-rtc-android-1v1-sample源码；

二：基本API说明

android SDK 主要基于java 语言调用，包括以下类：

BMediaKit 包含所有由应用程序调用的主要方法
IBMediaEventHandler 包含回调方法

注意:

android SDK 底层不提供权限请求，只做权限检测，需要用户应用层赋予应用所需要的权限；

接口调用流程图

音频调用接口流程图：

视频调用接口流程图：

BMediaKit 接口类

注：调用 BMediaKit 的接口最好在同一个线程进行，不建议在不同的线程同时调用。

初始化BMediaKit实例(create)

public static BMediaKit create(Context context, String appId, IBMediaEventHandler handler)

该方法初始化 BMediaKit 为一个单例

注意事项:

输入参数:

context:

appId:

handler:

返回值：

示例代码
BMediaKit mBMediaKit = BMediaKit.create(getBaseContext(), “6638******fdd2”, mRtcEventHandler);

设置参数(setParameter)

public void setParameter(String key, String value);

该方法用于设置SDK特殊的参数；

输入参数：

key:

value:

返回值：

无

示例代码

mBMediaKit.setParameter("abc", "123");

设置频道模式(setChannelProfile)

public int setChannelProfile(int profile);

该方法用于设置频道模式(profile).

注意事项:

输入参数：

profile:

返回值：

示例代码
int ret = mBMediaKit.setChannelProfile(CHANNEL_PROFILE_VOICE_VIDEO);

设置视频会议属性(setVideoConferenceProfile)

public int setVideoConferenceProfile(int profile);

该方法用于设置视频会议属性(profile).

注意事项:

输入参数:

profile:

返回值：

示例代码

int ret = mBMediaKit.setVideoConferenceProfile(VIDEO_CONFERENCE_PROFILE_MCU);

设置音频会议属性(setAudioConferenceProfile)

public int setAudioConferenceProfile(int profile);

该方法用于设置音频会议属性(profile).

注意事项:

params

profile:

返回值：

示例代码

int ret = mBMediaKit.setAudioConferenceProfile(AUDIO_CONFERENCE_PROFILE_MCU);

设置媒体属性(setMediaProfile)

public int setMediaProfile(int audioProfile, int videoProfile);

该方法用于设置媒体模式.

注意事项:

params

audioProfile:

videoProfile:

返回值：

示例代码

int ret = mBMediaKit.setMediaProfile(AUDIO_PROFILE_VOICE_STANDARD，VIDEO_PROFILE_480P);

设置加入频道用户Id(setJoinChannelUserId)

public int setJoinChannelUserId(String uid);

该方法用于设置加入频道用户Id.

注意事项:

输入参数：

uid:

返回值

示例代码
int ret = mBMediaKit.setJoinChannelUserId(“abcd”);

查询SDK版本号(getSdkVersion)

public static int getSdkVersion()；

该方法返回SDK版本号。

输入参数：

无

返回值

示例代码
int version = BMediaKit::getSdkVersion();

加入频道(joinChannel)

public int joinChannel(String channelId);

该方法允许用户加入频道。如果频道尚未建立，调用该方法可以自动创建频道。 同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的应用程序是不能互通的。如果已在通话中，用户必须调用 leaveChannel() 退出当前通话，才能进入下一个频道。

注意事项:

输入参数：

channelId:

返回值

示例代码
int ret = mBMediaKit.joinChannel(“123”);

带uid加入频道(joinChannel)

public int joinChannel(String channelId, String uid);

该方法允许用户加入频道。如果频道尚未建立，调用该方法可以自动创建频道。 同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的应用程序是不能互通的。如果已在通话中，用户必须调用 leaveChannel() 退出当前通话，才能进入下一个频道。

注意事项:

输入参数：

channelId:

uid:

返回值

示例代码
int ret = mBMediaKit.joinChannel(“123”，“abc”);

离开频道(leaveChannel)

public int leaveChannel();

该方法为用户离开频道，即挂断或退出通话。通过调用 joinChannel 加入频道后，必须调用 leaveChannel() 以结束通话，否则不能进行下一次通话。 不管当前是否在通话中，都可以调用 leaveChannel()，没有副作用。leaveChannel() 会把会话相关的所有资源释放掉。

输入参数：

无

返回值

示例代码
int ret = mBMediaKit.leaveChannel();

开启本地音频的采集和上行(startLocalAudio)

startLocalAudio()

开启本地音频的采集和上行。调用该方法后，打开录音设备，在同一频道内的其他用户听到你的声音；

params

无

返回值

示例代码

int ret = mBMediaKit.startLocalAudio();

关闭本地音频的采集和上行(stopLocalAudio)

stopLocalAudio()

开启本地音频的采集和上行。调用该方法后，关闭录音设备，在同一频道内的其他用户将无法听到你的声音，；

params

无

返回值

示例代码

    int ret = mBMediaKit.stopLocalAudio();

将自己禁音(muteLocalAudioStream)

public int muteLocalAudioStream(boolean muted);

静音/取消静音。调用该方法后，在同一频道内的其他用户将无法听到你的声音；

输入参数：

muted:

返回值

示例代码
int ret = mBMediaKit.muteLocalAudioStream(true);

静音指定用户音频(muteRemoteAudioStream)

public int muteRemoteAudioStream(String uid, boolean muted);

该方法用于允许/禁止播放远端指定用户的音频流。没有被禁止用户的音频流接受和播放正常；

输入参数：

uid:

muted:

返回值

示例代码
int ret = mBMediaKit.muteRemoteAudioStream(“nick”，true);

打开外放扬声器模式(setEnableSpeakerphone)

public int setEnableSpeakerphone(boolean enableSpeaker);

该方法用于打开/关闭外放扬声器模式，即听筒和扬声器播放的切换；

输入参数：

enableSpeaker:

返回值

示例代码
int ret = mBMediaKit.setEnableSpeakerphone(true);

调节播放信号音量(adjustPlaybackSignalVolume)

public int adjustPlaybackSignalVolume(int volume);

该方法用于调节播放信号音量；软件调节播放信号音量，默认值为100（原始音量），最大调整为200（即原始音量的2倍），如果为小于等于0，即软件级静音，无法听到任何远端音频流；

输入参数：

volume:

返回值

示例代码
int ret = mBMediaKit.adjustPlaybackSignalVolume(50);

调节录音信号音量(adjustRecordingSignalVolume)

public int adjustRecordingSignalVolume(int volume);

该方法用于调节录音信号音量；软件调节录音信号音量，默认值为100（原始音量），最大调整为400（即原始音量的4倍）；如果为小于等于0，即软件级静音，对方将听不到你说话声音；

输入参数：

volume:

返回值

示例代码
int ret = mBMediaKit.adjustRecordingSignalVolume(50);

启用用户说话音量提示(enableAudioVolumeIndication)

public int enableAudioVolumeIndication(int interval);

该方法允许 SDK 定期向应用程序反馈当前房间里用户的音量。

注意事项:

输入参数：

interval:

返回值

示例代码
int ret = mBMediaKit.enableAudioVolumeIndication(500);

创建渲染视图(createRenderView)

public SurfaceView createRenderView();

该方法创建视频渲染视图，返回 SurfaceView 的类型。view 的操作和布局由 App管理, MAPLE SDK 在 App 提供的 view 上进行渲染。显示视频视图必须调用该方法，而不是直接调用 SurfaceView。

输入参数：

无

返回值

示例代码
SurfaceView view = mBMediaKit.createRenderView();

设置本地视频显示属性(setupLocalVideo)

public int setupLocalVideo(BMVideoCanvas local);

该方法设置本地视频显示信息。应用程序通过调用此接口绑定本地视频流的显示视窗(view)，并设置视频显示模式。

注意事项:

输入参数：

local:

Class BMVideoCanvas 描述:

返回值

示例代码
int ret = mBMediaKit.setupLocalVideo(new BMVideoCanvas(surfaceView, BMVideoCanvas.RENDER_MODE_HIDDEN, “nick”));

设置远端视频显示属性(setupRemoteVideo)

public int setupRemoteVideo(BMVideoCanvas remote);

该方法绑定远程用户和显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远程视频的 uid；

注意事项:

输入参数：

remote:

Class BMVideoCanvas 描述:

返回值

示例代码
int ret = mBMediaKit.setupRemoteVideo(new BMVideoCanvas(surfaceView, BMVideoCanvas.RENDER_MODE_HIDDEN, “abc”));

开启视频预览(startPreview)

public int startPreview();

该方法用于启动本地视频预览。

注意事项:

输入参数：

无

返回值

示例代码
int ret = mBMediaKit.startPreview();

停止视频预览(stopPreview)

public int stopPreview();

该方法用于停止本地视频预览。

注意事项:

输入参数：

无

返回值

示例代码
int ret = mBMediaKit.stopPreview();

切换前置/后置摄像头 (switchCamera)

public int switchCamera();

该方法用于在前置/后置摄像头间切换。

注意事项:

输入参数：

无

返回值

示例代码
int ret = mBMediaKit.switchCamera();

设置是否打开闪光灯(enableCameraTorchOn)

public int enableCameraTorchOn(boolean enabled);

该方法用于开关摄像头闪光灯。

注意事项:

输入参数：

enabled:

返回值

示例代码
int ret = mBMediaKit.enableCameraTorchOn(true);

暂停/恢复发送本地视频流(muteLocalVideoStream)

public int muteLocalVideoStream(boolean muted);

该方法用于允许/禁止往网络发送本地视频流；

注意事项:

输入参数:

muted:

返回值:

示例代码

int ret = mBMediaKit.muteLocalVideoStream(true);

暂停/恢复指定远端视频流(muteRemoteVideoStream)

public int muteRemoteVideoStream(boolean muted, String uid);

该方法用于允许/禁止播放指定远端视频流；

注意事项:

输入参数:

uid:

muted:

返回值:

示例代码

int ret = mBMediaKit.muteRemoteVideoStream(true，"abc");

暂停/恢复指定远端视频流(muteRemoteVideoStream2)

public int muteRemoteVideoStream2(boolean muted, String uid);

该方法用于允许/禁止播放指定远端视频流；

注意事项:

输入参数:

uid:

muted:

返回值:

示例代码

int ret = mBMediaKit.muteRemoteVideoStream2(true，"abc");

开关视频美颜功能(enableBeautify)

public int enableBeautify(boolean enabled);

该方法用于打开/关闭视频美颜功能；

注意事项:

params

enabled:

返回值:

示例代码

int ret = mBMediaKit.enableBeautify(true);

设置美颜等级(setBeautifyLevel)

public int setBeautifyLevel(float value);

该方法用于设置美颜等级功能；

注意事项:

params

value:

返回值:

示例代码

int ret = mBMediaKit.setBeautifyLevel(0.5);

IBMediaEventHandler 回调接口类

注意:

必须在加入频道前调用create(Context context, String appId, IBMediaEventHandler handler)方法时传入handler来使能回调产生。

加入频道成功回调 (onJoinChannelSuccess)

public void onJoinChannelSuccess(String channelId, String uid){}

表示客户端登入服务器成功，且创建和分配了频道 ID 和用户 ID。频道 ID 的分配是根据 joinChanel API 中指定的频道名称。如果调用 joinChannel 时并未指定用户 ID，服务器就会随机分配一个。

回调参数

channelId:

uid:

加入频道失败回调 (onJoinChannelFailed)

public void onJoinChannelFailed(int reason){}

表示客户端登入服务器失败。

回调参数

reason:

离开频道回调 (onLeaveChannel)

public void onLeaveChannel(int reason){}

用程序调用 leaveChannel() 方法时，SDK提示应用程序离开频道成功或者失败。参数reason表示具体原因状态码。

回调参数

reason:

强行踢出频道回调 (onForceKickOutChannel)

public void onForceKickOutChannel(int reason){}

由于某种原因，自己强行被系统踢下线。参数reason表示具体原因状态码。

回调参数

reason:

用户加入当前频道回调 (onUserJoinedNotice)

public void onUserJoinedNotice(List<String> uids) {}

提示有用户加入了频道。如果该客户端加入频道时已经有人在频道中，SDK也会向应用程序上报这些已在频道中的全部用户。

回调参数

uids:

用户离开当前频道回调 (onUserOfflineNotice)

public void onUserOfflineNotice(List<String> uids) {}

提示有用户离开了频道（或掉线）。

回调参数

uids:

发生警告回调 (onWarning)

public void onWarning(int warn){}

该回调方法表示 SDK 运行时出现了（网络或媒体相关的）警告。 通常情况下，SDK上报的警告信息应用程序可以忽略，SDK 会自动恢复。

回调参数

reason:

发生错误回调 (onError)

public void onError(int err) {}

表示 SDK 运行时出现了（网络或媒体相关的）错误。 通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 APP 干预或提示用户。

回调参数

reason:

启用用户说话音量提示回调 (onAudioVolumeIndication)

public void onAudioVolumeIndication(int volume){}

该方法允许 SDK 定期向应用程序反馈当前谁在输入声音的音量。该提示默认为关闭状态，如有需要，调用 enableAudioVolumeIndication 方法触发该提示。

回调参数

totalVolume:

volumeInfo * 类型：String * 默认值：无 * 描述：说话者音量信息(0~255)；

连接丢失回调 (onConnectionLost)

public void onConnectionLost(){}

连接丢失监听事件；sdk 和服务器失去了网络连接，并且尝试自动重连一段事件（15s左右）后仍未连上。回调该事件后，sdk将不会再次自动重连，需要用户手动调用leaveChannel，后再次尝试加入频道；

回调参数

无

远端第一帧视频解码成功提示回调 (onFirstRemoteVideoFrameSizeChanged)

public void onFirstRemoteVideoFrameSizeChanged(String uid, int width, int height){}

该方法允许 SDK 向应用程序反馈远端第一帧视频解码成功的回调。当调用muteRemoteVideoStream2或者muteRemoteVideoStream后，该回调会产生；

回调参数

width:

height:

uid:

回调状态码

状态码 值 描述
KC_StatusOk 200 状态正常
KC_JoinChannelFailed 4000 加入频道失败
KC_LoginSignalServerFailed 4001 登录信令服务器失败
KC_ConnectMediaServerFailed 4003 连接媒体服务器失败
KC_AppIdInvalid 4005 无效的AppId
KC_HttpRequestFailed 4006 加入频道失败
KC_LeaveChannelFailed 4100 离开频道失败
KC_KickedOutReLogin 4200 相同userId用户登录，服务器强行踢出当前用户
KC_KickedOutTimeOut 4201 客户端长时间未通知服务器状态，服务器强行踢出当前用户