全部产品

iOS SDK

更新时间:2017-07-27 10:00:56   分享:   

功能介绍

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

SDK下载地址

一句话识别iOSSDK

获取appkey

获取appkey

重要接口说明

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

语音请求初始化方法

- (instancetype)init;

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

设置语音请求的appkey

- (void)setAppkey:(NSString *)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)obj options:(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 )recognizer didCompleteRecognizingWithResult:(NlsRecognizerResult)result error:(NSError*)error;

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

语音识别时返回语音音量

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

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

语音识别时返回语音数据

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

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

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

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

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

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

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

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

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

-(void)recognizerDidStopRecording:(NlsRecognizer )recognizer withRecorderData:(NSData)data;

  • 说明 录音模式下停止的回调通知,可得到录音数据(保留方法)
  • 参数
    • recognizer NlsRecognizer
    • data 录音数据
  • 返回值 无

设置SDK工作模式

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

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

设置SDK是否监听App状态

NlsRecognizer @property(nonatomic,assign,readwrite) BOOL cancelOnAppEntersBackground;

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

设置cancel时是否回调onRecognizeComplete方法

NlsRecognizer @property(nonatomic,assign,readwrite) BOOL enableUserCancelCallback;

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

设置是否记录语音

NlsRecognizer @property(nonatomic,assign,readwrite) BOOL enableVoiceLog;

  • 说明 打开语音记录功能,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
  • 返回值 无

设置最长录音时间,缺省时为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 With Libraries,点击上图中左下角的+号,在弹出界面中依次添加所依赖的framework。

Link Binary With Libraries

  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>
  4. @interface AppDelegate ()
  5. @end
  6. @implementation AppDelegate
  7. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  8. -
  9. #warning configure语音服务,必须在调用语音服务前执行该方法。
  10. [NlsRecognizer configure];
  11. ……

实现语音识别功能

ViewController中实现语音识别方法:

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