maple-rtc 语音SDK集成文档 - cocos2dx

简介：

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

一：下载SDK

1.1 Cocos2d语音SDK

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

1.2 Cocos2d语音demo源码下载

演示的cocos2d 语音demo源码自行前往github下载；

二：集成指南

2.1 Android 集成指南

2.1.1 Android studio配置：

在工程下面建一个BMGamingSDK目录, 把include和libs文件夹拷贝到 BMGamingSDK。添加jar文件，在proj.android-studio/app/build.gradle的dependencies处添加如下：

在proj.android-studio/app/jni的Android.mk中添加库文件和头文件的引用：

在proj.android-studio/app/AndroidManifest.xml添加如下权限:

android.permission.INTERNET

android.permission.BLUETOOTH

android.permission.RECORD_AUDIO

android.permission.MODIFY_AUDIO_SETTINGS

确保已满足以下环境要求:

• Android Studio 2.0 或更高版本；
• 支持音频功能的Andoird 真机（4.0 或更高版本）
• 一个AppID，获取App ID 质询商务；

2.2 iOS 集成指南

2.2.1 XCode 配置：

在工程下面建一个BMGamingSDK目录, 把include和libs文件夹拷贝到 BMGamingSDK。添加MapleAudioKit.framework和添加以下必要的系统库：

引用头文件：

#include "../BMGamingSDK/include/BMediaNativeCore.h"

设置project privacy来获取 microphone 权限；

设置Other Link Flags 加-ObjC

确保已满足以下环境要求:

• Xcode 8.0 或更高版本；
• 支持音视频功能的iOS 真机（8.0 或更高版本）；
• 一个AppID，获取App ID 质询商务；

三：基本API说明

Cocos2dx 主要基于c++ 语言调用，包括以下类：

注意:

android 需要单独调用一个额外接口来注册Android的activity到SDK；该接口需要在Android java客户端启动的入口方法中加入protected void onCreate(final Bundle savedInstanceState)如下示例：

import com.maple.rtc.BMediaKit;
BMediaKit.registerActivity(this);

如果不注册activity，Android后续的C++接口调用可能都会失败；

接口调用流程图

BMedia 接口类

注：如无特殊说明接口，建议在主线程调用；

• setChannelProfile
• setJoinChannelUserId
• getSdkVersion
• setEventHandler
• joinChannel
• leaveChannel
• muteLocalAudioStream
• muteRemoteAudioStream
• setEnableSpeakerphone
• adjustPlaybackSignalVolume
• adjustRecordingSignalVolume
• enableAudioVolumeIndication

设置频道属性(setChannelProfile)

virtual void setChannelProfile(CHANNEL_PROFILE_TYPE profile);

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

注意事项:

• 同一频道内只能同时设置一种模式；
• 该方法必须在加入频道前调用和进行设置，进入频道后无法再设置；

输入参数：

profile:

• 类型：CHANNELPROFILETYPE 枚举类型
• 默认值：CHANNELPROFILEVOICE_ONLY(纯语音模式)
• 描述：频道模式，CHANNELPROFILEVOICEONLY = 0 纯语音模式，CHANNELPROFILEVOICEVIDEO = 1 语音视频模式，CHANNELPROFILELIVE_LOOK = 2 直播观看模式，

返回值：

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->setChannelProfile(CHANNEL_PROFILE_VOICE_ONLY);

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

virtual int setJoinChannelUserId(const char* uid);

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

注意事项:

• 加入频道的用户Id必须在整个appId中唯一，相同的用户Id登录会被对方踢下线；
• 用户Id为字符串，长度小于等于32个字符；
• 该方法必须在加入频道前调用和进行设置，进入频道后无法再设置；

输入参数：

uid:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：加入频道的用户Id

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->setJoinChannelUserId(“abcd”);

设置回调函数(setEventHandler)

virtual void setEventHandler(IBMediaEventHandler* handler);

该方法为设置一个回调函数到SDK。如果不设置，后续全面回调函数无法返回；该方法必须在加入频道前调用和进行设置，进入频道后无法再设置；

输入参数：

handler： * 类型：IBMediaEventHandler * 默认值：无 * 描述：具体查看IBMediaEventHandler 类方法；

返回值

无

示例代码

int version = BMediaKit_getInstance(MAPLE_APP_ID)->setEventHandler(this);

查询SDK版本号(getSdkVersion)

static int getSdkVersion();

该方法返回SDK版本号。

输入参数：

无

返回值

• 类型：int
• 默认值：无
• 描述：SDK编译版本号；

示例代码

int version = BMediaKit_getInstance(MAPLE_APP_ID)->getSdkVersion();

加入频道(joinChannel)

virtual int joinChannel(const char* channelId);

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

注意事项:

• 调用该方法时，系统会随机产生一个用户ID，在onJoinChannelSuccess(const char* channelId, const char* uid)监听到当前加入频道的uid值；
• 加入频道后，扬声器和麦克风默认打开；摄像头预览默认关闭；

输入参数：

channelId:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：加入频道Id

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->joinChannel(“123”);

带uid加入频道(joinChannel)

