Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

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

Importa

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

Avvio rapido

Richiedi l'accesso al microfono, aggiungi un partialResults listener e avvia una sessione con aggiornamenti in 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();

Errori comuni

• Pulizia: rimuovi i listener quando esci dalla schermata.
• Località: usa i tag BCP 47 corrispondenti alla tua UI.
• Web: non supportato; usa un API vocale del browser separatamente se ti serve la dettatura solo per Web.

Panoramica API

available

Verifica se il servizio di riconoscimento vocale nativo è utilizzabile sul dispositivo attuale.

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

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

isOnDeviceRecognitionAvailable

Verifica se il nuovo percorso di riconoscimento on-device della piattaforma è disponibile per la locale selezionata.

Questo è il controllo di capacità da usare prima di abilitare useOnDeviceRecognition. Un true risultato indica che il dispositivo, la versione dell'OS e la locale possono usare il nuovo percorso on-device per quella piattaforma.

Restituisce false quando il dispositivo supporta solo il percorso legacy del recognizer.

Documentazione della piattaforma SDK: iOS: Speech Android: SpeechRecognizer

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

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

start

Inizia a catturare l'audio e a trascrivere il parlato.

Quando partialResults è true, la promise restituita si risolve immediatamente e gli aggiornamenti vengono trasmessi tramite il partialResults listener fino alla fine della sessione.

Il percorso predefinito mantiene il comportamento del vecchio recognizer per la retrocompatibilità. Passa useOnDeviceRecognition: true solo dopo aver verificato .

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

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

stop

Interrompe l'ascolto e rilascia le risorse native.

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

await SpeechRecognition.stop();

forceStop

Termina forzatamente la sessione corrente.

Su Android, tenta prima un arresto normale e poi passa a destroy/recreate. timeout. Su iOS, la sessione corrente viene interrotta immediatamente.

Se è presente una trascrizione parziale in cache, viene emessa tramite il partialResults listener con forced: true.

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

await SpeechRecognition.forceStop();

getLastPartialResult

Recupera l'ultimo risultato parziale della trascrizione in cache.

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

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

setPTTState

Aggiorna lo stato attuale del pulsante push-to-talk.

Da usare insieme a continuousPTT o con un flusso hold-to-talk personalizzato.

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

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

getSupportedLanguages

Restituisce i locale supportati dal recognizer sottostante.

Sui dispositivi Android 13+ questa lista non è più esposta; in tal caso languages è vuota.

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

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

isListening

Indica se il plugin sta attivamente ascoltando la voce.

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

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

checkPermissions

Ottiene lo stato attuale dei permessi.

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

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

requestPermissions

Richiede i permessi per il microfono e il riconoscimento vocale.

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

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

Riferimento ai tipi

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

Configura il comportamento del riconoscitore quando chiami .

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

Opzioni per .

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

Risultato di .

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

Opzioni per .

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

Mappa dei permessi restituita da checkPermissions e requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

Viene emesso quando viene prodotto un risultato segmentato (solo Android).

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

Viene emesso ogni volta che viene prodotta una trascrizione parziale.

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

Viene emesso quando cambia lo stato di ascolto.

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

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Per iniziare per pianificare le operazioni della dashboard e di API, collegalo a Usare @capgo/capacitor-speech-recognition per la funzionalità nativa in Usare @capgo/capacitor-speech-recognition, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.