SDK使用

1.1 SDK简介

1.先声口语测评SDK主要有三大类“SSOralEvaluatingConfig.h”，“SSOralEvaluatingManager.h”和>>“SSOralEvaluatingManagerConfig.h”。

2.“SSOralEvaluatingConfig.h” 用于配置开始评测所需的参数

3.“SSOralEvaluatingManager.h” 生成管理引擎对象

4.”SSOralEvaluatingManagerConfig.h” 用于配置初始化引擎对象的参数

1.2 SDK导入

1.手动导入:

• 1.1 将“SingSound.framework”,“SingSound.Bundle”和”libssound.a”拖入工程（注：记得选“copy item if need”）然后去Build Phases下“Link Binary With Libraries”下有“SingSound.framework”和“Copy Bundle Resources”下有“SingSound.Bundle”。

• 1.2 导入必要的库“libz.1.1.3tbd”,“libz.1.tbd”

2.pod方式导入:

• 2.1 指定Master仓库和Pod仓库：

  source 'https://github.com/CocoaPods/Specs.git'

  source 'https://pt.singsound.com:10081/singsound-public/SingSoundSDKCocoaPodRepo.git'

• 2.2 添加依赖：

  pod 'SingSoundSDK'

  注：如果在pod install的过程中遇到Couldn’t determine repo type for URL的错误，请先手动添加源：

  pod repo add SingSoundSDKCocoaPodRepo https://pt.singsound.com:10081/singsound-public/SingSoundSDKCocoaPodRepo.git

  然后再执行install命令

3.在项目的info.plist 文件中增加“NSMicrophoneUsageDescription”以添加麦克风访问权限。

1.3 SDK实现

1.导入头文件 #import \<SingSound/SSOralEvaluatingManager.h>

//配置主要参数
    SSOralEvaluatingManagerConfig *config = [[SSOralEvaluatingManagerConfig alloc]init];
    config.appKey = @"appkey";
    config.secretKey = @"secretKey";
    config.allowDynamicService = YES; //开启动态获取测评地址
    [SSOralEvaluatingManager registerEvaluatingManagerConfig:config];
    [[SSOralEvaluatingManager shareManager]registerEvaluatingType:OralEvaluatingTypeLine];//注册全局评测器类型：在线，离线，混合

2.1 在需要评测功能的文件中遵守代理协议“SSOralEvaluatingManagerDelegate” 。

2.2 开始和停止

//开始评测
- (void)startEvaluating:(UIButton *)button {
    //请确保SSOralEvaluatingManager的当前代理是自己
    [SSOralEvaluatingManager shareManager].delegate = self;
    //初始化参数
    SSOralEvaluatingConfig *config = [[SSOralEvaluatingConfig alloc]init];
    config.oralContent = @"hello";
    config.oralType = OralTypeWord;
    //开始评测
    [[SSOralEvaluatingManager shareManager] startEvaluateOralWithConfig:config];
}
//结束评测
- (void)stopEvaluating:(UIButton *)button {
    //结束评测返回结果
    [[SSOralEvaluatingManager shareManager] stopEvaluate];
}

2.3 协议实现

- (void)oralEvaluatingDidEndWithResult:(NSString *)result isLast:(BOOL)isLast {
//评测结果回调
    NSLog(@"result:%@",result);
}
- (void)oralEvaluatingDidEndError:(NSError *)error {
//评测错误回调
    NSLog(@"error:%@",error);
}
- (void)oralEvaluatingDidVADFrontTimeOut {
    NSLog(@"前置超时");
    //建议取消
    [[SSOralEvaluatingManager shareManager] cancelEvaluate];
}
- (void)oralEvaluatingDidVADBackTimeOut {
    NSLog(@"后置超时");
}

1.4 动态评测地址配置

• 说明：使用 SingSound.framework v1.2.0(查看framework的info.plist或者 打印version方法查看)以上的版本，可无需集成”ServiceManager.h”，SDK内部已具有动态获取测评地址功能

1、首先项目中导入阿里云HTTPDNS SDK ，参考文档 https://help.aliyun.com/document_detail/30141.html ，只导入即可，注册和调用是通过ServiceManager.h 来完成的。
2、导入 ServiceManager.h 和 ServiceManager.m。

3、#import “ServiceManager.h”，程序启动调用注册方法

[[ServiceManager shareManager]registerHTTPDNS];

