CloudVoice语音直播iOS SDK集成说明书

文档编号：17002B2-DD6-1
版权所有 CloudVoice技术部

版权申明
本文档包含了来自CloudVoice的机密技术和商业信息，这些信息作为CloudVoice专用。接受本文档即视为表示同意对其内容保密，并且未经CloudVoice书面许可，不得复制、泄露或散布本文档的全部或部分内容。
本文档及其描述的内容及产品的著作权和版权受有关法律保护，对本文档内容的任何形式的非法复制，泄露或散布，将导致承担相应的法律责任。
CloudVoice保留在不另行通知的情况下修改本文档的权利，并保留对本文档内容的全部解释权。
“CLOUDVOICE”标识是CloudVoice的注册商标。
 
This document contains confidential technical and commercial information from CLOUDVOICE Co., Ltd, and is intended for the use of Customers or CLOUDVOICE’s partners only for the purposes of related projects to CLOUDVOICE. No part of it may be reproduced or transmitted in any form or means without the written permission of CLOUDVOICE.
This document and the product it describes are protected by copyright according to the applicable laws.
The information in this document is subject to change without notice and describes only the product defined in the introduction of this documentation. CLOUDVOICE will, if necessary, explain issues, which may not be covered by the document.
“CLOUDVOICE” logo is a registered trademark of CLOUDVOICE Co., Ltd.

修订历史

版本差异

1.概述 ( Overview )

1.1 范围 ( Scope )

定义CloudVoice语音直播iOS SDK 客户端集成接口。

1.2 发布 ( Issue )

本文档发布于CloudVoice技术部技术部、产品部及此项目合作公司相关人员。本文档不属于客户契约性文档，不能发布予客户。

1.3 综述 ( Brief )

2.定义 ( Definition )

2.1 术语 ( Terminologies )

表格 1    术语表

2.2 约束 ( Constraints )

3.运行环境

iOS 7.0及以上、真机环境

4. 集成步骤（必读）

4.1 申请appId

（1）向CloudVoice申请appId，否则使用会失效；

4.2 导入CloudVoiceVLSDK文件夹

