Components
SpeechToText
Docs
API 사용 가이드와 옵션을 설명합니다. 스타일·props 프리뷰는 Overview를 참고하세요.
API
mic 클릭으로 인식 시작, 인식 중 stop으로 종료(또는 timeout 무음 자동 종료) 후 onResult로 최종 텍스트를 받습니다. 미지원 브라우저는 disabled + onUnsupported.
import { useState } from "react";
import {
SpeechToText,
isSpeechRecognitionSupported,
} from "@/components/speech-to-text";
function DictationField() {
const [text, setText] = useState("");
return (
<>
{/* 기본: timeout 미전달 → 무음 3초 후 자동 종료 */}
<SpeechToText
lang="ko-KR"
onResult={setText}
onInterim={(t) => console.log("interim", t)}
onError={(err) => console.warn(err.code, err.message)}
onUnsupported={() => console.warn("unsupported")}
/>
{/* timeout 커스텀 (ms) */}
<SpeechToText timeout={10_000} onResult={setText} />
{/* 배경 · 아이콘 */}
<SpeechToText
className="bg-[var(--surface-primary)] text-text-inverse"
icon={<CustomMic />}
listeningIcon={<CustomStop />}
onResult={setText}
/>
<p>{text}</p>
</>
);
}
// 사전 체크 (선택)
if (!isSpeechRecognitionSupported()) {
// 대체 UI
}Props
| Name | Type | Default | Description |
|---|---|---|---|
className | string | — | 버튼 루트 클래스. bg-*가 있으면 기본 bg-surface-default를 제거합니다. |
icon | ReactNode | — | idle(시작) 아이콘. 기본 MicIcon. |
listeningIcon | ReactNode | — | listening(멈춤) 아이콘. 기본 stop 스퀘어. |
lang | string | "ko-KR" | 인식 언어 (BCP 47). |
continuous | boolean | true | true: 멈출 때까지 인식. false: 한 발화 후 브라우저가 종료할 수 있음. |
timeout | number | 3000 | 인식 결과 없이 이 시간(ms)이 지나면 자동 종료. 미전달 시 3000. 0 이하면 비활성. 소비 앱이 원하는 값을 전달. |
disabled | boolean | false | 비활성. API 미지원 시에도 버튼이 disabled입니다. |
onResult | (text: string) => void | — | 인식 종료 후 최종 텍스트(trim). 빈 문자열이면 호출하지 않음. |
onInterim | (text: string) => void | — | 인식 중 interim 텍스트 (선택). |
onError | (error: SpeechToTextError) => void | — | 권한·네트워크·미지원 등. code: not-allowed | unsupported | insecure-context | … |
onUnsupported | () => void | — | SpeechRecognition 미존재 또는 비 HTTPS 컨텍스트. |
onListeningChange | (listening: boolean) => void | — | 인식 시작/종료 상태 변화. |
isSpeechRecognitionSupported | () => boolean | — | 유틸. window + secure context + SpeechRecognition/webkit 존재 여부. |
Notes
- 흐름: idle(mic) → 클릭 시작 → listening(stop) → 종료 시 onResult.
- window.SpeechRecognition 또는 webkitSpeechRecognition 필요 (주로 Chromium).
- secure context(HTTPS · localhost) 필수. HTTP면 insecure-context.
- 마이크 권한은 start 시 브라우저가 요청. 거부 시 onError(not-allowed).
- timeout: 시작 후·마지막 결과 이후 무음이면 자동 stop. 기본 3초.
- aborted(사용자 stop/abort)는 onError로 전달하지 않음.