Video SDK for Cocos2d C++ 快速接入

适用范围

本规范仅适用于使用游密实时音视频引擎Cocos2d-x接口(C++接口)开发多人实时语音功能的开发者。

SDK目录概述

语音SDK中有两个子文件夹:lib、include,下面依次介绍下这两个子文件夹。

  1. include:SDK的头文件。 详细介绍下inlude,所有接口都在这个文件夹中。
    • IYouMeVoiceEngine.h封装了语音SDK的全部功能接口,集成方可通过IYouMeVoiceEngine::getInstance ()->…来调用语音SDK接口。
    • IYouMeEventCallback.h包含语音SDK的所有回调事件接口,例如初始化结果,频道加入成功等,都将通过此接口通知集成方。
    • YouMeConstDefine.h包含语音SDK的所有枚举类型定义,如错误码等。
  2. 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开发环境配置

  1. 修改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
    
  2. 如果需要显示指定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
    
  3. 复制youme_voice_engine/lib/android/youme_voice_engine.jar到proj.android/libs/ youme_voice_engine.jar。

  4. 修改proj.android/AndroidManifest.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.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
  5. 打开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开发环境配置

添加头文件和依赖库:

  1. 添加头文件路径:在Build Settings -> Search Paths -> Header Search Paths中添加../youme_voice_engine/include (建议直接将此include文件夹拖到xcode需要填入的位置,然后路径会自动生成)。
  2. 添加库文件路径:在Build Settings -> Search Paths -> Library Search Paths中添加../youme_voice_engine/lib/ios/Release-universal (建议直接将此Release-universal文件夹拖到xcode需要填入的位置,然后路径会自动生成)。
  3. 添加依赖库:在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开发环境配置

  1. youme_voice_engine复制到Cocos2d-x开发工具生成的游戏目录根目录下

  2. 在项目 -> 属性 -> C/C++ -> 常规 -> 附加包含目录 中添加..\youme_voice_engine\include

  3. youme_voice_engine/lib目录下的dll到执行目录(如果是64位机器,使用youme_voice_engine/lib/x64)。

  4. 在项目->属性->链接器->输入->附加依赖库 中添加 youme_voice_engine.lib

视频关键接口流程

  1. 在收到YOUME_EVENT_JOIN_OK事件后,
    注册视频回调:api.SetVideoCallback();
    控制自己的摄像头打开:api.StartCapturer();
    控制自己的摄像头关闭:api.StopCapturer();
  2. 以上步骤完成,如果自己或者远端有视频流过来,会通知 YOUME_EVENT_OTHERS_VIDEO_ON 事件,在该事件里绑定视频流和渲染组件 VideoRenderer.getInstance().addRender(String userId, SurfaceViewRenderer view);
  3. 其它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下必须实现以下方法:

    
    //监听各类回调事件
    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,后面确定时通过 SetServerRegion 设置。如果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类型定义