云知声语音云应用开发指南

Size: px

Start display at page:

Download "云知声语音云应用开发指南"

稍暌极乔
5 years ago
Views:

1 云知声智能语音交互平台通用方案 SDK ios 开发指南北京云知声信息技术有限公司 Beijing Unisound Information Technology Co.,Ltd.

2 重要声明版权声明版权所有 2013, 北京云知声信息技术有限公司, 保留所有权利商标声明北京云知声信息技术有限公司的产品是北京云知声信息技术有限公司专有在提及其他公司及其产品时将使用各自公司所拥有的商标, 这种使用的目的仅限于引用本文档可能涉及北京云知声信息技术有限公司的专利 ( 或正在申请的专利 ) 商标版权或其他知识产权, 除非得到北京云知声信息技术有限公司的明确书面许可协议, 本文档不授予使用这些专利 ( 或正在申请的专利 ) 商标版权或其他知识产权的任何许可协议不作保证声明北京云知声信息技术有限公司不对此文档中的任何内容作任何明示或暗示的陈述或保证, 而且不对特定目的的适销性及适用性或者任何间接特殊或连带的损失承担任何责任本手册内容若有变动, 恕不另行通知本手册例子中所用的公司人名和数据若非特别声明, 均属虚构未得到北京云知声信息技术有限公司明确的书面许可, 不得为任何目的以任何形式或手段 ( 电子的或机械的 ) 复制或传播手册的任何部分保密声明本文档 ( 包括任何附件 ) 包含的信息是保密信息接收人了解其获得的本文档是保密的, 除用于规定的目的外不得用于任何目的, 也不得将本文档泄露给任何第三方本软件产品受最终用户许可协议 (EULA) 中所述条款和条件的约束, 该协议位于产品文档和 / 或软件产品的联机文档中, 使用本产品, 表明您已阅读并接受了 EULA 的条款版权所有北京云知声信息技术有限公司 Copyrights Beijing Unisound Information Technology Co., Ltd.

3 目录 1. 概述目的范围使用开发开发前准备支持的平台环境搭建通用方案 SDK 接口定义语音理解对象 (USCSpeechUnderstander) 创建对象设置 VAD 超时设置在线识别录音采样率开始语音理解文本理解停止语音理解取消语音理解设置识别语言设置识别超时时间设置识别领域语音理解对象回调 (USCSpeechUnderstanderDelegate) 语音识别开始回调检测到开始说话语音识别结果回调语义解析结果回调结束回调... 10

4 VAD 超时回调音量大小回调语义结果对象 (USCUnderstanderResult) 获取语义结果获取语义结果 (JSON 格式 ) 示例代码附录 1: 错误代码 FAQ... 13

5 1. 概述云知声智能语音交互平台旨在使第三方应用便利的集成和使用语音理解 ( 语音云和语义云 ) 服务本 SDK 开发包针对通用方案定制优化, 使开发者可以迅速开发基于通用需求的客户端软件通用方案内置了基础的技术服务, 并不包含内容服务, 为开发者提供创建一个全新自定义应用的入口本文档默认读者已经掌握 ios 应用程序开发的相关知识 1.1. 目的本文档对云知声通用方案 SDK 接口定义进行文档读者为使用云知声通用方案 SDK 进行开发的产品设计师软件工程师 1.2. 范围本文档定义云知声通用方案 SDK 的使用体系结构 API 接口不包含核心引擎的性能定义, 也不包含其它配套或附赠产品的使用 2. 使用 2.1. 开发本文属于入门级文档, 旨在帮助开发者快速学习云知声通用方案 SDK 的使用并应用到自身的开发工作中, 开发者仅需关注文档中所提供的接口而不用了解具体实现 1

6 2.2. 开发前准备对于个人开发者使用语音服务, 需要经过我们的授权, 请到注册成为我们的开发者, 并创建应用, 在我的应用中获取 AppKey 和 AppSecret 使用该应用授权码可以帮助开发者监控语音识别服务的使用情况 2.3. 支持的平台系统 : 支持 ios5.1.1 及以上系统机型 : iphone,ipad,ipod 等苹果设备构架 : 支持 armv7, armv7s,armv64 硬件要求 : 设备上有麦克风网络 : 有网络连接注意 : 由于模拟器的录音效果不好, 目前暂不提供模拟器版本的静态库 3. 环境搭建用户需使用 MAC OS X 及以上操作系统, 安装 XCode 开发工具, 使用公有云服务需要网络连接 1 打开 XCode 新建一个项目, 把 usc_ios_commonschema_sdk_v1.5 文件夹中的 lib 文件夹下的所有文件 ( 如下图 ) 添加到自己的项目中, 在弹出的窗口中勾选 Copy items into destination group s folder(if needed), 确保 TARGETS->Build Phases->Link Binary With Libraries 引用 libusc.a : 打开 Configure.h 文件, 设置 APPKEY 和 SECRET 2

