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

Size: px

Start display at page:

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

圳似鄂
4 years ago
Views:

云知声智能语音交互平台音乐搜索方案 SDK Android 开发指南 V2.0.

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

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

3 目录 1. 概述目的范围使用开发开发前准备支持的平台环境搭建音乐搜索方案 SDK 示例语音理解示例音乐搜索方案 SDK 接口定义语音理解对象 (USCSpeechUnderstander) 创建对象设置 VAD 超时设置在线识别带宽设置回调接口开始语音理解文本理解停止语音理解取消语音理解上传用户数据语音理解对象回调接口 (USCSpeechUnderstanderListener) 语音识别开始回调检测到开始说话录音设备打开录音停止语音识别结果回调... 9

4 语义解析结果回调结束回调 VAD 超时回调音量大小回调上传结果回调语义结果对象 (USCUnderstanderResult) 获取语义结果获取语义请求文本附录 1:Android 开发环境搭建附录 2: 错误代码 FAQ... 16

5 1. 概述云知声智能语音交互平台旨在使第三方应用便利的集成和使用语音理解 ( 语音云和语义云 ) 服务本 SDK 开发包针对音乐搜索方案定制优化, 使开发者可以迅速开发基于音乐搜索需求的客户端软件, 准确的定位用户寻找的音频资源方案支持多维度的口语化的搜索需求, 可以按照专辑歌手等维度进行单独搜索和组合搜索, 最大程度满足用户的开放式搜索需求本文档默认读者已经掌握 Android 应用程序开发的相关知识 1.1. 目的本文档对云知声音乐搜索方案 SDK 接口定义进行文档读者为使用云知声音乐搜索方案 SDK 进行开发的产品设计师软件工程师 1.2. 范围本文档定义云知声音乐搜索方案 SDK 的使用体系结构 API 接口不包含核心引擎的性能定义, 也不包含其它配套或附赠产品的使用 2. 使用 2.1. 开发本文属于入门级文档, 旨在帮助开发者快速学习云知声 SDK 的使用, 并应用到实际的开发工作中, 开发者仅需关注文档中所提供的接口而不用了解具体实现 2.2. 开发前准备对于个人开发者使用云知声语音服务, 请到注册成为云知声开发者, 并创建应用, 在我的应用中获取 AppKey 和 AppSecret 使用应用授权码可以帮助开发者监控语音识别服务的使用情况 1

6 2.3. 支持的平台系统 : 支持 Android 2.1 及以上系统通过 minsdkversion 检测机型 : 手机平板及其它智能终端设备架构 : 支持 arm x86 及 mips 平台外设 : 设备上有麦克风网络 : 有网络连接 3. 环境搭建本文档默认开发者已掌握 JDK Eclipse Android SDK ADT 等相关 Android 开发工具的搭建, 如要查看 Android 开发环境搭建的相关流程, 请参考 Android 开发环境搭建 1) 在 Eclipse 中建立 Android 工程 2) 将开发工具包中的 libs 目录拷贝到工程根目录下, 确保 libuscasr.so 文件存在 : so 动态库包含 armeabi armeabi-v7a mips x86 四种架构, 对于普通 Android 手机开发者, 如果不需要支持特殊机型, 只需引入 armeabi 架构 so 动态库即可, 以减少应用程序安装包大小 3) 在 Eclipse 中右键单击工程, 选择 Project->Properties->Java Build Path->Libraries->Add JARS 或 ADD External JARS 导入工程 libs 目录下的 usc.jar 文件 4) 在工程 AndroidManifest.xml 文件中添加如下权限 <uses-permission android:name="android.permission.record_audio"/> <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.access_wifi_state"/> <uses-permission android:name="android.permission.read_phone_state"/> 各权限的使用 android.permission.record_audio android.permission.internet android.permission.access_network_state android.permission.access_wifi_state android.permission.read_phone_state 用途允许应用使用麦克风允许应用联网, 发送语音数据至服务器, 获得识别结果获取当前网络状态, 优化录音及网络获取当前 wifi 状态, 优化录音及网络获取用户手机的 IMEI, 用来唯一标示用户 2

7 4. 音乐搜索方案 SDK 示例 4.1. 语音理解示例 // 创建语音理解对象,appKey 和 secret 通过网站申请 USCSpeechUnderstander munderstander= new USCSpeechUnderstander(this,appKey,secret); String recognizertext = ""; // 识别结果 String understandtext = ""; // 语义结果 // 语音理解对象回调监听 munderstander.setlistener(new USCSpeechUnderstanderListener() { public void onrecognizerresult(string result, boolean islast) { // 语音识别结果实时返回, 保留识别结果组成完整的识别内容 recognizertext += result; public void onunderstanderresult(uscunderstanderresult result) { // 语义结果返回 understandtext = result.getstringresult(); public void onend(uscerror error) { // 语音理解结束 if(error == null) { // 识别成功, 可在此处理 text 结果 public void onvadtimeout() { // 用户停止说话回调 mrecognizer.stop(); public void onupdatevolume(int volume) { // 实时返回说话音量 0~100 public void onuploaduserdata(uscerror error) { // 完成个性化用户数据上传 public void onrecognizerstart() { // 录音设备打开识别开始, 用户可以开始说话 public void onrecordingstop(list<byte[]> arg0) { // 停止录音, 等待识别结果回调 public void onspeechstart() { // 用户开始说话回调 ); // 开始 munderstander.start(); 3

