시작하기

설치

bun add @capgo/capacitor-speech-recognition
bunx cap sync

수입

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

API 개요

available

__CAPGO_KEEP_1__은 현재 장치에서 사용할 수 있는 네이티브 음성 인식 서비스가 있는지 확인합니다.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.available();

isOnDeviceRecognitionAvailable

선택한 지역의 플랫폼에서 사용할 수 있는 최신 장치 내 인식 경로가 있는지 확인합니다.

이 기능을 사용하기 전에 사용해야 하는 기능 체크입니다. useOnDeviceRecognition. A true 결과가 'A'이면 현재 장치, OS 버전 및 지역이 해당 플랫폼에서 최신 장치 내 경로를 사용할 수 있습니다.

리턴 false 장치가 오래된 인식기 경로만 지원할 때 리턴

플랫폼 SDK 문서: iOS: Speech Android:

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.isOnDeviceRecognitionAvailable();

start

음성 녹음과 음성 인식을 시작합니다.

When partialResults is true, 반환된 promise는 즉시 해결되고 세션이 끝날 때까지 partialResults listener를 통해 업데이트가 스트리밍됩니다.

기본 경로는 백워드 호환성을 위해 레거시 인식기 동작을 유지합니다. useOnDeviceRecognition: true 만약

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.start();

stop

만들어야 합니다.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.stop();

forceStop

현재 세션을 강제로 중지합니다.

안드로이드에서 이 기능은 정상적인 중지를 먼저 시도하고, 그 다음 destroy/recreate를 사용합니다. timeoutiOS에서 현재 세션은 즉시 중지됩니다.

부분 전사록이 캐시되어 있다면, partialResults listener에 forced: true.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.forceStop();

getLastPartialResult

지금까지 캐시된 부분 전사록 결과를 가져옵니다.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.getLastPartialResult();

setPTTState

현재 push-to-talk 버튼 상태를 업데이트합니다.

이 기능을 사용할 때는 continuousPTT 또는 사용자 지정 대기열로 말하기 흐름을 사용합니다.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.setPTTState({} as PTTStateOptions);

getSupportedLanguages

Recognizer 내부에서 지원하는 지역을 가져옵니다.

Android 13+ 장치에서는 이 목록을 더 이상 노출하지 않습니다. 그 경우는 빈 목록입니다. languages __CAPGO_KEEP_0__

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.getSupportedLanguages();

isListening

__CAPGO_KEEP_0__

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.isListening();

checkPermissions

Copy to clipboard

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.checkPermissions();

requestPermissions

마이크 + 음성 인식 권한을 요청합니다.

import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.requestPermissions();

타입 참조

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

recognizer가 호출될 때의 동작을 구성합니다.

export interface SpeechRecognitionStartOptions {
  /**
   * Locale identifier such as `en-US`. When omitted the device language is used.
   */
  language?: string;
  /**
   * Maximum number of final matches returned by native APIs. Defaults to `5`.
   */
  maxResults?: number;
  /**
   * Prompt message shown inside the Android system dialog (ignored on iOS).
   */
  prompt?: string;
  /**
   * When `true`, Android shows the OS speech dialog instead of running inline recognition.
   * Defaults to `false`.
   */
  popup?: boolean;
  /**
   * Emits partial transcription updates through the `partialResults` listener while audio is captured.
   */
  partialResults?: boolean;
  /**
   * Enables native punctuation handling where supported (iOS 16+).
   */
  addPunctuation?: boolean;
  /**
   * Opt in to the platform's newer on-device recognition path when available.
   *
   * On iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.
   * On recent Android versions, this uses the on-device `SpeechRecognizer` path.
   *
   * It is intentionally opt-in so existing apps keep the legacy flow unless they choose
   * to roll out the new behavior.
   *
   * Use {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.
   *
   * Platform SDK docs:
   * iOS: [Speech](https://developer.apple.com/documentation/speech),
   * [SpeechAnalyzer](https://developer.apple.com/documentation/speech/speechanalyzer),
   * [SpeechTranscriber](https://developer.apple.com/documentation/speech/speechtranscriber)
   * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)
   *
   * Defaults to `false`.
   */
  useOnDeviceRecognition?: boolean;
  /**
   * Allow a number of milliseconds of silence before splitting the recognition session into segments.
   * Required to be greater than zero and currently supported on Android only.
   */
  allowForSilence?: number;
  /**
   * EXPERIMENTAL: Keep a PTT session alive across silence by restarting recognition while the button stays held.
   *
   * This restart behavior is implemented for Android inline recognition and iOS native recognition.
   */
  continuousPTT?: boolean;
}

SpeechRecognitionMatches

export interface SpeechRecognitionMatches {
  matches?: string[];
}

ForceStopOptions

의 옵션

export interface ForceStopOptions {
  /**
   * Android only: timeout in milliseconds before forcing stop via destroy/recreate.
   *
   * On iOS, the current session is stopped immediately and this value is ignored.
   *
   * Defaults to `1500`.
   */
  timeout?: number;
}

LastPartialResult

의 결과

export interface LastPartialResult {
  /**
   * Whether a partial result is currently cached.
   */
  available: boolean;
  /**
   * The most recent transcript text known to the native recognizer.
   */
  text: string;
  /**
   * All current match alternatives when available.
   */
  matches?: string[];
}

PTTStateOptions

의 옵션

export interface PTTStateOptions {
  /**
   * Whether the PTT button is currently held.
   */
  held: boolean;
}

SpeechRecognitionLanguages

export interface SpeechRecognitionLanguages {
  languages: string[];
}

SpeechRecognitionListening

export interface SpeechRecognitionListening {
  listening: boolean;
}

SpeechRecognitionPermissionStatus

Permission map returned by checkPermissions and requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

Android에서만 segmented 결과가 생성될 때 발생합니다.

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

부분 전사 결과가 생성될 때 발생합니다.

export interface SpeechRecognitionPartialResultEvent {
  /**
   * Current recognition matches when the native recognizer reports them.
   *
   * This can be omitted for forced or accumulated-only payloads.
   */
  matches?: string[];
  /**
   * Accumulated transcription from earlier continuous PTT cycles.
   */
  accumulated?: string;
  /**
   * Final accumulated text including the current result.
   */
  accumulatedText?: string;
  /**
   * `true` when the plugin is restarting recognition inside a continuous PTT session.
   */
  isRestarting?: boolean;
  /**
   * `true` when the payload was emitted by `forceStop()`.
   */
  forced?: boolean;
}

SpeechRecognitionListeningEvent

청취 상태가 변경될 때 발생합니다.

export interface SpeechRecognitionListeningEvent {
  /**
   * Finite state of the recognition session.
   */
  state?: ListeningFiniteState;
  /**
   * Unique identifier for the current listening session.
   */
  sessionId?: number;
  /**
   * Why this state transition occurred.
   */
  reason?: ListeningReason;
  /**
   * Error code when the transition is caused by an error.
   */
  errorCode?: string;
  /**
   * Backward-compatible binary state used by earlier releases.
   */
  status?: 'started' | 'stopped';
}

진실의 근원

이 페이지는 플러그인의 src/definitions.ts업스트림에서 pubic API이 변경될 때 다시 싱크를 실행하세요.