Qwen-Audio-3.0-Realtime即時語音對話HarmonyOS SDK

使用者指南：關於模型介紹和選型建議請參見即時語音對話。

快速開始

取得與設定 API Key
下載 SDK 並執行範例程式碼：
- 下載最新 SDK 整合包。
- 解壓縮 .tar.gz 格式的 SDK 整合包。在 entry/libs 目錄中獲取 HAR 格式 SDK，並新增至專案相依性。需要 C++ 接入時，使用整合包內的 native/libs 與 native/include 獲取動態連結庫和標頭檔。
- 用 DevEco Studio 開啟工程。範例程式碼位於DashQwenAudioChatPage.ets，替換 API Key 後體驗功能。

呼叫步驟

初始化 SDK
按業務需求設定參數：透過 initialize 介面的 parameters 參數設定連線與控制參數；透過 setParams 介面設定語音對話效果參數。
呼叫 startDialog 啟動對話流程。
在 onNuiAudioStateChanged 回呼中，根據音訊狀態開啟錄音裝置。
在 onNuiNeedAudioData 回呼中持續提供錄音資料，或者透過 updateAudio 持續推送錄音資料。
在 onNuiAssistEventCallback 回呼中持續取得 AI 傳回的語音資料。
在 onNuiEventCallback 回呼中監聽事件並取得事件資訊。
呼叫 stopDialog 停止對話，並透過監聽 EVENT_TRANSCRIBER_COMPLETE 事件確認對話已結束。
當對話功能不再使用時，呼叫 release 介面釋放 SDK 資源。

音訊裝置管理

與 Android 使用 AudioRecord / AudioTrack 不同，HarmonyOS 透過 @kit.AudioKit 提供音訊採集與播放能力，分別使用 AudioCapturer（錄音）和 AudioRenderer（播放）。本產品範例已封裝為 AudioRecorder.ets 與 AudioPlayer.ets 兩個工具類別，可直接複用。

錄音（AudioCapturer）

建立：透過 audio.createAudioCapturer(capturerOptions) 非同步建立，取樣率固定 16kHz、16bit、單聲道（SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW）。
音源（audio.SourceType）：
- SOURCE_TYPE_MIC：麥克風原始音源，用於開啟 SDK 內部 AEC 時使用（資料經 updateAudio 送至 SDK）。
- SOURCE_TYPE_VOICE_COMMUNICATION：通話音源，系統採集時已做回音消除，用於關閉 SDK 內部 AEC 時使用（音訊經 onNuiNeedAudioData 拉取）。
資料事件：透過 capturer.on('readData', (buffer: ArrayBuffer) => void) 持續獲得錄音資料。
狀態事件：透過 capturer.on('stateChange', (state: audio.AudioState) => void) 監聽，STATE_RUNNING 表示開始錄音，STATE_STOPPED 表示停止。
控制：start() 開始、stop() 停止、release() 釋放。

import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioCapturerInfo: audio.AudioCapturerInfo = {
  source: audio.SourceType.SOURCE_TYPE_MIC,
  capturerFlags: 0
};
const options: audio.AudioCapturerOptions = { streamInfo: audioStreamInfo, capturerInfo: audioCapturerInfo };

audio.createAudioCapturer(options).then((capturer) => {
  capturer.on('readData', (buffer: ArrayBuffer) => {
    // 将录音数据送入SDK
    nuiInstance.updateAudio(buffer, false);
  });
  capturer.start();
});

注意：HarmonyOS 的 AudioCapturer 為非同步建立，建立完成後才能呼叫 start()。因此不要在 STATE_OPEN 時新建並立即啟動錄音器——應先建立完畢，再在 STATE_OPEN 回調中 start()（範例在 doInit 階段建立，onNuiAudioStateChanged 階段啟動）。

播放（AudioRenderer）

建立：透過 audio.createAudioRenderer(rendererOptions) 非同步建立。
取樣率：DashScope realtime 合成的語音回答音訊為 24kHz（AudioPlayer 建構時傳入）。
資料事件：透過 renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => ...) 拉取待播放音訊，返回 AudioDataCallbackResult.VALID 表示已填充資料，INVALID 表示無資料。
狀態事件：透過 renderer.on('stateChange', (state: audio.AudioState) => void) 監聽播放入口/結束。
控制：start() 開始、stop() 停止、pause() 暫停（暫停會保留已緩衝資料）。

