前提條件

• 閱讀接口說明，詳情請參見接口說明。

• 已獲取項目Appkey，詳情請參見創建項目。

• 已獲取Access Token，詳情請參見獲取Token概述。

下載安裝

1. 下載V1.5.016.napi.001.003_5d87aea0fa4f42e1b5bb254573fbbcc6af546c6b.tar.gz。

   重要

   下載后請在樣例初始化代碼中替換您的阿里云賬號信息、Appkey和Token才可運行。

   類別	兼容范圍
   系統	支持HarmonyOS Next 5.0 版本，API LEVEL 12, DevEco Studio版本號5.0.3.403
   架構	arm64-v8a

   此SDK還包含如下功能，若未支持您想要的功能，請前往對應文檔獲取SDK。

   功能	是否支持
   一句話識別	是
   實時語音識別	是
   語音合成	是
   實時長文本語音合成	是
   流式文本語音合成	是
   離線語音合成	否
   錄音文件識別極速版	是
   喚醒及命令詞	否
   聽悟實時推流	是

2. 以arkts HAR包的形式進行集成。解壓壓縮包，其中entry/libs/neonui.har是SDK生成的HAR包文件，在用戶工程項目中導入調用即可。如果需要HarmonyOS Next CPP接入方式，可在壓縮包的native/libs和native/include中獲得動態庫和頭文件。

3. 使用DevEco Studio打開工程目錄，其中語音合成示例代碼為TTSPage.ets文件，替換UserKey.ets中 UserKey類的Appkey和Token后，即可直接運行。

SDK關鍵接口

• tts_initialize：初始化SDK。

  /**
   * 初始化SDK，SDK為單例，請先釋放后再次進行初始化。請勿在UI線程調用，可能會引起阻塞。
   * @param callback：事件監聽回調，參見下文具體回調。
   * @param ticket：json string形式的初始化參數，參見下方說明或接口說明：http://bestwisewords.com/document_detail/173642.html。
   * @param level：log打印級別，值越小打印越多。
   * @param save_log：是否保存log為文件，存儲目錄為ticket中的debug_path字段值。注意，log文件無上限，請注意持續存儲導致磁盤存滿。
   * @return：參見錯誤碼：http://bestwisewords.com/document_detail/459864.html。
   */
  public tts_initialize(callback:NuiTtsSdkListener ,
                              ticket:string ,
                              level:number ,
                              save_log:boolean ):number

  其中，NuiTtsSdkListener類型包含如下回調。

  • onTtsEventCallback：SDK事件回調。

    /**
     * 事件回調
     * @param event：回調事件，參見如下事件列表。
     * @param task_id：請求的任務ID。
     * @param ret_code：參見錯誤碼，出現TTS_EVENT_ERROR事件時有效，可查閱http://bestwisewords.com/document_detail/459864.html。
     */
    onTtsEventCallback: (event:NuiSdkTtsEvent, taskid:string, ret_code:number) => void;

    事件列表：

    名稱	說明
    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：合成的音頻數據，寫入播放器。
     */
    onTtsDataCallback: (info:string, info_len:number , buffer:ArrayBuffer|null) => void;

    其中，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參數。

  /**
   * 以鍵值對形式設置參數, 參見接口說明:http://bestwisewords.com/document_detail/173642.html
   * @param param：參數名，參見接口說明。
   * @param value：參數值，參見接口說明。
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public setparamTts(param:string, value:string):number

• getparamTts：獲取參數。

  /**
   * 獲取參數值
   * @param param：參數名，參考接口說明:http://bestwisewords.com/document_detail/173642.html。
   * @return：參數值。
   */
  public getparamTts(param:string):string

