Qwen-Audio-ASR-Filetrans非リアルタイム音声認識HarmonyOS SDK

クイックスタート

APIキーの取得： APIキーの取得。セキュリティのため、APIキーを環境変数として設定することを推奨します。
SDK をダウンロードしてサンプルコードを実行します：
- 最新のSDKパッケージをダウンロードしてください。
- TARパッケージを展開します。neonuiディレクトリからHAR形式のSDKを取得し、プロジェクトの依存関係に追加してください。 C++統合の場合は、TARパッケージ内のnative/libsおよびnative/includeから動的ライブラリとヘッダーファイルを取得してください。
- DevEco Studioでプロジェクトを開きます。サンプルコードはDashFunAsrFileTranscriberPage.etsにあります。APIキーを置き換えて機能を試してください。

呼び出し手順

同期モード

SDK を初期化します。
ビジネス要件に基づいてパラメータを設定します。
startFileTranscriberを呼び出し、async_requestをfalseに設定して認識タスクを開始します。
onFileTransEventCallbackインターフェースでEVENT_FILE_TRANS_RESULTイベントをリッスンし、最終的な認識結果を取得します。
releaseを呼び出してSDKリソースを解放してください。

非同期モード

SDK を初期化します。
ビジネス要件に基づいてパラメータを設定します。
startFileTranscriberを呼び出し、async_requestをtrueに設定して認識タスクを開始します。
queryFileTranscriberを呼び出して、認識の進行状況または結果を照会します。
onFileTransEventCallbackインターフェースでEVENT_FILE_TRANS_QUERY_RESULTイベントをリッスンし、現在の照会結果を取得します。
onFileTransEventCallbackインターフェースでEVENT_FILE_TRANS_RESULTイベントをリッスンし、最終的な認識結果を取得します。
releaseを呼び出してSDKリソースを解放してください。

リクエストパラメーター

接続および制御パラメータ

以下のパラメータを設定するには、initializeFileTrans の parameters パラメータにJSON文字列を渡してください。例以下のJSON文字列は例であり、すべてのパラメータを含んでいるわけではありません。必要に応じてパラメータを追加してください。

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

パラメータの説明

パラメーター	タイプ	必須	説明
`url`	`string`	はい	エンドポイント。これは`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription`に固定されています。`{WorkspaceId}`を実際のワークスペースIDに置き換えてください。
`apikey`	`string`	はい	APIキー。長期的なキーの漏洩リスクを軽減するため、有効期間の短い、より安全な一時APIキーの使用を推奨します。
`service_mode`	`string`	はい	動作モード。非リアルタイム音声認識の場合、これは`"1"`に固定されています。
`device_id`	`string`	はい	エンドユーザーを識別する一意の文字列。アプリ内のユーザーIDや、クライアントによって生成された一意のデバイス識別子に設定できます。このIDは主にログ追跡およびトラブルシューティングに使用されます。
`debug_path`	`string`	いいえ	ログファイルの保存パスです。このパラメーターは、`initializeFileTrans` を呼び出す際に `save_log` を true に設定した場合にのみ有効になります。この場合、ログファイルのパスを指定する必要があります。指定しない場合はエラーが発生します。ローカルには最大2つのログファイルが保持されます。
`max_log_file_size`	`number`	いいえ	ログファイルの最大サイズをバイト単位で設定します。このパラメーターは、`initializeFileTrans` を呼び出す際に `save_log` を true に設定した場合にのみ有効になります。デフォルト値：104857600（100 * 1024 * 1024 バイト、つまり 100 MiB）。

音声認識効果パラメータ

setParams を使用して nls_config パラメータを設定するか、startFileTranscriber を使用してすべての音声認識効果パラメータを設定してください。例以下のJSON文字列は例であり、すべてのパラメータを含んでいるわけではありません。必要に応じてパラメータを追加してください。

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

パラメータの説明