import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_24000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_VOICE_ASSISTANT,
  rendererFlags: 0
};
const options: audio.AudioRendererOptions = { streamInfo: audioStreamInfo, rendererInfo: audioRendererInfo };

audio.createAudioRenderer(options, (err, renderer) => {
  renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => {
    // 从队列取出AI返回的音频填入data, 返回VALID/INVALID
    return audio.AudioDataCallbackResult.VALID;
  });
  renderer.start();
});

AEC 參考訊號：開啟 SDK 內部 AEC 時，播放器輸出的音訊需作為參考訊號送入 SDK，呼叫 nuiInstance.pushReferenceData(data, false)（對應 Android updateRefAudio）。

權限宣告

使用錄音功能需在 module.json5 中宣告麥克風權限：

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}

請求參數

連線與控制參數

透過在 initialize 介面的 parameters 參數中傳入一個 JSON 字串來設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

參數說明

參數	類型	是否必須	說明
`url`	`String`	是	服務位址： `wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 華北 2（北京）：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 新加坡：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 呼叫時，請將 `{WorkspaceId}` 替換為真實的Workspace ID。
`apikey`	`String`	是	API Key。
`service_mode`	`String`	是	執行模式。即時語音對話固定為 `"1"`。
`device_id`	`String`	是	用於識別終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
audio_update_manually	`String`	否	是否啟用主動推送音訊資料模式，預設值："false"。當設定為 "true" 啟用主動推送音訊資料模式時，且 SDK 版本支援端側音訊能力（如 AEC、VAD），則預設開啟端側音訊能力。
workspace	`String`	否	當參數 audio_update_manually 設定為 "true" 時，且啟用端側音訊能力（如 AEC、VAD）時，必須設定 workspace，即端側資源檔案儲存的路徑。
`debug_path`	`String`	否	日誌檔案的儲存路徑。此參數僅在呼叫 initialize 介面時將 `save_log` 設為 true 時生效。此時必須設定日誌檔案路徑，否則將報錯。本機最多保留兩個日誌檔案。
`save_wav`	`String`	否	是否儲存偵錯用的音訊檔案。音訊檔案儲存於`debug_path`下。預設值："false"。取值範圍： "true"：是 "false"：否此參數僅在呼叫initialize介面時將`save_log`設為true時生效。同時，`debug_path`也必須被設定。
`max_log_file_size`	`int`	否	設定日誌檔案的最大位元組數。此參數僅在呼叫initialize介面時將`save_log`設為true時生效。預設值：104857600（100 × 1024 × 1024 位元組, 即 100MiB）。
`log_track_level`	`int`	否	控制透過日誌回呼（`onNuiLogTrackCallback`）對外傳送的日誌內容的過濾層級。預設值：2。取值範圍： 0：`LOG_LEVEL_VERBOSE` 1：`LOG_LEVEL_DEBUG` 2：`LOG_LEVEL_INFO` 3：`LOG_LEVEL_WARNING` 4：`LOG_LEVEL_ERROR` 5：`LOG_LEVEL_NONE`（表示關閉此功能）注意：`log_track_level`與`level`（透過initialize介面設定）共同決定最終回調的日誌。一條日誌的級別數值必須同時大於或等於`log_track_level`和`level`的值，才會被回調。例如，`log_track_level`設為2 (INFO)，`level`設為3 (WARNING)，則只有WARNING及以上級別（數值>=3）的日誌才會被回調。
aec_params	`object`	否	端側 AEC 能力進階參數設定物件。當參數 audio_update_manually 設定為 "true" 時才啟用此設定物件。
aec_params.enable_aec	`boolean`	否	是否開啟端側 AEC 回音消除能力。當參數 audio_update_manually 設定為 "true" 時，且 SDK 版本支援端側 AEC 音訊能力，則預設開啟。
aec_params.save_audio	`boolean`	否	是否開啟端側 AEC 回音消除模組音訊儲存功能。當 `save_wav` 為 "true"，且設定了 `debug_path`，則預設開啟，將 AEC 執行音訊資料儲存到 `debug_path` 下。
aec_params.enable_aec_data_callback	`boolean`	否	是否將 AEC 後的資料傳送給使用者，預設為 false；開啟後在 onNuiAssistEventCallback 的 EVENT_AEC_DATA 接收。
vad_params	`object`	否	端側 VAD 能力進階參數設定物件。當參數 audio_update_manually 設定為 "true" 時才啟用此設定物件。
vad_params.enable_vad	`boolean`	否	是否開啟端側 VAD 人聲偵測能力。當參數 audio_update_manually 設定為 "true" 時，且 SDK 版本支援端側 VAD 音訊能力，則預設開啟。
vad_params.save_audio	`boolean`	否	是否開啟端側 VAD 人聲偵測模組音訊儲存功能。當 `save_wav` 為 "true"，且設定了 `debug_path`，則預設開啟，將 VAD 執行音訊資料儲存到 `debug_path` 下。

語音對話效果參數

透過在 setParams 介面的 params 參數中傳入一個 JSON 字串來設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-realtime-plus",
        "sr_format": "pcm"
    }
}

參數說明

一級參數	類型	是否必須	說明
`service_type`	`int`	是	語音服務類型。即時語音對話固定為 `4`。
`nls_config`	`object`	是	語音對話核心設定物件，包含模型選擇、對話效果控制等關鍵參數。
`nls_config.model`	`string`	是	指定模型名稱。支援 qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash 系列模型。
`nls_config.sr_format`	`string`	是	輸入音訊格式。當前僅支援 `pcm`（16kHz 16bit 單聲道），為預設值。
`nls_config.modalities`	`string`	否	array 格式的字串，模型輸出模態設定，可選值： `["text"]`：僅輸出文字。 `["audio", "text"]`（預設值）：同時輸出文字和音訊。
nls_config.voice	`string`	否	TTS 音色名稱，3.1 Plus 的預設值為 `longanqian_v3.1`，3.0 Plus/Flash 的預設值為 `longanqian`。支援兩種類型，僅可在第一次 `session.update` 中設定，後續傳入將被忽略。系統音色：可選值：`longanqian`、`longanlingxin`、`longanlingxi`、`longanxiaoxin`、`longanlufeng`。聲音複製音色：透過聲音複製 API 建立，將返回的 `voice_id` 填入此參數。詳見音色配置。 3.1 Plus 還支援 `longanqian_v3.1`、`longanhuan_v3.1`、`longanlingxin_v3.1`、`longanfengyue_v3.1`、`xunanchuan_v3.1`、`beth_v3.1`、`betty_v3.1`、`cally_v3.1`。
nls_config.enable_speech_emotion	`boolean`	否	是否開啟情緒增強功能。開啟後，回覆音色的情緒變化更明顯。預設值：`true`。可選值：`true`、`false`。
nls_config.instructions	`string`	否	系統指令，用於設定模型的角色身分、回答風格和行為偏好。對整個對話生效。
nls_config.max_history_turns	`int`	否	允許單次請求的最大歷史 QA 輪數。取值範圍為 1-50，預設值為 20。
nls_config.tools	`string`	否	array 格式的字串。Function Calling 工具定義清單。配置後模型可根據使用者輸入自主決定是否呼叫工具。內部參數說明： type`string`（必選）固定為 `function`。 function.name`string`（必選）工具函數名稱。 function.description`string`（可選）對工具函數功能的描述，模型據此判斷是否呼叫該工具。 function.parameters`object`（可選）對工具函數入參的描述，模型據此提取所需入參。若函數無需入參，可不指定。範例： `[ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的天气信息。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市" } }, "required": [ "city" ] } } } ]`
nls_config.turn_detection	`string`	否	JSON 物件形式的字串。輪次偵測設定。未設定時則切換為 push-to-talk 模式（手動提交音訊並觸發推理）。否則啟用雙工對話模式。
nls_config.turn_detection.type	`string`	否	VAD 類型，可選值： `server_vad`（預設值）：基於聲學特徵偵測語音起止，自動觸發推理。 `smart_turn`：融合聲學感知與語意理解的智慧輪次偵測，透過聲學與語意雙重判斷輪次邊界。無語意的聲音（如「嗯」、「啊」）不會觸發對話輪或打斷模型播報。
nls_config.turn_detection.threshold	float	否	VAD 靈敏度，僅在 server_vad 模式下生效（smart_turn 模式下無效）。值越低，VAD 越靈敏，越容易將微弱聲音（包括背景雜訊）識別為語音；值越高，越不靈敏，需要更清晰、音量更大的語音才能觸發。取值範圍為 [-1.0, 1.0]，預設值為 0.5。
nls_config.turn_detection.silence_duration_ms	`int`	否	語音結束後需保持靜音的最短時間（毫秒），僅在 server_vad 模式下生效（smart_turn 模式下無效）。逾時即觸發模型回應。值越低，回應越快，但可能在短暫停顿時誤觸發。取值範圍為 [200, 6000]，預設值為 800。對話場景推薦 400-800。
nls_config.turn_detection.voiceprint_audio_urls	`string`	否	array 形式的字串。僅在 smart_turn 模式下生效。目標使用者預錄音訊的公網可存取 URL 清單，用於說話人增強。傳入後，模型將在雙工對話中精準鎖定目標說話人，有效忽略旁人聲音與背景雜訊。最多支援 5 個 URL。音訊格式要求：16kHz PCM 或 WAV。

關鍵介面

NativeNui

initialize

初始化語音對話 SDK 執行個體。SDK 為單例模式，在呼叫 release 前禁止重複初始化。此介面會引起阻塞，應在非 UI 執行緒呼叫。 方法簽章

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

參數說明

參數	類型	說明
`callback`	`INativeNuiCallback`	事件和資料回調介面的實作。
`parameters`	`string`	JSON 字串，包含驗證、連線和偵錯參數。請參見連線與控制參數。
`level`	`number`	控制 SDK 自身日誌的列印層級。
`save_log`	`boolean`	是否儲存本機日誌。若為 `true`，須在連線與控制參數中透過 `debug_path` 指定路徑，並可透過 `max_log_file_size` 設定檔案大小。

setParams

以 JSON 格式設定語音對話效果參數。在 startDialog 之前呼叫。 方法簽章

public setParams(params: string): number

參數說明

參數	類型	說明
`params`	`string`	語音對話效果參數。

startDialog

開始對話。 方法簽章

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

參數說明

參數	類型	說明
`vad_mode`	`Constants.VadMode`	VAD 模式。固定為 `Constants.VadMode.TYPE_P2T`。
`dialog_params`	`string`	如果連線與控制參數的 `apikey` 參數使用的是臨時 API Key，當其過期時，可在此處進行更新。內容為 JSON 格式： `{ "apikey": "st-****" }`

stopDialog

結束對話，呼叫此介面後，伺服器端將返回最終對話結果並結束任務。 方法簽章

public stopDialog(): number

cancelDialog

立即結束對話，呼叫此介面後，不等待伺服器端返回最終對話結果就立即結束任務。 方法簽章

public cancelDialog(): number

dialogAction

在互動過程中下達對話動作指令，用於更新對話上下文等執行階段行為。 方法簽章

public dialogAction(params: string): number

參數說明

參數	類型	說明
`params`	`string`	JSON 格式的字串，用於更新對話上下文等執行階段行為。
`params.type`	`String`	固定"action"。
`params.command`	`String`	具體的執行指令，當前支援"function_call"、"play_start"、"play_over"。 `function_call`：更新函數呼叫請求的指令。 `play_start`：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器開始播放音訊。 `play_over`：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器已經播放結束。
`params.context`	`String`	當 `command` 為 `"function_call"` 時，更新函數呼叫請求。
`params.context.type`	`String`	事件類型，當`command`為`"function_call"`時必須設定。 `conversation.item.create`：手動向對話上下文插入一條對話項目。可用於注入歷史上下文、補充文字資訊，或寫回 Function Calling 的工具執行結果。 `response.create`：在 `conversation.item.create` 指令傳送後，透過此指令觸發第二輪推理。
`params.context.item`	`object`	`params.context.type` 為 conversation.item.create 時必須設定，表示要建立的對話項目。詳見如下。
`params.context.response`	`object`	`params.context.type` 為 response.create 時可設定，表示用於覆蓋本輪推理的工作階段預設設定。未傳送時使用目前工作階段設定。詳見如下。

context.item參數：

參數	類型	說明
id	`String`	選填。對話項目的唯一識別碼。未傳送時由伺服器端自動產生。若指定的 ID 已存在於對話中，會傳回錯誤。
type	`String`	必選。對話項類型，可選值： `message`：一般對話訊息。 `function_call`：函數呼叫請求。通常由伺服器端產生，用戶端也可用於補充歷史上下文。 `function_call_output`：工具執行結果。用戶端收到 `function_call` 後執行工具，並用該類型寫回結果。
role	`String`	`message` 類型必選。訊息角色，可選值：`system`、`user`、`assistant`。
content	array	`message` 類型必選。訊息內容清單。每個元素包含 `type` 和對應的資料欄位。各 role 支援的 content 類型： system `input_text`：系統訊息，必填欄位 `text`。 user `input_text`：使用者文字輸入，必填欄位 `text`。 `input_audio`：使用者音訊輸入，必填欄位 `audio`（Base64 編碼）。 assistant `output_text`：助手文字輸出，必填欄位 `text`。
call_id	`String`	（`function_call` / `function_call_output` 類型必選）函數呼叫的唯一識別碼，用於關聯請求和結果。
name	`String`	（`function_call` 類型必選）要呼叫的函數名稱。
arguments	`String`	`function_call` 類型必選）函數呼叫參數，JSON 字串格式。
output	`String`	（`function_call_output` 類型必選）工具執行結果，JSON 字串格式。

context.response參數：

參數	類型	說明
modalities	`array`	array 格式的字串，模型輸出模態設定，可選值： `["text"]`：僅輸出文字。 `["audio", "text"]`（預設值）：同時輸出文字和音訊。
voice	string	覆蓋本輪的 TTS 音色。

範例：

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": [
        "text",
        "audio"
      ]
    },
    "type": "response.create"
  }
}

