시작하기

1. 패키지 설치

   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. 네이티브 프로젝트와 동기화

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. 플랫폼 권한 구성(아래 참조)

플랫폼 구성

iOS

앱의 Info.plist 파일에 다음 키를 추가하세요.

<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

플러그인은 필수 RECORD_AUDIO 권한을 AndroidManifest.xml에 자동으로 추가합니다. 추가 구성이 필요하지 않습니다.

기본 사용법

가용성 확인

음성 인식을 사용하기 전에 기기에서 음성 인식을 사용할 수 있는지 확인하세요.

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

권한 요청

인식을 시작하기 전에 필요한 권한을 요청하십시오:

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

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

인식 시작

선택적 구성으로 음성 듣기를 시작하세요.

// 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
});

결과 듣기

인식이 활성화된 동안 부분 결과를 구독합니다.

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();

인식 중지

듣기를 중지하고 리소스를 정리하십시오.

await SpeechRecognition.stop();

완전한 예

다음은 플러그인 사용 방법을 보여주는 전체 예입니다.

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

API 참조

사용 가능()

현재 기기에서 네이티브 음성인식 서비스를 사용할 수 있는지 확인합니다.

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

시작(옵션?)

오디오 캡처 및 음성 기록을 시작합니다.

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[] }

중지()

듣기를 중지하고 기본 리소스를 분해합니다.

await SpeechRecognition.stop();

getSupportedLanguages()

기본 인식기가 지원하는 로캘을 가져옵니다.

참고: Android 13개 이상의 장치는 더 이상 이 목록을 노출하지 않습니다. 이 경우 languages은 비어 있게 됩니다.

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

isListening()

플러그인이 음성을 적극적으로 듣고 있는지 여부를 반환합니다.

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

checkPermissions()

현재 권한 상태를 가져옵니다.

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

요청권한()

마이크+음성인식 권한을 요청합니다.

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

이벤트 리스너

부분 결과

partialResults이 활성화된 동안 부분 기록 업데이트를 수신합니다.

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

세그먼트 결과(Android 전용)

분할된 인식 결과를 들어보세요.

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

endOfSegmentedSession(Android 전용)

분할된 세션 완료 이벤트를 수신합니다.

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

청취 상태

기본 청취 상태에 대한 변경 사항을 수신합니다.

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

제거AllListeners()

등록된 모든 리스너를 제거합니다.

await SpeechRecognition.removeAllListeners();

모범 사례

1. 항상 가용성과 권한을 확인하세요

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

2. 청취자 정리 메모리 누수를 방지하려면 더 이상 필요하지 않은 리스너를 항상 제거하세요.

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

3. 오류를 적절하게 처리

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

4. 시각적 피드백 제공 listeningState 이벤트를 사용하여 앱이 적극적으로 듣고 있을 때 사용자에게 표시합니다.

5. 다양한 억양과 언어로 테스트 음성 인식 정확도는 언어와 억양에 따라 다릅니다. 타겟 고객을 대상으로 철저하게 테스트하세요.

플랫폼 노트### iOS

• iOS 10.0+ 필요
• 네이티브 SFSpeechRecognizer 사용
• iOS 16+에서 구두점을 지원합니다.
• 마이크 및 음성 인식 권한이 모두 필요합니다.
• 기기 언어가 요청한 언어와 일치하지 않을 경우 인식이 실패할 수 있습니다.

Android

• Android 6.0(API 23) 필요+
• SpeechRecognizer API 사용
• 구성 가능한 무음 감지로 분할된 세션 지원
• Android 13+는 지원되는 언어 목록을 공개하지 않습니다.
• 일부 장치에서는 시스템 인식 UI가 표시될 수 있습니다.

웹

• 웹 스피치를 통한 제한적 지원 API
• 모든 브라우저가 음성 인식을 지원하는 것은 아닙니다.
• HTTPS 연결이 필요합니다
• 브라우저마다 동작이 다를 수 있습니다.

문제 해결

권한이 거부되었습니다

권한이 거부된 경우 사용자에게 앱 설정을 안내하세요.

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

결과가 반환되지 않았습니다.

• 마이크가 작동하는지 확인하세요
• 조용한 환경을 보장합니다.
• 언어 코드가 장치 기능과 일치하는지 확인
• 네트워크 연결을 확인하세요(일부 플랫폼에서는 필요함)

인식이 예기치 않게 중지됩니다.

• isListening()을 사용하여 상태를 확인하세요.
• listeningState 이벤트 듣기
• 필요한 경우 자동 재시작 로직을 구현합니다.

다음 단계

• GitHub의 API 참조 보기
• 문제 신고
• 예제 앱 살펴보기