# @capgo/capacitor-speech-synthesis 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/

版本：8\.0\.27
npm 元数据更新时间：2026-10-15T04:17:50.476Z
中文译文更新时间：2026-11-09T03:25:47.096Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-speech-synthesis
原文对照：https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/?lang=original
项目主页：https://capgo.app/docs/plugins/speech-synthesis/
源码仓库：https://github.com/Cap-go/capacitor-speech-synthesis

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：159 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-19T01:45:27.051Z
- 最新版本发布：2026-10-15T04:17:50.147Z
- 近 30 天下载量：49811（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

从文字中合成语音,对语言,语音,发音,速率,音量有完全控制.

## 安装

```sh
npm install @capgo/capacitor-speech-synthesis
```

也可以使用：`pnpm add @capgo/capacitor-speech-synthesis`、`yarn add @capgo/capacitor-speech-synthesis`、`bun add @capgo/capacitor-speech-synthesis`

## README

# @ capgo/ 电容- speech- synthesis

高声读取您 Capacitor app 中的文本, 并使用本地的文本对发音, 并控制语言、 语音、 发音、 速率和音量 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-speech-synthesis)](https://capgo.app/?ref=plugin_speech_synthesis)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_speech_synthesis)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_speech_synthesis) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-speech-synthesis` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-speech-synthesis到我的Capacitor应用上并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_speech_synthesis) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_speech_synthesis)

![@capgo/capacitor-speech-synthesis for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-speech-synthesis/main/assets/github-social-preview.png)

## 主要特点

-   **说**数字 : `speak()` 包括语言,语音,投出,速率,音量和队列策略.
-   **播放控件**数字 : `pause()`, (中文(简体) ), `resume()`, (中文(简体) ), `cancel()` 财务报告和审定财务报表 `isSpeaking()`。暂停和恢复不支持在Android上.
-   **声音和语言**数字 : `getVoices()`, (中文(简体) ), `getLanguages()`, (中文(简体) ), `isLanguageAvailable()` 财务报告和审定财务报表 `isVoiceAvailable()`。 。 。 .
-   **保存到文件**数字 : `synthesizeToFile()` 将语音写入iOS和Android上的音频文件.
-   **活动**数字 : `start`, (中文(简体) ), `end`, (中文(简体) ), `boundary` 财务报告和审定财务报表 `error` 听众.
-   **平台**:iOS,Android和Web. iOS使用AVSpeech合成器,Android使用TextToSpeech. Web 使用 Web 语音 API.

## 为什么是演讲综述?

提供免费、开源的选项,提供完整的文字对语音能力:

-   **跨平台** - 在iOS、Android和Web上使用一致的API
-   **完全语音控制** - 从系统声音中选择,调整投出率、速率和音量
-   **事件驱动** - 听语音事件(开始、结束、字段、错误)
-   **文件导出** - 将语音保存到iOS和Android上的音频文件
-   **现代 APIs** - 使用AVSpeech合成器(iOS)、TextToSpeech(Android)和Web Speech API
-   **生产准备** - 有综合文档的完整类型脚本支持

适合无障碍功能,语言学习应用,音频书播放器,以及任何需要文本到语音的应用.

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

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

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-speech-synthesis
npx cap sync
```

## API 密码

-   [`speak(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-speak)
-   [`synthesizeToFile(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-synthesizetofile)
-   [`cancel()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-cancel)
-   [`pause()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-pause)
-   [`resume()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-resume)
-   [`isSpeaking()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-isspeaking)
-   [`isAvailable()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-isavailable)
-   [`getVoices()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-getvoices)
-   [`getLanguages()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-getlanguages)
-   [`isLanguageAvailable(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-islanguageavailable)
-   [`isVoiceAvailable(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-isvoiceavailable)
-   [`initialize()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-initialize)
-   [`activateAudioSession(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-activateaudiosession)
-   [`deactivateAudioSession()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-deactivateaudiosession)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-getpluginversion)
-   [`addListener('start', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-addlistenerstart-)
-   [`addListener('end', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-addlistenerend-)
-   [`addListener('boundary', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-addlistenerboundary-)
-   [`addListener('error', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-addlistenererror-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-interfaces)

从文本中合成语音的语音合成插件 .

### 说话(...)

```typescript
speak(options: SpeakOptions) => Promise<SpeakResult>
```

以指定选项表达给定文本. 语音被添加到语音队列中.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SpeakOptions](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-speakoptions)` | \- 语音选项,包括文本和语音设置 |

**回返情况:** `Promise<[SpeakResult](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-speakresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 合成 ToFile (...)

```typescript
synthesizeToFile(options: SpeakOptions) => Promise<SynthesizeToFileResult>
```

将语音合成到音频文件(只有Android/iOS). 返回保存音频的文件路径.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SpeakOptions](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-speakoptions)` | \- 语音选项,包括文本和语音设置 |

**回返情况:** `Promise<[SynthesizeToFileResult](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-synthesizetofileresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 取消( )

```typescript
cancel() => Promise<void>
```

取消所有已排队的语音并停止当前语音.

**自:** 1.0.0 (单位:千美元)

* * *

### 暂停( c)

```typescript
pause() => Promise<void>
```

立即暂停演讲.

**自:** 1.0.0 (单位:千美元)

* * *

### 恢复( )

```typescript
resume() => Promise<void>
```

复次暂停演说.

**自:** 1.0.0 (单位:千美元)

* * *

### 正在发言( S)

```typescript
isSpeaking() => Promise<{ isSpeaking: boolean; }>
```

检查语音合成是否正在说话 .

**回返情况:** `Promise<{ isSpeaking: boolean; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 易读 ()

```typescript
isAvailable() => Promise<{ isAvailable: boolean; }>
```

检查设备上是否有语音合成可用 .

**回返情况:** `Promise<{ isAvailable: boolean; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 获取声音( )

```typescript
getVoices() => Promise<{ voices: VoiceInfo[]; }>
```

获取所有可用的声音 .

**回返情况:** `Promise<{ voices: VoiceInfo[]; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 获取语言( C)

```typescript
getLanguages() => Promise<{ languages: string[]; }>
```

获取所有可用的语言.

**回返情况:** `Promise<{ languages: string[]; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 可用语言(...)

```typescript
isLanguageAvailable(options: IsLanguageAvailableOptions) => Promise<{ isAvailable: boolean; }>
```

检查是否有特定语言可用.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[IsLanguageAvailableOptions](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-islanguageavailableoptions)` | \- 要检查的语言 |

**回返情况:** `Promise<{ isAvailable: boolean; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 可声波(...)

```typescript
isVoiceAvailable(options: IsVoiceAvailableOptions) => Promise<{ isAvailable: boolean; }>
```

检查是否有特定的声音可用 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[IsVoiceAvailableOptions](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-isvoiceavailableoptions)` | \- 声音ID来检查 |

**回返情况:** `Promise<{ isAvailable: boolean; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 初始化()

```typescript
initialize() => Promise<void>
```

初始化语音合成引擎(iOS优化). 这可以减少第一个演讲请求的延迟.

**自:** 1.0.0 (单位:千美元)

* * *

### 激活音频会话(...)

```typescript
activateAudioSession(options: ActivateAudioSessionOptions) => Promise<void>
```

用特定类别(仅iOS)激活音频会话.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ActivateAudioSessionOptions](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-activateaudiosessionoptions)` | \- 音频会话类别 |

**自:** 1.0.0 (单位:千美元)

* * *

### 解除会议( )

```typescript
deactivateAudioSession() => Promise<void>
```

取消音频会话(只有iOS).

**自:** 1.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地插件版本.

**回返情况:** `Promise<{ version: string; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加倾听器( “ start” ,...)

```typescript
addListener(eventName: 'start', listenerFunc: (event: UtteranceEvent) => void) => Promise<PluginListenerHandle>
```

听到一个词开始说话.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'start'` | \- 事件名称( “ 启动 ”) |
| **`listenerFunc`** | `(event: [UtteranceEvent](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-utteranceevent)) => void` | \- 回调功能 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-pluginlistenerhandle)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加倾听器( “ end' ,...)

```typescript
addListener(eventName: 'end', listenerFunc: (event: UtteranceEvent) => void) => Promise<PluginListenerHandle>
```

听当一个演讲结束的时候.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'end'` | \- 事件名称('end') |
| **`listenerFunc`** | `(event: [UtteranceEvent](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-utteranceevent)) => void` | \- 回调功能 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-pluginlistenerhandle)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 边界 ” ,...)

```typescript
addListener(eventName: 'boundary', listenerFunc: (event: BoundaryEvent) => void) => Promise<PluginListenerHandle>
```

说话时听字边框.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'boundary'` | \- 事件名称 ('边界') |
| **`listenerFunc`** | `(event: [BoundaryEvent](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-boundaryevent)) => void` | \- 回调功能 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-pluginlistenerhandle)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加倾听器( 'error',...)

```typescript
addListener(eventName: 'error', listenerFunc: (event: ErrorEvent) => void) => Promise<PluginListenerHandle>
```

听取合成错误.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'error'` | \- 事件名称 ('error') |
| **`listenerFunc`** | `(event: [ErrorEvent](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-errorevent)) => void` | \- 回调功能 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-speech-synthesis/#readme-pluginlistenerhandle)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除所有事件听众.

**自:** 1.0.0 (单位:千美元)

* * *

### 接口

#### 说回声

由发言文本产生.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`utteranceId`** | `string` | 此语句的独有标识符 . | 1.0.0 (单位:千美元) |

#### 说选项

发言文本的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`text`** | `string` | 语出之文. | 1.0.0 (单位:千美元) |
| **`language`** | `string` | BCP-47语言标记(例如"en-US","es-ES"). | 1.0.0 (单位:千美元) |
| **`voiceId`** | `string` | 要使用的语音标识符 . | 1.0.0 (单位:千美元) |
| **`pitch`** | `number` | 发声(0.5比2.0,默认:1.0). | 1.0.0 (单位:千美元) |
| **`rate`** | `number` | 发声率(0.1比10.0,默认:1.0. | 1.0.0 (单位:千美元) |
| **`volume`** | `number` | 音量(0.0至1.0,默认:1.0). | 1.0.0 (单位:千美元) |
| **`queueStrategy`** | `'Add' | 'Flush'` | 队列策略 : “ 添加 ” 以附加或“ Flush ” 来替换队列 。 默认: “ 添加 ” | 1.0.0 (单位:千美元) |

#### 合成到文件结果

合成到文件的结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`filePath`** | `string` | 音频保存的文件路径 . | 1.0.0 (单位:千美元) |
| **`utteranceId`** | `string` | 此语句的独有标识符 . | 1.0.0 (单位:千美元) |

#### 语音信息

关于一个声音的信息.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 独特的语音标识符. | 1.0.0 (单位:千美元) |
| **`name`** | `string` | 显示语音名称 . | 1.0.0 (单位:千美元) |
| **`language`** | `string` | BCP-47语言代码. | 1.0.0 (单位:千美元) |
| **`gender`** | `'male' | 'female' | 'neutral'` | 语音的性别(仅iOS). | 1.0.0 (单位:千美元) |
| **`isNetworkConnectionRequired`** | `boolean` | 此语音是否需要网络连接 . | 1.0.0 (单位:千美元) |
| **`default`** | `boolean` | 是否这是默认的声音( 只有Web) . | 1.0.0 (单位:千美元) |

#### IsLangage 可用选项

检查语言可用性选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`language`** | `string` | BCP-47语言代码需要检查. | 1.0.0 (单位:千美元) |

#### 可选择选项

用于检查语音可用的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`voiceId`** | `string` | 声音ID检查. | 1.0.0 (单位:千美元) |

#### 启动会议

启动音频会话的选项( 只有iOS) .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`category`** | `'Ambient' | 'Playback'` | 音频会话分类 。 - 'Ambient':与其他音频相混合 - 'Playback': 停止其它音频 | 1.0.0 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 绝食晚会

语音开始或结束时发生事件.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`utteranceId`** | `string` | 语音识别符. | 1.0.0 (单位:千美元) |

#### 边界事件

事件以字形边界发射.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`utteranceId`** | `string` | 语音识别符. | 1.0.0 (单位:千美元) |
| **`charIndex`** | `number` | 文中人物索引. | 1.0.0 (单位:千美元) |
| **`charLength`** | `number` | 当前单词的字符长度 . | 1.0.0 (单位:千美元) |

#### 错误事件

合成错误事件.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`utteranceId`** | `string` | 语音识别符. | 1.0.0 (单位:千美元) |
| **`error`** | `string` | 错误信息 . | 1.0.0 (单位:千美元) |

## 常见问题

### @capgo/capacitor-speech-synthesis 是什么？

从文字中合成语音,对语言,语音,发音,速率,音量有完全控制\.

### 如何安装 @capgo/capacitor-speech-synthesis？

在项目目录运行 npm install @capgo/capacitor-speech-synthesis，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-speech-synthesis 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-speech-synthesis 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-speech-synthesis 可以商用吗？

@capgo/capacitor-speech-synthesis 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-speech-synthesis 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-speech-synthesis 在 2026/10/09 – 2026/11/07 这 30 天内被下载 49,811 次，日均约 1,660 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-speech-synthesis 还在维护吗？

最新版本 8\.0\.27 发布于 2026/10/15（25 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 29 个；首次发布于 2025/11/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。