离线语音合成服务Android NUI SDK_智能语音交互(ISI)-阿里云帮助中心

本文介绍了如何使用阿里云离线语音合成服务提供的Android NUI SDK，包括下载安装SDK和语音包、SDK关键接口及代码示例。

前提条件

阅读接口说明，详情请参见接口说明。
已获取项目Appkey，详情请参见创建项目。
已获取AccessKey ID和 AccessKey Secret，详情请参见开通服务。

下载安装

下载SDK。

重要

下载后在样例初始化代码中替换您的阿里云账号信息、Appkey才可运行。

对象	说明
SDK名称	智能语音交互移动端SDK
开发者	阿里云计算有限公司
SDK版本	2.6.3-028
SDK包名	com.alibaba.idst.nui
SDK更新时间	2024-12-20
SDK大小	MinSizeRel/nuisdk-release.aar	14.6MB
	RelWithDebugInfo/nuisdk-release.aar	19.6MB
SDK MD5值	MinSizeRel/nuisdk-release.aar	c4b462321c93766e3d865640e9793859
	RelWithDebugInfo/nuisdk-release.aar	3c30a9aba5b7e4e24a2935e3baaee75e
隐私政策	智能语音交互产品隐私政策
SDK整合包下载	下载Android SDK

类别	兼容范围
系统	支持Android 4.0 以上版本，API LEVEL 14
架构	armeabi-v7a，arm64-v8a，x86，x86_64

此SDK还包含如下功能，若未支持您想要的功能，请前往对应文档获取SDK。

功能	是否支持
一句话识别	是
实时语音识别	是
语音合成	是
实时长文本语音合成	是
流式文本语音合成	是
离线语音合成	是
录音文件识别极速版	是
唤醒及命令词	否
听悟实时推流	是

下载语音包，详情请参见接口说明中的语音包列表。
重要
SDK和语音包是完全独立的，下载SDK后并不能直接使用，需要下载语音包，并设置语音包存放路径。
解压ZIP包，在app/libs目录下获取AAR格式的SDK包。若需要Android CPP接入方式，则可在ZIP包的android_libs和android_include中获得动态库和头文件。
使用Android Studio打开此工程。其中语音合成示例代码为TtsLocalActivity.java文件。

SDK关键接口

tts_initialize：初始化SDK。

/**
 * 初始化SDK，离线合成暂不支持多实例，请先释放后再次进行初始化。请勿在UI线程调用，可能会引起阻塞。
 * 初始化是耗时操作，不需要合成一个任务就进行该操作；在启动和退出时进行一次即可。
 * @param callback：事件监听回调，参见下文具体回调。
 * @param ticket：json string形式的初始化参数，参见下方说明或接口说明：https://help.aliyun.com/document_detail/204185.html。
 * @param level：log打印级别，值越小打印越多。
 * @param save_log：是否保存log为文件，存储目录为ticket中的debug_path字段值。注意，log文件无上限，请注意持续存储导致磁盘存满。
 * @return：参见错误码：https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int tts_initialize(INativeTtsCallback callback,
                                       String ticket,
                                       final Constants.LogLevel level,
                                       boolean save_log)；

INativeTtsCallback类型包含如下回调：

onTtsEventCallback：SDK事件回调。

/**
 * 事件回调
 * @param event：回调事件，参见如下事件列表。
 * @param task_id：请求的任务ID。
 * @param ret_code：参见错误码，出现TTS_EVENT_ERROR事件时有效，可查阅https://help.aliyun.com/document_detail/459864.html。
 */
void onTtsEventCallback(TtsEvent event, String task_id, int ret_code);

事件列表：

名称	说明
TTS_EVENT_START	语音合成开始，准备播放。
TTS_EVENT_END	语音合成结束，合成数据已全部抛出，但并不表示播放结束。
TTS_EVENT_CANCEL	取消语音合成。
TTS_EVENT_PAUSE	语音合成暂停。
TTS_EVENT_RESUME	语音合成恢复。
TTS_EVENT_ERROR	语音合成发生错误。可通过getparamTts("error_msg")获得详细错误消息。

onTtsDataCallback：合成数据回调。

/**
 * @param info：使用时间戳功能时，返回JSON格式的时间戳结果。
 * @param info_len：info字段的数据长度，暂不使用。
 * @param data：合成的音频数据，写入播放器。
 */
