> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

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

> **Note**
>
> **ハウツーガイド** ·
> [クライアント側](/docs/ja/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) または
> [サーバー側 ストリーミング](/docs/ja/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)のガイドを完了していることを前提としています。

## 概要

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

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

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

```python
# 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
))
```

```typescript
// Initialize the connection
const connection = await elevenlabs.speechToText.realtime.connect({
  modelId: "scribe_v2_realtime",
  includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
});
```

**`React`**

```typescript title="React"
const connection = useScribe({
  modelId: "scribe_v2_realtime",
  // Configuring this callback will automatically set the `includeTimestamps` option to `true`
  onCommittedTranscriptWithTimestamps: (data) => {
    console.log("Committed with timestamps:", data.text);
    console.log("Timestamps:", data.words);
  },
});
```

**`JavaScript`**

```typescript title="JavaScript"
const connection = Scribe.connect({
  modelId: "scribe_v2_realtime",
  includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
});
```

## コミット戦略

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

### 手動コミット

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

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

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

```python
await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})

# When ready to finalize the segment
await connection.commit()
```

```typescript
connection.send({
  audioBase64: audioBase64,
  sampleRate: 16000,
});

// When ready to finalize the segment
connection.commit();
```

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

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

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

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

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

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

```typescript
connection.send({
  audioBase64: audioBase64,
  previousText: "The previous text context",
});
```

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

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

[クライアント側インテグレーション](/docs/ja/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming)でマイクからのオーディオを文字起こしする場合は、VAD戦略の使用をおすすめします。

**`クライアント`**

```typescript title="クライアント"
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,
});
```

```python
from dotenv import load_dotenv
from elevenlabs import AudioFormat, CommitStrategy, ElevenLabs, RealtimeAudioOptions

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

connection = await elevenlabs.speech_to_text.realtime.connect(
    RealtimeAudioOptions(
        model_id="scribe_v2_realtime",
        audio_format=AudioFormat.PCM_16000,
        commit_strategy=CommitStrategy.VAD,
        vad_silence_threshold_secs=1.5,
        vad_threshold=0.4,
        min_speech_duration_ms=100,
        min_silence_duration_ms=100,
    )
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { ElevenLabsClient, AudioFormat, CommitStrategy } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient();

const connection = await elevenlabs.speechToText.realtime.connect({
  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: ""`）、ある場合は最新の部分テキストを繰り返します。

> **Warning**
>
> キープアライブは自動で継続する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`）。

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

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

```text
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秒のオーディオチャンクを送信してください。
* チャンクを小さくするとレイテンシーは低くなりますが、オーバーヘッドは増加します。
* チャンクを大きくすると効率は向上しますが、レイテンシーが発生する場合があります。

## 次のステップ

#### [サーバー側ストリーミング](/docs/ja/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

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

#### [イベントリファレンス](/docs/ja/eleven-api/guides/how-to/speech-to-text/realtime/event-reference)

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