Android SDK

前提条件

• 阅读接口说明，详情请参见接口说明。

• 已获取项目Appkey，详情请参见创建项目。

• 已获取Access Token，详情请参见获取Token概述。

下载安装

1. 下载SDK和示例代码。

   重要

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

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

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

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

2. 解压ZIP包，在app/libs目录下获取AAR格式的SDK包，将AAR包集成到您的工程项目中进行依赖。如果需要Android CPP接入方式，可在ZIP包的android_libs和android_include中获得动态库和头文件。

3. 使用Android Studio打开此工程查看参考代码实现，其中语音合成示例代码为TtsBasicActivity.java文件，替换appkey和token后可直接运行。

SDK关键接口

• tts_initialize：初始化SDK。

  /**
   * 初始化SDK，SDK为单例，请先释放后再次进行初始化。请勿在UI线程调用，可能会引起阻塞。
   * @param callback：事件监听回调，参见下文具体回调。
   * @param ticket：json string形式的初始化参数，参见下方说明或接口说明：https://help.aliyun.com/document_detail/173642.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：合成数据回调。

    /**
     * 合成数据回调，开启enable_subtitle后，交替返回info和data
     * @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。
    token	String	是	请确保该Token可以使用并在有效期内。 Token可以在初始化时设置，也可通过参数设置进行更新。
    device_id	String	是	用户层面的账户号，请保证唯一性。
    mode_type	String	是	设置成在线语音合成模式，语音合成必须设置成2，如果不设置会导致无法运行。
    tts_version	String	是	设置语音合成模式。 1：长文本语音合成（超过300字符） 0：短文本语音合成（300字符以内）
    custom_params	String	否	若需要设置交互协议支持但是接口说明中未说明的参数，可通过此万能设置接口进行配置。其中custom_params为key，value为JSON字符串。具体设置方法请见代码示例。

• setparamTts：设置TTS参数。

  /**
   * 以键值对形式设置参数, 参见接口说明:https://help.aliyun.com/document_detail/173642.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/173642.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();

调用步骤

1. 初始化SDK和播放组件。

2. 根据业务需求设置参数。

3. 调用startTts进行播放。

4. 在合成数据回调中，将数据写入播放器进行播放，建议使用流式播放。

5. 收到语音合成结束的回调。

代码示例

语音合成初始化

//这里获得资源路径, 即工作路径
//  内部通过context.getApplicationContext().getFilesDir().toString() + "/asr_my" 创建工作路径，
//  例如 /data/user/0/mit.alibaba.nuidemo/files/asr_my
String workspace = CommonUtils.getModelPath(this);

//从nuisdk.aar中assets资源拷贝到workspace中
CommonUtils.copyAssetsData(this);

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

其中，genTicket生成为String JSON字符串，包含资源目录和用户信息。其中用户信息包含如下字段，获取方式请参考接口说明文档。

/**
 * ticket生成示例，详见Demo工程中代码示例
 */
private String genTicket(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 object = Auth.getTicket(Auth.GetTicketMethod.GET_TOKEN_FROM_SERVER_FOR_ONLINE_FEATURES);
        if (!object.containsKey("token")) {
            Log.e(TAG, "Cannot get token!!!");
        }

        object.put("device_id", "empty_device_id"); // 必填, 推荐填入具有唯一性的id, 方便定位问题

        object.put("url", "wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1"); // 默认
        //工作目录路径，SDK从该路径读取配置文件
        object.put("workspace", workpath); // 必填, 且需要有读写权限

        // 设置为在线合成
        //  Local = 0,
        //  Mix = 1,  // init local and cloud
        //  Cloud = 2,
        object.put("mode_type", Constants.TtsModeTypeCloud);
        str = object.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    Log.i(TAG, "UserContext:" + str);
    return str;
}

根据需求设置参数

//详细参数可见: https://help.aliyun.com/document_detail/173642.html

//  在线语音合成发音人可以参考阿里云官网
//  https://help.aliyun.com/document_detail/84435.html
nui_tts_instance.setparamTts("font_name", "xiaoyun");

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

// 字级别音素边界功能开关，该参数只对支持字级别音素边界接口的发音人有效。“1”表示打开，“0”表示关闭。
nui_tts_instance.setparamTts("enable_subtitle", "1");

// 设置文档中不存在的参数, key为custom_params, value以json string的形式设置参数
// nui_tts_instance.setparamTts("custom_params",{\"enable_phoneme_timestamp\":true}");

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

//  支持一次性合成300字符以内的文字，其中1个汉字、1个英文字母或1个标点均算作1个字符，
//  超过300个字符的内容将会截断。所以请确保传入的text小于300字符(不包含ssml格式)。
//  长短文本语音合成收费不同，须另外开通长文本语音服务，请注意。
//  不需要长文本语音合成功能则无需考虑以下操作。
int charNum = nui_tts_instance.getUtf8CharsNum(ttsText);
if (charNum > 300) {
    // 超过300字符设置成 长文本语音合成 模式
    nui_tts_instance.setparamTts("tts_version", "1");
} else {
    // 未超过300字符设置成 短文本语音合成 模式, 此为默认设置
    nui_tts_instance.setparamTts("tts_version", "0");
}

启动语音合成

// 每个instance一个task，若想同时处理多个task，请启动多instance
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();

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