React SDK
useScribe: React에서 실시간 음성 텍스트 변환 전사
Scribe와 그 기능에 대한 개요는 음성 텍스트 변환 개요를 참조하세요. 단계별 사용 가이드는 클라이언트 측 스트리밍을 참조하세요.
설치
AI 코딩 어시스턴트에서 오디오를 텍스트로 변환하려면 ElevenLabs 음성 텍스트 변환 스킬을 사용하세요.
@elevenlabs/react는 @elevenlabs/client의 모든 항목을 다시 내보내므로 두 패키지를
모두 설치할 필요가 없습니다.
사용 방법
다음은 Scribe에 연결하고 실시간 트랜스크립션을 표시하는 최소한의 작동 예시입니다.
토큰 가져오기
Scribe는 인증을 위해 일회용 토큰이 필요합니다. 서버에 API 엔드포인트를 만드세요.
ElevenLabs API 키는 민감한 정보입니다. 절대 클라이언트에 노출하지 마세요. 항상 서버에서 토큰을 생성하세요.
Hook 옵션
기본 옵션과 콜백으로 Hook을 구성하세요.
연결 옵션
VAD 옵션
이 옵션은 VAD 커밋 전략을 사용할 때 트랜스크립션이 자동으로 커밋되는 시점을 제어합니다.
오디오 옵션
microphone 객체는 다음을 허용합니다.
동작 옵션
콜백
모든 이벤트 콜백은 선택 사항이며 Hook 옵션으로 제공할 수 있습니다.
- onConnect - WebSocket 연결이 설정되었을 때 호출되는 핸들러입니다.
- onDisconnect - WebSocket 연결이 닫혔을 때 호출되는 핸들러입니다.
- onSessionStarted - Scribe 세션이 시작될 때 호출되는 핸들러입니다.
- onPartialTranscript - 중간 트랜스크립션 결과와 함께 호출되는 핸들러입니다.
{ text: string }을 받습니다. - onCommittedTranscript - 최종 트랜스크립션 결과와 함께 호출되는 핸들러입니다.
{ text: string }을 받습니다. - onCommittedTranscriptWithTimestamps - 단어 수준 타이밍을 포함한 최종 트랜스크립션 결과와 함께 호출되는 핸들러입니다.
{ text: string; words?: { start: number; end: number }[] }을 받습니다. - onError - 모든 오류를 처리하는 일반 오류 핸들러입니다.
Error | Event를 받습니다. - onAuthError - 인증 오류 발생 시 호출되는 핸들러입니다.
{ error: string }을 받습니다.
오류 콜백
일반 onError 콜백은 모든 오류에 대해 실행됩니다. 세부적인 처리를 위한 특정 오류 콜백도 사용할 수 있습니다. 모든 특정 오류 콜백은 { error: string }을 받습니다.
마이크 모드
사용자의 마이크에서 오디오를 직접 스트리밍합니다.
수동 오디오 모드(파일 트랜스크립션)
사전 녹음된 오디오 파일을 텍스트로 변환합니다.
반환값
상태
- status - 현재 연결 상태입니다:
"disconnected","connecting","connected","transcribing"또는"error". - isConnected - 연결 여부를 나타내는 불리언 값입니다.
- isTranscribing - 현재 텍스트 변환 중인지 나타내는 불리언 값입니다.
- partialTranscript - 현재 부분(중간) 트랜스크립트 문자열입니다.
- committedTranscripts -
TranscriptSegment객체 배열입니다(아래 참조). - error - 현재 오류 메시지 또는
null입니다.
커밋된 각 트랜스크립트 세그먼트는 다음 구조를 가집니다.
메서드
connect(options?)
Scribe에 연결합니다. 여기서 제공하는 옵션은 Hook 기본값보다 우선합니다.
disconnect()
연결을 끊고 리소스를 정리합니다.
sendAudio(audioBase64, options?)
오디오 데이터를 전송합니다(수동 모드 전용).
previousText 필드는 세션의 첫 번째 오디오 청크에서만 전송할 수 있습니다. 이후 청크에서
전송하면 오류가 발생합니다.
commit()
현재 트랜스크립션을 수동으로 커밋합니다.
clearTranscripts()
상태에서 모든 트랜스크립트를 지웁니다.
getConnection()
기본 연결 인스턴스를 가져옵니다.
커밋 전략
트랜스크립션이 커밋되는 시점을 제어합니다.
자세한 내용은 트랜스크립트 및 커밋 전략을 참조하세요.
전체 예시
다음은 VAD 기반 커밋 전략과 함께 useScribe Hook을 사용하는 React 컴포넌트의 전체 예시입니다.