iOS SDK是什么?

功能介绍


语音iOSSDK提供一句话识别服务，提供将实时短语音转成文字的功能，可直接用于语音搜索类应用。提供用户自定义热词设置接口，提高语音识别率。用户自定义热词词表的提交方式是RESTFUL接口，详细见「 用户自定义热词」，热词生效接口见下文。

SDK下载地址


一句话识别iOSSDK

获取appkey


获取appkey

重要接口说明



发送语音请求的对象及方法：NlsRequest.h



语音请求初始化方法


- (instancetype)init;

• 说明 语音识别、语音合成的语音请求初始化方法
• 返回值 self

设置语音请求的appkey


- (void)setAppkey:(NSString *)appKey;

• 说明 设置语音请求的appkey。
• 参数appKey 用户在列表中选择合适的appkey

返回值 无

设置发送的请求是否需要带语音数据


- (void)setBstreamAttached:(BOOL)bstreamAttached;

• 说明设置是否要发送语音数据到服务器。若发送的是语音识别请求，则bstreamAttached为YES；若发送的是语音合成请求，则bstreamAttached为NO。
• 参数bstreamAttached 是否要发送语音数据到服务器。

返回值 无

设置语音识别ASR请求


- (void)setAsrRequest;

• 说明 设置语音识别ASR请求
• 参数 无
• 返回值 无

设置语音识别识别结果返回模式


- (void)setAsrResponseMode:(NSString *)responseMode;

• 说明 设置语音识别ASR识别结果返回模式
• 参数responseMode语音识别结果返回模式，0是流式，1是非流式。如不设置此参数，以appkey的识别结果返回模式为准，若设置此方法，则以responseMode的值为准。

返回值 无

用户自定义热词接口，设置词表id


- (void)setAsrVocabularyId:(NSString *)vocabularyId;

• 说明 用户自定义热词接口，设置词表id
• 参数 vocabularyId 词表id，可选项。使用词表时必选
• 返回值 无

数加验证


- (void)Authorize:(NSString )authId withSecret:(NSString)secret;

• 说明 数加验证，未经过数加验证的语音请求均为非法请求。
• 参数authId 数加验证的ak_id
• secret 数加验证的ak_secret

返回值 无

将语音请求NlsRequest对象转换成JSON字符串


+ (NSString )getJSONStringfromNlsRequest:(NlsRequest)nlsRequest;

• 说明 将语音请求NlsRequest对象转换成JSON字符串形式。
• 参数nlsRequest NlsRequest对象

返回值 NlsRequest的JSON字符串

将对象转换成JSONString方法


+ (NSString *)getJSONString:(id)objoptions:(NSJSONWritingOptions)options error:(NSError)error;**

• 说明 将object转换成JSONString。
• 参数obj 被转化对象
• options NSJSONWritingOptions
• error NSError

返回值 NlsRequest的JSON字符串

将对象转换成NSDictionary方法


+ (NSDictionary *)getObjectData:(id)obj;

• 说明 将object转换成NSDictionary。
• 参数obj 被转化对象

返回值 NSDictionary

语音服务SDK的核心类：NlsRecognizer.h


语音服务SDK的核心类，封装了录音设备的初始化，压缩处理，语音检测（VAD）等复杂逻辑，自动的将语音数据同步传送到语音服务器上。开发者只需要传递正确的delegate，就能完成语音识别和语音合成。

语音识别的关键回调函数


-(void)recognizer:(NlsRecognizer )recognizerdidCompleteRecognizingWithResult:(NlsRecognizerResult)resulterror:(NSError*)error;

• 说明 语音识别的关键回调函数，delegate必须实现。若appkey为流式返回appkey，将会多次回调该方法。
• 参数recognizer NlsRecognizer
• result 返回值对象 NlsRecognizerResult
• error 语音识别错误和异常 NSError

返回值 无

语音识别时返回语音音量


-(void)recognizer:(NlsRecognizer *)recognizerrecordingWithVoiceVolume:(NSUInteger)voiceVolume;

• 说明 返回录音的语音音量，调用频率取决于SDK内部设定。
• 参数recognizer NlsRecognizer
• voiceVolume 0-100的数值

返回值 无

语音识别时返回语音数据


-(void)recognizer:(NlsRecognizer )recognizerrecordingWithVoiceData:(NSData)voiceData;

• 说明 返回录音的数据，调用频率取决于SDK内部设定。
• 参数recognizer NlsRecognizer
• frame 返回的语音

返回值 无

语音识别时开始录音的回调通知


-(void)recognizerDidStartRecording:(NlsRecognizer*)recognizer;

