Getting Started

설치

Capgo AI-assisted 설치를 사용하여 플러그인을 설치할 수 있습니다. 다음 명령어를 사용하여 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.

만약 Capgo AI-assisted 설치를 사용하지 않는다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요.

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

Import

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

API 개요

speak

지정된 옵션으로 주어진 텍스트를 말합니다. 음성 큐에 음성 발화가 추가됩니다.

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

장치에서 음성 합성이 사용 가능한지 확인합니다.

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

speech synthesis 엔진을 초기화합니다 (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;
}

실질적인 출처

이 페이지는 플러그인의 src/definitions.ts공개 API이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속

만약에 Getting Started 계획 대시보드 및 API 운영을 위해 연결하세요. Using @capgo/capacitor-speech-synthesis for the native capability in Using @capgo/capacitor-speech-synthesis, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.