SpeechToText · Docs

스토리북 개발자들을 위한 내부 문서

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

NameTypeDefaultDescription
className
string버튼 루트 클래스. bg-*가 있으면 기본 bg-surface-default를 제거합니다.
icon
ReactNodeidle(시작) 아이콘. 기본 MicIcon.
listeningIcon
ReactNodelistening(멈춤) 아이콘. 기본 stop 스퀘어.
lang
string"ko-KR"인식 언어 (BCP 47).
continuous
booleantruetrue: 멈출 때까지 인식. false: 한 발화 후 브라우저가 종료할 수 있음.
timeout
number3000인식 결과 없이 이 시간(ms)이 지나면 자동 종료. 미전달 시 3000. 0 이하면 비활성. 소비 앱이 원하는 값을 전달.
disabled
booleanfalse비활성. API 미지원 시에도 버튼이 disabled입니다.
onResult
(text: string) => void인식 종료 후 최종 텍스트(trim). 빈 문자열이면 호출하지 않음.
onInterim
(text: string) => void인식 중 interim 텍스트 (선택).
onError
(error: SpeechToTextError) => void권한·네트워크·미지원 등. code: not-allowed | unsupported | insecure-context | …
onUnsupported
() => voidSpeechRecognition 미존재 또는 비 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로 전달하지 않음.