全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网

iOS SDK

更新时间:2017-09-29 14:33:29

功能介绍

语音SDK的iOS版本提供自然语音理解NLU服务。

提供用户自定义热词设置接口,提高语音识别率。用户自定义热词词表的提交方式是RESTFUL接口,详细见「用户自定义热词」,热词生效接口见下文。

SDK下载地址

NLU_iOSSDK

重要接口说明

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

语音请求初始化

- (instancetype)initWithRequestProto:(NlsRequestProto * )nlsRequestProto;

  • 说明 语音请求初始化方法
  • 参数
    • nlsRequestProto NlsRequestProto对象
  • 返回值 self

设置语音请求的appkey

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

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

- (void)setBstreamAttached:(BOOL)bstreamAttached;

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

设置语音识别ASR请求

- (void)setAsrRequest;

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

设置自然语言处理NLU请求

- (void)setDsRequest;

  • 说明 设置自然语言处理NLU请求。
  • 返回值 无

数加验证

- (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)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;

  • 说明 语音识别是否已经开始
  • 返回值 语音识别是否已经开始

参数和错误码说明

发送NLU语音请求的参数:

  1. {
  2. "requests": {
  3. "asr_in": {
  4. "version": "3.0",// 协议版本号
  5. "asrSC": "opu",// 输入的语音格式,默认opu
  6. "user_id": "user_id",// 用户名,可选项。使用词表时必选
  7. "vocabulary_id": "vid", // 词表id,可选项。使用词表时必选
  8. "response_mode":0 //语音识别结果返回模式,0是流式,1是非流式。如不设置此参数,以appkey的识别结果返回模式为准,若设置此方法,则以responseMode的值为准。
  9. },
  10. "ds_in": {
  11. "type": "dialogue",
  12. "version": "1.0",
  13. "content": {}
  14. }
  15. },
  16. "context": {
  17. "device": {//使用默认值即可
  18. "timezone": "8",
  19. "device_id": "aliyun.dataapi.nls",
  20. "system_locale": "zh-CN",
  21. "device_type": "aliyun.dataapi.nls"
  22. },
  23. "application": {//使用默认值即可
  24. "user_id": "public_user_ios",
  25. "version": "2.0.3",
  26. "application_id": "com.aliyun.dataapi.nls.api.nlu"
  27. },
  28. "auth": {} //数加验证
  29. },
  30. "app_key": "",
  31. "bstream_attached": true,// 请求包的后面是不是还接着二进制语音流。
  32. "version": "4.0"// 协议版本号
  33. }

返回的识别结果result是一个NlsRecognizerResult的对象,NLU的返回需要参见下面的“语义表示协议”:

  1. {
  2. "status" : "1",// 服务器状态,0为失败,非零为成功
  3. "id" : "",
  4. "finish" : "1",
  5. "results" : {
  6. "asr_out" : {
  7. "result" : "",// 语音识别结果
  8. "status" : 1,// 服务器状态,0为失败,非零为成功
  9. "finish" : 1,// 0为未结束,非零为结束,识别是否已经结束
  10. "version" : "4.0"
  11. },
  12. "ds_out" : {
  13. "dm_result" : {// 保留字段
  14. },
  15. "nlg_result" : {// 保留字段
  16. },
  17. "status" : "ok",
  18. "ds_rt" : "",
  19. "nlu_result" : {// nlu结果
  20. },
  21. "web_result" : {// 保留字段
  22. }
  23. },
  24. "out" : {}// 保留字段
  25. },
  26. "bstream_attached" : false,// 应答包的后面是不是还接着二进制语音流。
  27. "version" : "4.0"// 协议版本号
  28. }

若识别发生错误,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)onStartNluButtonClick:(id)sender {
  22. // 初始化NlsRequestProto,包含application信息和device信息
  23. NlsRequestProto * nlsRequestProto = [[NlsRequestProto alloc] init];
  24. // 初始化语音请求类
  25. NlsRequest * nlsRequest = [[NlsRequest alloc] initWithRequestProto:nlsRequestProto];
  26. [nlsRequest setAppkey:@""]; // requested appkey见一句话识别简介内容
  27. [nlsRequest setBstreamAttached:YES]; // requested 语音识别,必需为YES
  28. [nlsRequest setAsrRequest]; // requested asr_in的初始化
  29. //使用用户自定义热词功能时,必须传入user_id和vocabulary_id。
  30. //[nlsRequest setAsrUserId:@"user_id"];
  31. //[nlsRequest setAsrVocabularyId:@"vocabulary_id"];
  32. [nlsRequest setDsRequest]; // requested ds_in
  33. #warning 请修改为您在阿里云申请的数字验证串Authorize withSecret
  34. [nlsRequest Authorize:@"" withSecret:@""]; // requested Access Key ID 和 Access Key Secret
  35. // 初始化语音服务核心类
  36. NlsRecognizer *r = [[NlsRecognizer alloc] initWithNlsRequest:nlsRequest svcURL:nil];//requested 使用默认svcURL
  37. //vad:自动语音检测,可根据需要设置是否打开,YES为打开,NO为关闭。
  38. [r setVad:self.setVadFlag];
  39. r.delegate = self;
  40. r.cancelOnAppEntersBackground = YES;
  41. r.enableUserCancelCallback = YES;
  42. self.recognizer = r;
  43. NSString *nlsRequestJSONString = [NlsRequest getJSONStringfromNlsRequest:nlsRequest];
  44. NSLog(@"setupAsrIn : %@",nlsRequestJSONString);
  45. //开始语音识别
  46. [self.recognizer start];
  47. }
  48. - (void)onStopAsrButtonClick:(id)sender {
  49. //结束语音识别
  50. [self.recognizer stop];
  51. }
  52. #pragma mark - Notification Callbacks
  53. -(void)asrStatusChanged:(NSNotification*)notify{
  54. //处理网络变化
  55. }
  56. #pragma mark - RecognizerDelegate
  57. -(void) recognizer:(NlsRecognizer *)recognizer didCompleteRecognizingWithResult:(NlsRecognizerResult*)result error:(NSError*)error{
  58. //处理识别结果和错误信息
  59. //若appkey为流式返回appkey,将会多次回调该方法
  60. }
  61. -(void) recognizer:(NlsRecognizer *)recognizer recordingWithVoiceVolume:(NSUInteger)voiceVolume{
  62. //处理音量变化
  63. }
  64. -(void) recognizerDidStartRecording:(NlsRecognizer *)recognizer{
  65. //处理开始识别事件
  66. }
  67. -(void) recognizerDidStopRecording:(NlsRecognizer *)recognizer{
  68. //处理结束识别事件
  69. }
  70. @end
本文导读目录