updateAudio

參數 audio_update_manually 設定為 "true" 時，錄音資料不再是透過 onNuiNeedAudioData 填入，而是用此介面主動推送。 方法簽章

public updateAudio(data: ArrayBuffer, first_pack: boolean): number

參數說明

參數	類型	說明
`data`	`ArrayBuffer`	推送的音訊資料（PCM）。
`first_pack`	`boolean`	是否為首包。SDK內部會按`data.byteLength`計算位元組數。

pushReferenceData（對應Android updateRefAudio）

參數 audio_update_manually 設定為 "true" 時，且啟用了端側 AEC 回音消除能力，則需要用此介面推送播放器播放的音訊資料作為參考訊號。 方法簽章

public pushReferenceData(data: ArrayBuffer, first_pack: boolean): number

參數說明

參數	類型	說明
`data`	`ArrayBuffer`	推送的音訊資料（PCM）。
`first_pack`	`boolean`	是否為首包。SDK內部會按`data.byteLength`計算位元組數。

release

釋放 SDK 所有內部資源。此方法呼叫後，SDK 執行個體將變為不可用狀態，如需再次使用，必須重新呼叫 initialize 進行初始化。 方法簽章

public release(): number

GetVersion

取得目前 SDK 版本資訊。 方法簽章

public GetVersion(): string

