> 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/ko/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) 또는
> [서버 측 스트리밍](/docs/ko/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming) 가이드를 완료했다고 가정합니다.

## 개요

오디오를 트랜스크립션하면 부분 트랜스크립트와 커밋된 트랜스크립트를 받게 됩니다.

* **부분 트랜스크립트** - 트랜스크립션의 중간 결과
* **커밋된 트랜스크립트** - "commit" 메시지를 수신했을 때 전송되는 트랜스크립션 세그먼트의 최종 결과입니다. 하나의 세션에 여러 개의 커밋된 트랜스크립트가 있을 수 있습니다.

커밋 트랜스크립트에는 선택적으로 단어 수준 타임스탬프가 포함될 수 있습니다. 이는 "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)의 두 가지 방법으로 트랜스크립트 세그먼트를 커밋할 수 있습니다.

### 수동 커밋

수동 커밋 전략에서는 트랜스크립트 세그먼트를 커밋할 시점을 직접 제어합니다. 이는 기본적으로 사용되는 전략입니다. 세그먼트를 커밋하면 처리된 누적 트랜스크립트가 지워지고, 컨텍스트를 잃지 않은 채 새 세그먼트가 시작됩니다. 지연 시간을 개선하려면 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/ko/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming)에서 마이크 오디오를 트랜스크립션할 때는 VAD 전략을 사용하는 것이 좋습니다.

`vad_silence_threshold_secs`는 0.192~~3.0초를 허용합니다. JavaScript 및 React SDK는 0.3~~3.0만 허용합니다.

**`클라이언트`**

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

## 배경 오디오 필터링

`filter_background_audio=true` 쿼리 매개변수를 설정하면 주변 대화와 같은 배경 음성 및 주변 소음으로 인한 오탐 활성화를 줄일 수 있습니다. 필터링을 활성화하면 음성 활동 감지는 배경 음성을 무시하도록 조정된 모델을 사용하며, 직접 설정하지 않는 한 `vad_threshold`의 기본값은 `0.15`입니다.

> **Warning**
>
> `filter_background_audio`는 `include_timestamps`와 함께 사용할 수 없습니다. 둘 다 설정하면 서버가
> `invalid_request` 오류를 전송하고 연결을 종료합니다.

필터링은 과금에 영향을 주지 않습니다. 필터가 무시하는 오디오를 포함해 스트리밍하는 모든 오디오는 과금됩니다.

## 무음 중 연결 유지

공식 SDK는 메시지가 도착하지 않아도 연결을 끊지 않으므로 대부분의 통합에서는 이 기능이 필요하지 않습니다. 자체 WebSocket 클라이언트나 중간의 프록시 또는 로드 밸런서가 일정 시간 프레임이 도착하지 않으면 연결을 닫는 경우, 연결할 때 선택적 `keepalive_interval_ms` 쿼리 매개변수를 전달하세요. 이는 예를 들어 10\~15초간 멈춤이 있는 전화 통화처럼 긴 무음 구간에서 중요합니다. 서버는 매 간격마다 대략 한 번씩 keepalive `partial_transcript`를 전송합니다. 현재 세그먼트에 커밋되지 않은 텍스트가 없으면 비어 있으며(`text: ""`), 있으면 최신 부분 텍스트를 반복합니다.

> **Warning**
>
> Keepalive는 독립적으로 실행되는 ping이 아닙니다. 오디오(무음 프레임도 가능)를 계속 스트리밍해야 합니다.
> 오디오 전송을 중단하면 keepalive가 전송되지 않으며, 클라이언트 메시지가 없는 상태로 15초가 지나면 서버가 연결을 종료합니다.
> 이 서버 제한은 구성할 수 없습니다.

* `500`\~`10000`(밀리초) 사이의 정수를 허용합니다. 기본적으로 비활성화되어 있으며, 기존 동작을 유지하려면 매개변수를 생략하세요.
* 범위를 벗어나거나 정수가 아닌 값을 사용하면 서버가 `invalid_request` 오류를 전송하고 연결을 종료합니다.
* Keepalive는 독립 타이머가 아니라 전송한 무음 오디오를 모델이 실제로 처리하는 과정에 의해 발생하므로, 트랜스크립션 경로가 작동 중임도 확인합니다.
* 오디오는 약 1초 청크 단위로 처리되므로 keepalive는 해당 주기에 맞춰 반올림된 간격으로 도착합니다(예: `1000`은 약 1초마다, `3000`은 약 3초마다 발생). 서버는 트랜스크립션 전 처음 약 2초의 오디오를 버퍼링하므로, 세션의 첫 keepalive는 시작 후 약 2초 뒤에 도착합니다. 여유를 확보하려면 자체 읽기 타임아웃의 약 3분의 1 이하로 간격을 설정하세요.
* Keepalive의 `text`는 현재 세그먼트에 아직 커밋되지 않은 텍스트가 없을 때만 비어 있습니다. 음성 후 커밋 전 일시 정지가 발생하면(특히 `filter_background_audio=true`를 사용하거나 커밋하지 않는 수동 커밋 모드에서 잘 보임) keepalive는 최신 부분 텍스트를 대신 반복하므로 중간 텍스트가 비어 있지 않습니다. 커밋 후에는 새 음성이 도착할 때까지 keepalive가 다시 비어 있습니다.
* `commit_strategy=manual` 및 `commit_strategy=vad` 모두와 `filter_background_audio=true`에서 작동합니다. 이미 스트리밍 중인 오디오 외에는 과금에 영향을 주지 않습니다.
* `session_started` 메시지의 `config`는 `keepalive_interval_ms`를 다시 반환합니다(비활성화된 경우 `null`).

> **Info**
>
> 비어 있는 `partial_transcript`(`text: ""`)는 "현재 세그먼트에 음성이 없음"을 의미합니다. 일시 정지 중 반복되는
> 동일한 `partial_transcript`도 keepalive입니다. 클라이언트는 반복을 특별 처리하지 말고 기존 방식대로 부분 트랜스크립트를 렌더링하면 됩니다.

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/ko/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

WebSocket API를 사용하여 서버 측 오디오 트랜스크립션을 설정합니다.

#### [이벤트 레퍼런스](/docs/ko/eleven-api/guides/how-to/speech-to-text/realtime/event-reference)

실시간 STT API의 이벤트 및 오류 유형 전체 목록입니다.