离线命令词识别 Android SDK 文档

1、简介

离线命令词识别,是基于语法规则,将与语法一致的自然语言音频转换为文本输出的技术。语法识别的结果值域只在语法文件所列出的规则里,故有很好的匹配率,另外,语法识别结果携带了结果的置信度,应用可以根据置信分数,决定这个结果是否有效。语法识别多用于要更准确结果且有限说法的语音控制,如空调的语音控制等。在使用离线语法识别时,需要设置本地语法名字(在语法文件中定义)。

离线命令词识别详细的接口介绍及说明请参考: MSC Android API 文档

在集成过程中出现错误,请优先查询SDK&API 错误码查询。如有疑问,请提交工单进行咨询,可登录讯飞开放平台论坛与广大开发者共同学习和交流。

2、SDK集成指南

2.1、Demo运行步骤

根据官网控制台提示,直接下载SDK,SDK中包含简易可运行的Demo。如下图所示:

下载完SDK后,解压至相应的路径。
注:使用demo测试时,需将res中除layout外资源拷贝到demo中assets相应的路径下
以Android Studio集成开发工具为例,测试时建议直接用真机进行测试。

方法一(导入project方式):

打开Android Studio,在菜单栏File--->new--->import project当前解压sdk路径,使用离线服务能力选择导入mscV5PlusDemo,如下图所示:

导入成功之后sync编译下,编译无误可连接手机,开启手机USB开发调试模式,直接在Android Studio运行导入的mscV5PlusDemo,最后生成的apk可直接安装在对应的手机上,如下图所示:

如果编译时出现“ERROR: Plugin with id 'com.android.application' not found.”错误,请在build.gradle文件中添加以下代码。

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
         //版本号请根据自己的gradle插件版本号自行更改
        classpath 'com.android.tools.build:gradle:3.4.0'
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

如在导入项目中还出现其他问题,可参考帖子:安卓demo常见错误排查

方法二(导入module方式):

打开Android Studio,在菜单栏File--->new--->import module当前解压sdk路径,使用离线服务能力选择导入mscV5PlusDemo,导入成功之后sync编译下,编译无误可连接手机,开启手机USB开发调试模式,直接在Android Studio运行导入的mscV5PlusDemo,最后生成的apk可直接安装在对应的手机上。

2.2、项目集成步骤

2.2.1、SDK包说明

《Android SDK目录结构一览》

  • sample:
    • 相关离线能力demo(离线命令词识别asrDemo)
  • assets:
    • SDK相关资源配置文件
  • Libs:
    • 动态库和jar包
  • res:
    • UI文件和相关布局文件xml
    • 离线服务离线资源
  • readme说明(必看)
  • release 版本说明

2.2.2、导入SDK

将在官网下载的Android SDK 压缩包中libs目录下所有子文件拷贝至Android工程的libs目录下。如下图所示:

注:

  1. arm版本已经逐步淘汰了,arm架构的推荐使用armeabi-v7a。
  2. 如果您需要将应用push到设备使用,请将设备cpu对应指令集的libmsc.so push到/system/lib中。
  3. 集成到项目,需要将sdk中Demo/src/main/下文件拷贝到项目main中,以AS为例,且需要在项目main文件夹下新建Jnilibs并拷贝libmsc.so。
  4. msc.jar需要拷贝至项目libs下,并且右键jar添加Add As Library。
  5. sdk下文件夹main/assets/,自带UI页面(iflytek文件夹)和相关其他服务资源文件(语法文件、音频示例、词表),使用自带UI接口时,可以将assets/iflytek文件拷贝到项目中;

2.2.3、添加用户权限

在工程 AndroidManifest.xml 文件中添加如下权限(可根据需求添加相关权限)