• 说明 开始录音的回调通知
• 参数recognizer NlsRecognizer

返回值 无

语音识别时停止录音的回调通知


-(void)recognizerDidStopRecording:(NlsRecognizer*)recognizer;

• 说明 停止录音的回调通知
• 参数recognizer NlsRecognizer

返回值 无

录音模式下停止的回调通知


-(void)recognizerDidStopRecording:(NlsRecognizer )recognizerwithRecorderData:(NSData)data;

• 说明 录音模式下停止的回调通知，可得到录音数据（保留方法）
• 参数recognizer NlsRecognizer
• data 录音数据

返回值 无

设置SDK工作模式


NlsRecognizer @property(nonatomic,assign,readwrite)kNlsRecognizerMode mode;

• 说明 设置语音SDK的工作模式，若不设置，默认为语音识别模式kMODE_RECOGNIZER

设置SDK是否监听App状态


NlsRecognizer @property(nonatomic,assign,readwrite) BOOLcancelOnAppEntersBackground;

• 说明 设置SDK是否监听App状态，缺省为NO。如果设为YES，则SDK会监听App状态，一旦切换到后台，就自动取消请求。

设置cancel时是否回调onRecognizeComplete方法


NlsRecognizer @property(nonatomic,assign,readwrite) BOOLenableUserCancelCallback;

• 说明NlsRecognizer的cancel方法被调用的时候，会触发delegate的onRecognizeComplete方法，错误码为kERR_USER_CANCELED,错误信息为kNlsRecognizerErrorUserCanceled。如果App不想被回调，请设置为NO即可。参见cancel方法。

设置是否记录语音


NlsRecognizer @property(nonatomic,assign,readwrite) BOOLenableVoiceLog;

• 说明打开语音记录功能，SDK将会把语音识别的文件记录到当前App的document下面，调试用。缺省关闭，在DEBUG模式下有效，Release模式下无效。（保留字段）

配置语音服务模块的基础参数


+(void)configure;

• 说明 配置语音服务模块的基础参数，请在App启动的时候调用
• 参数 无
• 返回值 无

初始化NlsRecognizer


-(id)initWithNlsRequest:(NlsRequest )nlsRequest svcURL:(NSString)svcURL;

• 说明 初始化NlsRecognizer，注意: 通过该API使用的appKey必须提前通过configure函数预先配置好
• 参数nlsRequest 语音请求NlsRequest
• svcURL 语音服务地址

返回值 无

VAD设置，设置是否打开VAD开关


-(void)setVad;

• 说明 设置是否打开VAD开关，VAD默认关闭。
• 参数isVad 是否打开静音检测开关

返回值 无

VAD设置，检测到用户语音后，自动停止的间隙


-(void)setVadAutoStopTimeInterval:(NSTimeInterval)timeinterval;

• 说明 检测到用户语音后，自动停止的间隙。
• 参数timeinterval 静音触发自动停止的时长，以秒表示.缺省0.7s

返回值 无

vAD设置，打开VAD时，设置最短录音时间，缺省时为5s


-(void)setMinRecordTime:(NSTimeInterval) timeinterval;

• 说明 打开VAD时，设置最短录音时间，缺省时为5s
• 参数timeinterval 最短录音时间，缺省时为5s

返回值 无

[font='iconfont'] 设置最长录音时间，缺省时为60s


-(void)setMaxRecordTime:(NSTimeInterval) timeinterval;

• 说明 设置最长录音时间，缺省时为60s
• 参数timeinterval 最短录音时间，缺省时为60s

返回值 无

开始语音识别


-(void)start;

• 说明 开始语音识别。打开录音设备，同时开始识别。
• 返回值 无

停止语音识别


-(void)stop;

• 说明停止语音识别。停止录音设备，delegate的didStopRecord会被回调。网络请求在后台继续，如果有识别结果返回，则会通过delegate的didCompleteRecognizingWithResult回调方法单独返回。
• 返回值 无

取消语音识别


-(void)cancel;

• 说明取消语音识别。取消语音识别，录音会停止，网络请求会取消。根据enableUserCancelCallback的设置，决定是否回调delegate方法。
• 返回值 无

语音识别是否已经开始


-(BOOL)isStarted;

• 说明 语音识别是否已经开始
• 返回值 YES表示语音识别已经开始，NO表示语音识别未开始。

参数和错误码说明


发送ASR语音请求的参数：

