Qwen-Audio-ASR-Streaming の HarmonyOS SDK のパラメーター、インターフェイス、コールバックと使用方法を説明します。
クイックスタート
- API キーを取得します。長期有効な API キーをクライアントにハードコーディングしないでください。アプリケーションサーバーが一時 API キーを取得し、クライアントへ渡すことを推奨します。
-
最新 SDK をダウンロードして展開します。
entry/libs/neonui.harをアプリのentry/libsにコピーし、entry/oh-package.json5に依存関係を追加します。HarmonyOS C++ での統合には、native/libs内の共有ライブラリとnative/include内のヘッダーファイルを使用します。 -
アプリの
module.json5でネットワークとマイクの権限を宣言し、実行時にマイク権限を要求します。reason_internetとreason_microphoneはリソース名の例です。対応する説明をアプリのリソースで定義してください。 -
SDK パッケージのサンプルプロジェクトを DevEco Studio で開きます。サンプルページは
entry/src/main/ets/pages/dashscope/DashFunAsrSpeechTranscriberPage.etsです。API キーを設定して実行します。
呼び出し手順
NativeNui(Constants.ModeType.MODE_DIALOG)インスタンスを作成します。initializeで SDK を初期化し、接続・制御パラメーターを設定します。setParamsでモデルと認識パラメーターを設定します。startDialogを呼び出して認識を開始します。onNuiAudioStateChangedで音声の状態に応じて録音デバイスを開始、一時停止、または閉じます。onNuiNeedAudioDataで録音データを継続的に供給します。能動送信が有効なら、代わりにupdateAudioを呼び出します。onNuiEventCallbackで認識結果とタスク状態を取得します。stopDialogを呼び出し、EVENT_TRANSCRIBER_COMPLETEを待ちます。- 認識が不要になったら
releaseでリソースを解放します。
リクエストパラメーター
接続・制御パラメーター
initialize の parameters 引数に JSON 文字列を渡します。
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
url | string | はい | サービスエンドポイント:
{WorkspaceId} を実際の ワークスペース ID に置き換えます。 |
service_mode | string | はい | 動作モード。リアルタイム音声認識では "1"(Constants.ModeFullCloud)に設定します。 |
device_id | string | はい | アプリ内ユーザーIDやクライアント生成のデバイスIDなど、一意のエンドユーザー識別子です。主にログのトレースとトラブルシューティングに使用されます。 |
apikey | string | いいえ | API キー。初期化時に渡せます。startDialog の dialog_params で一時 API キーを渡すことを推奨します。 |
audio_update_manually | string | いいえ | 音声の能動送信を有効にするかどうか。デフォルトは "false"。"true" なら updateAudio を呼び、"false" なら SDK が onNuiNeedAudioData から取得します。"true" で SDK がデバイス側 AEC や VAD をサポートする場合、その機能はデフォルトで有効になります。 |
workspace | string | いいえ | デバイス側リソースの保存ディレクトリ。audio_update_manually が "true" で、AEC や VAD などのデバイス側処理が有効な場合は必須です。 |
debug_path | string | いいえ | ログディレクトリ。save_log が true の場合は必須です。SDK は最大 2 個のログファイルを保持します。 |
save_wav | string | いいえ | デバッグ用音声を保存するかどうか。デフォルトは "false"。音声は debug_path に保存します。"true" の場合は debug_path も設定し、initialize の save_log に true を渡します。 |
save_wav_by_id | string | いいえ | save_wav が有効な場合、検索しやすいよう保存音声のファイル名に task_id を使うかどうか。デフォルトは "false"。 |
max_log_file_size | number | いいえ | ログファイル 1 個の最大サイズ(バイト)。デフォルトは 104857600(100 MiB)。save_log が true の場合のみ有効です。 |
log_track_level | number | いいえ | onNuiLogTrackCallback のログフィルターレベル。デフォルトは 2。値は 0(VERBOSE)、1(DEBUG)、2(INFO)、3(WARNING)、4(ERROR)、5(NONE)。ログのレベルが log_track_level と initialize の level の両方以上の場合のみ返します。例えば 2 と 3 なら、WARNING 以上のみ返します。 |
enable_reconnection | string | いいえ | ネットワーク切断後の再接続と送信再開を有効にするかどうか。デフォルトは "false"。 |
aec_params | object | いいえ | デバイス側 AEC の設定。audio_update_manually が "true" の場合のみ使用します。 |
aec_params.enable_aec | boolean | いいえ | デバイス側 AEC を有効にするかどうか。SDK ビルドがサポートする場合はデフォルトで有効です。 |
aec_params.save_audio | boolean | いいえ | AEC 処理後の音声を保存するかどうか。save_wav が有効で debug_path が設定済みならデフォルトで有効です。 |
aec_params.enable_aec_data_callback | boolean | いいえ | AEC 処理後のデータを onNuiAssistEventCallback の EVENT_AEC_DATA イベントで返すかどうか。デフォルトは false。 |
vad_params | object | いいえ | デバイス側 VAD の設定。audio_update_manually が "true" の場合のみ使用します。 |
vad_params.enable_vad | boolean | いいえ | デバイス側 VAD を有効にするかどうか。SDK ビルドがサポートする場合はデフォルトで有効です。 |
vad_params.save_audio | boolean | いいえ | VAD 処理後の音声を保存するかどうか。save_wav が有効で debug_path が設定済みならデフォルトで有効です。 |
audio_config | object | いいえ | SDK が音声を取得するモードの録音設定。audio_update_manually が "false" の場合のみ使用します。 |
audio_config.mic.enable_volume_calculation | boolean | いいえ | 音量を計算して報告するかどうか。デフォルトは true。音量コールバックが不要なら無効にします。 |
audio_config.mic.volume_mode | string | いいえ | 音量の計算モード。"dbfs" にすると 20*log10(rms/32768) で標準 dBFS を計算します。フルスケールは 0 dB です。 |
認識パラメーター
setParams の params 引数に JSON 文字列を渡します。
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
service_type | number | はい | 音声サービスの種類。4(Constants.kServiceTypeSpeechTranscriber)に設定します。 |
nls_config | object | はい | 認識設定オブジェクト。 |
nls_config.model | string | はい | モデル名。 |
nls_config.sr_format | string | はい | 音声形式:pcm または opus。opus の場合もアプリケーションは PCM データを送信し、SDK が Opus にエンコードします。 |
nls_config.sample_rate | number | はい | サンプリングレート(Hz)。任意のサンプリングレートをサポートします。ただし、端末側 AEC または VAD を有効にする場合、8000 Hz は使用できません。 |
nls_config.max_sentence_silence | number | いいえ | VAD の無音しきい値(ミリ秒)。発話後の無音時間がこの値を超えると、発話の終了と判断します。デフォルト:800。有効範囲:[200, 6000]。 |
nls_config.multi_threshold_mode_enabled | boolean | いいえ | 複数しきい値モードを有効にするかどうか。デフォルト:false。VAD 分割が長くなりすぎるのを防ぎます。 |
nls_config.heartbeat | boolean | いいえ | ハートビートを有効にするかどうか。デフォルト:false。有効な場合、無音音声を継続送信すると接続を維持できます。無効な場合は一定時間後にタイムアウトします。無音音声とは、音声ファイルやストリームに可聴信号が含まれないデータです。 |
nls_config.vocabulary_id | string | いいえ | 事前作成したホットワードリストの ID。リストを事前に作成してください。語彙が既知で比較的安定しており、複数のリクエストで同じリストを再利用する場合に使用します。事前作成ホットワード を参照してください。 |
nls_config.instant_vocabulary | object | いいえ | リクエスト単位のホットワード。キーはホットワード文字列、値は整数の重みです。事前にリストを作成する必要がなく、セッション単位の一時的な最適化に適しています。重みは [1, 5] または 50。[1, 5] では値が大きいほど出力されやすくなります。重み 50 のスーパーホットワードは最大 50 個です。事前作成ホットワードと併用すると両方の集合を統合します。統合後に 2000 件を超える場合、2000 件をランダムに選択します。リクエスト単位のホットワード を参照してください。 |
nls_config.language_hints | string[] | いいえ | 音声の言語。デフォルト値はなく、省略時はモデルが自動検出します。最大で最初の 4 つの値が有効です。言語コードは リアルタイム音声認識ガイド を参照してください。 |
nls_config.speech_noise_threshold | number | いいえ | VAD の音声・ノイズ判定しきい値。有効範囲:[-1.0, 1.0]。-1 に近づけるとノイズが音声と判定されやすくなり、ノイズを文字起こしする可能性が高まります。1 に近づけると音声がノイズと判定されやすくなり、音声の一部が除去される可能性があります。この高度な設定は認識に大きく影響するため、十分にテストし、0.1 刻みで調整してください。 |
nls_config.special_word_filter | object | いいえ | 機微な語句のフィルタリング設定。機微な語句のフィルタリング を参照してください。 |
nls_config.enable_connection_fast_check | boolean | いいえ | ネットワーク切断の高速検出を有効にするかどうか。デフォルト:false。 |
APIs
NativeNui
SDK をインポートします。
インスタンスの作成
| パラメーター | 型 | 説明 |
|---|---|---|
mode_type | Constants.ModeType | SDK モード:対話・認識は MODE_DIALOG、音声合成は MODE_TTS、ストリーミング入力音声合成は MODE_STREAM_INPUT_TTS。リアルタイム音声認識では MODE_DIALOG に設定します。 |
flag | string | ログを区別するための任意のインスタンス ID。 |
initialize
| パラメーター | 型 | 説明 |
|---|---|---|
callback | INativeNuiCallback | イベントとデータのコールバック。 |
parameters | string | 接続・制御パラメーターを含む JSON 文字列。 |
level | number | SDK のログレベル:LOG_LEVEL_VERBOSE(0)、LOG_LEVEL_DEBUG(1)、LOG_LEVEL_INFO(2)、LOG_LEVEL_WARNING(3)、LOG_LEVEL_ERROR(4)、LOG_LEVEL_NONE(5)。 |
save_log | boolean | ローカルログを保存するかどうか。デフォルト:false。true の場合は parameters 内に debug_path を指定してください。max_log_file_size も設定できます。 |
setParams
startDialog の前に認識パラメーターを設定します。params は認識パラメーターを含む JSON 文字列です。
startDialog
| パラメーター | 型 | 説明 |
|---|---|---|
vad_mode | Constants.VadMode | VAD モード。リアルタイム音声認識では Constants.VadMode.TYPE_P2T に設定します。 |
dialog_params | string | JSON 文字列。期限切れの一時 API キーの更新、または input_context による入力コンテキストの指定に使用します。 |
stopDialog
EVENT_TRANSCRIBER_COMPLETE の受信でタスクが終了します。
cancelDialog
dialogAction
| パラメーター | 型 | 説明 |
|---|---|---|
action_params | string | アクションを含む JSON 文字列。 |
action_params.type | string | "action" に設定します。 |
action_params.command | string | play_start:オンデバイス AEC を使用する場合、プレーヤーが音声の再生を開始したことを SDK に通知します。 play_over:オンデバイス AEC を使用する場合、プレーヤーが音声の再生を終了したことを SDK に通知します。 |
updateAudio
audio_update_manually が "true" の場合、onNuiNeedAudioData に格納せず、このメソッドで録音データを能動的に送信します。
| パラメーター | 型 | 説明 |
|---|---|---|
data | ArrayBuffer | 認識対象の音声データ。 |
first_pack | boolean | 最初の音声パケットかどうか。最初は true、以降は false に設定します。 |
pushReferenceData
audio_update_manually が "true" でデバイス側 AEC が有効な場合、プレーヤーの再生音声を AEC 参照信号として送信します。
| パラメーター | 型 | 説明 |
|---|---|---|
data | ArrayBuffer | 参照音声データ。 |
first_pack | boolean | 最初の音声パケットかどうか。最初は true、以降は false に設定します。 |
release
initialize を先に呼び出します。
GetVersion
refreshApikey
| パラメーター | 型 | 説明 |
|---|---|---|
apikey | string | 既存の API キー。 |
url | string | 任意の認証エンドポイント。デフォルトは空文字列で、既定のエンドポイントを使用します。 |
INativeNuiCallback
onNuiEventCallback
| パラメーター | 型 | 説明 |
|---|---|---|
event | Constants.NuiEvent | コールバックイベント。 |
resultCode | number | EVENT_ASR_ERROR イベント発生時のみ有効です。 |
arg2 | number | Reserved. |
kwsResult | KwsResult | ウェイクワードの結果。リアルタイム音声認識では無視してください。 |
asrResult | AsrResult | 認識結果。allResponse はサーバーの完全な JSON 応答です。タスク ID は header.task_id、発話テキストは payload.output.sentence.text から取得できます。 |
| イベント | 説明 |
|---|---|
EVENT_TRANSCRIBER_STARTED | タスクが開始しました。asrResult.allResponse 内の header.task_id にタスク ID が含まれます。問題調査に備えて記録してください。 |
EVENT_VAD_START | タスク開始後に発生します。発話開始の検出を示すイベントではありません。 |
EVENT_VAD_END | 発話の終了が検出されました。 |
EVENT_SENTENCE_START | 文の開始が検出されました。 |
EVENT_ASR_PARTIAL_RESULT | 中間認識結果が返されました。 |
EVENT_SENTENCE_END | 文の終了が検出され、文全体の認識結果が返されました。 |
EVENT_ASR_WARN | 認識中に致命的でない警告が発生しました。例:再接続が有効な場合のネットワーク切断。 |
EVENT_ASR_ERROR | 認識中にエラーが発生しました。resultCode にエラーコードが含まれます。 |
EVENT_MIC_ERROR | 2 秒間連続で音声データを受信していません。録音コード、権限、他のアプリによる録音デバイスの使用状況を確認してください。 |
EVENT_TRANSCRIBER_COMPLETE | 認識が終了しました。 |
EVENT_AEC_DATA | onNuiAssistEventCallback を通じて返される AEC 処理済み音声データ。 |
onNuiAudioStateChanged
| State | 説明 |
|---|---|
STATE_OPEN | 対話が開始しました。録音デバイスを開くことができます。 |
STATE_PAUSE | 対話が停止しました。録音を停止できます。 |
STATE_CLOSE | SDK インスタンスが解放されました。録音デバイスを完全に閉じることができます。 |
AudioCapturer は非同期で作成されます。初期化中に録音インスタンスを作成してください。STATE_CLOSE では録音を停止し、インスタンスは再利用のため保持します。統一された release 処理で解放してください。これにより、次の STATE_OPEN で直ちに start が呼ばれた際、再作成中のレコーダーがその呼び出しを受け付けない問題を避けられます。
onNuiNeedAudioData
buffer.byteLength バイト(通常は 20 ms のモノラル 16 ビット PCM)を格納し、書き込んだバイト数を返します。0 以下はエラーまたはデータなしを示します。
onNuiAudioRMSChanged
audio_config.mic.volume_mode が "dbfs" の場合、val は -160~0 です。コールバック実装では 0 を返せます。
onNuiAssistEventCallback
| パラメーター | 型 | 説明 |
|---|---|---|
event | Constants.NuiEvent | 補助イベント。 |
info | string | 追加情報。通常は JSON 文字列です。 |
infoLen | number | 追加情報の長さ。 |
data | ArrayBuffer | AEC 処理済み音声などの補助データ。 |
onNuiLogTrackCallback
log_track_level と initialize の level の両方で決まります。
結果オブジェクト
AsrResult
| Property | 型 | 説明 |
|---|---|---|
finish | boolean | 現在の結果が最終結果かどうか。 |
resultCode | number | 結果のステータスコード。 |
asrResult | string | 認識テキスト。EVENT_ASR_ERROR の場合はエラーメッセージが含まれます。 |
allResponse | string | タスク ID と発話テキストを含む、JSON 文字列形式の完全なサーバー応答。 |
KwsResult
| Property | 型 | 説明 |
|---|---|---|
type | Constants.WuwType | ウェイクワードの種類。リアルタイム音声認識では無視してください。 |
kws | string | ウェイクワード。リアルタイム音声認識では無視してください。 |
定数と列挙型
| 名前 | 説明 |
|---|---|
Constants.ModeType | SDK モード:MODE_DIALOG、MODE_TTS、MODE_STREAM_INPUT_TTS。 |
Constants.VadMode | VAD モード。リアルタイム音声認識では TYPE_P2T を使用し、ユーザーが stopDialog を呼び出して認識を終了します。 |
Constants.AudioState | 音声状態:STATE_OPEN、STATE_PAUSE、STATE_CLOSE。 |
Constants.LogLevel | ログレベル:LOG_LEVEL_VERBOSE(0)から LOG_LEVEL_NONE(5)まで。 |
Constants.NuiResultCode | SDK エラーコード。例:SUCCESS(0)、ILLEGAL_PARAM(240002)、NECESSARY_PARAM_LACK(240004)、SDK_NOT_INIT(240011)。 |
Constants.kServiceTypeSpeechTranscriber | リアルタイム音声認識の service_type 値。値は 4 です。 |
Constants.ModeFullCloud | フルクラウドモード。service_mode の値は "1" です。 |
サンプルコード
以下は SDK の主要な処理の例です。完全な権限処理、録音キュー、応答解析については、SDK パッケージの DashFunAsrSpeechTranscriberPage.ets を参照してください。
@kit.AudioKit の AudioCapturer を使用します。音声はモノラル 16 ビット PCM で、選択モデルが対応するサンプリングレートにしてください。