4、调用获取评测地址方法，需要填入appKey，示例代码：

  [[ServiceManager shareManager]getServiceAddressWithAppkey:\@"t146"
    callback:\^(NSString \*serviceAddress) {

  NSLog(\@"获取到的地址%\@",serviceAddress);

  }];

5、拿到serviceAddress之后，初始化引擎，填入到引擎里的服务器地址。示例代码：

  SSOralEvaluatingManagerConfig \*config = [[SSOralEvaluatingManagerConfig
    alloc]init];

  [config setValue:serviceAddress forKey:\@"service"];

异常处理
因评测服务器异常产生错误时，会调用

- (void)oralEvaluatingDidEndError:(NSError *)error

当error.code为 16385，16386 ,16387,16388,16389 时，可以用ServiceManager 里的方法重新获取可用的评测地址，并拿着这个地址重新注册引擎，需要等待引擎初始化成功回调后，再进行下一次评测。

注册引擎方法参考本文档1.3的内容。

类介绍

SSOralEvaluatingManagerConfig

1 appkey

@property (nonatomic, copy) NSString *appKey;

参数

2 设置secretKey

@property (nonatomic, copy) NSString *secretKey;

参数

3 设置服务器超时时间

@property (nonatomic, assign) NSTimeInterval serverTimeout;

参数

4 设置开启关闭vad

@property (nonatomic, assign) BOOL vad;

参数

5 设置前置超时时间

@property (nonatomic, assign) NSTimeInterval frontTime;

参数

6 设置后置超时时间

@property (nonatomic, assign) NSTimeInterval backTime;

参数

7 设置离线评测资源（单词或句子）

@property (nonatomic,assign) NSInteger offLineSource;

参数

0表示英文资源 1表示只中文资源 2中文和英文 默认0英文 |

8 设置log信息路径

@property (nonatomic, strong) NSString *logPath;

参数

9 设置log信息级别

@property (nonatomic, strong) NSNumber *logLevel

参数

10 设置连接超时时间

@property (nonatomic, assign) NSTimeInterval connectTimeout;

参数

11 是否打印log

@property (nonatomic, assign) BOOL isOutputLog;

参数

12 配置协议头

@property (nonatomic, copy) NSString *protocolHeader;

参数

13 配置端口号

@property (nonatomic, copy) NSString *portNumber;

参数

14 动态服务器配置

@property (nonatomic,assign)BOOL allowDynamicService;

参数

15 开启异步测评

@property (nonatomic,assign)BOOL enableAsync;

参数

16 配置离线资源路径

@property (nonatomic, copy) NSString *resourcePath;

参数

SSOralEvaluatingManager

1 设置代理
函数
@property (nonatomic, weak) id\<SSOralEvaluatingManagerDelegate> delegate;

参数

2 单利返回对象
函数
+(instancetype)shareManager;

3 返回版本号
函数
+(NSString *)version;

4 注册初始化参数
函数

• (void)registerEvaluatingManagerConfig:(SSOralEvaluatingManagerConfig *)config;

参数

5 注册全局评测模式
函数
-(void)registerEvaluatingType:(OralEvaluatingType)type

参数

（初始化对象）
函数

• (instancetype)initWithManagerConfig:(SSOralEvaluatingManagerConfig *)config type:(OralEvaluatingType)type;

6 开始评测
函数
-(void)startEvaluateOralWithConfig:(OralEvaluatingConfig *)config;

参数

7 开始评测
函数
-（void)startEvaluateOralWithConfig:(SSOralEvaluatingConfig )config storeWavPath:(NSString )storeWavPath;

参数

8 开始评测(本地音频文件评测，音频格式可选（wav,mp3等），需要将音频格式设置的参数信息跟评测参数同步。)
函数
-(void)startEvaluateOralWithWavPath:(NSString )wavPath config:(OralEvaluatingConfig )config;

参数

9 停止评测，返回结果
函数
-(void)stopEvaluate;

10 取消评测
函数
-(void)cancelEvaluate;

11 清除所有录音文件
注：只针对调用startEvaluateOralWithConfig:(SSOralEvaluatingConfig *)config
函数
+(BOOL)clearAllRecord;

12 返回录音文件地址
注：只针对调用startEvaluateOralWithConfig:(SSOralEvaluatingConfig )config
函数
+(NSString )recordPathWithTokenId:(NSString *)tokenId;

