科大讯飞开放平台

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 - context

      appId - appId

      apiKey - apiKey

      apiSecret - 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 - IatParam

      callBack - 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不支持多路会话。