• startTts：開始播放。

  /**
   * 開始合成任務
   * @param priority：任務優先級，請使用"1"。
   * @param taskid：任務ID，可傳入32個字節的uuid，或傳入空內容由SDK自動生成。
   * @param text：播放的文本內容。
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public startTts(priority:string, taskid:string, text:string):number

• cancelTts：取消播放。

  /**
   * 取消合成任務
   * @param taskid：傳入想要停止的任務ID，如果為空則取消所有任務。
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public cancelTts(taskid:string):number

• pauseTts：暫停播放。

  /**
   * 暫停合成任務
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public pauseTts():number

• resumeTts：恢復播放。

  /**
   * 恢復暫停的任務
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public resumeTts():number

• tts_release：釋放SDK資源。

  /**
   * 釋放SDK
   * @return：參見錯誤碼:http://bestwisewords.com/document_detail/459864.html。
   */
  public tts_release():number

調用步驟

1. 創建SDK類對象實例

2. 初始化SDK和播放組件。

3. 根據業務需求設置參數。

4. 調用startTts進行播放。

5. 在合成數據回調中，將數據寫入播放器進行播放，建議使用流式播放。

6. 收到語音合成結束的回調。

代碼示例

語音合成初始化

//這里獲得資源路徑, 即工作路徑，使用固定的路徑 context.resourceDir+"/resources_cloud"
ttsLongText:boolean = false;  //默認 非長文本TTS配置
ticket: string = "this is ticket string"

resourceDir:string = ""
let context = getContext(this) as common.UIAbilityContext;
this.resourceDir = context.resourceDir;

//SDK初始化
g_ttsinstance:NativeNui = new NativeNui(Constants.ModeType.MODE_TTS, "")

let path:string = this.resourceDir+"/resources_cloud"
this.ticket = genTicketTTS(path)
console.info("ticket is %s", this.ticket);

let level:number= 1
let save_log:boolean = false
let retcode:number = this.g_ttsinstance.tts_initialize(g_ttscallback_instance,this.ticket,level, save_log)

其中，genTicket生成為String JSON字符串，包含資源目錄和用戶信息。其中用戶信息包含如下字段，獲取方式請參考接口說明文檔。

/**
 * ticket生成示例，詳見Demo工程中代碼示例
 */
function genTicketTTS(workpath:string):string {
  let str:string = "";
  //注意:
  //  語音交互服務需要先準備好賬號，并開通相關服務。具體步驟請查看：
  //    http://bestwisewords.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：http://bestwisewords.com/zh/ram/product-overview/what-is-sts
  //STS SDK概覽：http://bestwisewords.com/zh/ram/developer-reference/sts-sdk-overview
  //STS Python SDK調用示例：http://bestwisewords.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
  
  // "mode_type" 設置為在線合成
  //  Local = 0,
  //  Mix = 1,  // init local and cloud
  //  Cloud = 2,

  let object:object = Object({
    "app_key" : UserKeyTTS.app_key,
    "token" : UserKeyTTS.token,
    "url" : UserKeyTTS.url,
    "device_id" : "empty_device_id_womx",  // 必填, 推薦填入具有唯一性的id, 方便定位問題
    "mode_type" : "2",
    "workspace" : workpath    // 必填, 工作目錄路徑，SDK從該路徑讀取配置文件，且需要有讀寫權限
  })
  str = JSON.stringify(object);
  console.info("UserContext:" + str);
  return str;
}

根據需求設置參數

//詳細參數可見: http://bestwisewords.com/document_detail/173642.html

//  在線語音合成發音人可以參考阿里云官網
//  http://bestwisewords.com/document_detail/84435.html
this.g_ttsinstance.setparamTts("font_name", "xiaoyun");

//  設置發音人對應的語音合成采樣率, 設置后也請設置播放器的對應采樣率， 否則無法播放出正常音頻。
this.g_ttsinstance.setparamTts("sample_rate", "16000");

// 字級別音素邊界功能開關，該參數只對支持字級別音素邊界接口的發音人有效?！?”表示打開，“0”表示關閉。
this.g_ttsinstance.setparamTts("enable_subtitle", "1");