参数

13 评测引擎释放
函数
-(void)engineDealloc;

14 开始评测—不开启录音，需要外部传输音频数据

-(void)startNoAudioStreamEvaluateOralWithConfig:(SSOralEvaluatingConfig *)config;

15 传输音频数据（NSData类型）给测评服务器

-(void)feedAudioToEvaluateWithData:(NSData *)data;

16 配置授权ID和过期时间

-(void)setAuthInfoWithWarrantId:(NSString )warrant_id AuthTimeout:(NSString )timeout;

SSOralEvaluatingConfig

1 设置音频格式

@property (nonatomic, strong) NSString *audioType;

2 设置音频格式-采样率

@property (nonatomic, assign) NSInteger sampleRate;

3 设置音频格式-声道

@property (nonatomic, assign) NSInteger channel;

4 设置音频格式-采样字节数

@property (nonatomic, assign) NSInteger sampleBytes;

5 设置题型

@property (nonatomic, assign) OralType oralType;

6 评测模式

@property (nonatomic, assign) MixedType mixedType;

7 设置评测文本内容

@property (nonatomic, copy) NSString *oralContent;

8 设置分值

@property (nonatomic, assign) NSUInteger rank;

9 是否开启边读边评，实时返回数据

@property (nonatomic, assign) BOOL openFeed;

10 是否开启比较音频数据（目前仅支持 OralTypeSentence（英文句子））

@property (nonatomic, assign) BOOL openCompareAudio;

11 设置标准音频地址 与openCompareAudio 关联

@property (nonatomic, copy) NSString * stdAudioUrl;

12 设置用户id

@property (nonatomic, copy) NSString *userId;

13 设置评分精度

@property (nonatomic, assign) EvaluatingPrecision precision;

14 设置答案

@property (nonatomic, strong) NSArray\<__kindof SSOralEvaluatingAnswer *> *answerArray;

15 评分松紧度，范围0.8\~1.5，数值越小，打分越严厉和typeThres不能同时传
函数
@property (nonatomic, assign) CGFloat rateScale;

16 评分松紧度，可传 1，2，3，4。1 表示严格，2 表示宽松，3 表示非常严 格，4 非常宽松。和rateScale不能同时传
函数
@property (nonatomic, assign) NSUInteger typeThres;

17 句子评测中是否输出每个单词的音标分
@property (nonatomic, assign) BOOL isOutputPhonogramForSentence;

18 重传机制类型
@property (nonatomic, assign) NSInteger enableRetry;

19 指定单词的发音
@property (nonatomic, copy) NSDictionary *phonesDic;

20 此字段 用于英文扩展选择题
@property (nonatomic, assign) NSUInteger pronScale;

21 关键字数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *keywordArray;

22 要点数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *pointsArray;

23 错误答案数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *wrongWordArray;

24 问题 （非必选）
@property (nonatomic, strong) NSString *question;

25 录音文本（非必选）
@property (nonatomic, strong) NSString *recorderContent;

26 开启音素检错
@property (nonatomic, assign) BOOL checkPhones;

27 评测音节信息
@property (nonatomic,assign)BOOL isSyllable;

28 学段 （非必填）
@property (nonatomic,assign) NSInteger grade;

29 录音回调时间间隔
@property (nonatomic,assign) int recordTimeinterval;

30 是否由外部设置AVAudioSession category
@property (nonatomic,assign) BOOL initiativeSetAudio;

31 本地音频评测feed间隔
@property (nonatomic,assign) NSTimeInterval feedTime;

32 本地音频评测,分片数据大小
@property (nonatomic,assign) NSInteger feedSize;

33 是否开启vad功能
@property (nonatomic,assign) BOOL vadEnable;

SSOralEvaluatingConfig

1 设置音频格式

@property (nonatomic, strong) NSString *audioType;

2 设置音频格式-采样率

@property (nonatomic, assign) NSInteger sampleRate;

3 设置音频格式-声道

@property (nonatomic, assign) NSInteger channel;

4 设置音频格式-采样字节数

@property (nonatomic, assign) NSInteger sampleBytes;

5 设置题型

@property (nonatomic, assign) OralType oralType;

6 评测模式

@property (nonatomic, assign) MixedType mixedType;

7 设置评测文本内容

@property (nonatomic, copy) NSString *oralContent;

