Talk SDK for iOS 使用指南

适用范围

本文档适用于游密实时语音引擎（Talk SDK）Xcode开发环境下接入。

开发环境

在开始集成游密Video SDK 前，请确保开发环境满足以下要求：

Xcode 5.0 或以上版本
iOS 7.0 或以上版本且支持音频的 iOS 设备或模拟器（推荐使用真机）
iOS 设备已经连接到 Internet

SDK目录概述

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

include：SDK的头文件。重点介绍inlude下的需要使用到的重要文件。
- YMVoiceService.h封装了语音SDK的全部功能接口，集成方可通过[YMVoiceService getInstance]直接调用。
- VoiceEngineCallback.h包含需要实现的语音SDK的回调接口协议。
- YouMeConstDefine.h包含错误码定义等各类枚举类型定义。
lib：iOS库文件，包含libyoume_voice_engine.a文件和libYouMeCommon.a文件。

集成SDK

将SDK放置到xcode工程目录下（可视实际情况自行放置），如下图所示：
打开XCode工程，找到工程目录，新建一个文件夹（可命名为SDKInclude），然后将SDK下的include文件夹里的头文件都加入进来(右键点击选择“Add Files to ...”)。
添加库文件路径：Build Settings -> Search Paths -> Library Search Paths，直接将SDK的lib-ios文件夹拖到xcode需要填入的位置，自动生成路径。
添加头文件路径：Build Settings -> Search Paths -> Header Search Paths，直接将SDK的include文件夹拖到xcode该位置上，自动生成路径。

添加依赖库：在Build Phases -> Link Binary With Libraries下添加：

- 搜索添加以下库：
libc++.tbd
libsqlite3.0.tbd
libz.1.2.5.tbd
libresolv.9.tbd
SystemConfiguration.framework
CoreTelephony.framework
AVFoundation.framework
AudioToolBox.framework
CFNetwork.framework
- 在"Add Other"处选择YoumeTalkSDK-lib-ios文件夹，选择以下文件添加：
>libYouMeCommon.a  
>libyoume_voice_engine.a

为iOS10以上版本添加录音权限配置 iOS10系统使用录音权限，需要在target的info.plist中新加NSMicrophoneUsageDescription键，值为字符串如“语音通话需要录音权限”(授权弹窗出现时提示给用户)。首次录音时会向用户申请权限。配置方式如下(选择Private-Microphone Usage Description)：

接口调用基本流程

实现回调(参考api手册里面的实现回调) -> 初始化（initSDK）->收到初始化成功回调通知 0(0表示sdk初始化成功)->加入语音单频道（joinChannelSingleMode ）->收到加入频道成功回调通知 2（2表示进入语音频道成功）->打开麦克风（setMicrophoneMute （false））->收到麦克风已打开回调通知 29(29表示自己麦克风被打开)->打开扬声器（setSpeakerMute （false））->收到扬声器已打开回调通知 31（31表示自己扬声器被打开） ->设置音量（setVolume （70）（该音量建议70））->(到了前面一步已经可以和当前进入同一频道的人进行实时通话了)->使用其他接口 ->结束

接口调用示例

在新建的项目里的ViewController.m 文件里实现以下代码：

使用者要遵守协议VoiceEngineCallback并实现相关函数（回调函数）。回调都在子线程中执行，不能用于更新UI等耗时操作。

首先需要先引用相应的头文件：

#import "YMVoiceService.h"
#import "VoiceEngineCallback.h"

要遵守协议VoiceEngineCallback来注册回调事件,并监听实现回调事件：

@interface ViewController ()<VoiceEngineCallback>

@end

-(void)onYouMeEvent:(YouMeEvent_t)eventType errcode:(YouMeErrorCode_t)iErrorCode roomid:(NSString *)roomid param:(NSString *)param {
    switch (eventType)
    {
            //case案例只覆盖了部分，仅供参考，详情请查询枚举类型YouMeEvent
        case YOUME_EVENT_INIT_OK:
            [[YMVoiceService getInstance]joinChannelSingleMode:@"123" channelID:@"1001" userRole:1 checkRoomExist:false];
            //"初始化成功";
            break;
        case YOUME_EVENT_INIT_FAILED:
            // "初始化失败，错误码：" + errorCode;
            break;
        case YOUME_EVENT_JOIN_OK:
            [[YMVoiceService getInstance]setMicrophoneMute:false];
            [[YMVoiceService getInstance]setSpeakerMute:false];
            //"加入频道成功";
            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_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:
            //麦克风的语音级别，值把iErrorCode转为整形即是音量值
            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;
        default:
            //"事件类型" + eventType + ",错误码" +errcode
            break;
    }
}
//RestAPI回调
-(void)onRequestRestAPI: (int)requestID iErrorCode:(YouMeErrorCode_t) iErrorCode  query:(NSString*) strQuery  result:(NSString*) strResult {
}
//获取频道用户列表回调
-(void)onMemberChange:(NSString*) channelID changeList:(NSArray*) changeList isUpdate:(BOOL)isUpdate{
}

在ViewDidLoad 函数里实现SDK初始化：

    [[YMVoiceService getInstance]initSDK:self appkey:@"YOUME" appSecret:@"123456" regionId:RTC_CN_SERVER serverRegionName:@"cn"];