パラメーター	タイプ	必須	説明
`file_urls`	`array[string]`	はい	文字起こし対象のオーディオまたはビデオファイルのURLリスト。HTTPおよびHTTPSがサポートされています。単一のリクエストでサポートされるURLは 1 つだけです。サポートされるオーディオ形式、ファイルサイズおよび再生時間の制限などの入力要件については、オーディオ仕様を参照してください。オーディオファイルがAlibaba Cloud OSSに保存されている場合、RESTful APIは `oss://` プレフィックス付きの一時的なURLをサポートしますが、SDKはサポートしていません。一時URLの有効期間は48時間であり、期限切れ後は使用できません。本番環境では一時URLを使用しないでください。ファイルアップロード認証情報インターフェースは100 QPSに制限されており、スケールアウトすることはできません。本番環境、高同時実行シナリオ、またはストレステストで使用しないでください。本番環境では、Alibaba Cloud OSSなどの安定したストレージを使用して、ファイルの長期的な可用性を確保し、スロットリングを回避してください。 - 一時的なパブリックOSS URLにアクセスできない場合は、`X-DashScope-OssResourceResolve`リクエストヘッダーを`enable`に設定してください。この方法は推奨されません。SDKはリクエストヘッダーの設定をサポートしていません。
`async_request`	`boolean`	いいえ	非同期リクエストを使用するかどうかを指定します。デフォルト値：`false`。有効な値：- true：非同期リクエスト - false：同期リクエスト。
`apikey`	`string`	いいえ	接続および制御パラメーターの `apikey` が一時的なAPIキーである場合、期限切れになる前にここで更新してください。
`nls_config`	`object`	はい	モデル選択および認識効果制御のための主要なパラメータを含む、コアとなる音声認識設定オブジェクト。
`nls_config.model`	`string`	はい	モデル名。
`nls_config.special_word_filter`	`object`	いいえ	音声認識中に処理するセンシティブワードを指定し、単語ごとに異なる処理方法をサポートします。詳細については、センシティブワードフィルタリングを参照してください。
`nls_config.channel_id`	`array[integer]`	いいえ	マルチトラックオーディオファイル内で認識対象とするオーディオトラックのインデックスを指定します。インデックスは 0 から始まります。たとえば、`[0]` は最初のトラックを認識し、`[0, 1]` は1番目と2番目のトラックを認識します。省略した場合、最初のトラックが処理されます。指定された各トラックは個別に課金されます。たとえば、1つのファイルに対して `[0, 1]` を指定すると、2つの別々の料金が発生します。デフォルト値：`[0]`。
`nls_config.diarization_enabled`	`boolean`	いいえ	話者分離を有効にするかどうかを指定します。この機能はデフォルトで無効になっています。モノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。有効にすると、認識結果に`speaker_id`が含まれ、話者を区別できます。話者分離が有効になっている場合、認識の失敗やタイムアウトを避けるため、音声の長さを2時間以内に制限することを推奨します。デフォルト値：false。`speaker_id`の例については、認識結果の説明を参照してください。
`nls_config.speaker_count`	`integer`	いいえ	このパラメータは、`diarization_enabled`を`true`に設定して話者分離を有効にした場合にのみ機能します。話者数の参照値を提供します。有効な値は2から100までの整数です。デフォルトでは、話者数は自動的に決定されます。このパラメータが設定されている場合、アルゴリズムが指定された数を出力するように導くだけであり、その数を保証するものではありません。デフォルト値はありません。
`nls_config.vocabulary_id`	`string`	いいえ	事前コンパイル済みホットワードリストのIDです。事前にホットワードリストを作成し、認識時にそのIDを渡すことで、リスト内のホットワードを使用できます。これは、語彙が既知で比較的安定しており、リクエスト間で同じ語彙を再利用する必要がある場合に適しています。詳細については、事前コンパイル済みホットワードを参照してください。
`nls_config.language_hints`	`array[string]`	いいえ	認識対象のオーディオの言語コードを指定します。事前に言語を特定できない場合は、このパラメータを省略するとモデルが自動的に言語を検出します。最大 4 個の値を指定できます。それ以上指定した場合は、最初の 4 個だけが有効です。サポートされている言語コードを表示するにはクリックしてください zh: 中国語 en: 英語 ja: 日本語 ko: 韓国語 vi: ベトナム語 th: タイ語 id: インドネシア語 ms: マレー語 tl: フィリピン語 hi: ヒンディー語 ar: アラビア語 fr: フランス語 de: ドイツ語 es: スペイン語 pt: ポルトガル語 ru: ロシア語 it: イタリア語 nl: オランダ語 sv: スウェーデン語 da: デンマーク語 fi: フィンランド語 no: ノルウェー語 el: ギリシャ語 pl: ポーランド語 cs: チェコ語 hu: ハンガリー語 ro: ルーマニア語 bg: ブルガリア語 hr: クロアチア語 sk: スロバキア語
`nls_config.parameters`	`object`	いいえ	追加のパラメータをJSONオブジェクトとして設定します。

主要インターフェース

NativeNui

initializeFileTrans

音声転写SDKインスタンスを初期化します。releaseを呼び出す前に、インスタンスを再度初期化しないでください。

リアルタイム音声認識とは異なり、非リアルタイムのオーディオファイル文字起こしでは、initialize を使用する代わりに initializeFileTrans を使用し、INativeFileTransCallback コールバックを渡す必要があります。

このインターフェースは呼び出し元のスレッドをブロックします。UIスレッド以外から呼び出してください。 メソッドシグネチャ

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

パラメータの説明

パラメーター	タイプ	説明
`callback`	`INativeFileTransCallback`	ファイル転写イベントおよびデータコールバックインターフェースの実装。
`parameters`	`string`	認証、接続、およびデバッグパラメータを含むJSON文字列。接続および制御パラメータを参照してください。
`level`	`number`	SDKのログレベルを制御します。有効な値は`Constants.LogLevel`列挙型で定義されています。
`save_log`	`boolean`	ローカルログを保存するかどうかを指定します。このパラメーターが `true` の場合、接続および制御パラメーターの `debug_path` を使用してパスを指定してください。また、`max_log_file_size` を使用してファイルサイズを設定することもできます。

setParams

nls_configパラメータのみを設定または更新します。すべてのパラメータがstartFileTranscriberで提供されている場合、このメソッドを呼び出す必要はありません。 メソッドシグネチャ