void onTtsDataCallback(String info, int info_len, byte[] data);

其中，ticket内容参数说明，生成示例参见下方代码示例：

参数	类型	是否必选	说明
workspace	String	是	工作目录路径，SDK从该路径读取配置文件。需要有读写权限。
app_key	String	是	管控台创建项目的appkey。
ak_id	String	是	阿里云账号的AccessKey中的AccessKey ID，用于标识用户。或为阿里云STS（Security Token Service）的AccessKey ID。具体可见代码示例中账号鉴权相关说明。
ak_secret	String	是	阿里云账号的AccessKey中的AccessKey Secret，用于验证用户的密钥。AccessKey Secret必须保密。或为阿里云STS（Security Token Service）的AccessKey Secret。具体可见代码示例中账号鉴权相关说明。
token	String	否	访问令牌（Access Token）。若使用阿里云账号的AccessKey，则使用此参数token。若使用阿里云STS（Security Token Service）的AccessKey，则使用sts_token。具体可见代码示例中账号鉴权相关说明。
sts_token	String	否	临时安全令牌（STS Token）。若使用阿里云STS（Security Token Service）的AccessKey，则使用此参数sts_token。若使用阿里云账号的AccessKey，则使用token。具体可见代码示例中账号鉴权相关说明。
device_id	String	是	用户层面的账户号。此为扣费依据，若device_id重复则会被认为非法ID，导致离线语音合成无法工作。若device_id随机变化，则会出现重复计费的情况。请保证此device_id唯一性且不会变化。
mode_type	String	是	设置成离线语音合成模式，语音合成必须设置成“0”，这个设置很重要, 遗漏会导致无法运行

setparamTts：设置参数。

/**
 * 以键值对形式设置参数, 参见接口说明:https://help.aliyun.com/document_detail/204185.html
 * @param param：参数名，参见接口说明。
 * @param value：参数值，参见接口说明。
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int setparamTts(String param, String value);

getparamTts：获取参数。

/**
 * 获取参数值
 * @param param：参数名，参考接口说明:https://help.aliyun.com/document_detail/204185.html。
 * @return：参数值。
 */
public String getparamTts(String param);

startTts：开始合成。

/**
 * 开始合成任务
 * @param priority：任务优先级，请使用"1"。
 * @param taskid：任务ID，可传入32个字节的uuid，或传入空内容由SDK自动生成。
 * @param text：播放的文本内容。
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int startTts(String priority, String taskid, String text);

cancelTts：取消合成。

/**
 * 取消合成任务
 * @param taskid：传入想要停止的任务ID，如果为空则取消所有任务。
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int cancelTts(String taskid);

pauseTts：暂停合成。

/**
 * 暂停合成任务
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int pauseTts();

resumeTts：恢复合成。

/**
 * 恢复暂停的任务
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int resumeTts();

tts_release：释放SDK资源。

/**
 * 释放SDK
 * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
 */
public synchronized int tts_release();

调用步骤

初始化SDK和播放组件。
根据业务需求设置参数。
调用startTts进行播放。
在合成数据回调中，将数据写入播放器进行播放，建议使用流式播放。
收到语音合成结束的回调。

代码示例

语音合成初始化。

//设置默认目的地路径最下级目录名字
// 比如设置当前 /data/user/0/mit.alibaba.nuidemo/files/asr_my
// 未调用此接口, 则默认为 /data/user/0/mit.alibaba.nuidemo/files/asr_my
CommonUtils.setTargetDataDir("asr_my");

//这里获得当前nuisdk.aar中assets可以搬运的默认目的地路径,
// 比如 /data/user/0/mit.alibaba.nuidemo/files/asr_my
path = CommonUtils.getModelPath(this);
Log.i(TAG, "workpath:" + path);

//这里主动调用完成SDK配置文件的拷贝目的地为CommonUtils.getModelPath(this);
// 比如当前为 /data/user/0/mit.alibaba.nuidemo/files/asr_my
if (CommonUtils.copyTtsAssetsData(this)) {
    Log.i(TAG, "copy assets data done");
} else {
    Log.e(TAG, "copy assets failed");
    ToastText("从aar的assets拷贝资源文件失败, 请检查资源文件是否存在, 详情可通过日志确认。");
    return;
}
// 注意: 比如鉴权文件为 /data/user/0/mit.alibaba.nuidemo/files/asr_my/tts/ttset.bin
// 切勿覆盖和删除asr_my内文件