将压缩包根目录下的文件夹：CloudVoiceVLSDK文件夹拖入到您的工程文件夹下，里面含有libCloudVoiceVLSDK.a静态库（含基本的语音直播，文字聊天功能）及include文件夹的头文件(CloudVoiceVLSDK.h，CloudVoiceVLProtocol.h），拖到工程中后弹出以下对话框，勾选”Copy items if needed”，与“Create groups”单选按钮组并点击“Finish“按钮, 如图：

4.3 添加引用库

在需要导入的framework，tdb，a请不要重复添加
最终效果图如下：

4.3.1 编译设置

（1）由于SDK 静态库内部有Category  所以需要设置：
Build Settings->other linker flags 设置   -ObjC（区分大小写）

（2）注：由于声音录制只支持真机，故测试语音直播效果需要使用真机设备调试！

4.4 使用说明(必读)

在objective-C 下使用SDK接口，在任何地方引用SDK，只需要包含CloudVoiceVLSDK.h、和CloudVoiceVLProtocol.h（模型）头文件，并遵循相应的监听回调协议(CloudVoiceVLSDKDelegate)即可。
所有所有登录，退出，发送消息，开始直播，结束直播接口均通过[CloudVoiceVLSDK  shareInstance]对象来操作，所需用到模型全部在CloudVoiceVLProtocol.h里。
代码示例:
[[CloudVoiceVLSDK  shareInstance] addDelegate:self];
[[CloudVoiceVLSDK  shareInstance] userLoginWith:req];
如果不再使用请切记清除代理实例，避免在回调发生时实例已经不存在而已产生致命错误，在ARC开启时，这个引用会导致实例无法自动销毁，一般在- (void) viewWillDisappear:(BOOL)animated里销毁
代码示例:
[[CloudVoiceVLSDK  shareInstance] removeDelegate:self];
简单介绍下各个主要文件的作用：
CloudVoiceVLSDK.h文件中主要是初始化，开始语音直播等功能接口
CloudVoiceVLProtocol.h文件含有所有需要使用到的model

5.CloudVoiceVLSDK  接口设计

注：本SDK接口都是使用单例模式调用

5.1 单例接口

5.1.1 调用接口

+ (instancetype)shareInstance;
代码示例:
[CloudVoiceVLSDK  shareInstance];

5.1.2 回应结果

返回接口实例（单例模式）,建议cp首先设置代理,然后初始化，登录，再调用其他接口。
代码示例:
[[CloudVoiceVLSDK  shareInstance] addDelegate:self];

5.2 设置日志级别

5.2.1 功能

SDK内置的日志打印，为的是如果SDK有问题，可用打开日志看一下SDK内部打印。不设置默认是关闭的。

5.2.2 调用接口

- (void)setLogLevel:(int)logLevel;

代码示例
[[CloudVoiceVLSDK  shareInstance] setLogLevel:0];

5.3 初始化设置

5.3.1 功能

SDK的初始化非常重要，请准确填写您的appId以及运行环境。appId是由用户提供 游戏名称、包名和公司名称给CloudVoice后，CloudVoice会分配一个唯一的appId来标示这个APP应用 Demo的appId为100000.运行环境分为测试环境和正式环境两种，测试环只是为境了把业务的逻辑全测试通过，发布版本要选为正式环境。
注意：初始化只需调用一次。请勿重复初始化。

5.3.2 调用接口

*- (void)initWithAppId:(NSString )appId isTest:(BOOL)isTest audioType:(CloudVoiceVLSDKAudioType)audioType;

** 代码示例:
[[CloudVoiceVLSDK sharedInstance] initWithAppId:@“100000” isTest:NO audioType:CloudVoiceVLSDKAudioType_OPUS]; **

5.4 登录帐号

5.4.1 调用登录接口

-(void)userLoginWith:(CloudVoiceVLLiveUserLoginReq)voiceLiveUserLoginReq;*

代码示例:
CloudVoiceVLLiveUserLoginReq *voiceLiveUserLoginReq= [[CloudVoiceVLLiveUserLoginReqalloc] init];
voiceLiveUserLoginReq.appId = @”100000”;//此处填写申请的应用编号
voiceLiveUserLoginReq.roomId = @”100000”;//此处填写房间编号
   voiceLiveUserLoginReq.userId = @”100000”;//此处填写用户编号
   voiceLiveUserLoginReq.type = @”0”;//此处填写用户类型0为观众 1为主播
   voiceLiveUserLoginReq.ext = @””;//此处填写扩展字段，可放空
voiceLiveUserLoginReq.nickname = @”我是大帅哥”;//用户昵称
[[CloudVoiceVLSDK  sharedInstance] userLoginWith:voiceLiveUserLoginReq];//发起登录请求

5.4.2 登录接口回调

-(void)voiceSDK :(CloudVoiceVLSDK )voiceSDK didLoadUserLoginResp:(CloudVoiceVLRoomLoginResp)voiceLiveUserLoginResp
CloudVoiceVLUserLoginResp是一个模型共有2个字段。

代码示例:
- (void)voiceSDK:(CloudVoiceVLSDK  )voiceSDK didLoadUserLoginResp:(CloudVoiceVLRoomLoginResp)voiceLiveUserLoginResp
{
   if (voiceLiveUserLoginResp.result == 0)//登录成功
   {
       //登录成功，可以进行登录房间的操作
   }
   else//登录失败
   {
       //登录失败，请重新验证
}
if (voiceLiveRoomLoginResp.anchorOnlive == 1)
{
   [CloudVoiceVLProgressHud showTextHUDMaintain2Seccond:@“主播当前离线”];
}
else if (voiceLiveRoomLoginResp.anchorOnlive == 0)
{
   [CloudVoiceVLProgressHud showTextHUDMaintain2Seccond:@“主播当前在线”];
}
}   

5.5 语音直播

5.5.1 调用发送文字消息接口

-(void)sendMessageWith:(CloudVoiceVLRoomSendRoomMsgReq *)voiceLiveRoomSendRoomMsgReq;
CloudVoiceVLRoomSendRoomMsgReq是一个模型，共5个字段。

代码示例:
   CloudVoiceVLRoomSendRoomMsgReq *voiceLiveRoomSendRoomMsgReq = [[CloudVoiceVLRoomSendRoomMsgReq alloc] init];
 
   voiceLiveRoomSendRoomMsgReq.msg_type = @“1”;
   voiceLiveRoomSendRoomMsgReq.payload = @”消息内容”;
   voiceLiveRoomSendRoomMsgReq.ext = @“”;
   voiceLiveRoomSendRoomMsgReq.ext2 = @“”;
 
   [[CloudVoiceVLSDK  sharedInstance] sendMessageWith:voiceLiveRoomSendRoomMsgReq];

5.5.2 发送文字消息回应

- (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomSendMsgResp:(CloudVoiceVLRoomSendMsgResp *)voiceLiveRoomSendMsgResp;
CloudVoiceVLRoomSendRoomMsgReq是一个模型，共5个字段。

代码示例:
- (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomSendMsgResp:(CloudVoiceVLRoomSendMsgResp *)voiceLiveRoomSendMsgResp
{
   if (voiceLiveRoomSendMsgResp.result == 0)
   {
       NSLog(@“消息发送成功”);
   }
   else
   {
       NSLog(@“消息发送失败”);
   }
}

5.5.3 收到文字消息

- (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomReceiveMsg:(CloudVoiceVLRoomReceiveMsg *)voiceLiveRoomReceiveMsg;
CloudVoiceVLRoomReceiveMsg是一个模型，共9个字段。

5.5.4 获取房间在线人数接口

• (void)getVoiceRoomUserCount;
  代码示例:
  [[CloudVoiceVLSDK  sharedInstance] getVoiceRoomUserCount];

5.5.5 获取房间在线人数接口回调

• (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomGetRoomCountResp:(CloudVoiceVLRoomGetRoomCountResp *)voiceLiveRoomGetRoomCountResp;
  CloudVoiceVLRoomGetRoomCountResp是一个模型，共3个字段。

5.5.6 开启语音直播声音

• (void)openVoice;

5.5.7 关闭语音直播声音

• (void)pasueVoice;

5.5.8 麦操作

• (void)micActionWithTargetId:(NSString *)targetId msgType:(CloudVoiceVLSDK MicActionType)msgType ext:(NSString *)ext;

代码示例:
[[CloudVoiceVLSDK  sharedInstance] micActionWithTargetId:model.userId msgType: CloudVoiceVLSDK MicActionType_Up
ext:nil];

5.5.9 麦操作回调

• (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomMicAction:(int)result msg:(NSString *)msg;

5.5.10 回复连麦申请

-(void)micActionResultWithMicActionResultModel:(CloudVoiceVLRoomReceiveMicActionResultNotify *)model;
CloudVoiceVLRoomReceiveMicActionResultNotify 是一个模型，共3个字段。

代码示例:
 CloudVoiceVLRoomReceiveMicActionResultNotify *model = [[CloudVoiceVLRoomReceiveMicActionResultNotify alloc] init];
           model.userId = “100000”;
           model.resType = 0;
           model.nickname = “大帅哥”;
[[CloudVoiceVLSDK  sharedInstance] micActionResultWithMicActionResultModel:model];

5.5.11 查询连麦用户/申请列表

• (void)micQueryWithMsgType:(CloudVoiceVLSDK MicQueryType)msgType;

代码示例:
[[CloudVoiceVLSDK  sharedInstance] micQueryWithMsgType: CloudVoiceVLSDK MicQueryType_UserMic
];

5.5.12 打开某个用户的声音

• (void)openVoiceWithUserId:(NSString *)userId;

代码示例:
[[CloudVoiceVLSDK  sharedInstance] openVoiceWithUserId:”100000”];

5.5.13 暂停某个用户的声音

• (void)pasueVoiceWithUserId:(NSString *)userId;

代码示例:
[[CloudVoiceVLSDK  sharedInstance] pasueVoiceWithUserId:”100000”];

5.5.14 接收到麦操作的通知

• (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomReceiveMicActionResultNotify:(CloudVoiceVLRoomReceiveMicActionResultNotify *)notify;
  CloudVoiceVLRoomReceiveMicActionResultNotify 是一个模型，共3个字段。

5.5.15 操作麦回复的通知

• (void)voiceSDK:(CloudVoiceVLSDK  *)voiceSDK didLoadLiveRoomReceiveMicActionResultNotify:(CloudVoiceVLRoomReceiveMicActionResultNotify *)notify;
  CloudVoiceVLRoomReceiveMicActionResultNotify是一个模型，共3个字段。

5.5.16 音量等级的通知

• (void)voiceSDK:(CloudVoiceVLSDK *)voiceSDK didLoadAudioVolumeIndication:(int)lever userId:(NSString *)userId

5.5.17 初始化音频文件地址

• (void)initAudioFileWithPaths:(NSArray <NSString >)paths

代码示例:
[[CloudVoiceVLSDK  sharedInstance] initAudioFileWithPaths:@[]];

5.5.18 播放音频

• (void)play

5.5.19 暂停音频

• (void)pause

5.5.20 停止音频

• (void)stop

5.5.21 播放下一首音频

• (void)next

5.5.22 获取音频列表文件名称

• (NSArray<NSString *> *)getAudioFileNameList

5.5.23 设置音频播放

• (void)setPlayAudioWithIndex:(int)index

代码示例:
[[CloudVoiceVLSDK  sharedInstance] setPlayAudioWithIndex:0];

5.5.24 音频播放时间戳回调

• (void)setAudioPlayerSliderBlock:(void (^)(NSTimeInterval duration,NSTimeInterval currentTime))block

代码示例:
[[CloudVoiceVLSDK  sharedInstance] setAudioPlayerSliderBlock: block];

5.5.25 其他相关功能请看Demo

6.附录 ( Appendices )

6.1 类属性说明

CloudVoiceVLProtocol类属性说明

6.2 文档绑定

表格 2    文档绑定关系表

6.3 注意事项