8 设置分值

@property (nonatomic, assign) NSUInteger rank;

9 是否开启边读边评，实时返回数据

@property (nonatomic, assign) BOOL openFeed;

10 是否开启比较音频数据（目前仅支持 OralTypeSentence（英文句子））

@property (nonatomic, assign) BOOL openCompareAudio;

11 设置标准音频地址 与openCompareAudio 关联

@property (nonatomic, copy) NSString * stdAudioUrl;

12 设置用户id

@property (nonatomic, copy) NSString *userId;

13 设置评分精度

@property (nonatomic, assign) EvaluatingPrecision precision;

14 设置答案

@property (nonatomic, strong) NSArray\<__kindof SSOralEvaluatingAnswer *> *answerArray;

15 评分松紧度，范围0.8\~1.5，数值越小，打分越严厉和typeThres不能同时传
函数
@property (nonatomic, assign) CGFloat rateScale;

16 评分松紧度，可传 1，2，3，4。1 表示严格，2 表示宽松，3 表示非常严 格，4 非常宽松。和rateScale不能同时传
函数
@property (nonatomic, assign) NSUInteger typeThres;

17 句子评测中是否输出每个单词的音标分
@property (nonatomic, assign) BOOL isOutputPhonogramForSentence;

18 重传机制类型
@property (nonatomic, assign) NSInteger enableRetry;

19 指定单词的发音
@property (nonatomic, copy) NSDictionary *phonesDic;

20 此字段 用于英文扩展选择题
@property (nonatomic, assign) NSUInteger pronScale;

21 关键字数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *keywordArray;

22 要点数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *pointsArray;

23 错误答案数组（非必选）
@property (nonatomic, strong) NSArray\<__kindof NSString *> *wrongWordArray;

24 问题 （非必选）
@property (nonatomic, strong) NSString *question;

25 录音文本（非必选）
@property (nonatomic, strong) NSString *recorderContent;

26 开启音素检错
@property (nonatomic, assign) BOOL checkPhones;

27 评测音节信息
@property (nonatomic,assign)BOOL isSyllable;

28 学段 （非必填）
@property (nonatomic,assign) NSInteger grade;

29 录音回调时间间隔
@property (nonatomic,assign) int recordTimeinterval;

30 是否由外部设置AVAudioSession category
@property (nonatomic,assign) BOOL initiativeSetAudio;

31 本地音频评测feed间隔
@property (nonatomic,assign) NSTimeInterval feedTime;

32 本地音频评测,分片数据大小
@property (nonatomic,assign) NSInteger feedSize;

33 是否开启vad功能
@property (nonatomic,assign) BOOL vadEnable;

SSOralEvaluatingManagerDelegate

1 引擎初始化成功
函数
-(void)oralEvaluatingInitSuccess;

2 评测开始
函数
-(void)oralEvaluatingDidStart;

3 评测停止
函数
-(void)oralEvaluatingDidStop;

4 评测成功回调
函数
-(void)oralEvaluatingDidEndWithResult: (NSDictionary *)result isLast:(BOOL)isLast;

参数

5 评测失败回调
函数
-(void)oralEvaluatingDidEndError: (NSError *)error;

参数

6 录音数据回调
函数
-(void)oralEvaluatingRecordingBuffer: (NSData *)recordingData;

参数

7 录音音量大小回调
函数
-(void)oralEvaluatingDidUpdateVolume: (int)volume;

参数

8 VAD(前置时间）超时回调
函数
-(void)oralEvaluatingDidVADFrontTimeOut;

9 VAD(后置时间）超时回调
函数
-(void)oralEvaluatingDidVADBackTimeOut;

10 录音即将超时（只支持在线模式，单词20s，句子40s)
函数
-(void)oralEvaluatingDidRecorderWillTimeOut;

11 边读边评—-实时回调
函数
-(void)oralEvaluatingRealTimeCallBack:(NSDictionary *)result;

12 授权ID需要更新回调
-(void)onWarrantIdNeedUpdate;

13 评测成功回调 （等同上述编号4 回调）
函数
-(void)oralEvaluatingDidEndWithResult: (NSDictionary*)result RequestId:(NSString*)request_id;

参数

14 评测失败回调 （等同上述编号5 回调）
函数
-(void)oralEvaluatingDidEndError: (NSError *)error RequestId:(NSString *)request_id;

参数