Skip to main content

Paraformer非リアルタイム音声認識HarmonyOS SDK

このガイドでは、Paraformer非リアルタイム音声認識HarmonyOS SDKを使用して音声をテキストに変換する方法について説明します。

ユーザーガイド： 非リアルタイム音声認識

クイックスタート

  1. APIキーの取得： APIキーの取得と設定。セキュリティのため、APIキーは環境変数として設定することをお勧めします。
    サードパーティアプリケーションまたはユーザーに一時的なアクセス権を付与する場合、あるいは機密データへのアクセスや削除などの高リスク操作を厳密に制御する場合は、一時的なAPIキーを使用します。一時的なAPIキーは、デフォルトで60秒間有効です。有効期限が切れた後は、新しいものを取得してください。
  2. SDKをダウンロードしてサンプルコードを実行します:
    • 最新のSDKパッケージをダウンロードします。
    • TARパッケージを展開します。neonuiディレクトリからHAR形式のSDKを取得し、プロジェクトの依存関係に追加します。 C++統合の場合、TARパッケージのnative/libsおよびnative/includeから動的ライブラリとヘッダーファイルを取得します。
    • DevEco Studioでプロジェクトを開きます。サンプルコードはDashParaformerFileTranscriberPage.etsにあります。APIキーを置き換えて、機能を試してください。

呼び出し手順

同期モード

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

非同期モード

  1. SDKを初期化します。
  2. ビジネス要件に基づいてパラメータを設定します。
  3. startFileTranscriberを呼び出して、async_requestをtrueに設定した認識タスクを開始します。
  4. queryFileTranscriberを呼び出して、認識の進行状況または結果をクエリします。
  5. onFileTransEventCallbackインターフェースで、EVENT_FILE_TRANS_QUERY_RESULTイベントをリッスンして現在のクエリ結果を取得します。
  6. onFileTransEventCallbackインターフェースで、EVENT_FILE_TRANS_RESULTイベントをリッスンして最終認識結果を取得します。
  7. 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"
}
  • パラメータの説明
パラメータ型必須説明
urlstringはいエンドポイント。これはwss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionに固定されています。{WorkspaceId}を実際のワークスペースIDに置き換えます。
apikeystringはいAPIキー。長期キーの漏洩リスクを軽減するため、有効期間の短い、より安全な一時的なAPIキーを使用することをお勧めします。
service_modestringはい動作モード。非リアルタイム音声認識の場合、これは"1"に固定されています。
device_idstringはいエンドユーザーを識別する一意の文字列。アプリ内のユーザーIDまたはクライアントによって生成された一意のデバイス識別子に設定できます。このIDは主にログの追跡とトラブルシューティングに使用されます。
debug_pathstringいいえログファイルの保存パス。このパラメータは、initializeFileTransを呼び出す際にsave_logをtrueに設定した場合にのみ有効になります。この場合、ログファイルのパスを指定する必要があります。指定しないとエラーが発生します。ローカルには最大2つのログファイルが保持されます。
max_log_file_sizenumberいいえログファイルの最大サイズをバイト単位で設定します。このパラメータは、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":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}
  • パラメータの説明
パラメータ型必須説明
file_urlsarray[string]はい

文字起こしする音声ファイルまたは動画ファイルのURLのリスト。HTTPおよびHTTPSがサポートされています。1つのリクエストでサポートされるURLは1つのみです。音声ファイルがAlibaba Cloud OSSに保存されている場合、SDKはoss://プレフィックスを使用する一時的なURLをサポートしません。- 音声フォーマット：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、およびwmv。

オーディオおよびビデオ形式には多くのバリアントがあるため、技術的にすべてをテストすることは不可能です。APIは、すべての形式が正しく認識されることを保証できません。ファイルをテストして、有効な認識結果が生成されることを確認してください。

