Memulai

1. Instal paket

   npm

   npm i @capgo/capacitor-speech-recognition

   pnpm

   pnpm add @capgo/capacitor-speech-recognition

   yarn

   yarn add @capgo/capacitor-speech-recognition

   bun

   bun add @capgo/capacitor-speech-recognition

2. Sinkronkan dengan proyek native

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Konfigurasi izin platform (lihat di bawah)

Konfigurasi Platform

iOS

Tambahkan kunci berikut ke file Info.plist aplikasi Anda:

<key>NSSpeechRecognitionUsageDescription</key>
<string>We need access to speech recognition to transcribe your voice</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio for transcription</string>

Android

Plugin secara otomatis menambahkan izin RECORD_AUDIO yang diperlukan ke AndroidManifest.xml Anda. Tidak diperlukan konfigurasi tambahan.

Penggunaan Dasar

Cek Ketersediaan

Sebelum menggunakan pengenalan suara, periksa apakah tersedia di perangkat:

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

const checkAvailability = async () => {
  const { available } = await SpeechRecognition.available();
  if (!available) {
    console.warn('Speech recognition is not supported on this device');
    return false;
  }
  return true;
};

Minta Izin

Minta izin yang diperlukan sebelum memulai pengenalan:

const requestPermissions = async () => {
  const { speechRecognition } = await SpeechRecognition.requestPermissions();

  if (speechRecognition === 'granted') {
    console.log('Permission granted');
    return true;
  } else {
    console.log('Permission denied');
    return false;
  }
};

Mulai Pengenalan

Mulai mendengarkan suara dengan konfigurasi opsional:

// Basic usage
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3,
  partialResults: true,
});

// With all options
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 5,
  prompt: 'Speak now...',          // Android only
  popup: false,                     // Android only
  partialResults: true,
  addPunctuation: true,             // iOS 16+ only
  allowForSilence: 2000,            // Android only, milliseconds
});

Dengarkan Hasil

Berlangganan hasil parsial saat pengenalan aktif:

const partialListener = await SpeechRecognition.addListener(
  'partialResults',
  (event) => {
    const transcription = event.matches?.[0];
    console.log('Partial result:', transcription);
  }
);

// Don't forget to remove the listener when done
await partialListener.remove();

Hentikan Pengenalan

Hentikan mendengarkan dan bersihkan resource:

await SpeechRecognition.stop();

Contoh Lengkap

Berikut contoh lengkap yang menunjukkan cara menggunakan plugin:

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

export class VoiceRecognitionService {
  private partialListener: any = null;
  private isListening = false;

  async initialize(): Promise<boolean> {
    // Check availability
    const { available } = await SpeechRecognition.available();
    if (!available) {
      throw new Error('Speech recognition not available');
    }

    // Request permissions
    const { speechRecognition } = await SpeechRecognition.requestPermissions();
    if (speechRecognition !== 'granted') {
      throw new Error('Permission denied');
    }

    return true;
  }

  async startListening(
    onPartialResult: (text: string) => void,
    onFinalResult: (text: string) => void
  ): Promise<void> {
    if (this.isListening) {
      console.warn('Already listening');
      return;
    }

    try {
      // Set up partial results listener
      this.partialListener = await SpeechRecognition.addListener(
        'partialResults',
        (event) => {
          const text = event.matches?.[0] || '';
          onPartialResult(text);
        }
      );

      // Start recognition
      const result = await SpeechRecognition.start({
        language: 'en-US',
        maxResults: 3,
        partialResults: true,
        addPunctuation: true,
      });

      this.isListening = true;

      // Handle final result if partialResults is false
      if (result.matches && result.matches.length > 0) {
        onFinalResult(result.matches[0]);
      }
    } catch (error) {
      console.error('Error starting speech recognition:', error);
      throw error;
    }
  }

  async stopListening(): Promise<void> {
    if (!this.isListening) {
      return;
    }

    try {
      await SpeechRecognition.stop();

      // Clean up listener
      if (this.partialListener) {
        await this.partialListener.remove();
        this.partialListener = null;
      }

      this.isListening = false;
    } catch (error) {
      console.error('Error stopping speech recognition:', error);
      throw error;
    }
  }

  async getSupportedLanguages(): Promise<string[]> {
    const { languages } = await SpeechRecognition.getSupportedLanguages();
    return languages;
  }

  async checkListeningState(): Promise<boolean> {
    const { listening } = await SpeechRecognition.isListening();
    return listening;
  }
}

Referensi API

available()

Memeriksa apakah layanan pengenalan suara native dapat digunakan di perangkat saat ini.

const result = await SpeechRecognition.available();
// Returns: { available: boolean }

start(options?)

