快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo 能力添加到你的 AI 工具中：

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

然后使用以下 prompt：

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

使用指定选项朗读给定文本。 该朗读任务将被添加到语音队列中。

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

初始化语音合成引擎（针对 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 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 以规划 dashboard 和 API 操作，并将其连接至 使用 @capgo/capacitor-speech-synthesis 在“使用 @capgo/capacitor-speech-synthesis”中实现原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。