- 音声サンプリングレートはモデルによって異なります：- paraformer-v2は任意のサンプリングレートをサポートします。- は任意のサンプリングレートをサポートします。- paraformer-8k-v2は8 kHzのみをサポートします。- は8 kHzのみをサポートします。- は16 kHz以上をサポートします。- 音声ファイルのサイズと長さ：ファイルは2 GBを超えることができず、長さは12時間を超えることができません。これらの制限を超えるファイルを処理するには、前処理を行ってファイルサイズを縮小してください。ベストプラクティスについては、「音声ファイル認識の文字起こし効率を向上させるための動画ファイルの前処理」を参照してください。

async_requestbooleanいいえ非同期リクエストを使用するかどうかを指定します。デフォルト値：false。有効な値：- true：非同期リクエスト - false：同期リクエスト。
apikeystringいいえ接続および制御パラメータのapikeyが一時的なAPIキーである場合、有効期限が切れる前にここで更新します。
nls_configobjectはいコア音声認識設定オブジェクト。モデル選択および認識効果制御の主要なパラメータが含まれています。
nls_config.modelstringはい音声認識モデル。
nls_config.language_hintsarray[string]いいえ認識するオーディオの言語コードを指定します。このパラメータはparaformer-v2にのみ適用されます。デフォルト値：["zh", "en"]。サポートされている言語コード：- zh：中国語 - en：英語 - ja：日本語 - yue：広東語 - ko：韓国語 - de：ドイツ語 - fr：フランス語 - ru：ロシア語。
nls_config.disfluency_removal_enabledbooleanいいえフィラーワードなどのディスフルエンシーを削除するかどうかを指定します。デフォルト値：false。有効な値：- true：ディスフルエンシーを削除 - false：ディスフルエンシーを保持。
nls_config.timestamp_alignment_enabledbooleanいいえタイムスタンプアライメントを有効にするかどうかを指定します。デフォルト値：false。有効な値：- true：有効 - false：無効。
nls_config.special_word_filterobjectいいえ音声認識中に処理するセンシティブワードを指定し、単語ごとに異なる処理方法をサポートします。このパラメータを省略すると、組み込みのセンシティブワードフィルタリングロジックが有効になります。Alibaba Cloud Model Studioセンシティブワードリストに一致する単語は、同じ数の*文字に置換されます。このパラメータを指定すると、一致した単語を*文字に置換するか、削除することができます。値は以下の形式のJSONオブジェクトです：{ "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true }。JSONフィールドの説明：- filter_with_signed：同じ数の*文字に置換する単語を指定するオプションのオブジェクト。前述の例では、「帮我测试一下这段代码」の結果は「帮我**一下这段代码」となります。そのword_listフィールドは、置換する文字列の配列です。- filter_with_empty：結果から削除する単語を指定するオプションのオブジェクト。前述の例では、「比赛这就要开始了吗？」の結果は「比赛这就要了吗」となります。そのword_listフィールドは、削除する文字列の配列です。- system_reserved_filter：オプションのブール値。デフォルト値：true。組み込みのセンシティブワードルールを有効にするかどうかを指定します。trueに設定すると、Alibaba Cloud Model Studioセンシティブワードリストに一致する単語が同じ数の*文字に置換されます。
nls_config.channel_idarray[integer]いいえ

マルチトラックオーディオファイルで認識するオーディオトラックのインデックスを指定します。インデックスは0から始まります。たとえば、[0]は最初のトラックを認識し、[0, 1]は1番目と2番目のトラックを認識します。省略した場合、最初のトラックが処理されます。

指定された各トラックは個別に課金されます。たとえば、1つのファイルに対して[0, 1]を指定すると、2つの個別の料金が発生します。

デフォルト値：[0]。

nls_config.diarization_enabledbooleanいいえ

話者分離を有効にするかどうかを指定します。この機能はデフォルトで無効になっています。モノラルオーディオにのみ適用されます。マルチチャンネルオーディオは話者分離をサポートしていません。有効にすると、認識結果にspeaker_idが含まれ、話者を区別します。

話者分離が有効になっている場合、認識の失敗やタイムアウトを回避するために、オーディオの長さを2時間以内に制限することをお勧めします。

speaker_idの例については、認識結果の説明を参照してください。

nls_config.speaker_countintegerいいえ話者数の参照値。この機能を使用するには、diarization_enabledをtrueに設定します。デフォルトでは、話者数は自動的に判定されます。このパラメータが設定されている場合、アルゴリズムが指定された数を出力するように誘導するだけであり、その数を保証するものではありません。有効範囲：[2, 100]。この機能は複数の話者を識別するため、最小値は2です。
nls_config.vocabulary_idstringいいえ特定の単語の認識精度を向上させるホットワード語彙ID。このパラメータはv2以降のモデルに適用されます。詳細については、カスタムホットワードを参照してください。

主要インターフェース

NativeNui

initializeFileTrans

音声転写SDKインスタンスを初期化します。releaseを呼び出す前に、インスタンスを再度初期化しないでください。
リアルタイム音声認識とは異なり、非リアルタイムオーディオファイル転写ではinitializeFileTransを使用し、initializeの代わりにINativeFileTransCallbackコールバックを渡す必要があります。
このインターフェースは呼び出し元のスレッドをブロックします。非UIスレッドから呼び出してください。
  • メソッドシグネチャ
public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number
  • パラメータの説明
パラメータ型説明
callbackINativeFileTransCallbackファイル転写イベントおよびデータコールバックインターフェースの実装。
parametersstring認証、接続、およびデバッグパラメータを含む JSON 文字列。接続および制御パラメータを参照してください。
levelnumberSDKログレベルを制御します。有効な値はConstants.LogLevel列挙型で定義されています。
save_logbooleanローカルログを保存するかどうかを指定します。このパラメータがtrueの場合、接続および制御パラメータのdebug_pathを使用してパスを指定します。max_log_file_sizeを使用してファイルサイズを設定することもできます。
  • 戻り値

setParams

nls_configパラメータのみを設定または更新します。すべてのパラメータがstartFileTranscriberで提供されている場合、このメソッドを呼び出す必要はありません。
  • メソッドシグネチャ
public setParams(params: string): number
  • パラメータの説明
パラメータ型説明
paramsstring音声認識効果パラメータ内のnls_configパラメータ。nls_config以外のパラメータは、このメソッドを使用して設定できません。例：{ "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }
  • 戻り値

startFileTranscriber

認識を開始します。
  • メソッドシグネチャ
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
  • パラメータの説明
パラメータ型説明
paramsstring音声認識効果パラメータ。例：{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }
task_idArrayBufferタスクIDバッファ。SDKは内部で生成されたランダムなタスクID文字列をこのバッファに書き込みます。バッファの長さは少なくとも33バイトである必要があります。例ではnew ArrayBuffer(64)を使用しています。呼び出しが成功した後、バッファをデコードしてタスクのtask_idを取得します。
  • 戻り値

queryFileTranscriber

非同期タスクの現在のステータスと結果をクエリします。呼び出しが成功すると、結果はonFileTransEventCallbackコールバック内のEVENT_FILE_TRANS_QUERY_RESULTイベントによって返されます。
  • メソッドシグネチャ
public queryFileTranscriber(task_id: string): number
  • パラメータの説明
パラメータ型説明
task_idstringクエリするタスクのID。startFileTranscriberによって書き込まれたバッファから取得します。
  • 戻り値

cancelFileTranscriber

現在のタスクを即座にキャンセルします。
  • メソッドシグネチャ
public cancelFileTranscriber(task_id: string): number
  • パラメータの説明
パラメータ型説明
task_idstringキャンセルするタスクの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;
  • パラメータの説明
パラメータ型説明
eventConstants.NuiEventコールバックイベント。
resultCodenumberEVENT_ASR_ERROR イベントが発生した場合にのみ有効です。
finishnumberタスクが終了したかどうかを示します。
asrResultAsrResult音声認識結果。
taskIdstringタスク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には有効期間があります。結果を速やかにダウンロードしてください。