트랜스크립트 및 커밋 전략

개요

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

• 부분 트랜스크립트 - 트랜스크립션의 중간 결과
• 커밋된 트랜스크립트 - “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 전략을 사용하는 것이 좋습니다.

vad_silence_threshold_secs는 0.1923.0초를 허용합니다. JavaScript 및 React SDK는 0.33.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입니다.

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

무음 중 연결 유지

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

다음 단계