public setParams(params: string): number

パラメータの説明

パラメーター	タイプ	説明
`params`	`string`	音声認識効果パラメーターの `nls_config` パラメーターです。`nls_config` 以外のパラメーターはこのメソッドでは設定できません。例：`{ "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`

startFileTranscriber

認識を開始します。 メソッドシグネチャ

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

パラメータの説明

パラメーター	タイプ	説明
`params`	`string`	音声認識効果パラメータ。例：`{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`
`task_id`	`ArrayBuffer`	タスクIDバッファ。SDKは内部で生成されたランダムなタスクID文字列をこのバッファに書き込みます。バッファの長さは少なくとも33バイトである必要があります。例では`new ArrayBuffer(64)`を使用しています。呼び出しが成功した後、バッファをデコードしてタスクの`task_id`を取得してください。

queryFileTranscriber

非同期タスクの現在のステータスと結果をクエリします。呼び出しが成功すると、onFileTransEventCallback コールバック内の EVENT_FILE_TRANS_QUERY_RESULT イベントによって結果が返されます。 メソッドシグネチャ

public queryFileTranscriber(task_id: string): number

パラメータの説明

パラメーター	タイプ	説明
`task_id`	`string`	照会対象のタスクIDで、`startFileTranscriber`によって書き込まれたバッファから取得されます。

cancelFileTranscriber

現在のタスクを即座にキャンセルします。 メソッドシグネチャ

public cancelFileTranscriber(task_id: string): number

パラメータの説明

パラメーター	タイプ	説明
`task_id`	`string`	キャンセルするタスクのIDです。

release

すべての内部SDKリソースを解放します。このメソッドが呼び出された後、SDKインスタンスは使用できなくなります。再度使用するには、initializeFileTransを呼び出して再初期化してください。 メソッドシグネチャ

public release(): number

GetVersion

現在のSDKバージョン情報を取得します。 メソッドシグネチャ

public GetVersion(): string

戻り値 現在の SDK バージョン情報。

INativeFileTransCallback

ファイル転写イベントおよび認識結果のコールバックを定義します。

onFileTransEventCallback

ファイル転写イベントをリッスンし、音声認識結果を取得します。 メソッドシグネチャ

onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;

パラメータの説明

パラメーター	タイプ	説明
`event`	`Constants.NuiEvent`	コールバックイベント。
`resultCode`	`number`	`EVENT_ASR_ERROR` イベントが発生した場合にのみ有効です。
`finish`	`number`	タスクが終了したかどうかを示します。
`asrResult`	`AsrResult`	音声認識結果。
`taskId`	`string`	タスクID。

Constants.NuiEvent

HarmonyOS SDKのイベントタイプはConstants.NuiEvent列挙型によって定義されています。以下のイベントは音声ファイル転写に適用されます：

イベント	説明
`EVENT_FILE_TRANS_CONNECTED`	サービスが接続されました。
`EVENT_FILE_TRANS_UPLOADED`	認識対象の音声ファイルがアップロードされました。
`EVENT_FILE_TRANS_QUERY_RESULT`	タスククエリの結果です。
`EVENT_FILE_TRANS_RESULT`	最終的な認識結果。
`EVENT_ASR_ERROR`	音声認識中にエラーが発生しました。

補助タイプ

Constants.LogLevel

levelパラメータの列挙値は以下の通りです：

値	説明
`LOG_LEVEL_VERBOSE`	最も詳細なログ。
`LOG_LEVEL_DEBUG`	デバッグログ。
`LOG_LEVEL_INFO`	情報ログ（デフォルト）。
`LOG_LEVEL_WARNING`	警告ログ。
`LOG_LEVEL_ERROR`	エラーログ。
`LOG_LEVEL_NONE`	ロギングを無効にします。

結果のダウンロード

非リアルタイム音声認識の結果は非同期に生成されます。EVENT_FILE_TRANS_RESULTイベントによって返されるレスポンスにはtranscription_urlが含まれます。このURLからJSON形式の認識テキストをダウンロードしてください。URLには有効期限があります。結果を速やかにダウンロードしてください。

​クイックスタート

​呼び出し手順

​同期モード

​非同期モード

​リクエストパラメーター

​接続および制御パラメータ

​音声認識効果パラメータ

​主要インターフェース

​NativeNui

​initializeFileTrans

​setParams

​startFileTranscriber

​queryFileTranscriber

​cancelFileTranscriber

​release

​GetVersion

​INativeFileTransCallback

​onFileTransEventCallback

​Constants.NuiEvent

​補助タイプ

​Constants.LogLevel

​結果のダウンロード

クイックスタート

呼び出し手順

同期モード

非同期モード

リクエストパラメーター

接続および制御パラメータ

音声認識効果パラメータ

主要インターフェース

NativeNui

initializeFileTrans

setParams

startFileTranscriber

queryFileTranscriber

cancelFileTranscriber

release

GetVersion

INativeFileTransCallback

onFileTransEventCallback

Constants.NuiEvent

補助タイプ

Constants.LogLevel

結果のダウンロード