Prise en main

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et 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 microphone, 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: retirez les listeners en quittant l’écran.
• Locales: use BCP 47 tags matching your UI.
• Le Web: non pris en charge ; utilisez un API de navigateur séparément si vous avez besoin de dictée Web uniquement.

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 la vérification de capacité à effectuer avant d’activer useOnDeviceRecognition. A true signifie que l’appareil actuel, la version du système d’exploitation et la locale peuvent utiliser le nouveau chemin on-device pour cette plateforme.

Retourne false lorsque l’appareil ne prend en charge que le chemin de reconnaissance legacy.

Docs plateforme SDK : iOS : Speech Android : SpeechRecognizer

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

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

start

Commence à capturer l'audio et à transcrire la parole.

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

Le chemin par défaut conserve le comportement du recognizer historique pour 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

Force l'arrêt de la session en cours.

Sur Android, cela tente d'abord un arrêt normal, puis se rabat sur destroy/recreate après 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.

Utilisez cette méthode avec continuousPTT ou avec un flux hold-to-talk personnalisé.

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

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

getSupportedLanguages

Récupère les locales prises en charge par le moteur de reconnaissance sous-jacent.

Sur les appareils Android 13+, cette liste n’est plus exposée ; 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 cours d’écoute de la voix.

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

Configurez le comportement du recognizer 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

Map des permissions renvoyée par checkPermissions et requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

Déclenché chaque fois 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 d'é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 de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/capacitor-speech-recognition pour la fonctionnalité native dans Utilisation de @capgo/capacitor-speech-recognition, Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.