7 2 要添加如下 Frameworks 库 : 3 由于静态库采用 C++ 混编, 修改相关文件的.m 后缀为.mm 如把 ViewController.m 改成 ViewController.mm 4 导入如下头文件 #import "USCSpeechUnderstander.h" #import "USCSpeechResult.h" #import "Configure.h" 5 具体详细用法请参看 demo 中的示例代码 6 如果项目要适配 ios8, 要在项目的 Info.plist 文件中添加 NSLocationAlwaysUsageDescription, 来支持定位如下图所示 : 3

8 4. 通用方案 SDK 接口定义 4.1. 语音理解对象 (USCSpeechUnderstander) 创建对象 - (id)initwithcontext:(nsstring*)context appkey:(nsstring *)appkey secret:(nsstring *)secret; 参数 context: 上下文环境, 一般设置 nil 即可 appkey: 申请应用后获得的 AppKey secret: 申请应用后获取的 Secret 1 请到网站创建应用并从我的应用中获取 App Key 和 secret 示例 : USCSpeechUnderstander *speechunderstander=[[uscspeechunderstander alloc]initwithcontext:nil appkey:appkey secret:secret]; 设置 VAD 超时 -(void)setvadfronttimeout:(int)fronttime BackTimeout:(int)backTime; 参数 fronttime: 用户不说话超时时间 backtime: 用户停止说话自动停止录音时间, 范围为 200~3000ms 1 超时单位为 ms, 默认 fronttime 为 3000ms,backTime 默认为 1000ms 示例 : 4

9 [self.speechunderstander setvadfronttimeout:3000 backtime:1000]; 设置在线识别录音采样率 - (void)setbandwidth:(int)rate; 参数 rate: 设置录音采样率, 支持参数 BANDWIDTH_AUTO RATE_8K RATE_16K, 默认为 RATE_16K 1 为了获得更好的识别效果推荐使用 RATE_16K 采样率对网络带宽要求 RATE_16K 2KB/ 秒, RATE_8K 1KB/ 秒 2 当设置成 BANDWIDTH_AUTO 时自动根据当前的网络环境切换到最佳的采样频率示例 : [self.speechunderstander setbandwidth:rate_16k]; 开始语音理解 - (void)start; 1 启动录音和识别, 收到 onrecognizerstart 回调代表启动成功, 用户才可以说话 2 如果取到识别结果, 会通过 onrecognizerresult 回调取到的结果, 语义解析结果通过 onunderstanderresult 回调取得 3 如过程中出现了错误, 会通过 onend 回调错误信息, 具体参照 onend 接口示例 : [self.speechunderstander start]; 5

10 文本理解 - (void)textunderstander:(nsstring *)text; 参数 : text: 需要语义解析的文本 1 如果用户需要手动输入文本以进行语义理解操作, 可以调用此, 而不必走语音输入进行语义请求示例 : [self.speechunderstander textunderstander:@" 明天的天气?"]; 停止语音理解 - (void)stop; 1 停止录音并等待语音理解结束 2 语音理解结束标志为收到 onend 回调, 具体参照 onend 接口示例 : [self.speechunderstander stop]; 取消语音理解 - (void)cancel; 1 本调用后, 放弃当前语音理解任务, 本次任务状态不再回调 6

11 2 应用被切换到后台时, 请用户调用 cancel 示例 : [self.speechunderstander cancel]; 设置识别语言 - (void)setlanguage:(nsstring *)language; 参数 : language: 语言可以设置 "chinese" ( 普通话 ), "english" ( 英文 ), "cantonese" ( 粤语 ) 默认为普通话示例 : [self.speechunderstander setlanguage:@"english"]; 设置识别超时时间 - (void)setrecognizationtimeout:(float)recognizationtime; 参数 : recognizationtime: 识别超时时间默认 30 秒示例 : [self.speechunderstander setrecognizationtimeout:30.f]; 设置识别领域 - (BOOL)setEngine:(NSString *)engine; 参数 : 7