傳回值說明 目前 SDK 版本資訊。

INativeNuiCallback：監聽回呼

onNuiEventCallback：監聽事件資訊

方法簽章

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;

參數說明

參數	類型	說明
`event`	`Constants.NuiEvent`	回調事件。
`resultCode`	`number`	僅在出現 `EVENT_ASR_ERROR` 事件時有效。
`arg2`	`number`	保留參數。
`asrResult`	`AsrResult`	語音辨識結果。
`kwsResult`	`KwsResult`	語音喚醒功能。無需關注此參數。

onNuiAudioStateChanged：監聽音訊狀態

SDK 透過此回調通知何時應該開始或停止錄音。 方法簽章

onNuiAudioStateChanged: (state: Constants.AudioState) => void

AudioState 狀態說明

狀態	說明
`STATE_OPEN`	互動啟動，可以開啟錄音裝置進行錄音。
`STATE_PAUSE`	互動停止，可以停止錄音。
`STATE_CLOSE`	SDK 執行個體已釋放，可以徹底關閉錄音裝置。

onNuiAudioRMSChanged：監聽錄音音量

監聽錄音資料的音量，可用於UI顯示。 方法簽章

onNuiAudioRMSChanged: (val: number) => number

參數說明

參數	類型	說明
`val`	`number`	錄音資料的音量值。

