接入准备
SDK 获取
接入须知
开发者在调用前请先查看智聆口语评测（新版）相关接口，了解接口的使用要求和使用步骤。
该接口需要手机能够连接网络（GPRS、3G 或 Wi-Fi 网络等），且系统为 iOS 12.0 及以上版本。
运行 Demo 必须设置 AppID、SecretID、SecretKey，可在 API 密钥管理 中获取。
SDK 导入
1. 下载并解压 iOS SDK 压缩包，压缩包包含 demo、sdk 和 doc，其中 sdk/QCloudSOE.xcframework 为口语评测的 SDK。
2. 在工程中添加依赖库，在 build Phases Link Binary With Libraries 中添加以下库：
QCloudSOE.xcframework
快速接入
完整代码请参考压缩包中的 demo 文件夹。
...id<TAIOralController> _ctl;...TAIOralConfig* config = [[TAIOralConfig alloc] init];config.appID = kQDAppId;config.secretID = kQDSecretId;config.secretKey = kQDSecretKey;config.token = kQDToken;[config setApiParam:TAIServerEngineTypeKey value:self.engineSeg.selectedSegmentIndex == 0 ? @"16k_en" : @"16k_zh"];[config setApiParam:TAIEvalModeKey value:[@(self.evalModeSeg.selectedSegmentIndex) stringValue]];[config setApiParam:TAIRefTextKey value:self.refText.text];[config setApiParam:TAIScoreCoeffKey value:[@(self.coeffSlider.value) stringValue]];[config setApiParam:TAISentenceInfoEnabledKey value:[@(self.sentenceInfoSeg.selectedSegmentIndex) stringValue]];if (_keywordText.text.length) {[config setApiParam:TAIKeywordKey value:_keywordText.text];}config.audioFile = [NSString stringWithFormat:@"%@/temp.pcm", NSTemporaryDirectory()];config.vadInterval = _vadSlider.value;config.vadVolume = _vadVolumeSlider.value;config.connectTimeout = 1000;if ([_sourceSeg selectedSegmentIndex] == 0) {_source = [[RecordDataSource alloc] init];} else {NSString* path = [NSString stringWithFormat:@"%@/%@", [[NSBundle mainBundle]bundlePath], @"hello_guagua.pcm"];_source = [[FileDataSource alloc] init:path];}_ctl = [config build:_source listener:self];...[_ctl stop]
接口说明
接口示例代码为 demo 部分代码，完整代码请参考 demo 目录。
TAIOralConfig
口语评测配置项，用于配置并创建 TAIOralController。
属性
类型 | 名称 | 说明 |
NSString* | appID | 腾讯云 appID |
NSString* | secretID | 腾讯云 secretID |
NSString* | secretKey | 腾讯云 secretKey |
NSString* | token | 腾讯云临时 token，设置为nil或空字符不生效 |
NSString* | audioFile | 数据文件，不为 nil 时会将从数据源读取的数据保存在此文件中 |
int | vadInterval | 静音检测时长，小于等于0时关闭静音检测，单位为 ms |
int | vadVolume | 静音检测音量阈值，音量阈值为0 - 120，默认为20，只有静音检测开启时生效 |
int | connectTimeout | websocket 连接超时设置，大于0时生效，单位为 ms |
说明：
静音检测说明：
SDK 内部根据音量大小和时间来判断是否静音，再音量小于 vadVolume 超过 vadInterval 的时长后判断为静音。
静音检测仅对 voice_format 为 pcm（格式为单通道 s16le）生效，其余格式不支持。
方法
setApiParam
设置 websocket 连接时传给后台的参数。
(TAIOralConfig*)setApiParam:(NSString*)key value:(NSString*)value;
build
创建 TAIOralController。
(id<TAIOralController>)build:(id<TAIOralDataSource>)source listener:(id<TAIOralListener>)listener;
说明：
TAIOralController 会强引用 source，但不会强引用 listener。
TAIOralController 自创建后会开始评测。
TAIOralController
口语评测控制器，用于停止或取消评测。
方法
cancel
取消评测任务。
(void)cancel;
说明：
取消任务成功后 SDK 会回调 SOECANCELERROR 类型的错误。
stop
停止评测任务。
(void)stop;
说明：
停止评测会向服务器发送结束评测信息，收到服务器成功的信息会回调任务结束。
TAIOralListener
口语评测消息回调协议。
方法
onFinish
评测成功。
(void)onFinish;
onError
评测失败。
(void)onError:(NSError*)error;
说明：
一次评测任务一定会回调一次成功或失败的信息。
onMessage
评测中收到的服务端信息。
(void)onMessage:(NSString*)value;
说明：
回调 websocket 连接后从服务端收到的所有信息。
onVad
静音回调。
(void)onVad:(BOOL)value;
说明：
静音检测的规则参考 TAIOralConfig 说明。
静音检测为边缘触发，仅在 SDK 判断静音状态改变时回调。
检测到静音为 Flase。
onVolume
音量回调。
(void)onVolume:(int)value;
说明：
音量范围为0 - 120。
音量回调仅对 voice_format 为 pcm（格式为单通道 s16le）生效。
onLog
日志回调。
(void)onLog:(NSString*)value level:(int)level;
说明：
目前 level 均为0。
TAIOralDataSource
口语评测数据源协议。
方法
start
开始读取。
(nullable NSError*)start;
说明：
SDK 内部开始读取数据源时回调该方法。
该方法返回不为 nil 时，评测失败，SDK 回调 SOEDATASOURCESTARTERROR 错误。
stop
停止读取。
(nullable NSError*)stop;
说明：
SDK 结束评测时回调该方法。
SDK 在评测中发生错误时结束时，不会主动调用 stop 方法，即使已经调用 start 方法。
该方法返回不为 nil 时，评测失败，SDK 回调 SOEDATASOURCESTOPERROR 错误。
read
读取数据
(NSData*)read:(int)ms error:(NSError**)error;
说明：
SDK 会通过不断调用该方法获取音频数据并发送给后端。
该方法返回的数据为 ms 毫秒产生的数据，当 voice_format 为 pcm 时，此时 read 需要返回 ms * 16 * 2 字节的数据。
该方法产生错误时可通过 error 参数传递到 SDK，评测失败，SDK 回调 SOEDATASOURCEERROR 错误。
具体实现可以参考 demo 中 RecordDataSource 和 FileDataSource。
empty
数据是否为空。
(bool)empty;
说明：
SDK 读取数据前会调用该方法判断数据源是否还有数据。
该方法返回为 True 时，SDK 会停止读取数据并向服务器发送结束信息。
错误码
名称 | 数值 | 说明 |
SOEPARAMETERERROR | 2000 | SDK 检测到参数不合法 |
SOEWEBSOCKETERROR | 2001 | Websocket 错误 |
SOEDATASOURCESTARTERROR | 2002 | 调用数据源 start 失败 |
SOEDATASOURCESTOPERROR | 2003 | 调用数据源 stop 失败 |
SOEDATASOURCEERROR | 2004 | 调用数据源 read 失败 |
SOECANCELERROR | 2005 | 参考 cancel 说明 |
SOESERVERERROR | 2006 | 服务器返回错误，服务端返回的数据 code 不为0时，返回此错误 |
SOEFILEWRITERERROR | 2007 | 当 audioFile 不为空，但 SDK 无法正常打开文件时，返回此错误 |
说明：
调用数据源方法失败时，数据源返回的错误在 InnerError 中。