初始化成功之后调用joinChannelSingleMode方法进入语音频道,在收到YOUME_EVENT_INIT_OK之后调用。

  -(void) joinroom(){
    /**

      第一个参数是用户id  全局唯一的用户标识，全局指在当前应用程序的范围内
      第二个参数是房间id  全局唯一的频道标识，全局指在当前应用程序的范围内
      第三个参数，角色身份说明
       YOUME_USER_NONE = 0,         ///< 非法用户，调用API时不能传此参数
       YOUME_USER_TALKER_FREE = 1,      ///< 自由讲话者，适用于小组通话（建议小组成员数最多10个），每个人都可以随时讲话, 同一个时刻只能在一个语音频道里面
       YOUME_USER_TALKER_ON_DEMAND = 2, ///< 需要通过抢麦等请求麦克风权限之后才可以讲话，适用于较大的组或工会等（比如几十个人），同一个时刻只能有一个或几个人能讲话, 同一个时刻只能在一个语音频道里面
       YOUME_USER_LISTENER = 3,         ///< 听众，主播/指挥/嘉宾的听众，同一个时刻只能在一个语音频道里面，只听不讲
       YOUME_USER_COMMANDER = 4,        ///< 指挥，国家/帮派等的指挥官，同一个时刻只能在一个语音频道里面，可以随时讲话，可以播放战歌，戴耳机情况下可以监听自己语音
       YOUME_USER_HOST = 5,             ///< 主播，广播型语音频道的主持人，同一个时刻只能在一个语音频道里面，可以随时讲话，可以播放战歌，戴耳机情况下可以监听自己语音
       YOUME_USER_GUSET = 6,            ///< 嘉宾，主播或指挥邀请的连麦嘉宾，同一个时刻只能在一个语音频道里面， 可以随时讲话
        */
       [[YMVoiceService getInstance]joinChannelSingleMode:@"123" channelID:@"1001" userRole:1 checkRoomExist:false];
    }

当onEvent返回 YouMeEvent.YOUME_EVENT_JOIN_OK 的时候表示进入频道成功，此时打开麦克风和扬声器：

 [[YMVoiceService getInstance]setMicrophoneMute:false];
 [[YMVoiceService getInstance]setSpeakerMute:false];

当onEvent返回相应的回调 YouMeEvent.YOUME_EVENT_LOCAL_MIC_ON（自己麦克风能被打开），YouMeEvent.YOUME_EVENT_LOCAL_SPEAKER_ON（自己的扬声器打开），表示当前已经打开了麦克风和扬声器（注意需要给权限）。

到了这一步已经可以和另外的在当前频道的人进行对话了。

语音通话流程图

流程图

语音通话时序图

时序图

语音通话相关代码

初始化

实现消息回调(遵守协议VoiceEngineCallback并实现相关回调函数onYouMeEvent)

- (void)onYouMeEvent:(YouMeEvent_t)eventType errcode:(YouMeErrorCode_t)iErrorCode roomid:(NSString *)roomid param:(NSString *)param
{
    switch (eventType) //case案例只覆盖了部分，仅供参考，详情请查询枚举类型YouMeEvent_t
    {
        case YOUME_EVENT_INIT_OK:
            break;
        case YOUME_EVENT_INIT_FAILED:
            break;
        case YOUME_EVENT_JOIN_OK:
            break;
        case YOUME_EVENT_LEAVED_ALL:
            break;
        case YOUME_EVENT_JOIN_FAILED:    
            break;
        case YOUME_EVENT_LOCAL_MIC_ON:
            break;
        case YOUME_EVENT_LOCAL_MIC_OFF:
            break;
        case YOUME_EVENT_LOCAL_SPEAKER_ON:
            break;
        case YOUME_EVENT_LOCAL_SPEAKER_OFF:
            break;
        default:
            break;
    }
}

初始化Talk SDK：其中appKey和appSecret为在游密后台申请的App Key和App Secret。regionId：IM服务器区域，一般使用0即RTC_CN_SERVER表示中国，其余设置值可查看官网文档-服务器部署地区定义。

[[YMVoiceService getInstance] initSDK: self appkey:strAppKey
           appSecret:strAppSecret
            regionId:RTC_CN_SERVER
    serverRegionName:@"cn" ];

加入频道

onYouMeEvent收到初始化成功消息YOUME_EVENT_INIT_OK后：加入频道其中userID：用户标识，channelID：频道标识，userRole：用户在语音频道里面的角色，主要分为YOUME_USER_HOST（可以随时讲话和播放战歌等）、YOUME_USER_LISTENER（只听不讲）、YOUME_USER_TALKER_FREE（自由讲话者）等，详情见YouMeUserRole定义。

 [[YMVoiceService getInstance] joinChannelSingleMode:userID channelID:channelID userRole:YOUME_USER_TALKER_FREE];

开关音频设备

onYouMeEvent收到加入频道成功消息YOUME_EVENT_JOIN_OK后: 打开/关闭麦克风：其中mute为true表示关闭麦克风，false表示开启麦克风。

[[YMVoiceService getInstance] setMicrophoneMute:false];

打开/关闭扬声器：其中mute为true表示关闭麦克风，false表示开启麦克风。

[[YMVoiceService getInstance] setSpeakerMute:false];

设置音量(音量范围0-100，建议设置70比较适中)。

[[YMVoiceService getInstance] setVolume:70];

离开频道，反初始化

离开频道。

[[YMVoiceService getInstance] leaveChannelAll];

反初始化。

[[YMVoiceService getInstance] unInit];

语言

Talk-iOS

快速接入

使用指南

API手册

场景方案

状态码

常见问题

异常处理

服务器RestAPI