iOS SDK 文档
1、简介
语音评测（Speech Evaluator）通过智能语音技术自动对发音水平进行评价、发音错误、缺陷进行定位和问题分析。目前评音评测提供汉语、英语两种语言的评测，支持单字（汉语专有）、词语、句子、篇章朗读等题型。
评测详细的接口介绍及说明请参考： MSC iOS API 文档 , 在集成过程中如有疑问，可登录讯飞开放平台论坛 ，查找答案或与其他开发者交流。
语音评测（普通版）已下线，老用户请查看语音评测（普通版） ，并请老用户尽快迁移至语音评测（流式版），迁移方式如下：
需指定参数，中文：sub=ise,ent=cn_vip,plev=0，英文：sub=ise,ent=en_vip,plev=0，详见参数说明
#2、SDK集成指南
#第一步：获取appid
appid是第三方应用集成讯飞开放平台SDK的身份标识，SDK静态库和appid是绑定的，每款应用必须保持唯一，否则会出现10407错误码。appid在开放平台申请应用时可以获得，下载SDK后可从SDK中sample文件夹的Demo工程里找到（例如: /sample/MSCDemo/MSCDemo/Definition.h 的APPID_VALUE）。
#第二步：工程配置
#添加库
将开发工具包中lib目录下的iflyMSC.framework添加到工程中。同时请将Demo中依赖的其他库也添加到工程中。 按下图示例添加 SDK 所需要的 iOS系统库：
| 库名称 | 添加范围 | 功能 |
|---|---|---|
| iflyMSC.framework | 必要 | 讯飞开放平台静态库。 |
| libz.tbd | 必要 | 用于压缩、加密算法。 |
| AVFoundation.framework | 必要 | 用于系统录音和播放 。 |
| SystemConfiguration.framework | 系统库 | 用于系统设置。 |
| Foundation.framework | 必要 | 基本库。 |
| CoreTelephony.framework | 必要 | 用于电话相关操作。 |
| AudioToolbox.framework | 必要 | 用于系统录音和播放。 |
| UIKit.framework | 必要 | 用于界面显示。 |
| CoreLocation.framework | 必要 | 用于定位。 |
| Contacts.framework | 必要 | 用于联系人。 |
| AddressBook.framework | 必要 | 用于联系人。 |
| QuartzCore.framework | 必要 | 用于界面显示。 |
| CoreGraphics.framework | 必要 | 用于界面显示。 |
| libc++.tbd | 必要 | 用于支持C++。 |
注意：
- 添加iflyMSC.framework时，请检查工程BuildSetting中的framwork path的设置，如果出现找不到framework的情况，可以将path清空，在Xcode中删除framework，然后重新添加。
- iflyMSC.framework最低支持iOS 8.0。
#设置Bitcode
在Xcode 7,8默认开启了Bitcode，而Bitcode 需要工程依赖的所有类库同时支持。MSC SDK暂时还不支持Bitcode，可以先临时关闭。后续MSC SDK支持Bitcode 时，会在讯飞开放平台上进行SDK版本更新，请关注。关闭此设置，只需在Targets - Build Settings 中搜索Bitcode 即可，找到相应选项，设置为NO。
#用户隐私权限配置
iOS 10发布以来，苹果为了用户信息安全，加入隐私权限设置机制，让用户来选择是否允许。 隐私权限配置可在info.plist 新增相关privacy字段，MSC SDK中需要用到的权限主要包括麦克风权限、联系人权限和地理位置权限：
<key>NSMicrophoneUsageDescription</key>
<string></string>
<key>NSLocationUsageDescription</key>
<string></string>
<key>NSLocationAlwaysUsageDescription</key>
<string></string>
<key>NSContactsUsageDescription</key>
<string></string>
即在Info.plist 中增加下图设置：
#第三步：初始化
初始化示例：
//Appid是应用的身份信息，具有唯一性，初始化时必须要传入Appid。
NSString *initString = [[NSString alloc] initWithFormat:@"appid=%@", @"YourAppid"];
[IFlySpeechUtility createUtility:initString];
| 参数 | 说明 | 必填 |
|---|---|---|
| appid | 8位16进制数字字符串，应用的唯一标识，与下载的SDK一一对应。 | 是 |
| usr | 保留字段，无需关注。 | 否 |
| pwd | 保留字段，无需关注。 | 否 |
注意： 初始化是一个异步过程，可放在App启动时执行初始化，具体代码可以参照Demo的MSCAppDelegate.m。
#第四步：启动服务
所有的服务皆遵循如下的流程，如下图：
所有服务的API详细说明可参见：https://www.xfyun.cn/doc/mscapi/iOS/iosevaluator.html
#3.语音评测
#1.评测
// 获取评测对象单例
_iFlySpeechEvaluator = [IFlySpeechEvaluator sharedInstance];
_iFlySpeechEvaluator.delegate = self;
// 设置训练参数
// 清空参数
[_iFlySpeechEvaluator setParameter:@"" forKey:[IFlySpeechConstant PARAMS]];
// 设置评测采样率
[self.iFlySpeechEvaluator setParameter:@"16000" forKey:[IFlySpeechConstant SAMPLE_RATE]];
// 设置评测题目结果格式，目前仅支持xml
[self.iFlySpeechEvaluator setParameter:@"xml" forKey:[IFlySpeechConstant ISE_RESULT_TYPE]];
// 设置评测题型
[self.iFlySpeechEvaluator setParameter:self.iseParams.category forKey:[IFlySpeechConstant ISE_CATEGORY]];
// 设置评测语言
[self.iFlySpeechEvaluator setParameter:self.iseParams.language
forKey:[IFlySpeechConstant LANGUAGE]];
// 设置评测结果级别
[self.iFlySpeechEvaluator setParameter:self.iseParams.rstLevel forKey:[IFlySpeechConstant ISE_RESULT_LEVEL]];
// 设置评测超时
[self.iFlySpeechEvaluator setParameter:self.iseParams.timeout forKey:[IFlySpeechConstant SPEECH_TIMEOUT]];
可通过setParameter设置的评测相关参数说明如下：
| 参数 | 说明 | 是否必需 |
|---|---|---|
| sub | 服务类型指定 ise(开放评测) | 是 |
| ent | 中文：cn_vip 英文：en_vip | 是 |
| category | 评测题型，可选值： read_syllable（单字，汉语专有） read_word（词语 read_sentence（句子） read_chapter（篇章）等 | 是 |
| plev | 全维度及纠错功能，可选值：0（给出全部信息，汉语包含rec_node_type、perr_msg、fluency_score、phone_score等信息的返回；英文包含accuracy_score、serr_msg、 syll_accent、fluency_score、standard_score、pitch等信息的返回） | 是 |
| ISE_RESULT_LEVEL | 评测结果等级 完整：complete（默认值） 精简：plain（评测返回结果将只有总分） | 否 |
实现协议：
//语音评测实现Delegate
// 音量和数据回调
- (void)onVolumeChanged:(int)volume buffer:(NSData *)buffer{}
// 开始录音回调
- (void)onBeginOfSpeech{}
// 停止录音回调
- (void)onEndOfSpeech{}
// 会话取消回调
- (void)onCancel{}
// 评测错误回调
- (void)onCompleted:(IFlySpeechError *)errorCode{}
// 评测结果回调
- (void)onResults:(NSData *)results isLast:(BOOL)isLast{}
#2.音频流评测
音频流评测功能可以让开发者将已录制好的音频数据写入评测控件，最后得到评测结果。
//设置音频源为音频流（-1）
[self.iFlySpeechEvaluatorr setParameter:@"-1" forKey:@"audio_source"];
//启动评测服务
[self.iFlySpeechEvaluator startListening：buffer params:nil];
//写入音频数据
NSData *data = [NSData dataWithContentsOfFile:_pcmFilePath]; //从文件中读取音频
[self.iFlySpeechEvaluator writeAudio:data];//写入音频，让SDK评测。建议将音频数据分段写入。
//音频写入结束或出错时，必须调用结束评测接口
[self.iFlySpeechEvaluator stopListening];//音频数据写入完成，进入等待状态
tartListening即开始评测录音，读完试题内容后可以调用 stopListening停止录音，也可以在一段时间后由SDK自动检测VAD并停止录音。当评测出错时，SDK会回调onError方法抛出IFlySpeechError 错误，通过IFlySpeechError的getErrorCode()方法可获得错误码，错误码列表和下表：
| 错误码 | 数值 | 含义 |
|---|---|---|
| MSP_ERROR_ASE_EXCEP_SILENCE | 11401 | 无语音或音量太小 |
| MSP_ERROR_ASE_EXCEP_SNRATIO | 11402 | 信噪比低或有效语音过短 |
| MSP_ERROR_ASE_EXCEP_PAPERDATA | 11403 | 非试卷数据 |
| MSP_ERROR_ASE_EXCEP_PAPERCONTENTS | 11404 | 试卷内容有误 |
| MSP_ERROR_ASE_EXCEP_NOTMONO | 11405 | 录音格式有误 |
| MSP_ERROR_ASE_EXCEP_OTHERS | 11406 | 其他评测数据异常，包括错读、漏读、恶意录入、试卷内容等错误 |
| MSP_ERROR_ASE_EXCEP_PAPERFMT | 11407 | 试卷格式有误 |
| MSP_ERROR_ASE_EXCEP_ULISTWORD | 11408 | 存在未登录词，即引擎中没有该词语的信息 |
解析评测结果： SDK通过onResult回调抛出XML格式的评测结果，结果格式及字段含义详见 语音评测（流式版）试题格式及结果说明 文档，具体解析过程可参考Demo工程IFlyMscDemo中ISE 目录下Result目录中的源代码。
#3、视频教程
#4、代理服务器设置方法
在createUtility接口的params参数中添加：
net_type=custom, proxy_ip=<host>, proxy_port=<port>
其中，<host>,<port>替换为实际的代理服务器地址和端口。
例如：
NSString *initString = [[NSString alloc] initWithFormat:@"appid=%@, net_type=custom, proxy_ip=192.168.1.2, proxy_port=8080", @"12345678"]; //注意：各参数间，以英文逗号分隔。
[IFlySpeechUtility createUtility:initString];
接口原型： (IFlySpeechUtility *)createUtility:(NSString *)params
注意： 若在设置代理参数后，使用语音服务过程中，报错10204/10205/10212等网络异常错误时，请查阅以下内容，做出相关操作：
- 讯飞语音SDK的通信协议使用的是标准HTTP1.1协议，其代理协议使用的是标准HTTP代理协议。
- 代理服务器需要支持全双工多问多答方式，即 pipeline 模式。
- 代理服务器不能对80端口做限制，不能对如下域名做拦截： hdns.openspeech.cn scs.openspeech.cn open.xf-yun.com dev.voicecloud.cn
- 需要确保代理服务器只负责转发数据包，不能改变数据包的完整性和时序性。
- 代理服务器在转发数据包时，不能在HTTP协议头部添加 IE6 标识头。
#5、常见问题
#ios常见问题资料
答：请参见论坛帖子：iOS MSC SDK常见问题总结
#iOS评测sdk如何下载？
答：文档中心---快速指引 有介绍步骤根据步骤下载在线评测sdk
#如何处理iOS SDK音频服务
答：请参见论坛帖子：讯飞语音iOS SDK音频问题详解
#语音评测参数描述、支持题型、结果格式及字段含义？
答： 参数描述、支持题型、结果格式及字段含义请参见 语音评测（流式版）相关描述说明 文档。
#语音评测最多支持多长时间的语音输入？
答：对于所有评测题型，建议使用3分钟以内的语音输入。
#语音评测支持传入的音频格式有哪些？
答：支持的音频类型是：单声道 16bit Inter PCM、WAV。 支持的音频采样率是：16000HZ。推荐使用Cool edit软件查询音频格式是否符合，音频格式不符合会检测为乱读，分值不能作为参考。
#错误码及相应解决方案查询网址
#如何设置语音云服务URL
答：对于一些特殊服务，需要在createUtility接口中添加：server_url = http://YourDomainName/msp.do （YourDomainName是指语音云服务域名，请开发者自行替换） 例如：
NSString *initString = [[NSString alloc] initWithFormat:@"appid=%@,server_url=%@", @"12345678",@"http://sdk.openspeech.cn/msp.do"]; //注意：各参数间，以英文逗号分隔。
[IFlySpeechUtility createUtility:initString];
接口原型： (IFlySpeechUtility *)createUtility:(NSString *)params