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

手順ガイド · クライアント側またはサーバー側ストリーミングのガイドを完了していることを前提としています。

概要

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

部分文字起こし - 文字起こしの途中結果
コミット済み文字起こし - 「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秒に達すると自動的にコミットします。

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

文字起こしの処理は、最初の2秒間のオーディオが送信された後に開始されます。

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

短時間に連続して何度も手動コミットすると、モデルのパフォーマンスが低下する場合があります。

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

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

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

previous_text コンテキストを送信できるのは、最初のオーディオチャンクを connection.send() で送信する場合のみです。後続のチャンクで送信するとエラーになります。以前のテキストは 50 文字未満の場合に最も効果的です。

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

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

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

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

vad_silence_threshold_secs には0.192～3.0秒を指定できます。JavaScriptおよびReact SDKでは0.3～3.0秒のみ指定できます。

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,
});

バックグラウンドオーディオのフィルタリング

近くの会話などのバックグラウンド音声や環境ノイズによる誤検出を減らすには、filter_background_audio=true クエリパラメータを設定します。フィルタリングを有効にすると、音声アクティビティ検出はバックグラウンド音声を無視するよう調整されたモデルを使用し、vad_threshold は自分で設定しない限りデフォルトで 0.15 になります。

filter_background_audio は include_timestamps と組み合わせられません。両方を設定すると、サーバーは invalid_request エラーを送信して接続を閉じます。

フィルタリングによって課金は変わりません。フィルタが無視するオーディオを含め、ストリーミングするすべてのオーディオが課金対象です。

無音中に接続を維持する

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

キープアライブは自律的に動作するpingではありません。オーディオのストリーミングを続ける必要があります（無音フレームでも問題ありません）。オーディオの送信を停止するとキープアライブは送信されず、サーバーはクライアントメッセージがない状態が15秒続くと接続を閉じます。このサーバーの制限は設定できません。

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）。

空の partial_transcript（text: ""）は「現在のセグメントに発話がない」ことを意味します。一時停止中に同じ内容の partial_transcript が繰り返し届く場合もキープアライブです。クライアントは繰り返しを特別扱いせず、これまでどおり部分文字起こしとして表示してください。

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

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

対応オーディオ形式

形式	サンプルレート	説明
pcm_8000	8 kHz	16ビットPCM、リトルエンディアン
pcm_16000	16 kHz	16ビットPCM、リトルエンディアン（推奨）
pcm_22050	22.05 kHz	16ビットPCM、リトルエンディアン
pcm_24000	24 kHz	16ビットPCM、リトルエンディアン
pcm_44100	44.1 kHz	16ビットPCM、リトルエンディアン
pcm_48000	48 kHz	16ビットPCM、リトルエンディアン
ulaw_8000	8 kHz	8ビットμ-lawエンコーディング

ベストプラクティス

オーディオ品質

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

チャンクサイズ

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

次のステップ

サーバー側ストリーミング

WebSocket APIを使用して、サーバー側のオーディオ文字起こしを設定します。

イベントリファレンス

リアルタイムSTT APIのイベントとエラータイプの完全な一覧です。