Mulai menangkap audio dan mentranskripsikan suara.

interface SpeechRecognitionStartOptions {
  language?: string;          // Locale identifier (e.g., 'en-US')
  maxResults?: number;        // Maximum number of results (default: 5)
  prompt?: string;            // Android only: Dialog prompt
  popup?: boolean;            // Android only: Show system dialog
  partialResults?: boolean;   // Stream partial results
  addPunctuation?: boolean;   // iOS 16+ only: Add punctuation
  allowForSilence?: number;   // Android only: Silence timeout in ms
}

const result = await SpeechRecognition.start(options);
// Returns: { matches?: string[] }

stop()

Menghentikan mendengarkan dan membersihkan resource native.

await SpeechRecognition.stop();

getSupportedLanguages()

Mendapatkan lokal yang didukung oleh recognizer yang mendasarinya.

Catatan: Perangkat Android 13+ tidak lagi mengekspos daftar ini; dalam hal itu languages akan kosong.

const result = await SpeechRecognition.getSupportedLanguages();
// Returns: { languages: string[] }

isListening()

Mengembalikan apakah plugin secara aktif mendengarkan suara.

const result = await SpeechRecognition.isListening();
// Returns: { listening: boolean }

checkPermissions()

Mendapatkan status izin saat ini.

const result = await SpeechRecognition.checkPermissions();
// Returns: { speechRecognition: 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' }

requestPermissions()

Meminta izin mikrofon + pengenalan suara.

const result = await SpeechRecognition.requestPermissions();
// Returns: { speechRecognition: 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' }

Event Listeners

partialResults

Dengarkan update transkripsi parsial saat partialResults diaktifkan.

const listener = await SpeechRecognition.addListener(
  'partialResults',
  (event: { matches: string[] }) => {
    console.log('Partial:', event.matches?.[0]);
  }
);

segmentResults (Hanya Android)

Dengarkan hasil pengenalan tersegmentasi.

const listener = await SpeechRecognition.addListener(
  'segmentResults',
  (event: { matches: string[] }) => {
    console.log('Segment:', event.matches?.[0]);
  }
);

endOfSegmentedSession (Hanya Android)

Dengarkan event penyelesaian sesi tersegmentasi.

const listener = await SpeechRecognition.addListener(
  'endOfSegmentedSession',
  () => {
    console.log('Segmented session ended');
  }
);

listeningState

Dengarkan perubahan ke status mendengarkan native.

const listener = await SpeechRecognition.addListener(
  'listeningState',
  (event: { status: 'started' | 'stopped' }) => {
    console.log('Listening state:', event.status);
  }
);

removeAllListeners()

Removes all registered listeners.

await SpeechRecognition.removeAllListeners();

Best Practices

1. Always check availability and permissions

   const { available } = await SpeechRecognition.available();
   if (!available) return;
   
   const { speechRecognition } = await SpeechRecognition.requestPermissions();
   if (speechRecognition !== 'granted') return;

2. Clean up listeners Always remove listeners when they’re no longer needed to prevent memory leaks:

   await listener.remove();
   // or
   await SpeechRecognition.removeAllListeners();

3. Handle errors gracefully

   try {
     await SpeechRecognition.start({ language: 'en-US' });
   } catch (error) {
     console.error('Speech recognition failed:', error);
     // Show user-friendly error message
   }

4. Provide visual feedback Use the listeningState event to show users when the app is actively listening.

5. Test with different accents and languages Speech recognition accuracy varies by language and accent. Test thoroughly with your target audience.

Platform Notes

iOS

• Requires iOS 10.0+
• Uses native SFSpeechRecognizer
• Supports punctuation on iOS 16+
• Requires both microphone and speech recognition permissions
• Recognition may fail if device language doesn’t match requested language

Android

• Requires Android 6.0 (API 23)+
• Uses SpeechRecognizer API
• Supports segmented sessions with configurable silence detection
• Android 13+ doesn’t expose list of supported languages
• Some devices may show system recognition UI

Web

• Limited support via Web Speech API
• Not all browsers support speech recognition
• Requires HTTPS connection
• May have different behavior across browsers

Troubleshooting

Permission Denied

If permissions are denied, guide users to app settings:

const { speechRecognition } = await SpeechRecognition.checkPermissions();
if (speechRecognition === 'denied') {
  // Show instructions to enable permissions in Settings
}

No Results Returned

• Check microphone is working
• Ensure quiet environment
• Verify language code matches device capabilities
• Check network connection (some platforms require it)

Recognition Stops Unexpectedly

• Use isListening() to check state
• Listen to listeningState events
• Implement auto-restart logic if needed

Next Steps

• View API reference on GitHub
• Report issues
• Explore example app