onNuiNeedAudioData：填入待處理音訊資料

開始對話後，該回呼會被連續觸發，需在其中提供待處理的音訊資料。參數 audio_update_manually 設定為 "true" 時可不關注這個回呼。 方法簽章

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

參數說明

參數	類型	說明
`buffer`	`ArrayBuffer`	填充的音訊資料。SDK會按`buffer.byteLength`獲取期望讀取的位元組數。

傳回值說明 實際填入的位元組數。

onNuiAssistEventCallback：輔助資料和資訊結果

此回調用於接收 SDK 內部的輔助事件和相關資料。 方法簽章

onNuiAssistEventCallback?: (event: Constants.NuiEvent, info: string, infoLen: number,
                            data: ArrayBuffer) => void;

參數說明

參數	類型	說明
`event`	`Constants.NuiEvent`	`NuiEvent`事件。
`info`	`string`	附加資訊，通常為JSON 字串。
`infoLen`	`number`	附加資訊長度。
`data`	`ArrayBuffer`	附加的二進位資料，例如AI返回的TTS音訊。

注意：HarmonyOS中此回調為可選實作（?），不關注時可不實作。

onNuiLogTrackCallback：監聽追蹤日誌

此回調用於接收 SDK 內部的詳細日誌，方便進行問題定位和偵錯。

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