<!--连接网络权限,用于执行云端语音能力 -->
<uses-permission android:name="android.permission.INTERNET"/>
<!--获取手机录音机使用权限,听写、识别、语义理解需要用到此权限 -->
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<!--读取网络信息状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--获取当前wifi状态 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!--允许程序改变网络连接状态 -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<!--读取手机信息权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<!--读取联系人权限,上传联系人需要用到此权限 -->
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<!--外存储写权限,构建语法需要用到此权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!--外存储读权限,构建语法需要用到此权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<!--配置权限,用来记录应用配置信息 -->
<uses-permission android:name="android.permission.WRITE_SETTINGS"/>
<!--手机定位信息,用来为语义等功能提供定位,提供更精准的服务-->
<!--定位信息是敏感信息,可通过Setting.setLocationEnable(false)关闭定位请求 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<!--如需使用人脸识别,还要添加:摄相头权限,拍照需要用到 -->
<uses-permission android:name="android.permission.CAMERA" />

注意:如需在打包或者生成APK的时候进行混淆,请在proguard.cfg中添加如下代码:

-keep class com.iflytek.**{*;}
-keepattributes Signature

2.2.4、接入

为保证用户个人隐私,防止APP不当收集用户信息,我们强烈建议您遵守以下流程接入本SDK保证合规,防止因调用时机不当引发的后果,例如但不限于:APP被应用市场下架等。

(1)您需要确保贵APP有《隐私政策》,并且在用户首次启动App时就弹出《隐私政策》争得用户同意。

(2)您务必在App的《第三方共享清单及SDK目录》中告知用户MSC SDK收集的个人信息类型以及MSC SDK隐私政策。

(3)个人信息收集说明:MSC SDK需要收集唯一设备识别码(android ID)以提供能力授权服务。

(4)隐私政策请点击查看。

(5)您务必严格遵守如下调用步骤,确保用户同意《隐私政策》之后,且在用户主动使用本SDK提供的各项功能时再进行相关函数调用。

确保App启动后,在用户阅读并同意《隐私政策》并取得用户授权之后,在用户使用SDK功能时,方可调函数SpeechUtility.createUtility(SpeechApp.this,xxxx)以使用MSC SDK。反之,如果用户不同意《隐私政策》授权,则不允许调用SpeechUtility.createUtility(SpeechApp.this,xxxx)初函数。
参考示例:SDK demo源码中获取到《隐私政策》的用户授权,后续的SDK demo函数SpeechUtility.createUtility(SpeechApp.this, xxxx)建议在用户使用SDK功能时进行使用。

接入即创建语音配置对象,只有接入后才可以使用MSC的各项服务。接入代码如下:

// 将“12345678”替换成您申请的APPID,申请地址:http://www.xfyun.cn
// 请勿在“=”与appid之间添加任何空字符或者转义符
SpeechUtility.createUtility(context, SpeechConstant.APPID +"=12345678");

3、参数说明

3.1、基础参数说明

参数名称 名称 说明
ENGINE_TYPE 引擎类型 离线命令词识别为本地引擎。设置为:local
RESULT_TYPE 返回结果格式 主要分为三种:json,xml,plain
默认:json
ASR_THRESHOLD 识别门限值 门限值越高,则识别的成功率越低,但返回的结果与实际结果更接近
值范围:[0,100]
默认值:30
GRM_BUILD_PATH 语法构建目录 使用离线语法时,需要构建语法并保存到本地,在构建和使用语法时,都需要设置语法的构建目录。
值范围:有效的文件夹径值(含文件名)
默认值:null
ASR_RES_PATH 识别资源路径 离线命令词识别需要使用本地资源,通过此参数设置本地资源所在的路径
值范围:有效的资源文件路径
默认值:null

备注:以上均为SDK常用参数说明,均在setParam()方法里面设置,设置示例: mAsr.setParameter(SpeechConstant.IRESULT_TYPE, "local");;更多详细参数请参考:MSC Android API 文档.

3.2、构建语法

本文只对构建和使用语法的 SDK 调用过程进行介绍,关于语法的规则说明,请参考语法开发指南

3.2.1、构建BNF

在构建时,除了指定引擎为本地引擎,语法类型为BNF外,还必须指定离线资源的路径(MSC模式下,需下载使用对应的离线识别SDK),语法构建的路径——本地语法构建结果文件保存的路径:


// 设置引擎类型
mAsr.setParamter( SpeechConstant.ENGINE_TYPE, SpeechConstant.TYPE_LOCAL );

