快速入门
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-speech-synthesis`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/speech-synthesis/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
安装
“安装”章节你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 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-synthesisbunx 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 概览
章节标题:“API 概览”speak
“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
“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
“cancel” 章节取消所有已排队的语音并停止当前朗读。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.cancel();pause
标题为“pause”的章节立即暂停朗读。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.pause();resume
标题为“resume”的章节恢复已暂停的语音播放。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.resume();isSpeaking
“isSpeaking” 章节检查语音合成当前是否正在朗读。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
const { isSpeaking } = await SpeechSynthesis.isSpeaking();console.log('Is speaking:', isSpeaking);isAvailable
标题为 “isAvailable” 的章节检查设备是否支持语音合成。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
const { isAvailable } = await SpeechSynthesis.isAvailable();if (isAvailable) { console.log('Speech synthesis is available');}getVoices
“getVoices” 章节获取所有可用语音。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
const { voices } = await SpeechSynthesis.getVoices();voices.forEach(voice => { console.log(`${voice.name} (${voice.language})`);});getLanguages
“getLanguages” 章节获取所有可用语言。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
const { languages } = await SpeechSynthesis.getLanguages();console.log('Available languages:', languages);isLanguageAvailable
“isLanguageAvailable” 章节检查是否支持特定语言。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
const { isAvailable } = await SpeechSynthesis.isLanguageAvailable({ language: 'es-ES'});console.log('Spanish available:', isAvailable);isVoiceAvailable
“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
“initialize” 章节初始化语音合成引擎(针对 iOS 优化)。 这可以降低首次语音请求的延迟。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.initialize();activateAudioSession
“activateAudioSession” 章节使用特定类别激活音频会话(仅限 iOS)。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.activateAudioSession({ category: 'Playback'});deactivateAudioSession
“deactivateAudioSession” 章节停用音频会话(仅限 iOS)。
import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';
await SpeechSynthesis.deactivateAudioSession();类型参考
“类型参考” 章节SpeakOptions
“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
“SpeakResult” 章节文本朗读结果。
export interface SpeakResult { /** * Unique identifier for this utterance. * * @since 1.0.0 */ utteranceId: string;}SynthesizeToFileResult
“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
“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
标题为“IsLanguageAvailableOptions”的章节检查语言可用性的选项。
export interface IsLanguageAvailableOptions { /** * The BCP-47 language code to check. * * @since 1.0.0 */ language: string;}IsVoiceAvailableOptions
标题为“IsVoiceAvailableOptions”的章节检查语音可用性的选项。
export interface IsVoiceAvailableOptions { /** * The voice ID to check. * * @since 1.0.0 */ voiceId: string;}ActivateAudioSessionOptions
标题为“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
标题为“UtteranceEvent”的章节在语音开始或结束时触发的事件。
export interface UtteranceEvent { /** * The utterance identifier. * * @since 1.0.0 */ utteranceId: string;}BoundaryEvent
标题为 “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
标题为 “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 的实现细节。