文字起こしとコミット戦略

概要

オーディオを文字起こしすると、部分文字起こしとコミット済み文字起こしを受け取ります。

• 部分文字起こし - 文字起こしの中間結果
• コミット済み文字起こし - 「commit」メッセージを受信した際に送信される、文字起こしセグメントの最終結果。1つのセッションには複数のコミット済み文字起こしを含められます。

コミット済み文字起こしには、任意で単語レベルのタイムスタンプを含められます。これは「include timestamps」オプションをtrueに設定した場合にのみ受信します。

# Initialize the connection
connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
  model_id="scribe_v2_realtime",
  include_timestamps=True, # Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
))

コミット戦略

WebSocket経由でオーディオチャンクを送信する際、文字起こしセグメントは手動コミットまたは音声アクティビティ検出（VAD）の2つの方法でコミットできます。

手動コミット

手動コミット戦略では、文字起こしセグメントをコミットするタイミングを制御します。これはデフォルトで使用される戦略です。セグメントをコミットすると、文脈を失わずに処理済みの蓄積文字起こしをクリアし、新しいセグメントを開始します。レイテンシーを改善するには、20～30秒ごとにコミットすることをおすすめします。手動でコミットしない場合でも、モデルは蓄積されたオーディオが約36秒に達すると自動的にコミットします。

最良の結果を得るには、無音の間やターンの切れ目など、論理的なタイミングでコミットしてください。

await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})
# When ready to finalize the segment
await connection.commit()

以前のテキストコンテキストを送信する

文字起こし用のオーディオを送信する際、最初のオーディオチャンクとともに以前のテキストコンテキストを送信すると、モデルが音声の文脈を理解しやすくなります。これは次のような場面で役立ちます。

• 会話型AIのユースケースにおけるエージェントのテキスト - モデルが会話の文脈をより簡単に理解し、より良い文字起こしを生成できます。
• ネットワークエラー後の再接続 - 以前のテキストを手がかりとして、モデルが文字起こしを継続できます。
• 一般的な文脈情報 - 文字起こしの内容に関する短い説明があると、モデルが文脈を理解しやすくなります。

await connection.send({
  "audio_base_64": audio_base_64,
  "previous_text": "The previous text context",
})

音声アクティビティ検出（VAD）

VAD戦略では、文字起こしエンジンが音声と無音のセグメントを自動的に検出します。無音のしきい値に達すると、文字起こしエンジンは文字起こしセグメントを自動的にコミットします。

クライアント側インテグレーションでマイクからのオーディオを文字起こしする場合は、VAD戦略の使用をおすすめします。

import { Scribe, AudioFormat, CommitStrategy } from "@elevenlabs/client";
const connection = Scribe.connect({
  token: "sutkn_1234567890",
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  commitStrategy: CommitStrategy.VAD,
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
  minSpeechDurationMs: 100,
  minSilenceDurationMs: 100,
});

無音中も接続を維持する

公式SDKはメッセージが届かなくても接続を切断しないため、ほとんどのインテグレーションでは対応不要です。独自のWebSocketクライアントや、その間にあるプロキシまたはロードバランサーが、しばらくフレームが届かないと接続を閉じる場合は、接続時に任意のkeepalive_interval_msクエリパラメータを渡してください。これは、たとえば10～15秒の間がある電話の通話など、長時間の無音時に重要です。サーバーはおおよそ各インターバルごとに、キープアライブのpartial_transcriptを送信します。現在のセグメントに未コミットのテキストがない場合は空（text: ""）、ある場合は最新の部分テキストを繰り返します。

• 500～10000（ミリ秒）の整数を受け付けます。デフォルトでは無効です。既存の動作を維持するにはパラメータを省略してください。
• 範囲外または整数以外の値を指定すると、サーバーはinvalid_requestエラーを送信して接続を閉じます。
• キープアライブは自動で継続するタイマーではなく、送信した無音オーディオをモデルが実際に処理することで駆動されます。そのため、文字起こし経路が稼働していることも確認できます。
• オーディオは約1秒のチャンクで処理されるため、キープアライブはその周期に合わせて丸められたインターバルで届きます（たとえば、1000は約1秒ごと、3000は約3秒ごとに発生します）。セッションの最初のキープアライブは、サーバーが文字起こし前に最初の約2秒間のオーディオをバッファリングするため、開始から約2秒後に届きます。余裕を持たせるため、インターバルは独自の読み取りタイムアウトの約3分の1以下に設定してください。
• キープアライブのtextが空になるのは、現在のセグメントにまだ未コミットのテキストがない場合だけです。発話後かつコミット前に一時停止が発生した場合、特にfilter_background_audio=trueまたはコミットを行わない手動コミットモードで顕著ですが、キープアライブは空にする代わりに最新の部分テキストを繰り返します。そのため中間テキストが消えることはありません。コミット後は、新しい発話が届くまでキープアライブは再び空になります。
• commit_strategy=manualとcommit_strategy=vadの両方、およびfilter_background_audio=trueで動作します。すでにストリーミングしているオーディオ以外に、課金への影響はありません。
• session_startedメッセージのconfigはkeepalive_interval_msをそのまま返します（無効な場合はnull）。

WebSocket URLにパラメータを追加します。

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&commit_strategy=vad&keepalive_interval_ms=1000

対応オーディオ形式

ベストプラクティス

オーディオ品質

• 品質と帯域幅の最適なバランスを得るには、16kHzのサンプルレートを使用してください。
• バックグラウンドノイズを最小限に抑えた、クリアなオーディオ入力を確保してください。
• クリッピングを避けるため、適切なマイクゲインを使用してください。
• 現時点ではモノラルオーディオのみをサポートしています。

チャンクサイズ

• スムーズなストリーミングのため、長さが0.1～1秒のオーディオチャンクを送信してください。
• チャンクを小さくするとレイテンシーは低くなりますが、オーバーヘッドは増加します。
• チャンクを大きくすると効率は向上しますが、レイテンシーが発生する場合があります。

次のステップ