// 设置语法结果文件保存路径,以在本地识别时使用
mAsr.setParameter( ResourceUtil.GRM_BUILD_PATH, grmPath );
    
//设置识别资源路径
mAsr.setParameter( ResourceUtil.ASR_RES_PATH, asrResPath );

/* 其中 "bnf" 指定语法类型为 BNF,  grammarContent 为语法内容,grammarListener 为构建结果监听器*/
ret = mAsr.buildGrammar( "bnf", grammarContent, grammarListener );

构建语法状态通过监听器 grammarListener 获取,当构建成功时,语法文件将保存到由 grmPath 指定的目录中,将在语法识别时用到(MSC 模式下)。

3.2.2、更新词典

离线语法词典,旨在更新已构建的语法文件中某个规则里的内容,因此在更新时,需要指定识别资源路径,语法文件路径,语法列表(语法文件的语法名字)。词典的内容格式及更详细调用说明,参考MSC Android API 文档中 SpeechRecognizer 类的 updateLexicon 函数介绍。

mAsr.setParameter( SpeechConstant.ENGINE_TYPE, SpeechConstant.TYPE_LOCAL );

// 指定资源路径
mAsr.setParameter( ResourceUtil.ASR_RES_PATH, asrResPath );

// 指定语法路径
mAsr.setParameter( ResourceUtil.GRM_BUILD_PATH, grmPath );

// 指定语法名字
mAsr.setParameter( SpeechConstant.GRAMMAR_LIST, grammarName );

// lexiconName 为词典名字,lexiconContents 为词典内容,lexiconListener 为回调监听器
ret = mAsr.updateLexicon( lexiconName, lexiconContents, lexiconListener );

3.3、离线命令词识别结果

离线命令词结果返回可设置三种格式,结构如下:

json格式
=============================================================
{
    "sn":1,
    "ls":true,
    "bg":0,
    "ed":0,
    "ws":[
        {
            "bg":0,
            "cw":[
                {
                    "id":10001,
                    "sc":81,
                    "w":"打电话给",
                    "gm":0
                }
            ],
            "slot":"<dialpre>"
        },
        {
            "bg":0,
            "cw":[
                {
                    "id":65535,
                    "sc":100,
                    "w":"丁伟",
                    "gm":0
                }
            ],
            "slot":"<contact>"
        }
    ],
    "sc":94}
=============================================================

xml格式
=============================================================
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<nlp>
    <version>1.1</version>
    <rawtext>打电话给丁伟</rawtext>
    <confidence>92</confidence>
    <engine>local</engine>
    <result>
        <focus>dialpre|contact</focus>
        <confidence>79|100</confidence>
        <object>
            <dialpre id="10001">打电话给</dialpre>
            <contact id="65535">丁伟</contact>
        </object>
    </result>
</nlp>
=============================================================

plain格式
=============================================================
confidence=93 grammar=0 input=打电话给丁伟
=============================================================         

4、视频教程

视频教程

5、常见问题

目前安卓平台具体支持安卓版本

答:Android版本SDK目前支持4.4以上版本,React-Native ,QT 等跨平台方案,目前暂不支持

错误码及相应解决方案查询网址

答:错误码及相应解决方案查询

离线命令词sdk如何下载试用?

答:文档中心---快速指引有介绍步骤---根据步骤下载相应平台的离线命令词sdk,离线命令词SDK包有10个装机量,试用期为90天。

离线命令词识别支持多少命令词?

答:离线识别的命令词是开发者自己定义,命令词最大长度为16个汉字,需要先构建语法,然后指定使用的语法。语法文件开发文档请参考识别语法分享--在线语法和离线语法编写指南(http://bbs.xfyun.cn/forum.php?mod=viewthread&tid=7595)

离线命令识别是否支持英文?

答:离线命令词只支持中文普通话,暂不支持英文。

离线命令词SDK在构建语法时报错23108。

答:离线命令词构建语法后会生成语法文件,不能删除此文件,删除后会报错23108。

离线命令识别返回11212错误。

答:11212是离线资源过期,测试阶段提供10个装机量、90天的免费试用权限,过期是无法继续使用的。