시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-speech-synthesis
bunx cap sync

가져오기

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

빠른 시작

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.speak({
  text: 'Gate B12 is boarding.',
  language: 'en-US',
  rate: 1.0,
});

예시: 네이티브에서 오디오 내보내기

const { uri } = await SpeechSynthesis.synthesizeToFile({
  text: lessonScript,
  language: 'es-ES',
});

자주 하는 실수

• iOS 초기화: 호출 initialize() iOS에서 첫 발화 지연을 줄이려면 초기에 실행하세요.
• 오디오 세션: 사용하세요 activateAudioSession() 음성이 다른 오디오와 섞이거나 소리를 줄여야 할 때.
• Web 음성: 브라우저마다 음성 목록이 다르므로, 항상 기본 음성으로 대체됩니다.

API 개요

speak

지정된 옵션으로 텍스트를 읽어줍니다. 발화(utterance)는 음성 대기열에 추가됩니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const result = await SpeechSynthesis.speak({
  text: 'Hello, world!',
  language: 'en-US',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  queueStrategy: 'Add'
});
console.log('Utterance ID:', result.utteranceId);

synthesizeToFile

음성을 오디오 파일로 합성합니다 (Android/iOS 전용). 오디오가 저장된 파일 경로를 반환합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const result = await SpeechSynthesis.synthesizeToFile({
  text: 'Hello, world!',
  language: 'en-US'
});
console.log('Audio file saved at:', result.filePath);

cancel

대기 중인 모든 음성 출력을 취소하고 현재 음성을 중단합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.cancel();

pause

음성 출력을 즉시 일시 중지합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.pause();

resume

일시 중지된 음성 출력을 다시 시작합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.resume();

isSpeaking

현재 음성 합성 기능이 작동 중인지 확인합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isSpeaking } = await SpeechSynthesis.isSpeaking();
console.log('Is speaking:', isSpeaking);

isAvailable

기기에서 음성 합성(speech synthesis)을 사용할 수 있는지 확인합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isAvailable();
if (isAvailable) {
  console.log('Speech synthesis is available');
}

getVoices

사용 가능한 모든 음성을 가져옵니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { voices } = await SpeechSynthesis.getVoices();
voices.forEach(voice => {
  console.log(`${voice.name} (${voice.language})`);
});

getLanguages

사용 가능한 모든 언어를 가져옵니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { languages } = await SpeechSynthesis.getLanguages();
console.log('Available languages:', languages);

isLanguageAvailable

특정 언어를 사용할 수 있는지 확인합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isLanguageAvailable({
  language: 'es-ES'
});
console.log('Spanish available:', isAvailable);

isVoiceAvailable

특정 음성을 사용할 수 있는지 확인합니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isVoiceAvailable({
  voiceId: 'com.apple.ttsbundle.Samantha-compact'
});
console.log('Voice available:', isAvailable);

initialize

음성 합성 엔진을 초기화합니다 (iOS 최적화). 첫 음성 요청 시 발생하는 지연 시간을 줄일 수 있습니다.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.initialize();

activateAudioSession

특정 카테고리로 오디오 세션을 활성화합니다 (iOS 전용).

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.activateAudioSession({
  category: 'Playback'
});

deactivateAudioSession

오디오 세션을 비활성화합니다 (iOS 전용).

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.deactivateAudioSession();

타입 레퍼런스

SpeakOptions

텍스트 읽기 옵션입니다.

export interface SpeakOptions {
  /**
   * The text to speak.
   *
   * @since 1.0.0
   */
  text: string;

  /**
   * The BCP-47 language tag (e.g., 'en-US', 'es-ES').
   *
   * @since 1.0.0
   */
  language?: string;

  /**
   * The voice identifier to use.
   *
   * @since 1.0.0
   */
  voiceId?: string;

  /**
   * The pitch of the voice (0.5 to 2.0, default: 1.0).
   *
   * @since 1.0.0
   */
  pitch?: number;

  /**
   * The speaking rate (0.1 to 10.0, default: 1.0).
   *
   * @since 1.0.0
   */
  rate?: number;

  /**
   * The volume (0.0 to 1.0, default: 1.0).
   *
   * @since 1.0.0
   */
  volume?: number;

  /**
   * The queue strategy: 'Add' to append or 'Flush' to replace queue.
   * Default: 'Add'
   *
   * @since 1.0.0
   */
  queueStrategy?: 'Add' | 'Flush';
}

SpeakResult

텍스트 읽기 결과입니다.

export interface SpeakResult {
  /**
   * Unique identifier for this utterance.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

SynthesizeToFileResult

파일 합성 결과입니다.

export interface SynthesizeToFileResult {
  /**
   * The file path where audio was saved.
   *
   * @since 1.0.0
   */
  filePath: string;

  /**
   * Unique identifier for this utterance.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

VoiceInfo

음성에 대한 정보입니다.

export interface VoiceInfo {
  /**
   * Unique voice identifier.
   *
   * @since 1.0.0
   */
  id: string;

  /**
   * Display name of the voice.
   *
   * @since 1.0.0
   */
  name: string;

  /**
   * BCP-47 language code.
   *
   * @since 1.0.0
   */
  language: string;

  /**
   * Gender of the voice (iOS only).
   *
   * @since 1.0.0
   */
  gender?: 'male' | 'female' | 'neutral';

  /**
   * Whether this voice requires a network connection.
   *
   * @since 1.0.0
   */
  isNetworkConnectionRequired?: boolean;

  /**
   * Whether this is the default voice (Web only).
   *
   * @since 1.0.0
   */
  default?: boolean;
}

IsLanguageAvailableOptions

언어 사용 가능 여부를 확인하는 옵션입니다.

export interface IsLanguageAvailableOptions {
  /**
   * The BCP-47 language code to check.
   *
   * @since 1.0.0
   */
  language: string;
}

IsVoiceAvailableOptions

음성 사용 가능 여부를 확인하는 옵션입니다.

export interface IsVoiceAvailableOptions {
  /**
   * The voice ID to check.
   *
   * @since 1.0.0
   */
  voiceId: string;
}

ActivateAudioSessionOptions

오디오 세션을 활성화하는 옵션입니다 (iOS 전용).

export interface ActivateAudioSessionOptions {
  /**
   * The audio session category.
   * - 'Ambient': Mixes with other audio
   * - 'Playback': Stops other audio
   *
   * @since 1.0.0
   */
  category: 'Ambient' | 'Playback';
}

UtteranceEvent

음성 출력이 시작되거나 종료될 때 발생하는 이벤트입니다.

export interface UtteranceEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

BoundaryEvent

단어 경계에서 발생하는 이벤트입니다.

export interface BoundaryEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;

  /**
   * The character index in the text.
   *
   * @since 1.0.0
   */
  charIndex: number;

  /**
   * The character length of the current word.
   *
   * @since 1.0.0
   */
  charLength?: number;
}

ErrorEvent

합성 오류 발생 시 발생하는 이벤트입니다.

export interface ErrorEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;

  /**
   * The error message.
   *
   * @since 1.0.0
   */
  error: string;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-speech-synthesis 사용하기 ‘@capgo/capacitor-speech-synthesis 사용하기’에서 네이티브 기능을 위해, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.