京东AI开放平台语音SDK用户接入手册V1.0
1. 概述
本文档是京东语音iOS SDK的用户指南,SDK集成了京东AI语音相关基础服务,描述了语音识别等相关接口的使用说明。
1-1. 基础功能
当前主要支持的功能 : 基本功能:录音,语音数据处理,语音端点检测,网络通讯,状态通知,实时反馈语音能量,识别结果返回等。
2. 使用说明
2-1. 下载地址
2-2. 鉴权说明
平台为每个API提供试用体验服务,您在AI市场选择“免费试用”规格下单后,即可开始体验业内领先的人工智能API服务。 免费试用服务具有调用量、QPS限制,如需更高性能的API服务,可以提交咨询工单,联系京东AI扩容购买。
该SDK封装ASR API的功能,需要先参考 接入流程 获取AppKey和SecretKey,并在调用SDK时作为参数传入。
3. 兼容性
类别 | 兼容范围 |
---|---|
系统 | 支持iOS8.0及以上系统 |
架构 | armv7、arm64、i386、x86_64 |
网络 | 支持移动网络、WIFI等网络环境 |
外设 | 设备有麦克风输入 |
开发环境 | 建议使用最新版本Xcode进行开发 |
4. 资源占用描述
SDK类型 | 文件 | 大小 |
---|---|---|
语音识别 JD_Speech.framework头文件 | JDAISASRDefines.h JDAISASRParameters.h JDAISSpeechManager.h |
7.7K |
语音识别 JD_Speech.framework头文件静态库 | JD_Speech | 26.4M |
VAD 模型文件 | JD_Speech_vad.bin | 635KB |
开启和关闭BITCODE对于最终编译大小影响不大,编译开启了BITCODE选项。 由于 BITCODE 开启会导致二进制文件体积增大,这部分会在 AppStore 发布时进行进一步编译优化,并不会引起最终文件的体积变化。 虽然ipa的包会有增大,但实际在AppStore的优化下,用户下载的应用大小会远小于ipa文件的大小。
5. 集成
5-1. Demo工程
强烈建议在使用iOS SDK之前,运行并试用Demo工程相关功能,参考Demo工程的调用和配置的方式。
- 双击使用Xcode打开JDASR_Speech_Test/JD_Speech_Test.xcodeproj
- 确保网络通畅,运行工程
5-2. 获取麦克风权限
首先要为APP声明使用麦克风权限,在新建的应用下面找到info.plist,然后在其中新增麦克风权限的声名:
<key>NSMicrophoneUsageDescription</key>
<string>microphoneDesciption</string>
这样添加了之后,系统就知道了APP要访问系统的麦克风权限。
5-3. 添加头文件和静态库
JD_Speech_vad.bin模型文件,将拖入工程目录作为Copy Bundle Resources。
JD_Speech.framework提供的是静态库,开发者只需要将库文件拖入工程目录即可,可参考demo程序的引用。
6. 语音SDK接口说明
详细接口代码请参考SDK头文件
JDAISSpeechManager.h
JDAISASRDefines.h
JDAISASRParameters.h
语音识别类:
JDAISSpeechManager
初始化对象:
// engineType
//引擎类型: JDAIS_ENGINETYPE_ASR
(instancetype) create : (NSString *)engineType;
设置监听回调:
//setListener
//语音状态回调接口
//请参考JDAISASRDefines.h头文件中的JDAISClientASRDelegate协议并且实现相关接口
(void) setListener : (id)setListener;
发送识别请求:
// cmd
// 语音识别命令,请参考JDAISASRDefines.h中定义
// JDAIS_ASR_CMD_START 开始识别
// JDAIS_ASR_CMD_CANCEL 取消识别
// JDAIS_ASR_CMD_STOP 停止识别
// params
// 参数列表,JSON格式类型,具体参数定义参考JDAISASRParameters.h
(void) send : (NSString *)cmd withParams:(NSString *)params;
params参数列表字段说明
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
JDAIS_ASR_SAMPLE | NSInteger | 否 | 录音采样率 16000(默认) |
JDAIS_ASR_DOMAIN | NSString | 否 | 领域模型,默认"search" |
JDAIS_ASR_SERVER_VAD_ENABLE | bool | 否 | 是否开启云端vad截断,0 关闭(默认),1 开启 |
JDAIS_ASR_APPKEY | NSString | 是 | 鉴权认证使用,具体参考鉴权说明 |
JDAIS_ASR_SECRETKEY | NSString | 是 | 鉴权认证使用,具体参考鉴权说明 |
JDAIS_ASR_AUDIO_SOURCE | NSString | 否 | 语音识别音频来源,默认从录影机输入,设置的文件路径格式为 "/sdcard/audio.pcm" |
JDAIS_ASR_RECOGNIZE_TYPE | NSInteger | 否 | 语音识别类型,0 实时识别,1,一句话识别(默认) |
JDAIS_ASR_IS_NEED_RECORD_FILE | NSInteger | 否 | 是否保存录音文件,0 不保存(默认),1 保存 |
JDAIS_ASR_RECORD_FILE_PATH | NSString | 否 | 保存文件路径,在JDAIS_ASR_IS_NEED_RECORD_FILE 设置后生效 |
JDAIS_ASR_POST_PROCESS_ENABLE | NSInteger | 否 | 是否开启后处理,0 不开启(默认),1 开启 |
JDAIS_ASR_PARTISAL_RESULT_ENABLE | NSInteger | 否 | 是否开启实时识别结果返回,0 不开启(默认), 1 开启 |
JDAIS_ASR_VAD_START_DELAY | float | 否 | 本地vad开始点延时范围(单位秒)[0.25,0.5] 默认0.25 |
JDAIS_ASR_VAD_END_DELAY | float | 否 | 本地vad结束点延时(单位秒)[0.4,2.0] 默认0.5 |
JDAIS_ASR_LOCAL_VAD_ENABLE | NSInteger | 否 | 是否启用本地vad,0 不开启,1 开启(默认) |
JDAIS_ASR_PHRASE_LIST | JSONString | 否 | 个性词表短语列表(JSON数组格式) |
语音识别状态回调:
@protocol JDAISClientASRDelegate<NSObject>
//event
//回调事件,请参考JDAISSASRDefines.h中定义
//EV_SJDAIS_ASR_SpeechStart 准备就绪,开始录音
//EV_SJDAIS_ASR_SpeechBegin 用户开始说话
//EV_SJDAIS_ASR_SpeechEnd 用户结束说话
//EV_SJDAIS_ASR_SpeechVolume 音量回调
//EV_SJDAIS_ASR_SpeechParitalResult 临时识别结果
//EV_SJDAIS_ASR_SpeechResult 最终结果
//result
//相关回调事件返回携带的结果,jSSON格式
//data
// 相关事件返回携带的音频数据,例如保存录音数据到本地
- (void)onEventSpeechRecognition:(NSString *)event withResult:(NSString*)result withData:(NSData *)data;
@end
result 参数JSON 字符串说明
名称 | 描述 | 取值 |
---|---|---|
result | 相关回调事件返回结果的JSON格式 | EV_SJDAIS_ASR_SpeechStart 准备就绪,开始录音 EV_SJDAIS_ASR_SpeechBegin 用户开始说话 EV_SJDAIS_ASR_SpeechEnd 用户结束说话 EV_SJDAIS_ASR_SpeechVolume 音量回调 EV_SJDAIS_ASR_SpeechParitalResult 临时识别结果 EV_SJDAIS_ASR_SpeechResult 最终结果 EV_SJDAIS_ASR_SpeechStart、EV_SJDAIS_ASR_SpeechBegin、EV_SJDAIS_ASR_SpeechEnd事件没有result事件返回。 EV_SJDAIS_ASR_SpeechVolume 对应的result格式:{“volume”: “20”} EV_SJDAIS_ASR_SpeechParitalResult,EV_SJDAIS_ASR_SpeechResult 格式一致 { “err_code”: “0” //识别错误 码,0 : 识别成功,非0 : 识别失败, 其他错误 信息见错误码 “request_id": “fe0c804d-dec9-4a80-8167-b730b697ee5b” “err_msg”: “speech recognition success” //错误信息 “context”:[{ // 识别文本,如果识别失败将不返回 “text”: “背 多 卢比” }] } |
Demo实例
// 实例化
JDAISSpeechManager* _JDSpeechManager = [JDAISSpeechManager create: JDAIS_ENGINETYPE_ASR];
// 注册监听回调
[_JDSpeechManager setListener:self];
// 设置参数
NSString *path =
[[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingPathComponent:@"HandelAudio.pcm"];
_asrSpeechManagerConfig = @{
JDAIS_ASR_SAMPLE:@(EVoiceRecognizeSampleRate16K),
JDAIS_ASR_DOMAIN:@(EVoiceRecognizeDomainSearch),
JDAIS_ASR_SERVER_VAD_ENABLE:@(EVoiceRecognizeVADEnabledNO),
// 申请的Appkey 和secretkey
JDAIS_ASR_APPKEY:@"1234",
JDAIS_ASR_SECRETKEY:@"1234",
JDAIS_ASR_RECOGNIZE_TYPE:@(_recognizeType), JDAIS_ASR_IS_NEED_RECORD_FILE:@(EVoiceRecognizeRecordAudioNO),
JDAIS_ASR_RECORD_FILE_PATH:path,
};
// 启动识别
[self.JDSpeechManager send:JDAIS_ASR_CMD_START
withParams:[HandelAudioDemoVC convertToJsonData:_asrSpeechManagerConfig]];
7. 常见问题及错误码描述
错误码 | 描述 | 错误原因 | 备注 |
---|---|---|---|
0 | 识别成功 | ||
-1001 | 录音异常 | 录音机被占用或者录音设备异常 | |
-1002 | 权限异常 | 未声明录音权限或者权限被其他软件限制 | |
-1003 | 网络连接失败 | 没有网络权限或者网络未连接 | |
-1004 | 网络超时 | 网络质量差 | |
-1005 | 语音太长 | 说话事件超出限制,语音最大长度为60秒 | |
-1006 | 没有识别到语音 | 用户没有说话 | |
-1007 | 服务端错误 | 服务器识别过程出错 | |
-1008 | 客户端错误 | 参数配置出错,集成过程中参数设置出错,请参照开发文档检查 | |
-1009 | 语音格式错误 | SDK只接收PCM或者WAV格式语音 | |
-1010 | AppId鉴权失败 | AppId没有设置或者不合法设置,请发送邮件到jdai-speech@jd.com进行申请 | |
-1011 | 语音文件头出错 | 文件头信息校验出错,请检查语音是否正常 | |
-1012 | 语音采样率或者通道错误 | SDK要求采样率为8000/16000单通道 | |
-1013 | Vad 初始化失败 | Vad 资源配置错误 |