1.     {
2.       "requests" : {
3.         "asr_in" : {
4.           "version" : "3.0",// 协议版本号
5.           "asrSC" : "opu",// 输入的语音格式，默认opu
6.           "user_id": "uid", // 用户id，可选项。使用词表时必选
7.           "vocabulary_id": "vid", // 词表id，可选项。使用词表时必选
8.           "response_mode":0 //语音识别结果返回模式，0是流式，1是非流式。如不设置此参数，以appkey的识别结果返回模式为准，若设置此方法，则以responseMode的值为准。
9.         },
10.         "context" : {
11.           "auth" : {} //requested
12.         }
13.       },
14.       "app_key" : "",
15.       "bstream_attached" : true,// 请求包的后面是不是还接着二进制语音流。语音识别时bstream_attached = YES 。
16.       "version" : "4.0"// 协议版本号
17.     }

返回的识别结果result是一个NlsRecognizerResult的对象：

1.     {
2.       "status" : "1",// 服务器状态，0为失败，非零为成功
3.       "id" : "",// 透传系统始终的uuid,服务端配置是否返回
4.       "finish" : "1",// 0为未结束，非零为结束，识别是否已经结束
5.       "results" : {
6.         "asr_out" : {
7.           "result" : "",// 语音识别结果
8.           "status" : 1,// 服务器状态，0为失败，非零为成功
9.           "finish" : 1,// 0为未结束，非零为结束，识别是否已经结束
10.           "version" : "4.0"
11.         },
12.         "out" : {}//保留字段
13.       },
14.       "bstream_attached" : false,// 应答包的后面是不是还接着二进制语音流。
15.       "version" : "4.0"// 协议版本号
16.     }

若识别发生错误，recognizer:didCompleteRecognizingWithResult:error:的回调函数中error不为nil。相应错误码的对应表如下所示。

• 客户端错误码

字段名	错误码	含义
kERR_NO_ERROR	0	成功
kERR_GENERIC_ERROR	1	识别失败
kERR_USER_CANCELED	520	用户取消
kERR_NETWORK_ERROR	530	网络及通讯异常
kERR_SERVICE_ERROR	540	语音服务异常或被降级
kERR_VOICE_ERROR	550	录音及语音识别异常
kERR_MIC_ERROR	560	Mic无法访问或硬件异常
kERR_TOOSHORT_ERROR	570	用户点击过快

• 服务端返回结果错误码

状态	status_code	CloseFrame状态码	HTTP语义
成功	200	1000	成功处理
请求格式有误	400	4400	错误请求
需要鉴权信息	401	4401	请求要求身份验证
鉴权失败	403	4403	服务器拒绝请求
超出最大并发量	429	4429	太多请求
请求超时	408	4408	处理请求超时
处理出错	500	4500	服务器内部错误
服务不可用	503	4503	服务不可用

完整示例



创建应用


使用Xcode创建iOS application应用工程。

添加Framework


在Xcode工程中需要引入所需要的framework，NlsClientSDK.framework。
添加方法：选中工程，点击TARGETS，在右侧的Build Phases中选择 Link Binary WithLibraries，点击上图中左下角的+号，在弹出界面中依次添加所依赖的framework。

1.     $lipo -info NlsClientSDK
2.     Architectures in the fat file: NlsClientSDK are: armv7 i386 x86_64 arm64

引入头文件


在需要调用SDK的文件中，添加如下头文件:

1.     #import <NlsClientSDK/NlsClientSDK.h>

语音服务注册


AppDelegate中注册语音服务：

1.     #import "AppDelegate.h"
2.     #import "ViewController.h"
3.     #import <NlsClientSDK/NlsClientSDK.h>
5.     @interface AppDelegate ()
6.     @end
8.     @implementation AppDelegate
9.     - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
10.     -    
11.     #warning configure语音服务，必须在调用语音服务前执行该方法。
12.     [NlsRecognizer configure];
13.         ……
14.     ｝

实现语音识别功能


ViewController中实现语音识别方法：

