## 产品概述
图灵机器人SDK IOS 版是运行在IOS系统上的语音识别、语义理解及语音合成一体化解决方案，基于该方案，开发者可以轻松构建功能完备、交互性强的语音识别和语义理解应用程序，而且如果只使用语义理解引擎也是可以的。
#### 概念解释
（1）语音识别：Automatic Speech Recognition（ASR），也称自动语音识别，其目标是将人类的语音中的词汇内容转换相应的文本。
（2）自然语言理解：Natural Language Understanding（NLU），俗称人机对话，是人工智能的分支学科。本学科通过电子计算机模拟人的语言交际过程，从而使计算机能理解和运用人类社会的自然语言，实现人机之间的自然语言通信，进而代替人的部分脑力劳动，包括查询资料、解答问题、摘录文献、汇编资料以及一切有关自然语言信息的加工处理。
#### 功能介绍
（1）语音识别：将语音识别成相应的文本。
（2）语义理解：将文本识别成领域相关的语义结果。
（3）语音合成 : 将文本转化成语音读出。
#### 应用场景
（1）产品需要流畅自然的中文聊天能力。我们提供精准的语义分析，可正确识别用户意图；支持多种上下文结构，满足连续对话和多重对话的需要。
（2）产品需要自定义语义库。支持可自定义的NLP智能知识库系统，满足用户特殊语义处理需求。
（3）产品需要广泛的知识库。支持上百个使用场景功能，以及丰富的百科知识。
## 使用说明
#### 适用环境
网络:支持 NET、Wifi 网络环境
#### 支持版本
系统:支持 iOS 5.0 及以上系统
#### 兼容性
架构:armv7、armv7s、arm64、i386、x86_64；
机型:iPhone 4+,iPad 2+和 iPod 5+；
硬件要求:需要有麦克风,用于支持语音录入
#### 开发包说明
| 文件名称 | 用途 |
| --- | --- |
| TRRTuringAPI.h | 图灵SDK API的通用头文件 |
| TRRTuringAPIConfig.h | 图灵SDK API的配置工具类头文件 |
| TRRTuringRequestManager.h | 图灵SDK API的请求管理器头文件 |
| TRRVoiceRecognitionManager.h | 图灵SDK的语音识别管理器头文件 |
| TRRSpeechSythesizer.h | 图灵SDK的语音合成管理器头文件 |
| BDVoiceRecognitionClient.h | 百度语音识别功能头文件 |
| libTuringSDK.a | 图灵SDK的静态链接库文件 |
| Localizable.strings | 语音识别接口的字符本地化文件（中文简体） |
#### 集成指南
###### 使用条件
（1）使用图灵开放API SDK，需要注册图灵API开发者帐号，在个人中心的“我的机器人》机器人详情》接入”页获取图灵APIKEY。
（2）由于语音识别和语音合成接口底层会调用Baidu相关接口。因此使用图灵IOS SDK，需 要开发者提前获取Baidu开发者帐号，并创建应用，获得AppID、APIKey、Secret Key。具体请参考http://yuyin.baidu.com/
###### 框架依赖
以下9个是本SDK可能用到的Framework，部分依赖关系来自于BaiduSDK。
~~~
1. SystemConfiguration.framework
2. Foundation.framework
3. AVFoundation.framework
4. GLKit.framework
5. OpenGLES.framework
6. libz.1.dylib
7. Security.framework
8. CFNetwork.framework
9. CoreLocation.framework
~~~
###### 第三方库
IOS SDK依赖以下第三方库（SDK包中已提供，请集成到应用工程中）
1.OpenUDID
2.JSONKit
3.TTTAttributedLabel
4.CoreAudioUtility(苹果Audio库)
对于采用ARC内存管理方式的工程，需要利用Non-ARC方式表姨OpenUDID和JSONKit（对相应文件添加CompilerFlags为-fno-objc-arc）
###### 其他集成准备事项
因为SDK包中采用Objective C++实现，因此需要保证工程中引用静态库头文件的实现文件的扩展名必须为.mm。
###### IOS9适配事项
（1）HTTP访问
IOS9系统默认使用HTTPS网络协议。由于百度和图灵SDK目前都只采用HTTP协议，因 此基于图灵SDK的应用程序也要允许HTTP访问。
~~~
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
~~~
（2）BITCODE问题由于底层的百度SDK编译时采用ENABLE_BITCODE模式，因此基于图灵SDK的应用程序也不能采用ENABLE_BITCODE模式
#### 语义理解
###### 获取语义理解设置对象
图灵API使用需要APIKEY（注册激活图灵帐号获取）和UserID（由SDK根据用户信息生成）。TRRTuringAPIConfig类会协助用户获得这两个属性，用来完成图灵API的设置
1. 利用图灵API KEY初始化TRRTuringAPIConfig对象。
~~~
- (instancetype)initWithAPIKey:(NSString *)apikey;
~~~
2. 该初始化过程中，SDK将读取本地是否缓存了UserID信息。用户可以检查 TRRTuringAPIConfig对象的UserID属性，如UserID等于nil，用户需要调用以下接口，联网获取UserID
~~~
- (void)request_UserIDwithSuccessBlock:(SuccessStringBlock)success failBlock:(FailBlock)failed;
~~~
由于联网获取UserID是异步操作，用户可以通过设置参数success和failed两个Block， 来处理操作成功和失败场景。 其中success Block的参数是成功获得的UserID，failed Block的参数是API失败类型，或相关信息字符串。>
###### 使用语义理解接口
1.首先要获得TRRTuringAPIConfig对象，并用该对象完成语义分析接口的设置；
~~~
- (instancetype)initWithConfig:(TRRTuringAPIConfig *)config;
~~~
2.调用语义分析接口
~~~
- (void)request_OpenAPIWithInfo:(NSString *)info successBlock: (SuccessDictBlock)success failBlock:(FailBlock)failed;
~~~
由于语义分析接口是异步操作，用户可以通过设置参数success和failed两个Block，来 处理操作成功和失败场景。其中success Block的参数是语义分析接口返回的JSON数 据转换成的Dictionary类型，failedBlock的参数是API失败类型，或相关信息字符串。
代码示例如下:
~~~
//初始化TRRTuringAPIConfig对象
TRRTuringAPIConfig *apiConfig ＝ [[TRRTuringAPIConfig alloc]initWithAPIKey:@"TuringApiKey"];
TRRTuringRequestManager apiRequest = [[TRRTuringRequestManager alloc] initWithConfig:apiConfig];
//如userID==nil,需要调⽤用request_UserIDwithSuccessBlock:failBlock:接⼝口获
取UserID
if (apiConfig.userID == nil) {
[apiConfig request_UserIDwithSuccessBlock:^(NSString *str) {
//获取UserID成功，继续调用OpenAPI接⼝
[apiRequest request_OpenAPIWithInfo:self.inputTextView.text successBlock:^(NSDictionary *dict) {
//处理语义分析接口的返回结果
_outputTextView.text = [dict objectForKey:@"text"];
} failBlock:^(TRRAPIErrorType errorType, NSString
*infoStr) {
//处理语义分析失败结果
_outputTextView.text = infoStr;
}];
}
failBlock:^(TRRAPIErrorType errorType, NSString *infoStr) {
//处理获取UserID失败的场景
_outputTextView.text = infoStr;
NSLog(@"erroresult = %@", infoStr);
}];
} else {
//如本地缓存了UserID，则直接调用OpenAPI接⼝
[apiRequest request_OpenAPIWithInfo:self.inputTextView.text successBlock:^(NSDictionary *dict) {
NSLog(@"apiResult =%@",dict);
_outputTextView.text = [dict objectForKey:@"text"];
} failBlock:^(TRRAPIErrorType errorType, NSString
*infoStr) {
_outputTextView.text = infoStr;
NSLog(@"errorinfo = %@", infoStr);
}];
}
~~~
#### 语音合成
图灵语音合成API底层会调用Baidu语音合成API，因此使用图灵SDK时需要获得Baidu语音合成API所需的APIKEY和SecretKey。
###### 初始化语音合成对象
初始化语音合成对象，并设置APIKEY和SecretKey。
~~~
- (instancetype)initWithAPIKey:(NSString *)apikey secretKey:(NSString*)secretkey;
~~~
###### 设置语音合成参数
通过以下接口设置语音合成参数，参数Key-Value取值参考Baidu SDK中的 BDSSpeechSynthesizer.h文件。
~~~
- (int)setParamForKey:(NSString *)key value:(NSString *)value;
~~~
如果不进行参数设置，图灵SDK将采用默认的参数进行语音合成，默认参数如下
（1）文本编码，默认编码类型为UTF8;
（2）发音人，默认为女声；
（3）发音音量、语速、音调采取［0-9］的中间值5；
（4）音频格式，默认为amr；
（5）音频比特率，默认为15.85k比特率；
###### 控制语音合成操作
利用以下接口可以完成语音合成操作的开始、暂停、恢复、停止等操作。除停止操作外，其他 三个操作都会返回int类型的返回值，其错误值含义请参考BDSSpeechSynthesizer.h文件
~~~
- (int)start:(NSString *)text;
- (int)pause;
- (int)resume;
- (void)stop;
~~~
#### 语音识别
图灵语音识别API底层会调用Baidu语音识别API，因此使用图灵SDK时需要获得Baidu语音识别API所需的APIKEY和Secret Key。
###### 获取语音识别单例句柄
语音识别结果为单例实现，在使用过程中可以调用以下接口获得单例句柄：
~~~
+ (TRRVoiceRecognitionManager *)sharedInstance;
~~~
###### 获取语音识别单例句柄
~~~
- ( void)setApiKey:(NSString *)apiKey secretKey:(NSString *)secretKey;
~~~
###### 控制语音识别操作
通过以下接口可以完成对语音识别操作的启动、关闭和取消功能
~~~
//启动语音识别操作, 返回值参考BDVoiceRecognitionClient.h中
TVoiceRecognitionStartWorkResult
- (int)startVoiceRecognition;
//停止语音识别操作，代表手动触发用户发音结束事件
- (void)stopRecognize;
//取消正在进行的语音识别操作
- (void)cancleRecognize;
~~~
###### 通过Delegate接收语音识别结果
~~~
通过实现TRRVoiceRecognitionManagerDelegate协议，应用程序可以接收语音识别的结果信息，包括正确的结果信息和发生错误时的错误信息。通过实现TRRVoiceRecognitionManagerDelegate协议，开发人员可以捕获识别引擎开始工作，检测到用户已说话，检测到用户已停止说话等事件。
@protocol TRRVoiceRecognitionManagerDelegate
<MVoiceRecognitionClientDelegate>
//接收语音识别结果的代理函数
- (void)onRecognitionResult:(NSString *)result;
//接收语音识别错误信息的代理函数。
- (void)onRecognitionError:(NSString *)errStr;
//已启动语音识别的事件处理函数。
- (void)onStartRecognize;
//检测到用户已说话的事件处理函数。
- (void)onSpeechStart;
//检测到用户已停止说话的事件代理函数。
- (void)onSpeechEnd;
@end
开发人员需要操作TRRVoiceRecognitionManager对象的属性delegate来设置代理
@property (nonatomic, weak) id delegate;
~~~
###### 设置语音识别参数
~~~
//获取采样速率信息
- (int)getCurrentSampleRate;
// 获取当前音量级别
- (int)getCurrentDBLevelMeter;
//当前识别类型数组，参见BDVoiceRecognitionClient.h
@property (nonatomic, strong) NSArray *recognitionPropertyList;
//设置城市信息
- (void)setCityID: (NSInteger)cityID;
//进行功能设置，具体参数及取值参考BDVoiceRecognitionClient.h
- (void)setConfig:(NSString *)key withFlag:(BOOL)flag;
//设置识别语言，具体参数及取值参考BDVoiceRecognitionClient.h
- (void)setLanguage:(int)language;
//关闭标点
- (void)disablePuncs:(BOOL)flag;
//设置是否需要对录音数据进行端点检测
- (void)setNeedVadFlag: (BOOL)flag;
//设置是否需要对录音数据进行压缩
- (void)setNeedCompressFlag: (BOOL)flag;
~~~
