Getting Started

Install

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

Import

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

API Overview

available

Checks whether the native speech recognition service is usable on the current device.

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

await SpeechRecognition.available();

isOnDeviceRecognitionAvailable

Checks whether the platform’s newer on-device recognition path is available for the selected locale.

This is the capability check you should use before enabling useOnDeviceRecognition. A true result means the current device, OS version, and locale can use the newer on-device path for that platform.

Returns false when the device only supports the legacy recognizer path.

Platform SDK docs: iOS: Speech Android: SpeechRecognizer

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

await SpeechRecognition.isOnDeviceRecognitionAvailable();

start

Begins capturing audio and transcribing speech.

When partialResults is true, the returned promise resolves immediately and updates are streamed through the partialResults listener until the session ends.

The default path keeps the legacy recognizer behavior for backward compatibility. Pass useOnDeviceRecognition: true only after checking .

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

await SpeechRecognition.start();

stop

Stops listening and tears down native resources.

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

await SpeechRecognition.stop();

forceStop

Force stops the current session.

On Android, this first tries a normal stop and then falls back to destroy/recreate after timeout. On iOS, the current session is stopped immediately.

If a partial transcript is cached, it is emitted through the partialResults listener with forced: true.

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

await SpeechRecognition.forceStop();

getLastPartialResult

Gets the last cached partial transcription result.

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

await SpeechRecognition.getLastPartialResult();

setPTTState

Updates the current push-to-talk button state.

Use this together with continuousPTT or with a custom hold-to-talk flow.

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

await SpeechRecognition.setPTTState({} as PTTStateOptions);

getSupportedLanguages

Gets the locales supported by the underlying recognizer.

Android 13+ devices no longer expose this list; in that case languages is empty.

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

await SpeechRecognition.getSupportedLanguages();

isListening

Returns whether the plugin is actively listening for speech.

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

await SpeechRecognition.isListening();

checkPermissions

Gets the current permission state.

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

await SpeechRecognition.checkPermissions();

requestPermissions

Requests the microphone + speech recognition permissions.

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

await SpeechRecognition.requestPermissions();

Type Reference

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

Configure how the recognizer behaves when calling .

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

Options for .

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

Result from .

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

Options for .

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

Raised whenever a segmented result is produced (Android only).

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

Raised whenever a partial transcription is produced.

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

Raised when the listening state changes.

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

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.