Premiers pas

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez la configuration manuelle, installez le plugin avec les commandes suivantes, puis suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

Demandez l'accès au micro, attachez un partialResults listener, puis lancez une session avec des mises à jour 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();

Erreurs courantes

• Nettoyage: supprimez les écouteurs en quittant l'écran.
• Locales: utilisez des tags BCP 47 correspondant à votre UI.
• Web: non supporté ; utilisez un API de navigateur séparément si vous avez besoin de la dictée uniquement sur le Web.

Aperçu de API

available

Vérifie si le service de reconnaissance vocale natif est utilisable sur l'appareil actuel.

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

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

isOnDeviceRecognitionAvailable

Vérifie si le nouveau chemin de reconnaissance on-device de la plateforme est disponible pour la locale sélectionnée.

C'est le contrôle de capacité que vous devez utiliser avant d'activer useOnDeviceRecognition. Un true "result" signifie que l'appareil actuel, la version de l'OS et la locale permettent d'utiliser le nouveau chemin on-device pour cette plateforme.

Retourne false lorsque l'appareil ne prend en charge que l'ancien chemin de reconnaissance.

Documentation de la plateforme SDK : iOS : Speech Android : SpeechRecognizer

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

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

start

Commence la capture audio et la transcription de la parole.

Quand partialResults est true, la promesse retournée se résout immédiatement et les mises à jour sont transmises via le partialResults listener jusqu'à la fin de la session.

Le chemin par défaut conserve le comportement de l'ancien recognizer pour assurer la rétrocompatibilité. Passez useOnDeviceRecognition: true uniquement après avoir vérifié .

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

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

stop

Arrête l'écoute et libère les ressources natives.

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

await SpeechRecognition.stop();

forceStop

Arrête de force la session en cours.

Sur Android, cela tente d'abord un arrêt normal, puis effectue un destroy/recreate si nécessaire timeout. Sur iOS, la session en cours est arrêtée immédiatement.

Si une transcription partielle est en cache, elle est émise via le partialResults listener avec forced: true.

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

await SpeechRecognition.forceStop();

getLastPartialResult

Récupère le dernier résultat de transcription partielle en cache.

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

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

setPTTState

Met à jour l'état actuel du bouton 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

Récupère les locales supportées par le moteur de reconnaissance sous-jacent.

Les appareils Android 13+ n'exposent plus cette liste ; dans ce cas, languages est vide.

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

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

isListening

Indique si le plugin est en train d'écouter activement la parole.

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

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

checkPermissions

Récupère l'état actuel des permissions.

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

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

requestPermissions

Demande les permissions pour le micro et la reconnaissance vocale.

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

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

Référence de type

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

Configure le comportement du moteur de reconnaissance lors de l'appel de .

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 pour .

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

Résultat 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

Options pour .

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

Carte des permissions retournée par checkPermissions et requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

Déclenché dès qu'un résultat segmenté est produit (Android uniquement).

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

Déclenché dès qu'une transcription partielle est produite.

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

Déclenché lorsque l'état de l'écoute change.

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 de vérité

Cette page est générée à partir du src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Premiers pas pour planifier les opérations du dashboard et de API, connectez-l’à Utiliser @capgo/capacitor-speech-recognition pour la capacité native dans Utiliser @capgo/capacitor-speech-recognition, Aperçu de API pour les détails d'implémentation dans l'aperçu de API, Introduction pour les détails d'implémentation dans l'Introduction, Clés API pour les détails d'implémentation dans les clés API, et Appareils pour le détail d’implémentation dans Devices.