트랜스크립트 및 커밋 전략

개요

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

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

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

수동 커밋

수동 커밋 전략에서는 트랜스크립트 세그먼트를 커밋할 시점을 직접 제어합니다. 기본적으로 사용되는 전략입니다. 세그먼트를 커밋하면 처리된 누적 트랜스크립트가 지워지고, 컨텍스트를 유지한 채 새 세그먼트가 시작됩니다. 지연 시간을 줄이려면 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초간 멈춤이 있는 전화 통화처럼 긴 무음 구간에서 중요합니다. 각 간격마다 약 한 번씩 서버는 keepalive partial_transcript를 전송합니다. 현재 세그먼트에 커밋되지 않은 텍스트가 없으면 비어 있고(text: ""), 있으면 최신 부분 텍스트를 반복합니다.

• 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).

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초인 오디오 청크를 전송하세요.
• 청크가 작을수록 지연 시간은 줄어들지만 오버헤드는 늘어납니다.
• 청크가 클수록 효율적이지만 지연 시간이 발생할 수 있습니다.

다음 단계