12 名称 engine 描述识别领域选择, 参考以下 6 种 1. "general": 通用识别 2. "poi": 地名识别 3. "song": 歌名识别 4. "movietv": 影视名识别 5. "medical": 医药领域识别示例 : [self.speechunderstander setengine:@"poi"]; 4.2. 语音理解对象回调 (USCSpeechUnderstanderDelegate) 语音识别开始回调 - (void)onrecognizerstart; 1 录音初始化完成, 识别启动时, 回调此 2 由于录音初始化需要时间, 如果录音没有初始化完成就开始说话, 可能会导致语音前半部分被截断, 从而影响识别效果, 因此不能调用 start 后就开始说话, 而是要等待录音初始化完成才提示用户开始说话 3 建议开发者调用 start 后, 播放一个初始化的动画, 然后在 onrecognizerstart 中关闭此动画, 然后提示用户开始说话检测到开始说话 - (void)onspeechstart; 8

13 1 收到此回调代表已检测到用户开始说话 2 直到识别结束, 如果没有检测到用户说话不会有回调语音识别结果回调 - (void)onrecognizerresult:(nsstring *)result islast:(bool)islast; 参数 result: 识别返回的文字结果 islast: 是不是最后一次返回文字 1 控件采用边录音边识别方式, 可能会多次返回结果,isLast 为 true 表示识别结果已经取完, 随后将进行语义解析任务 false 表示结果未取完 2 建议用户在此接口中先将数据保存起来, 然后在 onend 中再进行下一步处理语义解析结果回调 - (void)onunderstanderresult:(uscspeechresult *)result; 参数 result: 返回的语义理解结果 1 当语音识别结束时即 onrecognizerresult 中 islast 为 true 时进行语义解析任务 2 由于语义结果数据较为复杂, 请查看 USCUnderstanderResult 接口根据自己的需求获取需要的数据 9

14 结束回调 - (void)onend:(nserror *)error; 参数 error: 标识语音理解是否成功 : 识别成功返回 nil, 否则返回错误信息 1 onend 回调时, 表示本次语音理解过程结束 2 如果语音理解成功,error 为 nil 3 错误代码相关请参考附 1: 错误代码 VAD 超时回调 - (void)onvadtimeout; 1 录音过程中, 如果用户间隔一段时间没有说话, 会回调此 2 用户可以在此中调用 stop 停止录音, 等待识别结果音量大小回调 - (void)onupdatevolume:(int)volume; 参数 volume: 录音时音量大小 1 录音过程中会不断的回调此, 实时返回音量大小 (0 到 100) 值越大表示音量越大 2 用户可以根据 volume 的大小来实现音量变化的动画效果 10

15 4.3. 语义结果对象 (USCUnderstanderResult) 获取语义结果 : -(NSString *)responsetext; 返回 : 返回的 JSON 中的文本返回的是 JSON 中 "general" 中 "text" 相对应的文本, 无则返回空获取语义结果 (JSON 格式 ) (NSString *)stringresult; 返回以 JSON 格式的语义解析结果, 可以根据需求获取 json 里面需要的数据 : 1 语义理解结果字符串中各个字段的含义请参考 <<USC_Semantic_Parsing_Service_Protocol.pdf>> 语义解析协议文档 11

16 5. 示例代码 // 1. 创建语义理解对象 USCSpeechUnderstander *speechunderstander = [[USCSpeechUnderstander alloc]initwithcontext:nil appkey:appkey secret:secret]; speechunderstander.delegate = self; // 2. 开始语义理解 [speechunderstander start]; : 具体详细代码请参照 demo 中代码附录 1: 错误代码错误代码代码解释服务器通讯错误服务器连接失败服务器验证错误说话时间超出限制数据压缩错误启动录音失败录音异常识别异常 12

17 FAQ 1. 如何联系我们? 如果应用开发过程中遇到问题, 可随时与我们联系, 联系方式如下 : QQ 语音云交流群 : 联系电话 :(+8610-) 传真 :(+8610-) 请发邮件至 :support@yunzhisheng.cn 13

云知声语音云应用开发指南

云知声语音云应用开发指南云知声智能语音交互平台语音输入方案 SDK Android 开发指南 V2.0.03 北京云知声信息技术有限公司 Beijing Unisound Information Technology Co., Ltd. 重要声明版权声明版权所有 2013, 北京云知声信息技术有限公司, 保留所有权利商标声明北京云知声信息技术有限公司的产品是北京云知声信息技术有限公司专有在提及其他公司及其产品时将使用各自公司所拥有的商标,