Getting Started

설치

Capgo의 AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 스킬을 추가하려면 다음 명령어를 사용하세요.

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 다음 프롬프트를 사용하세요.

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-speech-recognition` plugin in my project.

만약 Manual Setup을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 설명을 따르시오:

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

Import

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

API 개요

available

현재 기기의 내장 음성 인식 서비스가 사용 가능한지 확인합니다.

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

await SpeechRecognition.available();

isOnDeviceRecognitionAvailable

선택한 지역에서 플랫폼의 더 새로운 on-device recognition 경로가 사용 가능합니다.

이 기능을 사용하기 전에 이 기능을 사용해야 하는지 확인해야 합니다. useOnDeviceRecognition. A true 결과는 현재 장치, OS 버전 및 지역이 플랫폼의 더 새로운 on-device 경로를 사용할 수 있는지 여부를 나타냅니다.

리턴 false 장치가 오래된 recognizer 경로만 지원할 때 리턴됩니다.

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

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

await SpeechRecognition.isOnDeviceRecognitionAvailable();

start

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

음성 인식이 시작되면 partialResults 은, true반환된 프로미스가 즉시 해결되고 업데이트는 partialResults 리스너를 통해 세션 종료까지 스트리밍됩니다.

기본 경로는 백워드 호환성을 위해 레거시 인식기 동작을 유지합니다. 이 경로를 변경하려면 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로 fallback합니다. 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의 underlying에 의해 지원되는 언어 목록을 가져옵니다.

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

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

await SpeechRecognition.getSupportedLanguages();

isListening

클립보드에 복사

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

await SpeechRecognition.isListening();

checkPermissions

현재 권한 상태를 가져옵니다.

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

음성 인식기 동작을 구성합니다.

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

__CAPGO_KEEP_0__

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

PTTStateOptions

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

__CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__에 의해 반환되는 권한 맵 checkPermissions 그리고 requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

안드로이드 전용으로 결과가 나올 때마다 발생합니다.

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

__CAPGO_KEEP_0__

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';
}

__CAPGO_KEEP_0__

이 페이지는 플러그인의 src/definitions.ts. Re-run the sync when the public API changes upstream.

Getting Started

__CAPGO_KEEP_0__ Getting Started API를 위한 대시보드와 API 운영을 계획하고 연결하세요. @capgo/capacitor-speech-recognition을 사용하여 @capgo/capacitor-speech-recognition을 사용하여 native 기능을 구현하는 방법 API 개요 API 개요에서 구현 세부 정보를 참조하세요. 소개 소개에서 구현 세부 정보를 참조하세요. API 키 API 키에서 구현 세부 정보를 참조하세요. 기기 기기에서 구현 세부 정보를 참조하세요.