HarmonyOS Next SDK

初始化

导入 SDK 类型。createRecognizer 的 callback 为下文的回调实现，其他参数由应用提供。

import { NativeNui, Constants, INativeNuiCallback, KwsResult, AsrResult } from 'neonui';

function createRecognizer(callback: INativeNuiCallback, resourceDir: string,
  filesDir: string, appkey: string, token: string, deviceId: string): NativeNui {
  const nui = new NativeNui(Constants.ModeType.MODE_DIALOG, 'asr');
  const parameters: Record<string, string> = {
    app_key: appkey,
    token: token,
    device_id: deviceId,
    url: 'wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1',
    workspace: resourceDir + '/resources_cloud',
    debug_path: filesDir,
    service_mode: Constants.ModeAsrCloud
  };
  const ret = nui.initialize(callback, JSON.stringify(parameters),
    Constants.LogLevel.LOG_LEVEL_VERBOSE, false);
  if (ret !== Constants.NuiResultCode.SUCCESS) {
    throw new Error('initialize failed: ' + ret);
  }
  return nui;
}

app_key、token、唯一的 device_id 和可读写的 workspace 为必填项。debug_path 用于保存调试文件。仅在需要时开启 save_log；开启后，日志持续写入且没有大小上限，需及时清理。save_wav 可用于保存音频调试数据，需要开启 save_log 并提供有效、可写的调试目录。

设置识别参数

在初始化成功后、开始识别前设置参数。

function configureRecognizer(nui: NativeNui, vadMode: boolean): number {
  const nlsConfig: Record<string, Object> = {
    enable_intermediate_result: true,
    enable_punctuation_prediction: true,
    enable_inverse_text_normalization: true,
    enable_voice_detection: vadMode
  };
  if (vadMode) {
    nlsConfig['max_start_silence'] = 10000;
    nlsConfig['max_end_silence'] = 800;
  }
  const parameters: Record<string, Object> = {
    nls_config: nlsConfig,
    service_type: Constants.kServiceTypeASR
  };
  return nui.setParams(JSON.stringify(parameters));
}

可按需在 nls_config 中配置customization_id、vocabulary_id、sample_rate（如 16000）和 sr_format（如 opus）。参数适用条件见接口说明，音频编码限制见下文常见问题。

开始识别

function startRecognizer(nui: NativeNui, token: string): number {
  const dialogParams: Record<string, string> = { token: token };
  return nui.startDialog(Constants.VadMode.TYPE_P2T, JSON.stringify(dialogParams));
}

使用 Constants.VadMode.TYPE_P2T。需要在开始一轮识别时更新 Token 或 Appkey，可在 dialog_params 中传入 token 或 app_key；某轮未传入临时参数时，继续使用初始化参数。

当前在线 SDK 不包含本地 VAD 模块。需要自动检测语音起止时，使用上例的 enable_voice_detection 开启云端 VAD，不使用仅适用于带离线功能 SDK 的 TYPE_VAD。

推送录音数据

在录音模块的 readData 回调中调用以下函数，按采集顺序传入音频。SDK 包中的录音封装为 AudioRecorder。

function pushAudio(nui: NativeNui, buffer: ArrayBuffer): number {
  return nui.updateAudio(buffer, false);
}

处理回调

以下 RecordingController 表示应用的录音控制接口，需连接到实际录音模块：start 启动录音，stop 停止录音。通过 onNuiAudioStateChanged 控制采集，将录音数据送给同一个 SDK 实例。

interface RecordingController {
  start(): void;
  stop(): void;
}

interface RecognitionPayload {
  result: string;
}

interface RecognitionResponse {
  payload: RecognitionPayload;
}

class NativeNuiCallbackHandle implements INativeNuiCallback {
  private recorder: RecordingController;
  constructor(recorder: RecordingController) {
    this.recorder = recorder;
  }

  onNuiAudioStateChanged(state: Constants.AudioState): void {
    if (state === Constants.AudioState.STATE_OPEN) {
      this.recorder.start();
    } else if (state === Constants.AudioState.STATE_CLOSE ||
      state === Constants.AudioState.STATE_PAUSE) {
      this.recorder.stop();
    }
  }

  onNuiNeedAudioData(buffer: ArrayBuffer): number {
    return 0;
  }

  onNuiEventCallback(event: Constants.NuiEvent, resultCode: number, arg2: number,
    kwsResult: KwsResult, asrResult: AsrResult): void {
    if (event === Constants.NuiEvent.EVENT_ASR_PARTIAL_RESULT ||
      event === Constants.NuiEvent.EVENT_ASR_RESULT) {
      if (asrResult && asrResult.asrResult) {
        try {
          const response = JSON.parse(asrResult.asrResult) as RecognitionResponse;
          if (response.payload) {
            console.info(response.payload.result);
          }
        } catch (e) {
          console.error('Invalid recognition response');
        }
      }
    } else if (event === Constants.NuiEvent.EVENT_ASR_ERROR ||
      event === Constants.NuiEvent.EVENT_MIC_ERROR) {
      console.error('recognition error: ' + resultCode);
    }
  }

  onNuiAudioRMSChanged(val: number): number {
    return 0;
  }

  onNuiLogTrackCallback(level: Constants.LogLevel, log: string): void {
  }
}

示例采用主动推送音频的方式，因此 onNuiNeedAudioData 返回 0。asrResult 可包含 task_id，可记录用于排查问题；allResponse 非空时包含完整 JSON 响应。出现 EVENT_ASR_ERROR 时，结合 resultCode、错误信息和任务 ID 排查；出现 EVENT_MIC_ERROR 时，检查录音权限、录音代码及录音模块是否被其他应用占用。EVENT_DIALOG_EX 无需处理。

结束识别

function stopRecognizer(nui: NativeNui): number {
  return nui.stopDialog();
}

需要立即取消、不等待最终结果时，改为调用 cancelDialog()。

释放资源

function releaseRecognizer(nui: NativeNui): number {
  return nui.release();
}

初始化与参数设置

initialize(callback: INativeNuiCallback, parameters: string,
  level: number, save_log: boolean = false): number
setParams(params: string): number
GetVersion(): string

parameters 和 params 为 JSON 字符串。level 为日志级别，值越小输出越多。save_log 默认关闭；开启时，日志目录由 debug_path 指定。GetVersion 返回 SDK 版本字符串。

识别与资源管理

startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
updateAudio(data: ArrayBuffer, first_pack: boolean): number
stopDialog(): number
cancelDialog(): number
release(): number

startDialog 启动识别，使用 TYPE_P2T，dialog_params 为本轮临时参数。updateAudio 向 SDK 送入音频。stopDialog 通知服务端结束识别并返回最终结果；cancelDialog 不等待最终结果，立即结束任务。release 释放 SDK 资源。

是否支持 OPUS 音频？

本 SDK 的一句话识别和录音文件识别极速版支持 OPUS 数据；实时语音识别仅支持 PCM 编码、16 bit 采样位数和单声道。详情请参见接口说明。

是否可以通过回调提供录音数据？

可以。若已通过共享数据和加锁保证录音数据生产、消费有序，可将资源文件 nui.json 中 nui_config.enable_callback_recording 设为 true，在 onNuiNeedAudioData 中填充录音数据，而不使用主动 updateAudio 推送。

实时语音识别与一句话识别的调用有何区别？

接口调用超时导致应用无响应，如何处理？

避免在 UI 线程执行同步 SDK 调用。线程调度方式可参考 SDK 包中的 OneSentenceAsrWorker.ets。