// 設置文檔中不存在的參數, key為custom_params, value以json string的形式設置參數
// this.g_ttsinstance.setparamTts("custom_params",{\"enable_phoneme_timestamp\":true}");

// 調整語速
// this.g_ttsinstance.setparamTts("speed_level", "1");
// 調整音調
// this.g_ttsinstance.setparamTts("pitch_level", "0");
// 調整音量
// this.g_ttsinstance.setparamTts("volume", "1.0");

//  支持一次性合成300字符以內的文字，其中1個漢字、1個英文字母或1個標點均算作1個字符，
//  超過300個字符的內容將會截斷。所以請確保傳入的text小于300字符(不包含ssml格式)。
//  長短文本語音合成收費不同，須另外開通長文本語音服務，請注意。
//  不需要長文本語音合成功能則無需考慮以下操作。
let charNum: number = this.g_ttsinstance.getUtf8CharsNum(ttsText);
console.info("chars:" + charNum + " of text:" + ttsText);
if (this.ttsLongText || charNum > 300) { //ttsLongText用于控制是否開啟長文本語音合成
  console.info(`tts text with config ${this.ttsLongText} ,and chars number ${charNum}.`);
  // 超過300字符設置成 長文本語音合成 模式
  this.g_ttsinstance.setparamTts("tts_version", "1");
} else {
  // 未超過300字符設置成 短文本語音合成 模式
  this.g_ttsinstance.setparamTts("tts_version", "0");
}

啟動語音合成

// 每個instance一個task，若想同時處理多個task，請啟動多instance
this.g_ttsinstance.startTts("1", "", ttsText);

回調處理

• onTtsEventCallback：語音合成事件回調，根據語音合成狀態控制播放器。

  function cb_tts_event_callback(event:NuiSdkTtsEvent, task_id:string, code:number):void{
    console.info("womx cb_tts_event_callback  %d %s %d", event, task_id, code);
  
    console.log(`womx cb_tts_event_callback uid[${process.uid}] pid[${process.pid}] tid[${process.tid}]`);
    if (event==NuiSdkTtsEvent.TTS_EVENT_START){
      waitinginit() //初始化AudioRenderer模塊并開啟播放
    } else if (event==NuiSdkTtsEvent.TTS_EVENT_END){
      /*
       * 提示: TTS_EVENT_END事件表示TTS已經合成完并通過回調傳回了所有音頻數據, 而不是表示播放器已經播放完了所有音頻數據。
       */
      console.info("womx call voiceEnd()");
      AudioRenderer.voiceEnd() //只是告知AudioRenderer模塊，生成的數據已經結束，把所有數據播放完畢即可結束播放。
    } else if (event == TtsEvent.TTS_EVENT_PAUSE) {
        console.info("womx call pause()");
    } else if (event == TtsEvent.TTS_EVENT_RESUME) {
        console.info("womx call resume()");
    } else if(event==NuiSdkTtsEvent.TTS_EVENT_CANCEL || event==NuiSdkTtsEvent.TTS_EVENT_ERROR ){
      console.info("womx call stop()");
      AudioRenderer.voiceStop(true) //調用await AudioRenderer.stop(true)
    }
  }

• onTtsDataCallback：語音合成數據回調，將回調中的合成數據寫入播放器進行播放。

  function cb_tts_user_data_callback(info:string, info_len:number , buffer:ArrayBuffer|null):void{
    if (buffer){
      console.info("womx cb_tts_user_data_callback %s %d %d. times=%d", info, info_len, buffer.byteLength, countNumber);
      if (buffer.byteLength > 0) {
        AudioRenderer.writePlayerData(buffer)
      }
    } else {
      console.info("womx cb_tts_user_data_callback %s %d undefined", info, info_len);
    }
  }

取消語音合成

this.g_ttsinstance.cancelTts("")

退出語音合成

this.g_ttsinstance.tts_release()