//SDK初始化
NativeNui nui_tts_instance = new NativeNui(Constants.ModeType.MODE_TTS);
int ret = nui_tts_instance.tts_initialize(new INativeTtsCallback() {}, genInitParams(path), Constants.LogLevel.LOG_LEVEL_VERBOSE, true);

其中，genInitParams生成为String JSON字符串，包含资源目录和用户信息。其中用户信息包含如下字段。

说明

精品版sdk_code为software_nls_tts_offline
普通版sdk_code为software_nls_tts_offline_standard

/**
 * ticket生成示例，详见Demo工程中代码示例
 */
private String genInitParams(String workpath) {
    String str = "";
    try {
        //郑重提示:
        //  语音交互服务需要先准备好账号，并开通相关服务。具体步骤请查看：
        //    https://help.aliyun.com/zh/isi/getting-started/start-here
        //
        //原始账号:
        //  账号(子账号)信息主要包括AccessKey ID(后续简称为ak_id)和AccessKey Secret(后续简称为ak_secret)。
        //  此账号信息一定不可存储在app代码中或移动端侧，以防账号信息泄露造成资费损失。
        //
        //STS临时凭证:
        //  由于账号信息下发给客户端存在泄露的可能，阿里云提供的一种临时访问权限管理服务STS(Security Token Service)。
        //  STS是由账号信息ak_id和ak_secret，通过请求生成临时的sts_ak_id/sts_ak_secret/sts_token
        //  (为了区别原始账号信息和STS临时凭证, 命名前缀sts_表示STS生成的临时凭证信息)
        //什么是STS：https://help.aliyun.com/zh/ram/product-overview/what-is-sts
        //STS SDK概览：https://help.aliyun.com/zh/ram/developer-reference/sts-sdk-overview
        //STS Python SDK调用示例：https://help.aliyun.com/zh/ram/developer-reference/use-the-sts-openapi-example
        //
        //账号需求说明:
        //  若使用离线功能(离线语音合成、唤醒), 则必须app_key、ak_id和ak_secret，或app_key、sts_ak_id、sts_ak_secret和sts_token
        //  若使用在线功能(语音合成、实时转写、一句话识别、录音文件转写等), 则只需app_key和token
        JSONObject initObject = Auth.getTicket(Auth.GetTicketMethod.GET_STS_ACCESS_FROM_SERVER_FOR_OFFLINE_FEATURES);
        if (!object.containsKey("token")) {
            Log.e(TAG, "Cannot get token!!!");
        }
      
        object.put("url", "wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1"); // 默认
        //工作目录路径，SDK从该路径读取配置文件
        object.put("workspace", workpath); // 必填, 且需要有读写权限

        initObject.put("mode_type", Constants.TtsModeTypeLocal); // 必填

        // 特别说明: 鉴权所用的id是由以下device_id，与手机内部的一些唯一码进行组合加密生成的。
        //   更换手机或者更换device_id都会导致重新鉴权计费。
        //   此外, 以下device_id请设置有意义且具有唯一性的id, 比如用户账号(手机号、IMEI等),
        //   传入相同或随机变换的device_id会导致鉴权失败或重复收费。
        object.put("device_id", "empty_device_id"); // 必填, 推荐填入具有唯一性的id, 方便定位问题

        str = object.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    Log.i(TAG, "UserContext:" + str);
    return str;
}

根据需求设置参数。

//设置本地发音人，如下载的aicheng语音包放在目录/sdcard/idst/目录下，那么命令为”/sdcard/idst/aicheng“
//  语音包和SDK是隔离的，需要先设置语音包
//  如果切换发音人：SDK可使用语音包与鉴权账号相关，由购买时获得的语音包使用权限决定
//  如已经购买aijia，按下边方式调用后，发音人将切为aijia
//  语音包下载地址：https://help.aliyun.com/document_detail/204185.html
//  语音包试听：https://www.aliyun.com/activity/intelligent/offline_tts
//  特别说明：离线语音合成的发音人, 并不一定也存在于在线语音合成；同理, 在线语音合成的发音人, 并不一定也存在于离线语音合成

//aar中的资源目录中自带了一个发音人aijia, /data/user/0/mit.alibaba.nuidemo/files/asr_my/tts/voices/aijia
String fullName = workspace + "/tts/voices/" + mFontName;

//切换发音人：一定要输入全路径名称
Log.i(TAG, "use extend_font_name:" + fullName);
ret = nui_tts_instance.setparamTts("extend_font_name", fullName);
if (ret != Constants.NuiResultCode.SUCCESS) {
    Log.e(TAG, "setparamTts extend_font_name " + fullName + " failed, ret:" + ret);
    String errmsg =  nui_tts_instance.getparamTts("error_msg");
    return ret;
}

//  设置发音人对应的语音合成采样率, 设置后也请设置播放器的对应采样率， 否则无法播放出正常音频。
nui_tts_instance.setparamTts("sample_rate", "16000");

// 调整语速
// nui_tts_instance.setparamTts("speed_level", "1");
// 调整音调
// nui_tts_instance.setparamTts("pitch_level", "0");
// 调整音量
// nui_tts_instance.setparamTts("volume", "1.0");

启动语音合成。

nui_tts_instance.startTts("1", "", ttsText);

回调处理。

onTtsEventCallback：语音合成事件回调，根据语音合成状态控制播放器。

public void onTtsEventCallback(INativeTtsCallback.TtsEvent event, String task_id, int ret_code) {
    Log.i(TAG, "tts event:" + event + " task id " + task_id + " ret " + ret_code);
    if (event == INativeTtsCallback.TtsEvent.TTS_EVENT_START) {
        mAudioTrack.play();
        Log.i(TAG, "start play");
    } else if (event == INativeTtsCallback.TtsEvent.TTS_EVENT_END) {
        /*
         * 提示: TTS_EVENT_END事件表示TTS已经合成完并通过回调传回了所有音频数据, 而不是表示播放器已经播放完了所有音频数据。
         */
        Log.i(TAG, "play end");

        // 表示推送完数据, 当播放器播放结束则会有playOver回调
        mAudioTrack.isFinishSend(true);
    } else if (event == TtsEvent.TTS_EVENT_PAUSE) {
        mAudioTrack.pause();
        Log.i(TAG, "play pause");
    } else if (event == TtsEvent.TTS_EVENT_RESUME) {
        mAudioTrack.play();
    } else if (event == TtsEvent.TTS_EVENT_ERROR) {
        // 表示推送完数据, 当播放器播放结束则会有playOver回调
        mAudioTrack.isFinishSend(true);

        String error_msg =  nui_tts_instance.getparamTts("error_msg");
        Log.e(TAG, "TTS_EVENT_ERROR error_code:" + ret_code + " errmsg:" + error_msg);
        ToastText(Utils.getMsgWithErrorCode(ret_code, "error"));
        ToastText("错误码:" + ret_code + " 错误信息:" + error_msg);
    }
}

onTtsDataCallback：语音合成数据回调，将回调中的合成数据写入播放器进行播放。

public void onTtsDataCallback(String info, int info_len, byte[] data) {
    if (info.length() > 0) {
        Log.i(TAG, "info: " + info);
    }
    if (data.length > 0) {
        mAudioTrack.setAudioData(data);
        Log.i(TAG, "write:" + data.length);
    }
}

取消语音合成。
```
nui_tts_instance.cancelTts("");
```
退出语音合成。
```
nui_tts_instance.tts_release();
```

常见问题

使用离线语音合成Android SDK，语音播报时出现不合理断句，该如何处理？

您可以通过SSML标记语言尝试解决。

调用Android SDK时，手机报错提示“audio recorder not init”。

您可以通过以下方式排查：

检查AudioRecord是否初始化正常。
检查语音播放器是否有问题。
编写AudioRecord录音代码，测试是否正常。

在模拟器上运行下载的Android程序，程序出现闪退现象，是什么原因？

模拟器可能会出现未知问题，建议您使用真机测试。

int ret = nui_instance.initialize(this, genInitParams(assets_path,debug_path), Constants.LogLevel.LOG_LEVEL_VERBOSE, true)。在该段代码中，录音权限是打开的，但代码仍然报错240021。

表示FILE_ACCESS_FAIL文件访问错误。你需要检查：

是否有文件读写权限。

是否完成SDK配置文件的拷贝，检查是否拷贝完成的代码示例如下：

if (CommonUtils.copyAssetsData(this)) {
Log.i(TAG, "copy assets data done");
} else {
Log.i(TAG, "copy assets failed");
return;
}