Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

npm install @capgo/capacitor-speech-recognition
npx cap sync

Importar

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

Inicio rápido

Solicita acceso al micrófono, adjunta un partialResults listener y luego inicia una sesión con actualizaciones en streaming.

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

await SpeechRecognition.requestPermissions();

const partialListener = await SpeechRecognition.addListener('partialResults', ({ matches }) => {
  setTranscript(matches?.[0] ?? '');
});

await SpeechRecognition.start({ language: 'en-US', partialResults: true });

// When leaving the screen:
await SpeechRecognition.stop();
await partialListener.remove();

Errores comunes

• Limpiar: elimina los listeners al salir de la pantalla.
• Locales: usa etiquetas BCP 47 que coincidan con tu UI.
• Web: no compatible; usa un API de voz del navegador por separado si necesitas dictado solo en Web.

Resumen de API

available

Comprueba si el servicio nativo de reconocimiento de voz está disponible en el dispositivo actual.

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

const result = await SpeechRecognition.available();
console.log(result);

isOnDeviceRecognitionAvailable

Comprueba si la ruta de reconocimiento on-device más reciente de la plataforma está disponible para el locale seleccionado.

Esta es la comprobación de capacidad que debes usar antes de habilitar useOnDeviceRecognition. Un true resultado significa que el dispositivo actual, la versión del SO y el locale pueden usar la ruta on-device más reciente para esa plataforma.

Devuelve false cuando el dispositivo solo admite la ruta del reconocedor legacy.

Documentación de la plataforma SDK: iOS: Voz Android: SpeechRecognizer

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

const result = await SpeechRecognition.isOnDeviceRecognitionAvailable();
console.log(result);

start

Inicia la captura de audio y la transcripción de voz.

Cuando partialResults es true, la promesa devuelta se resuelve de inmediato y las actualizaciones se partialResults listener hasta que termina la sesión.

La ruta predeterminada mantiene el comportamiento del reconocedor legacy por compatibilidad hacia atrás. Pasa useOnDeviceRecognition: true solo después de verificar .

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

const result = await SpeechRecognition.start();
console.log(result);

stop

Deja de escuchar y libera los recursos nativos.

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

await SpeechRecognition.stop();

forceStop

Fuerza la detención de la sesión actual.

En Android, primero intenta una detención normal y después recurre a destruir/recrear. timeout. En iOS, la sesión actual se detiene inmediatamente.

Si hay una transcripción parcial en caché, se emite a través del partialResults listener con forced: true.

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

await SpeechRecognition.forceStop();

getLastPartialResult

Obtiene el último resultado de transcripción parcial en caché.

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

const result = await SpeechRecognition.getLastPartialResult();
console.log(result);

setPTTState

Actualiza el estado actual del botón de push-to-talk.

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

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

await SpeechRecognition.setPTTState({ held: true });

getSupportedLanguages

Obtiene los locales admitidos por el reconocedor subyacente.

Los dispositivos con Android 13+ ya no exponen esta lista; en ese caso languages está vacía.

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

const result = await SpeechRecognition.getSupportedLanguages();
console.log(result);

isListening

Indica si el plugin está escuchando activamente el habla.

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

const result = await SpeechRecognition.isListening();
console.log(result);

checkPermissions

Obtiene el estado actual del permiso.

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

const result = await SpeechRecognition.checkPermissions();
console.log(result);

requestPermissions

Solicita los permisos de micrófono y reconocimiento de voz.

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

const result = await SpeechRecognition.requestPermissions();
console.log(result);

Referencia de tipos

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

Configura el comportamiento del reconocedor al llamar a .

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

Opciones para .

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

Resultado de .

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

Opciones para .

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

Mapa de permisos devuelto por checkPermissions y requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

Se dispara cada vez que se genera un resultado segmentado (solo Android).

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

Se dispara cada vez que se genera una transcripción parcial.

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

Se dispara cuando cambia el estado de escucha.

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

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Usando @capgo/capacitor-speech-recognition para la capacidad nativa en Uso de @capgo/capacitor-speech-recognition, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.