virtual int joinChannel(const char* channelId,  const char* uid);

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

注意事项:

• 该 uid 不能与AppId内现有的其他用户 uid 相同，否则AppId内持有相同 uid 用户的服务将被迫停止。
• uid 属性限制于setJoinChannelUserId(const char* uid)参数uid一样。
• 加入频道后，扬声器和麦克风默认打开；摄像头预览默认关闭；

输入参数：

channelId:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：加入频道Id

uid:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：加入频道的用户Id

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->joinChannel(“123”，“abc”);

离开频道(leaveChannel)

virtual int leaveChannel();

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

输入参数：

无

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->leaveChannel();

将自己禁音(muteLocalAudioStream)

virtual int muteLocalAudioStream(bool mute);

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

输入参数：

mute:

• 类型：bool
• 默认值：无
• 描述：true 设置本地静音，即麦克风静音； false 取消本地静音；

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->muteLocalAudioStream(true);

静音指定用户音频(muteRemoteAudioStream)

virtual int muteRemoteAudioStream(const char* uid, bool mute);

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

输入参数：

uid:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：加入频道的用户Id

mute:

• 类型：bool
• 默认值：无
• 描述：true 停止播放指定用户的音频流； false 允许播放指定用户的音频流；

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->muteRemoteAudioStream(“abc”，true);

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

virtual int setEnableSpeakerphone(bool enabled);

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

输入参数：

enabled:

• 类型：bool
• 默认值：无
• 描述：true 切换至外放扬声器模式； false 切换至听筒模式；

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->setEnableSpeakerphone(true);

调节播放信号音量(adjustPlaybackSignalVolume)

virtual int adjustPlaybackSignalVolume(int volume);

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

输入参数：

volume:

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

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->adjustPlaybackSignalVolume(50);

调节录音信号音量(adjustRecordingSignalVolume)

virtual int adjustRecordingSignalVolume(int volume);

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

输入参数：

volume:

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

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)-> adjustRecordingSignalVolume(50);

启用自己说话音量提示(enableAudioVolumeIndication)

virtual int enableAudioVolumeIndication(int interval);

该方法允许 SDK 定期向应用程序反馈当前自己说话状态以及自己的音量。

注意事项:

• 在onAudioVolumeIndication(bool isSpeak, int volume) 回调函数中获得相关信息;

输入参数：

interval:

• 类型：int
• 默认值：无
• 描述：指定音量提示的时间间隔。<10: 禁用音量提示功能 >=10: 提示间隔，单位为毫秒。建议设置到大于 500 毫秒

返回值

• 类型：int
• 默认值：无
• 描述：0 失败，1 成功

示例代码

int ret = BMediaKit_getInstance(MAPLE_APP_ID)->enableAudioVolumeIndication(500);

IBMediaEventHandler 回调接口类

• onJoinChannelSuccess
• onJoinChannelFailed
• onLeaveChannel
• onForceKickOutChannel
• onUserJoinedNotice
• onUserOfflineNotice
• onWarning
• onError
• onAudioVolumeIndication
• onConnectionLost

注意:

必须在加入频道前调用void setEventHandler(IBMediaEventHandler* handler)方法来使能回调产生。

加入频道成功回调 (onJoinChannelSuccess)

virtual void onJoinChannelSuccess(const char* channelId, const char* uid);

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

回调参数

channelId:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：返回加入的频道Id

uid:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：返回加入频道的用户Id， 如果 joinChannel 中指定了 uid，则此处返回该 ID；否则使用 maple 服务器自动分配的 ID；

加入频道失败回调 (onJoinChannelFailed)

virtual void onJoinChannelFailed(int reason);

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

回调参数

reason:

• 类型：int
• 默认值：无
• 描述：登录频道失败状态码

离开频道回调 (onLeaveChannel)

virtual void onLeaveChannel(int reason);

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

回调参数

reason:

• 类型：int
• 默认值：无
• 描述：离开频道状态码

强行踢出频道回调 (onForceKickOutChannel)

virtual void onForceKickOutChannel(int reason);

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

回调参数

reason:

• 类型：int
• 默认值：无
• 描述：踢出频道状态码

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

virtual void onUserJoinedNotice(const char* uids);

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

回调参数

uids:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：json 字符串数组，上层应用程序自行解析json字符串数组获取每个用户Id；

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

virtual void onUserOfflineNotice(const char* uids);

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

回调参数

uids:

• 类型：字符串常量（const char*）
• 默认值：无
• 描述：json 字符串数组，上层应用程序自行解析json字符串数组获取每个用户Id；

发生警告回调 (onWarning)

virtual void onWarning(int warn);

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

回调参数

reason:

• 类型：int
• 默认值：无
• 描述：警告状态代码

发生错误回调 (onError)

virtual void onError(int err);

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

回调参数

reason:

• 类型：int
• 默认值：无
• 描述：错误状态代码

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

virtual void onAudioVolumeIndication(int volume);

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

回调参数

volume:

• 类型：int
• 默认值：无
• 描述：输入声音的音量， 值为0~255；

连接丢失回调 (onConnectionLost)

virtual void onConnectionLost();

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

回调参数

无

回调状态码