8 5. 音乐搜索方案 SDK 接口定义 5.1. 语音理解对象 (USCSpeechUnderstander) 创建对象 public USCSpeechUnderstander(Context context, String appkey, String secret) context appkey secret 描述上下文环境申请应用后获得的 App Key 申请应用后获取的 secret 1 请到网站创建应用并从我的应用中获取 appkey 和 appsecret 设置 VAD 超时 public void setvadtimeout(int fronttime, int backtime) fronttime backtime 描述用户不说话超时时间, 参考范围为 2000ms~5000ms 用户停止说话自动停止录音时间, 范围为 200ms~3000ms 4

9 1 超时单位为 ms, 默认 fronttime 为 3000ms,backTime 默认为 1000ms 设置在线识别带宽 public 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 时自动根据当前的网络环境切换到最佳的采样频率设置回调接口 public void setlistener(uscspeechunderstanderlistener listener) listener 描述回调接口, 通知外部获取识别结果和语义解析结果 5

10 1 开发者需要实现此接口以获得语音识别的结果和语义解析结果, 具体请参考 USCSpeechUnderstanderListener 接口 2 如果用户调用 cancel 取消了当前的语音理解, 将不会再有消息通过此接口调用开始语音理解 public void start() 1 启动录音和识别, 收到 onrecognizerstart 回调代表启动成功, 用户才可以说话 2 如果取到识别结果, 会通过 onrecognizerresult 回调取到的结果并且可以通过 onunderstanderresult 取得语义解析结果 3 如果识别过程中出现错误, 可以通过 onend 回调错误信息, 具体请参照 onend 接口文本理解 public void textunderstander(string text) text 描述需要语义解析的文本 1 如果用户需要手动输入文本以进行语义理解操作, 可以调用此, 而不需走语音输入进行语义请求 6

11 停止语音理解 public void stop() 1 停止录音并等待语音理解结束 2 语音理解结束标志为收到 onend 回调, 具体参照 onend 接口取消语音理解 public void cancel() 1 本调用后, 放弃当前语音理解任务, 本次任务状态不再回调 2 应用被切换到后台时, 请用户调用 cancel 上传用户数据 public void setuserdata(map<integer, List<String>> userdata) userdata 描述用户上传的个性化数据,map 的 key 为数据类型,value 为数据列表 7

12 1 目前支持 2 种上传的数据类型 : USCConfig.NAME USCConfig.APP 人名应用名 2 调用 setuserdata 会自动启动一个线程在后台处理, 用户不需要自己再创建线程 3 上传结果会通过回调 onuploaduserdata 通知, 具体参照 onuploaduserdata 接口 4 目前采用的是覆盖上传, 即后一次会覆盖掉前一次上传的数据 5 由于上传数据会耗流量, 建议在数据有变化的情况下再调用此上传 5.2. 语音理解对象回调接口 (USCSpeechUnderstanderListener) 语音识别开始回调 public void onrecognizerstart() 1 录音初始化完成, 识别启动时, 回调此 2 由于录音初始化需要时间, 如果录音没有初始化完成就开始说话, 可能会导致语音前半部分被截断, 从而影响识别效果, 因此不能调用 start 后就开始说话, 而是要等待录音初始化完成才提示用户开始说话 3 建议开发者调用 start 后, 播放一个初始化的动画, 然后在 onrecognizerstart 中关闭此动画, 然后提示用户开始说话检测到开始说话 public void onspeechstart() 8

13 1 收到此回调代表已检测到用户开始说话 2 直到识别结束, 如果没有检测到用户说话不会有回调录音设备打开 public void onrecordingstart() 1 用户调用 start() 后, 录音设备打开会回调此录音停止 public void onrecordingstop() 1 录音停止回调, 请等待识别结果回调 2 当用户调用 stop() 停止录音, 会回调此录音停止语音识别结果回调 public void onrecognizerresult(string result, boolean islast) 9

