전사 결과 및 커밋 전략
이 가이드에서는 ElevenLabs 실시간 음성-텍스트 변환 API로 전사 결과와 커밋 전략을 처리하는 방법을 안내합니다.
개요
오디오를 전사하면 부분 전사 결과와 커밋된 전사 결과를 받게 됩니다.
- 부분 전사 결과 - 전사 중간 결과
- 커밋된 전사 결과 - “commit” 메시지를 받았을 때 전송되는 전사 세그먼트의 최종 결과입니다. 세션에는 여러 개의 커밋된 전사 결과가 있을 수 있습니다.
커밋 전사 결과에는 선택적으로 단어 수준 타임스탬프를 포함할 수 있습니다. 이는 “include timestamps” 옵션이 true로 설정된 경우에만 수신됩니다.
커밋 전략
WebSocket을 통해 오디오 청크를 보낼 때 전사 세그먼트는 수동 커밋, 음성 활동 감지(VAD), 턴 예측의 세 가지 방식으로 커밋할 수 있습니다. 턴 예측은 Scribe v3 Live에서만 사용할 수 있습니다.
수동 커밋
수동 커밋 전략에서는 전사 세그먼트를 커밋할 시점을 직접 제어합니다. 기본적으로 사용되는 전략입니다. 세그먼트를 커밋하면 처리된 누적 전사 결과가 지워지고, 문맥을 잃지 않은 채 새 세그먼트가 시작됩니다. 지연 시간을 개선하려면 20~30초마다 커밋하는 것이 좋습니다. 수동으로 커밋하지 않아도 모델은 누적 오디오가 약 36초에 도달하면 자동으로 커밋합니다.
최상의 결과를 위해 무음 구간이나 턴 전환 같은 논리적인 지점에서 커밋하세요.
짧은 시간 안에 수동으로 여러 번 커밋하면 모델 성능이 저하될 수 있습니다.
이전 텍스트 문맥 전송하기
전사를 위해 오디오를 보낼 때, 모델이 음성의 문맥을 이해하도록 첫 번째 오디오 청크와 함께 이전 텍스트 문맥을 보낼 수 있습니다. 이는 다음과 같은 상황에서 유용합니다.
- 대화형 AI 사용 사례의 에이전트 텍스트 - 모델이 대화 문맥을 더 쉽게 이해하고 더 나은 전사 결과를 생성할 수 있습니다.
- 네트워크 오류 후 재연결 - 모델이 이전 텍스트를 가이드로 사용해 전사를 계속할 수 있습니다.
- 일반적인 문맥 정보 - 전사 내용에 대한 짧은 설명은 모델이 문맥을 이해하는 데 도움이 됩니다.
previous_text 문맥은 첫 번째 오디오 청크를 connection.send()를 통해 보낼 때만 전송할 수 있습니다.
이후 청크에서 전송하면 오류가 발생합니다. 이전 텍스트는 50자 미만일 때 가장 잘 작동합니다.
음성 활동 감지(VAD)
VAD 전략에서는 전사 엔진이 음성 및 무음 세그먼트를 자동으로 감지합니다. 무음 임곗값에 도달하면 전사 엔진이 전사 세그먼트를 자동으로 커밋합니다.
클라이언트 측 통합에서 마이크 오디오를 전사할 때는 VAD 전략을 사용하는 것이 좋습니다.
vad_silence_threshold_secs에는 0.1923.0초를 사용할 수 있습니다. JavaScript 및 React SDK는 0.33.0만 지원합니다.
턴 예측
턴 예측은 Scribe v3 Live
(scribe_v3_live)에서만 사용할 수 있습니다. 다른 모델은 commit_strategy=turn_prediction을
invalid_request 오류로 거부하고 연결을 닫습니다.
짧은 VAD 무음 임곗값은 화자가 잠시 멈췄을 때 발화를 끊을 수 있으며, 긴 임곗값은 커밋 전 지연을 늘립니다. 턴 예측은 무음뿐 아니라 대화의 문맥을 사용하여 화자가 자신의 차례를 마쳤는지 추정합니다. 전화번호를 읽다가 중간에 멈춘 발신자가 끊길 가능성은 더 낮아집니다.
Scribe v3 Live는 모든 partial_transcript 메시지에 화자가 차례를 마쳤을 추정 확률인 turn_probability를 포함합니다.
commit_strategy=turn_prediction을 사용하면 부분 전사 결과의 turn_probability가 0.9 이상에 도달했을 때 서버가 현재 세그먼트를 커밋합니다. VAD는 계속 활성화되어 있으므로 vad_silence_threshold_secs 무음 임곗값에 도달해도 서버가 커밋합니다. VAD 파라미터(vad_silence_threshold_secs, vad_threshold, min_speech_duration_ms, min_silence_duration_ms)는 VAD와 동일한 방식으로 턴 예측에 적용됩니다.
Scribe v3 Live를 포함한 모든 모델의 기본 커밋 전략은 manual입니다. 턴 예측을 활성화하려면 commit_strategy=turn_prediction을 명시적으로 설정하세요.
Python 및 JavaScript SDK의 CommitStrategy 열거형에는 아직 turn_prediction이 포함되어 있지 않습니다.
턴 예측을 사용하려면 WebSocket API에 직접 연결하고 쿼리 파라미터를 설정하세요.
모델이 Scribe v3 Live인 경우 모든 커밋 전략과 함께 turn_probability가 전송됩니다. manual 전략에서는 이를 읽어 자체 애플리케이션에서 커밋 시점을 결정할 수 있습니다.
배경 오디오 필터링
filter_background_audio=true 쿼리 파라미터를 설정하면 주변 대화 같은 배경 음성과 주변 소음으로 인한 오탐 활성화를 줄일 수 있습니다. 필터링을 활성화하면 음성 활동 감지는 배경 음성을 무시하도록 조정된 모델을 사용하며, 직접 설정하지 않는 한 vad_threshold의 기본값은 0.15입니다.
filter_background_audio는 include_timestamps와 함께 사용할 수 없습니다. 둘 다 설정하면 서버가
invalid_request 오류를 전송하고 연결을 닫습니다.
필터링은 과금에 영향을 주지 않습니다. 필터가 무시하는 오디오를 포함해 스트리밍하는 모든 오디오에 요금이 부과됩니다.
무음 중 연결 유지하기
공식 SDK는 메시지가 도착하지 않아도 연결을 끊지 않으므로, 대부분의 통합에서는 이 기능이 필요하지 않습니다. 자체 WebSocket 클라이언트나 그 사이의 프록시 또는 로드 밸런서가 일정 시간 프레임이 도착하지 않으면 연결을 닫는 경우, 연결할 때 선택적 keepalive_interval_ms 쿼리 파라미터를 전달하세요. 예를 들어 10~15초간 멈춤이 있는 전화 통화처럼 긴 무음 구간에서 중요합니다. 서버는 간격마다 약 한 번씩 keepalive partial_transcript를 보냅니다. 현재 세그먼트에 커밋되지 않은 텍스트가 없으면 비어 있고(text: ""), 있으면 최신 부분 텍스트를 반복합니다.
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).
비어 있는 partial_transcript(text: "")는 “현재 세그먼트에 음성이 없음”을 의미합니다. 멈춤 중 반복되는
동일한 partial_transcript도 keepalive입니다. 클라이언트는 반복을 특별 처리하지 말고 기존 방식대로 부분 결과를 렌더링하면 됩니다.
WebSocket URL에 파라미터를 추가하세요.
지원되는 오디오 형식
모범 사례
오디오 품질
- 최상의 결과를 위해 품질과 대역폭의 최적 균형을 제공하는 16kHz 샘플 레이트를 사용하세요.
- 배경 소음이 최소화된 깨끗한 오디오 입력을 사용하세요.
- 클리핑을 방지할 수 있도록 적절한 마이크 게인을 사용하세요.
- 현재는 모노 오디오만 지원됩니다.
청크 크기
- 원활한 스트리밍을 위해 길이가 0.1~1초인 오디오 청크를 보내세요.
- 청크가 작을수록 지연 시간은 낮아지지만 오버헤드는 커집니다.
- 청크가 클수록 효율적이지만 지연 시간이 발생할 수 있습니다.