1.     #import "ViewController.h"
2.     #import <NlsClientSDK/NlsClientSDK.h>
4.     @interface ViewController ()<NlsRecognizerDelegate>
6.     @property(nonatomic,strong) NlsRecognizer *recognizer;
8.     @end
10.     @implementation ViewController
12.     - (void)viewWillAppear:(BOOL)animated
13.     {
14.         [super viewWillAppear:animated];
16.         // 检查asr服务是否可用
17.         if([NlsRecognizer isServiceAvailable]) {
18.             NSLog(@"当前语音服务可用");
19.         }
20.         else {
21.             NSLog(@"当前语音服务不可用");
22.         }
24.         // 监测语音服务状态
25.         [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(asrStatusChanged:) name:kNlsRecognizerServiceStatusChanged object:nil];
27.     }
29.     #pragma mark - Actions
30.     - (void)onStartAsrButtonClick:(id)sender {
32.         // 初始化语音请求类
33.         NlsRequest * nlsRequest = [[NlsRequest alloc] init];
34.         [nlsRequest setAppkey:@"appkey"]; // requested  appkey见一句话识别简介内容
35.         [nlsRequest setBstreamAttached:YES]; // requested 语音识别，setBstreamAttached = YES
36.         [nlsRequest setAsrRequest]; // requested 设置asr_in参数
37.         //使用用户自定义热词功能时，必须传入vocabulary_id。
38.         //[nlsRequest setAsrVocabularyId:@"vocabulary_id"];
39.     #warning 请修改为您在阿里云申请的数字验证串Access Key ID和Access Key Secret
40.         [nlsRequest Authorize:@"" withSecret:@""]; // requested
42.         // 初始化语音服务核心类
43.         NlsRecognizer *r = [[NlsRecognizer alloc] initWithNlsRequest:nlsRequest svcURL:nil]; // requested 采用默认svcURL
44.         //vad：自动语音检测，可根据需要设置是否打开，YES为打开，NO为关闭。
45.         [r setVad:self.setVadFlag];
48.         r.delegate = self;
49.         r.cancelOnAppEntersBackground = YES;
50.         r.enableUserCancelCallback = YES;
51.         self.recognizer = r;
53.         NSString *nlsRequestJSONString = [NlsRequest getJSONStringfromNlsRequest:nlsRequest];
54.         NSLog(@"setupAsrIn : %@",nlsRequestJSONString);
56.         //开始语音识别
57.         [self.recognizer start];
59.     }
61.     - (void)onStopAsrButtonClick:(id)sender {
62.         //结束语音识别
63.         [self.recognizer stop];
64.     }
66.     #pragma mark - Notification Callbacks
67.     -(void)asrStatusChanged:(NSNotification*)notify{
68.         //处理网络变化
69.     }
71.     #pragma mark - RecognizerDelegate
72.     -(void) recognizer:(NlsRecognizer *)recognizer didCompleteRecognizingWithResult:(NlsRecognizerResult*)result error:(NSError*)error{
73.         //处理识别结果和错误信息
74.         //若appkey为流式返回appkey，将会多次回调该方法
75.     }
77.     -(void) recognizer:(NlsRecognizer *)recognizer recordingWithVoiceVolume:(NSUInteger)voiceVolume{
78.         //处理音量变化    
79.     }
81.     -(void) recognizerDidStartRecording:(NlsRecognizer *)recognizer{
82.         //处理开始识别事件
83.     }
85.     -(void) recognizerDidStopRecording:(NlsRecognizer *)recognizer{
86.         //处理结束识别事件
87.     }
89.     @end

FAQ



问题1 : bitcode。

1. ld: 'xxx/NlsClientSDK.framework/NlsClientSDK(NlsRecognizer.o)' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target. for architecture arm64
2. clang: error: linker command failed with exit code 1 (use -v to see invocation)

解决1 : 本项目iOS sdk可支持bitcode。



问题2 : 数加验证失败4403。

1. {
2.     NSLocalizedDescription = "server closed connection, code:4403, reason:Unauthorized AppKey [xxx], wasClean:1";
3. }

解决2 : 检查数加验证的 ak_id 和 ak_secret是否正确;检查 appkey 填写是否正确。

1. #warning 请修改为您在阿里云申请的数字验证串Authorize withSecret
2.     [nlsRequest Authorize:@"Access Key ID" withSecret:@"Access Key Secret"]; // requested Access Key ID和Access Key Secret

1.     [nlsRequest setAppkey:@"your_appkey"]; // requested appkey见一句话识别简介内容

问题3 : Assertion failed。



解决3 :检查在开始语音识别前，是否注册;检查NlsRecognizer初始化时svcURL是否为nil。

1. //Config appkey.
2. [NlsRecognizer configure];

1. NlsRecognizer *r = [[NlsRecognizer alloc] initWithNlsRequest:nlsRequest svcURL:nil];

问题4 : 错误码4400。

1. {
2.     NSLocalizedDescription = "server closed connection, code:4400, reason:illegal params, operation forbidden, wasClean:1";
3. }

解决4 :检查appkey是否为空，填写正确的appkey。

1. #warning 请修改为您在阿里云申请的APP_KEY
2.     [nlsRequest setAppkey:@"your_appkey"]; // requested