科大讯飞开放平台
AIKit HarmonyOS SDK 接入指南
SDK Version: 1.0.0-beta1
Updated: 2020.10.15
1. 概述
尊敬的开发者朋友,欢迎您选择科大讯飞开放平台。本文档旨在帮助HarmonyOS 应用开发者在程序中快速接入AIKit HarmonyOS SDK。作为开发者,您只需要进行简单配置,就可以在您的应用中使用AIKit提供的各种AI能力。
关于SDK的具体使用方法,请仔细阅读下面的文档。
2. 集成说明
2.1 术语介绍
- APPID:应用 ID,请在
http://www.xfyun.cn/
中注册成为开发者并创建一款应用,您将获得标识您应用的唯一ID。 - APIKey:访问云端能力需要提供的参数。
- APISercet:访问云端能力需要提供的参数。
2.2 导入SDK依赖包
- 将 aikit.har 复制到Module的libs文件夹(没有的话须手动创建), 并将以下代码添加到您Module的build.gradle中:
depedencies {
implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
}
2.3 权限声明
权限 | 用途 |
---|---|
INTERNET | 允许程序联网的权限 |
MICROPHONE | 允许应用检测网络连接状态 |
权限配置请参考HarmonyOS 关于权限的使用指导,代码示例:
"reqPermissions": [
{
"name": "harmonyos.permission.INTERNET",
"reason": "the app need internet"
},
{
"name": "harmonyos.permission.MICROPHONE",
"reason": "the app need microphone",
"usedScene": {
"ability": [
"ccom.iflytek.aiaa.MainAbility"
],
"when": "always"
}
}
]
2.4 SDK初始化
2.4.1 初始化SDK
初始化即创建语音配置对象,只有初始化后才可以使用AIKit的各项服务。初始化代码如下:
// 初始化时 将 appid、apikey 和 apisecret 传入
SpeechUtility.getInstance().init(getContext(),
"xxxxx", // appid
"xxxxx", // apikey
"xxxxx" // apisecret
);
2.4.2 参数设置
初始化参数说明如下表
参数Key | 名称 | 是否必传 |
---|---|---|
context | 鸿蒙系统的 Context | Y |
APPID | 应用id | Y |
APIKEY | API Key | Y |
APISERCET | API密钥 | Y |
2.5 语音听写
语音听写,是基于自然语言处理,将自然语言音频转换为文本输出的技术。
2.5.1 音频文件语音识别
使用SpeechUtility.getInstance().voiceRecognize()
方法,参考代码如下:
/**
* 音频文件转文字 将开发包中的mp3转成文本
*/
private void audioFiles2String() {
try {
// 获取项目中的 测试的音频
String mp3Path = "resources/rawfile/test.mp3";
RawFileEntry rawFileEntry = getContext().getResourceManager().getRawFileEntry(mp3Path);
Resource resource = rawFileEntry.openRawFile();
// 创建语音听写参数类:IatParam
IatParam iatParam = new IatParam();
// 设置音频文件的格式
iatParam.setEncoding(IatParam.Encoding.lame);
SpeechUtility instance = SpeechUtility.getInstance();
// 开始语音识别
instance.voiceRecognize(iatParam, resource, new ResultCallBack<IatResult>() {
@Override
public void onResult(IatResult result) {
// 获取数据回掉 注意 回调在子线程执行
handler.postTask(() -> {
String s = CommonResultParser.parseIatResult(result.getData());
textField.append(s);
});
}
});
} catch (IOException e) {
e.printStackTrace();
}
}
2.5.2 录音并识别
使用录音功能需要先在Ability
类中动态申请"harmonyos.permission.MICROPHONE"
权限,参考代码如下:
if (verifySelfPermission("harmonyos.permission.MICROPHONE") != IBundleManager.PERMISSION_GRANTED) {
// 应用未被授予权限
if (canRequestPermission("harmonyos.permission.MICROPHONE")) {
// 是否可以申请弹框授权(首次申请或者用户未选择禁止且不再提示)
requestPermissionsFromUser(new String[]{"harmonyos.permission.MICROPHONE"},
REQUEST_MICROPHONE);
} else {
// 显示应用需要权限的理由,提示用户进入设置授权
}
} else {
// 权限已被授予
}
录音识别参考代码如下:
/**
* 开始录音
*/
private void startRecord() {
// 创建语音听写参数类:IatParam
IatParam iatParam = new IatParam();
iatParam.setEncoding(IatParam.Encoding.raw);
SpeechUtility.getInstance().startRecord(iatParam, new ResultCallBack<IatResult>() {
@Override
public void onResult(IatResult result) {
// 获取数据回掉 注意 回调在子线程执行
handler.postTask(() -> {
String s = CommonResultParser.parseIatResult(result.getData());
textField.append(s);
});
}
});
}
/**
* 停止录音
*/
private void stopRecord() {
SpeechUtility.getInstance().stopRecord();
}
2.5.3 参数设置
语音听写参数类 IatParam
支持设置的参数见下表:
参数名称 | 数据类型 | 名称 | 是否必须 | 说明 |
---|---|---|---|---|
encoding | string | 音频格式 | Y | 目前仅支持“ lame” 、“raw ”,mp3文件请使用“ lame”,pcm输入时使用 “raw ” |
ptt | int | 是否开启标点识别 | N | 0:不开启标点识别, 1:开启标点识别,默认不开启 |
nunum | int | 是否把中文数字转换成阿拉伯数字 | N | 0:关闭, 1:开启 默认关闭 |
dwa | string | pgs | N | 最小长度:0, 最大长度:10 |
evl | int | engine vad link | N | 0:关, 1:开启 |
proc | int | 是否使用后处理 | N | 0:关, 1:开 |
nbest | int | 句子级别多候选个数 | N | 最小值:0, 最大值:5 |
wbest | int | 词级别多候选个数 | N | 最小值:0, 最大值:5 |
pvinfo | int | 在 pgs 结果中展示vad信息 | N | 0:关, 1:开 |
aqc | int | aqc | N | 0:关, 1:开 |
ltc | int | 中英文筛选功能 | N | 最小值:0, 最大值:3 |
vad_enable | bool | 使能VAD | N | true/false |
vad_eos | int | 后端点 | N | 最小值:0, 最大值:60000,当vad_enable为true时有效 |
vrto | int | vad前置端点超时时间 | N | 最小值:0, 最大值:60000 |
2.5.4 结果解析
JSON字段 | 英文全称 | 类型 | 说明 |
---|---|---|---|
sn | sentence | number | 第几句 |
ls | last sentence | boolean | 是否最后一句 |
bg | begin | number | 保留字段,无需关注 |
ed | end | number | 保留字段,无需关注 |
ws | words | array | 词 |
cw | chinese word | array | 中文分词 |
w | word | string | 单字 |
sc | score | number | 分数 |
{
"sn": 1,
"ls": true,
"bg": 0,
"ed": 0,
"ws": [
{
"bg": 0,
"cw": [
{
"w": "今天",
"sc": 0
}
]
},
{
"bg": 0,
"cw": [
{
"w": "的",
"sc": 0
}
]
},
{
"bg": 0,
"cw": [
{
"w": "天气",
"sc": 0
}
]
},
{
"bg": 0,
"cw": [
{
"w": "怎么样",
"sc": 0
}
]
},
{
"bg": 0,
"cw": [
{
"w": "。",
"sc": 0
}
]
}
]
}
2.6 语音合成
与语音听写相反,语音合成是将一段文字转换为语音,可根据需要合成出不同音色、语速和语调的声音,让机器像人一样开口说话。文字格式为“utf8”。
2.6.1 接口说明
语音合成使用SpeechSynthesizer
接口,示例代码如下
/**
* 开始合成
*/
private void startTts() {
String stringSource = "这段话将被合成为语音";
// 建立个缓存文件保存合成的数据
File externalCacheDir = getContext().getExternalCacheDir();
File file = new File(externalCacheDir, "tts_test.mp3");
if (file.exists()) {
file.delete();
}
SpeechUtility instance = SpeechUtility.getInstance();
TtsParam ttsParam = new TtsParam();
instance.voiceSynthesise(ttsParam, stringSource, new ResultCallBack<TtsResult>() {
@Override
public void onResult(TtsResult result) {
// 获取数据回掉 注意 回调在子线程执行
// result.getData() 为合成的语音数据
FileUtil.append(file, result.getData());
// 合成完毕
if (result.getStatus() == SpeechUtility.StatusCode.END) {
handler.postTask(() -> showToast("合成完毕"));
// 开始播放
playMp3(file);
}
}
}
);
}
/**
* 播放音频
*
* @param file 源文件
*/
private void playMp3(File file) {
try {
Player player = new Player(getContext());
FileInputStream in = new FileInputStream(file);
// 从输入流获取FD对象
FileDescriptor fd = in.getFD();
Source source = new Source(fd);
player.setSource(source);
player.prepare();
player.play();
} catch (Exception e) {
e.printStackTrace();
}
}
2.6.2 参数设置
语音合成参数类 TtsParam
支持设置的参数见下表:
参数名称 | 数据类型 | 名称 | 是否必须 | 说明 |
---|---|---|---|---|
encoding | string | 输出音频格式 | N | 目前仅支持“ lame” (mp3文件) |
speed | int | 合成语速 | N | 默认50,取值范围:[0-100] |
volume | int | 合成音量 | N | 默认50,取值范围:[0-100] |
pitch | int | 合成语调 | N | 默认50,取值范围:[0-100] |
sample_rate | int | 采样率 | N | 暂时只支持16000 |
channels | int | 声道数 | N | 可选值1,2.默认值1 |
bit_depth | int | 位深 | N | 8,16默认值16 |
vcn | string | 发音人 | N | 可选值x2_lzy:x2_lzy, x2_chongchong:x2_chongchong, x2_yifei:x2_yifei, x2_xiaopei:x2_xiaopei, x2_xiaoyuan:x2_xiaoyuan |
2.6.3 结果解析
SDK返回合成结果为合成音频数据,可缓存到File中,然后用Player播放器播放。
3. 接口说明:
3.1 SpeechUtility类
路径 com.iflytek.cloud
getInstance
public static SpeechUtility getInstance()
创建配置单例
返回:
SpeechUtility
init
public void init(harmonyos.app.Context context, java.lang.String appId, java.lang.String apiKey, java.lang.String apiSecret)
初始化
参数:
context
- contextappId
- appIdapiKey
- apiKeyapiSecret
- apiSecret
voiceRecognize
public void voiceRecognize(com.iflytek.cloud.param.IatParam param, com.iflytek.cloud.result.ResultCallBack<com.iflytek.cloud.result.IatResult> callBack)
语音识别
参数:
param
- 语音识别入参callBack
- ResultCallBack
voiceRecognize
public void voiceRecognize(com.iflytek.cloud.param.IatParam param, java.io.InputStream resource, com.iflytek.cloud.result.ResultCallBack<com.iflytek.cloud.result.IatResult> callBack)
语音转写
参数:
param
- 语音转写的参数resource
- 语音流callBack
- 回调
startRecord
public void startRecord(com.iflytek.cloud.param.IatParam iatParam, com.iflytek.cloud.result.ResultCallBack<com.iflytek.cloud.result.IatResult> callBack)
开始录音,并将识别结果通过callBack返回
参数:
iatParam
- IatParamcallBack
- ResultCallBack
isRecording
public boolean isRecording()
判断是都在录音中
返回:
boolean
stopRecord
public void stopRecord()
停止录音
voiceSynthesise
public void voiceSynthesise(com.iflytek.cloud.param.TtsParam param, java.lang.String stringSource, com.iflytek.cloud.result.ResultCallBack<com.iflytek.cloud.result.TtsResult> callBack)
语音合成
参数:
param
- TtsParam 参数stringSource
- 待合成的内容callBack
- 合成回调
writeData
public void writeData(java.io.InputStream resource)
写入数据到引擎
参数:
resource
- 数据源
writeData
public void writeData(java.io.File file) throws java.io.FileNotFoundException
写入数据
参数:
file
- 数据源抛出:
java.io.FileNotFoundException
- FileNotFoundException
writeData
public void writeData(byte[] inData)
写入数据
参数:
inData
- 数据源
writeData
public void writeData(byte[] inData, int dataStatus)
写入数据
参数:
inData
- 数据源dataStatus
- 写入的状态码
writeDataEnd
public void writeDataEnd()
结束写入数据
destroy
public destroy()
销毁单例对象
3.2 IatParam类
包路径 com.iflytek.cloud.param;
说明:语音转写的入参封装类, 可通过该类的set
方法设置参数,也可以通过put(key,value)
方式设置参数。
3.3 TtsParam类
包路径 com.iflytek.cloud.param;
说明:语音合成的入参封装类, 可通过该类的set
方法设置参数,也可以通过put(key,value)
方式设置参数。
4. 常见问题:
SDK 都支持哪些 HarmonyOS 版本?
答:要求采用 HarmonyOS 1.0的手机版本。
如何查看SDK版本?
答:利用 Version.getVersion()可获得 SDK 版本号。
SDK是否支持同一业务同时开启多路会话?
答:SDK不支持多路会话。