14 result islast 描述识别结果 true 表示最后一次结果,false 表示结果未取完 1 控件采用边录音边识别方式, 可能会多次返回结果,isLast 为 true 表示识别结果已经取完, 随后将进行语义解析任务 false 表示结果未取完 2 建议用户在此接口中先将数据保存起来, 然后在 onend 中再进行下一步处理语义解析结果回调 public void onunderstanderresult(uscunderstanderresult result) result 描述语义返回结果 1 当语音识别结束时即 onrecognizerresult 中 islast 为 true 时进行语义解析任务 2 由于语义结果数据较为复杂, 请查看 USCUnderstanderResult 接口根据自己的需求获取需要的数据 10

15 结束回调 public void onend(uscerror error) error 描述标识语音理解是否成功 : 识别成功返回 null, 否则返回错误信息 1 onend 回调时, 表示本次语音理解过程结束 2 如果语音理解成功,error 为 null 3 错误代码相关请参考附 2: 错误代码 VAD 超时回调 public void onvadtimeout() 1 录音过程中, 如果用户间隔一段时间没有说话, 会回调此 2 用户可以在此中调用 stop 停止录音, 等待识别结果音量大小回调 public void onupdatevolume(int volume) 描述 11

16 volume 录音时音量大小 1 录音过程中会不断的回调此, 实时返回音量大小 (0 到 100) 值越大表示音量越大 2 用户可以根据 volume 的大小来实现音量变化的动画效果上传结果回调 public void onuploaduserdata(uscerror error) error 描述标识上传是否成功 : 上传成功返回 null, 否则返回错误信息 1 错误代码相关请参考附 2: 错误代码 5.3. 语义结果对象 (USCUnderstanderResult) 获取语义结果 public String getstringresult() 返回以字符串为格式的语义解析结果 12

17 1 音乐搜索方案默认选择音乐服务, 语义服务详情请参考 <<USC_Semantic_Parsing_Service_Protocol>> 语义解析协议文档 2 语义结果字符串中各个字段含义: 服务 ID: cn.yunzhisheng.music 功能描述 : 音乐查询操作码 (code): 取值 SEARCH_SONG SEARCH_ARTIST SEARCH_RANDOM SEARCH_BILLBOARD 按歌曲名搜索按歌手名搜索随机搜索, 随机来一首歌新歌和热歌排行榜语义表示 : 字段字段类型取空值 intent Song String YES 歌曲名, 若能识别到则有 Artist String YES 歌手名, 若能识别到则有 Genre String YES 音乐流派, 若能识别到则有 Keyword String NO 歌曲搜索的关键字特别地,code 为 SEARCH_BILLBOARD, 值可以为 HOT 和 NEW 表示搜索热门歌曲和最新歌曲 13

18 范例 : 歌曲查找 { "rc": 0, "text": " 来一首许巍的蓝莲花 ", "service": "cn.yunzhisheng.music","code": "SEARCH_SONG", "semantic": { "intent": { "artist":" 许巍 ","song":" 蓝莲花 ","keyword":" 许巍蓝莲花 " 获取语义请求文本 public String getrequesttext() 返回语义请求文本即语音识别的结果附录 1:Android 开发环境搭建本 SDK 支持的操作系统为 :Windows Mac OS X Linux 这里将介绍 Windows 上安装环境的搭建 : 1) 安装 JDK, 开发者可以从 Java 官网下载所需的版本 ; 2) 安装 Eclipse Java IDE, 可以从官网下载所需的版本 ; 3) 安装 Android SDK, 可以从 Android 官方网站下载所需的版本 ; 4) 安装 ADT 插件, 启动 eclipse 后, 点击 eclipse 的 Help->soft update->find and install->search for 14

19 new features to install->new remote site->name: 完成安装后重启 eclipse; 5) 安装 Android DDMS 和 Android Development Tools; 至此您已经完成了 Android 开发环境的搭建, 更多 Android 了解请参考 SDK 的开发指导文档附录 2: 错误代码错误代码代码解释服务器通讯错误服务器连接失败服务器验证错误说话时间超出限制数据压缩错误启动录音失败录音异常识别异常上传个性化数据服务器拒绝上传个性化数据网络连接失败上传个性化数据不能为空上传个性化数据内容太多上传个性化数据过于频繁上传个性化数据编码失败上传场景数据 : 服务器拒绝上传场景数据 : 网络连接失败上传场景数据 : 不能为空 15

20 上传场景数据 : 内容太多上传场景数据 : 编码失败上传场景数据 : 上传过于频繁 -101 语音播放异常 -400 app key 验证不通过 -401 app key 验证不通过 -402 服务器出错 -403 语音合成文本太长 -404 服务器认证失败 -405 服务器繁忙 FAQ 1. 如何联系我们? 如果应用开发过程中遇到问题, 可随时与我们联系, 联系方式如下 : QQ 语音云交流群 : 联系电话 :(+8610-) 传真 :(+8610-) 请发邮件至 :support@yunzhisheng.cn 16

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

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