NuiEvent：事件類型

HarmonyOS SDK 中事件類型透過 Constants.NuiEvent 列舉定義，以下列出即時語音對話相關的事件：

事件	說明
EVENT_TRANSCRIBER_STARTED	任務啟動成功。
EVENT_VAD_START	任務啟動後即觸發此事件。不代表偵測到人聲起點。
EVENT_VAD_END	偵測到人聲終點。
EVENT_ASR_PARTIAL_RESULT	語音辨識中間結果。
EVENT_ASR_RESULT	完整的語音辨識結果。
EVENT_ASR_ERROR	語音對話過程中發生錯誤。
EVENT_MIC_ERROR	因連續 2 秒未收到任何音訊資料而觸發。
EVENT_SENTENCE_START	偵測到一句話開始。
EVENT_SENTENCE_END	偵測到一句話結束，此時會返回一句完整的辨識結果。
EVENT_TRANSCRIBER_COMPLETE	語音對話結束。
EVENT_AUDIO_TRANSCRIPTION	音訊模式下的文字字幕增量事件，串流返回字幕片段。
EVENT_AUDIO_TRANSCRIPTION_COMPLETED	音訊模式下的字幕輸出完成事件。
EVENT_OTHER_RESULT	其他未歸類事件資訊，例如 function_call 的返回結果等。
EVENT_ASR_TTS_START	AI 開始返回 TTS 資料。
EVENT_ASR_TTS_DATA	AI 返回的 TTS 資料。
EVENT_ASR_TTS_COMPLETE	AI 返回 TTS 資料結束。
EVENT_RESULT_TRANSLATED	翻譯中間結果。
EVENT_RESULT_TRANSLATED_END	翻譯結果輸出結束。
EVENT_AEC_DATA	AEC 回音消除後的音訊資料。

​快速開始

​呼叫步驟

​音訊裝置管理

​錄音（AudioCapturer）

​播放（AudioRenderer）

​權限宣告

​請求參數

​連線與控制參數

​語音對話效果參數

​關鍵介面

​NativeNui

​initialize

​setParams

​startDialog

​stopDialog

​cancelDialog

​dialogAction

​updateAudio

​pushReferenceData（對應Android updateRefAudio）

​release

​GetVersion

​INativeNuiCallback：監聽回呼

​onNuiEventCallback：監聽事件資訊

​onNuiAudioStateChanged：監聽音訊狀態

​onNuiAudioRMSChanged：監聽錄音音量

​onNuiNeedAudioData：填入待處理音訊資料

​onNuiAssistEventCallback：輔助資料和資訊結果

​onNuiLogTrackCallback：監聽追蹤日誌

​NuiEvent：事件類型

快速開始

呼叫步驟

音訊裝置管理

錄音（AudioCapturer）

播放（AudioRenderer）

權限宣告

請求參數

連線與控制參數

語音對話效果參數

關鍵介面

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

dialogAction

updateAudio

pushReferenceData（對應Android updateRefAudio）

release

GetVersion

INativeNuiCallback：監聽回呼

onNuiEventCallback：監聽事件資訊

onNuiAudioStateChanged：監聽音訊狀態

onNuiAudioRMSChanged：監聽錄音音量

onNuiNeedAudioData：填入待處理音訊資料

onNuiAssistEventCallback：輔助資料和資訊結果

onNuiLogTrackCallback：監聽追蹤日誌

NuiEvent：事件類型