Video SDK for Cocos2d C++ 快速接入
适用范围
本规范仅适用于使用游密实时音视频引擎Cocos2d-x接口（C++接口）开发多人实时语音功能的开发者。
SDK目录概述
语音SDK中有两个子文件夹：lib、include,下面依次介绍下这两个子文件夹。
include：SDK的头文件。 详细介绍下inlude，所有接口都在这个文件夹中。IYouMeVoiceEngine.h封装了语音SDK的全部功能接口，集成方可通过IYouMeVoiceEngine::getInstance ()->…来调用语音SDK接口。IYouMeEventCallback.h包含语音SDK的所有回调事件接口，例如初始化结果，频道加入成功等，都将通过此接口通知集成方。YouMeConstDefine.h包含语音SDK的所有枚举类型定义，如错误码等。
lib：库文件，分为Android平台和iOS平台。Android平台下包括ARMv5、ARMv7和X86三种CPU架构下的libyoume_voice_engine.so文件，还包括youme_voice_engine.jar。iOS平台下包含libyoume_voice_engine.a文件。
开发环境集成
Cocos2d-x开发环境生成的目录结构如下图所示，将SDK目录更名为youme_voice_engine（内含“include”和“lib”两个子文件夹），并复制到游戏的根目录下，这个目录下包含了Android和iOS两个平台所需的所有C++头文件和库文件。
Android系统Eclipse开发环境配置
- 修改proj.android/jni/Android.mk文件，对应位置增加指定内容，分别对游密实时语音SDK的动态库进行预编译处理、添加头文件路径、链接动态库。
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
$(call import-add-path,$(LOCAL_PATH)/../../cocos2d)
$(call import-add-path,$(LOCAL_PATH)/../../cocos2d/external)
$(call import-add-path,$(LOCAL_PATH)/../../cocos2d/cocos)
#＝＝＝＝＝＝Youme 添加＝＝＝＝＝＝＝＝＝
LOCAL_MODULE := youme_voice_engine
LOCAL_SRC_FILES := ../$(LOCAL_PATH)/../../youme_voice_engine/lib/android/$(TARGET_ARCH_ABI)/libyoume_voice_engine.so
include $(PREBUILT_SHARED_LIBRARY)
#＝＝＝＝＝＝结束 Youme 添加＝＝＝＝＝＝＝
LOCAL_MODULE := cocos2dcpp_shared
LOCAL_MODULE_FILENAME := libcocos2dcpp
LOCAL_SRC_FILES := hellocpp/main.cpp \
../../Classes/Helloworld.cpp
#＝＝＝＝＝＝==Youme修改＝＝＝＝＝＝＝＝＝
LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
$(LOCAL_PATH)/../../youme_voice_engine/include
#＝＝＝＝＝＝结束 Youme 修改＝＝＝＝＝＝＝
# _COCOS_HEADER_ANDROID_BEGIN
# _COCOS_HEADER_ANDROID_END
LOCAL_STATIC_LIBRARIES := cocos2dx_static
#＝＝＝＝＝＝Youme 添加＝＝＝＝＝＝＝＝＝
LOCAL_SHARED_LIBRARIES := youme_voice_engine
#＝＝＝＝＝＝结束 Youme 添加＝＝＝＝＝＝＝
# _COCOS_LIB_ANDROID_BEGIN
# _COCOS_LIB_ANDROID_END
include $(BUILD_SHARED_LIBRARY)
$(call import-module,.)
# _COCOS_LIB_IMPORT_ANDROID_BEGIN
# _COCOS_LIB_IMPORT_ANDROID_END
- 如果需要显示指定CPU架构则修改proj.android/jni/Application.mk文件，增加指定部分的内容(v5版本为APP_ABI := armeabi)；如果不需要指定CPU架构Application.mk文件, 则不用修改。
#＝＝＝＝＝＝修改＝＝＝＝＝＝＝＝＝＝＝
APP_ABI := armeabi-v7a
#＝＝＝＝＝＝结束修改＝＝＝＝＝＝＝＝＝
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -DCC_ENABLE_CHIPMUNK_INTEGRATION=1 -std=c++11 -fsigned-char
APP_LDFLAGS := -latomic
ifeq ($(NDK_DEBUG),1)
APP_CPPFLAGS += -DCOCOS2D_DEBUG=1
APP_OPTIM := debug
else
APP_CPPFLAGS += -DNDEBUG
APP_OPTIM := release
endif
-
复制youme_voice_engine/lib/android/youme_voice_engine.jar到proj.android/libs/ youme_voice_engine.jar。
-
修改proj.android/AndroidManifest.xml文件，确保声明了如下的权限：
XML <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" /> <uses-permission android:name="android.permission.BLUETOOTH" /> -
打开eclipse，导入上一步Android工程，在项目的第一个启动的AppActivity（找到AppActivity.java文件）中导入package:
import com.youme.voiceengine.mgr.YouMeManager;
import com.youme.voiceengine.*;然后在onCreate方法里添加如下代码(没有此方法的话需要自己补上)：
@Override
public void onCreate(Bundle savedInstanceState)
{
//以下两个函数调用顺序不能错
YouMeManager.Init(this);
super.onCreate(savedInstanceState);
}
iOS系统XCode开发环境配置
添加头文件和依赖库:
- 添加头文件路径：在
Build Settings->Search Paths->Header Search Paths中添加../youme_voice_engine/include（建议直接将此include文件夹拖到xcode需要填入的位置，然后路径会自动生成)。 - 添加库文件路径：在
Build Settings->Search Paths->Library Search Paths中添加../youme_voice_engine/lib/ios/Release-universal（建议直接将此Release-universal文件夹拖到xcode需要填入的位置，然后路径会自动生成)。 - 添加依赖库：在
Build Phases->Link Binary With Libraries下添加：
libsqlite3.0.tbd
libyoume_voice_engine.a
libz.dylib
libz.1.2.5.tbd
libresolv.9.tbd
SystemConfiguration.framework
CoreTelephony.framework
AVFoundation.framework
AudioToolBox.framework
CFNetwork.framework
Windows平台VS开发环境配置
-
将
youme_voice_engine复制到Cocos2d-x开发工具生成的游戏目录根目录下。 -
在项目 -> 属性 -> C/C++ -> 常规 -> 附加包含目录 中添加
..\youme_voice_engine\include。 -
youme_voice_engine/lib目录下的dll到执行目录(如果是64位机器，使用youme_voice_engine/lib/x64)。
-
在项目->属性->链接器->输入->附加依赖库 中添加
youme_voice_engine.lib。
视频关键接口流程
- 在收到
YOUME_EVENT_JOIN_OK事件后，
注册视频回调：api.SetVideoCallback();。
控制自己的摄像头打开：api.StartCapturer();。
控制自己的摄像头关闭：api.StopCapturer();。 - 以上步骤完成，如果自己或者远端有视频流过来，会通知
YOUME_EVENT_OTHERS_VIDEO_ON事件，在该事件里绑定视频流和渲染组件VideoRenderer.getInstance().addRender(String userId, SurfaceViewRenderer view);。 - 其它API
是否屏蔽他人视频：api.maskVideoByUserId()。
切换摄像头：api.SwitchCamera();。
删除渲染绑定：VideoRenderer.getInstance().deleteRender();。
实现回调
使用者要继承类IYouMeEventCallback并实现其纯虚函数（回调函数），在调用初始化函数时传入指向子类的指针。回调都在子线程中执行，不能用于更新UI等耗时操作。
- 首先声明一个类YouMeVoiceEngineImp（类名可自取）来注册回调事件：
class YouMeVoiceEngineImp : public IYouMeEventCallback
{
public:
static YouMeVoiceEngineImp *getInstance ();
virtual void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param);
}
-
然后在该类YouMeVoiceEngineImp下必须实现以下方法：
C++ //监听各类回调事件 void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) { switch (event) { //case案例只覆盖了部分，仅供参考，详情请查询枚举类型YouMeEvent case YOUME_EVENT_INIT_OK: //"初始化成功"; break; case YOUME_EVENT_INIT_FAILED: // "初始化失败，错误码：" + errorCode; break; case YOUME_EVENT_JOIN_OK: //"加入频道成功"; break; case YOUME_EVENT_LEAVED_ALL: // "离开频道成功"; break; case YOUME_EVENT_JOIN_FAILED: //进入语音频道失败 break; case YOUME_EVENT_REC_PERMISSION_STATUS: // "通知录音权限状态，成功获取权限时错误码为YOUME_SUCCESS，获取失败为YOUME_ERROR_REC_NO_PERMISSION（此时不管麦克风mute状态如何，都没有声音输出）"; break; case YOUME_EVENT_RECONNECTING: //"断网了，正在重连"; break; case YOUME_EVENT_RECONNECTED: // "断网重连成功"; break; case YOUME_EVENT_MEMBER_CHANGE: //房间内成员列表变化 break; case YOUME_EVENT_OTHERS_MIC_OFF: //其他用户的麦克风关闭： break; case YOUME_EVENT_OTHERS_MIC_ON: //其他用户的麦克风打开： break; case YOUME_EVENT_OTHERS_SPEAKER_ON: //其他用户的扬声器打开： break; case YOUME_EVENT_OTHERS_SPEAKER_OFF: //其他用户的扬声器关闭 break; case YOUME_EVENT_OTHERS_VOICE_ON: //其他用户开始讲话 break; case YOUME_EVENT_OTHERS_VOICE_OFF: //其他用户停止讲话 break; case YOUME_EVENT_MY_MIC_LEVEL: //麦克风的语音级别 break; case YOUME_EVENT_MIC_CTR_ON: //麦克风被其他用户打开 break; case YOUME_EVENT_MIC_CTR_OFF: //麦克风被其他用户关闭 break; case YOUME_EVENT_SPEAKER_CTR_ON: //扬声器被其他用户打开 break; case YOUME_EVENT_SPEAKER_CTR_OFF: //扬声器被其他用户关闭 break; case YOUME_EVENT_LISTEN_OTHER_ON: //取消屏蔽某人语音 break; case YOUME_EVENT_LISTEN_OTHER_OFF: //屏蔽某人语音 break; //=====================视频相关========================= case YOUME_EVENT_OTHERS_VIDEO_ON: //其他用户视频流打开 //收到此事件即可以对该用户做视频渲染与显示操作 break; case YOUME_EVENT_OTHERS_VIDEO_OFF: //其他用户视频流断开 break; case YOUME_EVENT_OTHERS_CAMERA_PAUSE: //其他用户摄像头暂停 break; case YOUME_EVENT_OTHERS_CAMERA_RESUME: //其他用户摄像头恢复 break; case YOUME_EVENT_MASK_VIDEO_BY_OTHER_USER: //视频被其他用户屏蔽 break; case YOUME_EVENT_RESUME_VIDEO_BY_OTHER_USER: //视频被其他用户恢复 break; case YOUME_EVENT_MASK_VIDEO_FOR_USER: //屏蔽了谁的视频 break; case YOUME_EVENT_RESUME_VIDEO_FOR_USER: //恢复了谁的视频 break; case YOUME_EVENT_OTHERS_VIDEO_SHUT_DOWN: //其他用户视频断开 //包含以下情形：对方退出房间、对方网络不好、关闭了摄像头、屏蔽了对方的视频流 break; case YOUME_EVENT_MEDIA_DATA_ROAD_PASS: ///音视频数据通路连通，定时检测，一开始收到数据会收到PASS事件，之后变化的时候会发送 break; case YOUME_EVENT_MEDIA_DATA_ROAD_BLOCK: ///音视频数据通路不通 break; case YOUME_EVENT_QUERY_USERS_VIDEO_INFO: ///查询用户视频信息返回 break; case YOUME_EVENT_SET_USERS_VIDEO_INFO: ///设置用户接收视频信息返回 break; default: //"事件类型" + eventType + ",错误码" + break; } }
初始化
- 语法
YouMeErrorCode init(
const char* strAppKey,
const char* strAPPSecret,
YOUME_RTC_SERVER_REGION serverRegionId,
const char* strExtServerRegionName);-
功能
初始化语音引擎，做APP验证和资源初始化。 -
参数说明
strAPPKey：从游密申请到的 app key, 这个你们应用程序的唯一标识。
strAPPSecret：对应 strAPPKey 的私钥, 这个需要妥善保存，不要暴露给其他人。
serverRegionId：设置首选连接服务器的区域码，建议直接使用RTC_DEFAULT_SERVER。如果YOUME_RTC_SERVER_REGION定义的区域码不能满足要求，可以把这个参数设为 RTC_EXT_SERVER，然后通过后面的参数strExtServerRegionName 设置一个自定的区域值（如中国用 "cn" 或者 “ch"表示），然后把这个自定义的区域值同步给游密，我们将通过后台配置映射到最佳区域的服务器。
strExtServerRegionName：自定义的扩展的服务器区域名。不能为null，可为空字符串“”。只有前一个参数serverRegionId设为RTC_EXT_SERVER时，此参数才有效（否则都将当空字符串“”处理）。 -
返回值
返回YOUME_SUCCESS才会有异步回调通知。其它返回值请参考YouNeErrorCode类型定义。 -
异步回调
//涉及到的主要回调事件有：
// YOUME_EVENT_INIT_OK - 表明初始化成功
// YOUME_EVENT_INIT_FAILED - 表明初始化失败，最常见的失败原因是网络错误或者 AppKey-AppSecret 错误
void onEvent (const char* strParam);加入语音频道（单频道）
- 语法
YouMeErrorCode joinChannelSingleMode (const char* strUserID, const char* strChannelID, int userRole);-
功能
加入语音频道（单频道模式，每个时刻只能在一个语音频道里面）。 -
参数说明
strUserID：全局唯一的用户标识，全局指在当前应用程序的范围内。
strChannelID：全局唯一的频道标识，全局指在当前应用程序的范围内。
userRole：用户在语音频道里面的角色，见YouMeUserRole定义。 -
返回值
返回YOUME_SUCCESS才会有异步回调通知。其它返回值请参考YouNeErrorCode类型定义。 -
异步回调
//涉及到的主要回调事件有：
//YOUME_EVENT_JOIN_OK - 成功进入语音频道
//YOUME_EVENT_JOIN_FAILED - 进入语音频道失败，可能原因是网络或服务器有问题
void onEvent (const char* strParam);创建视频渲染
具体方法参见demo。
- 语法
int createRender(const char * userId);-
功能
根据用户ID创建渲染ID。 -
参数说明
userId：用户ID。 -
返回值
大于等于0时，为渲染ID；小于0则为错误码，具体的错误码请参考YouNeErrorCode类型定义。
打开摄像头
- 语法
YouMeErrorCode startCapture();-
功能
捕获本机摄像头数据，以便发送给房间内其他人。 -
返回值
如果成功则返回YOUME_SUCCESS，其它具体参见YouNeErrorCode类型定义。