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

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

版本：8\.4\.6
npm 元数据更新时间：2026-10-27T19:29:27.134Z
中文译文更新时间：2026-11-09T02:07:04.729Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：284 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-09T01:51:22.129Z
- 最新版本发布：2026-10-27T19:29:26.655Z
- 近 30 天下载量：268890（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 36 个）

## 中文简介

电容插件,用于在有活性部分结果的情况下进行综合在线语音识别.

## 安装

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

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

## README

# @ capgo/ 电容- speech- 识别

在您的 Capacitor app 中将语音转换成文本, 低潜度, 现场部分结果和本地识别器在 iOS 和 Android 上 .

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

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

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

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

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

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

## 主要特点

-   **现场录音**: 与 `partialResults: true`, (中文(简体) ), `start()` 用户说话时更新流程 . `stop()` 财务报告和审定财务报表 `forceStop()` 结束会话.
-   **语言和终端模式**数字 : `getSupportedLanguages()` 列出本地地址, `isOnDeviceRecognitionAvailable()` 检查设备支持和 `useOnDeviceRecognition: true` 选择加入.
-   **准确性选项**: 在iOS 16上和后期上标出和域名的上下文字符串.
-   **推着说话**数字 : `setPTTState()` 报告是否按住按钮,用于 `continuousPTT` 或你自己的握住和说话的流程.
-   **事件和权限**数字 : `listeningState`, (中文(简体) ), `audioLevel` 财务报告和审定财务报表 `error` 事件,加上麦克风和语音许可帮助者.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. iOS 使用语音框架, Android 使用 `SpeechRecognizer`. 分片结果仅为Android. 在网上不可用.

## 为什么是这个插件?

这个包是从极好的开始的 [`capacitor-community/speech-recognition`](https://github.com/capacitor-community/speech-recognition) 插件, 但是在最需要的调取请求中折叠( 插取支持、 分会话、 崩溃修正) , 并保留在 Capgo 伞下 。 你得到熟悉的API+:

-   ✅ **合并社区公关**,在iOS(PR #74)上分解切换,在Android(PR #104)上分解结果和沉默处理,以及 `recognitionRequest` 安全固定(PR #105)出舱.
-   🚀 **新建 Capgo 特性**,可配置的静音窗口,流线片段的收听器,一致的许可帮助器,以及一个被刷新的例子应用.
-   🛠️ **主动维修**,与所有 Capgo 插件(SPM, Podspec, 工作流程, 例如 app) 一样的常规, 因此它跟踪 Capacitor 主要版本, 不使用比特- rot .
-   📦 **降入移徙**, TypeScript 定义仍然与社区插件相容,同时披露额外的选项(`addPunctuation`, (中文(简体) ), `allowForSilence`, (中文(简体) ), `segmentResults`(见a/c.5/49/70,附件).

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/speech-识别/](https://capgo.app/docs/plugins/speech-recognition/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页: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-recognition` plugin in my project.
```

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

```bash
bun add @capgo/capacitor-speech-recognition
bunx cap sync
```

## 使用量

```ts
import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.requestPermissions();

const { available } = await SpeechRecognition.available();
if (!available) {
  console.warn('Speech recognition is not supported on this device.');
}

const partialListener = await SpeechRecognition.addListener('partialResults', (event) => {
  console.log('Partial:', event.matches?.[0]);
});

await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3,
  partialResults: true,
});

// Later, when you want to stop listening
await SpeechRecognition.stop();
await partialListener.remove();
```

### iOS 倒置和上下文字符串

iOS 用途 `SFSpeechRecognizer` 默认情况下,包括在iOS 26.以下版本. 设定 `useOnDeviceRecognition: true` 只当您想要iOS 26+时 `SpeechAnalyzer` 路径和 `isOnDeviceRecognitionAvailable()` 报告支持. 如果无法找到较新的路径, 插件会回到 `SFSpeechRecognizer`。 。 。 .

使用 `contextualStrings` 对特定应用术语的偏见。 打开 被传递到遗产路径 `SFSpeechRecognizer`; 在 iOS 26+ 上与 `useOnDeviceRecognition`,它们通过 `AnalysisContext` 编辑 `SpeechAnalyzer` 路径 :

```ts
await SpeechRecognition.start({
  language: 'en-US',
  partialResults: true,
  contextualStrings: ['Capgo', 'Live Update', 'channel override'],
});
```

## 设备识别模式

此插件现在支持在清晰的后端选择在设备上识别路径 `useOnDeviceRecognition` 旗帜.

### 这是什么

默认路径保留了长期存在的识别器流以进行后向相容. `useOnDeviceRecognition` 当平台支持时, 切换到更新的本地语音管道:

-   在iOS 26+上,它使用苹果的 `SpeechAnalyzer` 编号 : `SpeechTranscriber` 堆栈.
-   在更古老的iOS版本上,不支持的iOS 26+地區,或被禁用后旗会使用 `SFSpeechRecognizer`。 。 。 .
-   在近期的Android版本上,它使用在线设备 `SpeechRecognizer` 路径.

### 为什么你可能想要它

-   更好地与最新本地语音 API 保持一致 .
-   在支持的平台上改进了安装模型处理.
-   如果您想要采用更新的语句堆栈而不立即改变每个用户, 则需要更清洁的推出路径 .

### 为什么选入

即使有新的堆栈技术可用,改变识别行为也会默默地影响:

-   语句
-   平分行为
-   部分结果时间
-   产品计量和用户期望

因此插件默认保留了后遗症识别器,需要为新路径打出一个明确的旗帜.

### 建议推出

1.  检查通用语音支持 `available()`。 。 。 .
2.  检查设备上的路径 `isOnDeviceRecognitionAvailable()`。 。 。 .
3.  启用 `useOnDeviceRecognition` 只当第二次检查返回时 `true`。 。 。 .
4.  如果你的应用依赖于稳定的记录或分析,就逐步推出.

### 示例

```ts
import { SpeechRecognition } from '@capgo/capacitor-speech-recognition';

await SpeechRecognition.requestPermissions();

const { available } = await SpeechRecognition.available();
if (!available) {
  throw new Error('Speech recognition is not available on this device.');
}

const { available: onDeviceRecognitionAvailable } =
  await SpeechRecognition.isOnDeviceRecognitionAvailable({
    language: 'en-US',
  });

await SpeechRecognition.start({
  language: 'en-US',
  partialResults: true,
  useOnDeviceRecognition: onDeviceRecognitionAvailable,
});
```

### 还没用的时候

如果 :

-   您需要对现有用户采取不变的行为
-   您没有验证您的目标区域的记录
-   您想要在较旧和较新版本的 OS 版本中相同的制作行为

### 平台注释

-   iOS只在iOS 26+上使用更新的device路径,并且仅用于通过更新的语音堆栈对本地人Apple进行曝光.
-   Android只在内置模式中使用了安装在设备上的识别器. `popup: true` 继续使用系统对话框,但不兼容 `useOnDeviceRecognition`。 。 。 .
-   在Android上,一个被支持的device上语言可能需要模型下载才能开始识别.

## 推动对话和会议活动

此插件还支持围绕三个API构建的以推向对讲器为导向的流:

-   `setPTTState({ held })` 让您的用户界面在按下或放出按钮时告诉插件 .
-   `forceStop()` 立即停止活动会话,并以 `forced: true` 当可用时.
-   `getLastPartialResult()` 允许您在任何时间读取最新的缓存记录.

`continuousPTT` 是一种实验的跨平台模式,它通过在演讲部分最后敲定时重新启动识别,使一个所举行的推向对讲会保持活力。 Android和iOS都支持这种重启流,以进行内置/内置识别.

插件还发出决定会话生命周期事件, 以便 UIs 可以干净的反应 :

-   `listeningState` 现在携带 `state`, (中文(简体) ), `sessionId`, (中文(简体) ), `reason`选择 `errorCode` 除了遗产 `status`。 。 。 .
-   `error` 每一个本地识别器错误都会被释放, 而不是只依靠拒绝承诺.
-   `readyForNextSession` 当本地资源被撕毁,插件准备再开始时,信号.

### iOS 用户描述

在您的应用程序中添加以下密钥 `Info.plist`数字 :

-   `NSSpeechRecognitionUsageDescription`
-   `NSMicrophoneUsageDescription`

## API 密码

-   [`available()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-available)
-   [`isOnDeviceRecognitionAvailable(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-isondevicerecognitionavailable)
-   [`start(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-start)
-   [`stop()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-stop)
-   [`forceStop(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-forcestop)
-   [`getLastPartialResult()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-getlastpartialresult)
-   [`setPTTState(...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-setpttstate)
-   [`getSupportedLanguages()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-getsupportedlanguages)
-   [`isListening()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-islistening)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-requestpermissions)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-getpluginversion)
-   [`addListener('endOfSegmentedSession', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenerendofsegmentedsession-)
-   [`addListener('segmentResults', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenersegmentresults-)
-   [`addListener('partialResults', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenerpartialresults-)
-   [`addListener('listeningState', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenerlisteningstate-)
-   [`addListener('error', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenererror-)
-   [`addListener('audioLevel', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlisteneraudiolevel-)
-   [`addListener('readyForNextSession', ...)`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-addlistenerreadyfornextsession-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-type-aliases)

### 可用( )

```typescript
available() => Promise<SpeechRecognitionAvailability>
```

检查本地语音识别服务是否可以在当前设备上使用 .

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

* * *

### 可识别文件(...)

```typescript
isOnDeviceRecognitionAvailable(options?: Pick<SpeechRecognitionStartOptions, "language" | "preferLegacyRecognizer"> | undefined) => Promise<SpeechRecognitionAvailability>
```

检查是否为选定的地方提供在线语音识别 .

这是您启用前应该使用的能力检查 `useOnDeviceRecognition`。 。 。 . 在iOS上,结果取决于哪个识别器路径 `start()` 将使用 :

-   何时 `preferLegacyRecognizer` 实值 `false` (默认)在iOS 26+上,此检查现代 `SpeechAnalyzer` 路径.
-   在旧的iOS版本上,或何时 `preferLegacyRecognizer` 实值 `true`,这个检查 `SFSpeechRecognizer.supportsOnDeviceRecognition` 为遗产之路.

传出同样的 `preferLegacyRecognizer` 这里和里面的值 `start()` 因此,可用性 检查匹配的识别路径 .

SDK 平台文件 : iOS: (英语) [发言](https://developer.apple.com/documentation/speech) 机器人: [语音识别器](https://developer.android.com/reference/android/speech/SpeechRecognizer)

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[Pick](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-pick)<[SpeechRecognitionStartOptions](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionstartoptions), 'language' | 'preferLegacyRecognizer'>` |

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

* * *

### 启动(...)

```typescript
start(options?: SpeechRecognitionStartOptions | undefined) => Promise<SpeechRecognitionMatches>
```

开始捕捉音频和转录语音.

何时 `partialResults` 实值 `true`,返回的承诺立即解决,更新是 流经 `partialResults` 直到会话结束.

默认路径保留了后向相容性的遗留识别器行为. 过 `useOnDeviceRecognition: true` 仅在检查后 (原始内容存档于2018-10-29). QQlink Speech Recognition Plugin.is On Device Recognition Available }.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SpeechRecognitionStartOptions](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionstartoptions)` |

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

* * *

### 停止( )

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

停止倾听 并撕毁本土资源.

* * *

### 强制停止(...)

```typescript
forceStop(options?: ForceStopOptions | undefined) => Promise<void>
```

强制停止当前会话 .

在Android上,这首先尝试一个正常的停站,然后倒回到破坏/重建之后 `timeout`。 。 。 . 在iOS上,本会话被立即停止.

如果部分记录稿被缓存,则通过 `partialResults` 监听器 `forced: true`。 。 。 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ForceStopOptions](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-forcestopoptions)` |

* * *

### 获取 LastPartial Result ()

```typescript
getLastPartialResult() => Promise<LastPartialResult>
```

获取上次缓存的部分转录结果 .

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

* * *

### 设置PTT状态(...)

```typescript
setPTTState(options: PTTStateOptions) => Promise<void>
```

更新当前按下按键状态.

一起使用这个 `continuousPTT` 或带有自定义的握住对口流.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PTTStateOptions](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-pttstateoptions)` |

* * *

### 获取支持语言( )

```typescript
getSupportedLanguages() => Promise<SpeechRecognitionLanguages>
```

获得基础识别器支持的地方 .

Android 13+设备不再披露这一清单;在这种情况下 `languages` 为空.

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

* * *

### 正在听( )

```typescript
isListening() => Promise<SpeechRecognitionListening>
```

返回插件是否正在积极监听语音 .

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

* * *

### 检查( )

```typescript
checkPermissions() => Promise<SpeechRecognitionPermissionStatus>
```

获得当前权限状态.

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

* * *

### 请求( )

```typescript
requestPermissions() => Promise<SpeechRecognitionPermissionStatus>
```

请求麦克风+语音识别权限.

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

* * *

### 获取 PluginVersion ()

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

返回与此软件包捆绑的本地插件版本 .

当报告问题时,确认本地版本和联署材料版本相符是有用的.

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

* * *

### 添加倾听器( “ 结束会议 ” ,...)

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

听分会场完成活动(仅限Android).

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'endOfSegmentedSession'` |
| **`listenerFunc`** | `() => void` |

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

* * *

### 添加收听器( 组件Results',...)

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

听取分解识别结果(仅Android).

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'segmentResults'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionSegmentResultEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionsegmentresultevent)) => void` |

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

* * *

### 添加倾听器( “ 部分结果 ” , )

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

听到部分复制更新,同时发布 `partialResults` 已启用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'partialResults'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionPartialResultEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionpartialresultevent)) => void` |

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

* * *

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

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

聆听本地监听状态的变化 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'listeningState'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionListeningEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionlisteningevent)) => void` |

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

* * *

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

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

注意识别错误.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'error'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionErrorEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionerrorevent)) => void` |

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

* * *

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

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

在识别活动时, 请聆听现场麦克风输入级别 .

每秒给药约10至20次,正常 `0..1` 级别. 身份识别闲置时不会发生任何事件 .

仅iOS和Android. Web接受收听者注册,但不会放出事件.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'audioLevel'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionAudioLevelEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionaudiolevelevent)) => void` |

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

* * *

### 添加倾听器( 已准备好下次会议) ,...)

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

听好,确认器准备好再开会.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'readyForNextSession'` |
| **`listenerFunc`** | `(event: [SpeechRecognitionReadyEvent](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionreadyevent)) => void` |

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

* * *

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

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

删除每个已注册的收听者.

* * *

### 接口

#### 语音识别

| Prop | 类型 |
| --- | --- |
| **`available`** | `boolean` |

#### 语音识别开始选项

配置识别器在调用 QQlink Speech Recognition Plugin. start 时的表现 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`language`** | `string` | 本地标识符, 如 `en-US`当省略设备语言时. |  |  |
| **`maxResults`** | `number` | 本地 API 返回的最大最终匹配数 。 默认为 `5`。 。 。 . |  |  |
| **`prompt`** | `string` | 在Android系统对话框(在iOS上被点名)内显示的快速消息. |  |  |
| **`popup`** | `boolean` | 何时 `true`,Android显示OS语音对话框,而不是运行内置识别. 默认为 `false`。 。 。 . |  |  |
| **`partialResults`** | `boolean` | 输入部分文本更新 `partialResults` 音频被捕获时的听众. |  |  |
| **`addPunctuation`** | `boolean` | 启用所支持的本地 puntuation 处理( iOS 16+) . |  |  |
| **`contextualStrings`** | `string[]` | 应被本地语音API更准确识别的词汇或短语. 在iOS上,这些传递给 `SFSpeechRecognitionRequest.contextualStrings` 当插件使用遗产时 `SFSpeechRecognizer` 路径。 该路径是所有iOS版本的默认,倒置于iOS 26下方,通过离开仍然可以在iOS 26+上使用 `useOnDeviceRecognition` 已禁用或设置 `preferLegacyRecognizer` ——因此可以同时使用上下文的字符串和上声识别. 在iOS 26+上,插件使用时 `SpeechAnalyzer` 路径,相同的字符串通过 `AnalysisContext.contextualStrings` 通过 `SpeechAnalyzer.setContext(_:)`被Android忽视了. |  |  |
| **`useOnDeviceRecognition`** | `boolean` | 可用时可进入平台更新的安装设备识别路径. 在iOS 26+上,这个使用苹果公司的 `SpeechAnalyzer` 编号 : `SpeechTranscriber` 输油管。 在近期的Android版本上,它使用在线设备 `SpeechRecognizer` 路径。 除非他们选择推出新行为, 在 iOS 上, 离开此禁用保留 `SFSpeechRecognizer` 每个支持的OS版本。 关于遗产 `SFSpeechRecognizer` 路径,启用此拒绝 `ON_DEVICE_RECOGNITION_UNAVAILABLE` 当不支持本地地址的在线识别时。 在 iOS 26+ 上,启用此功能不包含 `preferLegacyRecognizer` 使用现代 `SpeechAnalyzer` 路径; 否则, 识别会回到具有同样拒绝规则的遗留路径。 使用 QQlink Speech Recognition Plugin.is 在生产中启用前使用 Device recognition Available } 。 SDK平台文件: iOS: [发言](https://developer.apple.com/documentation/speech), (中文(简体) ), [语音分析器](https://developer.apple.com/documentation/speech/speechanalyzer), (中文(简体) ), [语音翻译](https://developer.apple.com/documentation/speech/speechtranscriber) 机器人: [语音识别器](https://developer.android.com/reference/android/speech/SpeechRecognizer) 默认为 `false`。 。 。 . |  |  |
| **`preferLegacyRecognizer`** | `boolean` | 只有 iOS: 跳过现代 `SpeechAnalyzer` 路径,即使有,这样 `useOnDeviceRecognition` 适用于 `SFSpeechRecognizer` (单位:千美元)`requiresOnDeviceRecognition`相反。 在 iOS 26 设备上有用,其中现代路径开始和停止一个会话而不排放 `partialResults`。 。 。 . | `false` | 8.1.11 联合国 |
| **`allowForSilence`** | `number` | 允许在将承认会话分出分会话前保持多毫秒的沉默. 要求大于0,目前仅支持在Android上. |  |  |
| **`continuousPTT`** | `boolean` | 警告: 保持 PTT 会话在静默中保持活性, 在按钮保持时重新启动识别 。 此重启行为被应用于Android内线识别和iOS本土识别. |  |  |
| **`muteRecognizerBeep`** | `boolean` | 当内置识别开始或重启时,会压制Android系统鸣叫. 使用无证识别器意向外加临时通知/系统流积突变的最佳组合。 一些设备忽略了意图外加;音量回落是可移植路径. 默认为 `true` 何时 `continuousPTT` 已启用. |  |  |

#### 语音识别

| Prop | 类型 |
| --- | --- |
| **`matches`** | `string[]` |

#### 强制停止选项

QQlink 语音识别 Plugin. ForceStop} 的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`timeout`** | `number` | 仅Android:以毫秒计超时后再通过破坏/再造来强制停止. 在iOS上,当前会话被立即停止并被忽略这个值. 默认为 `1500`。 。 。 . |

#### 最后一个部分

由QQlink Speech Recognition Plugin.getLastPartial Result}所出 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`available`** | `boolean` | 目前是否缓存部分结果 . |
| **`text`** | `string` | 当地人认识的最新记录文本. |
| **`matches`** | `string[]` | 当前所有可用的选项都匹配 . |

#### PTT 状态选项

QQlink 语音识别 Plugin. setPTT State } 的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`held`** | `boolean` | PTT 按钮目前是否被持有 . |
| **`mute`** | `boolean` | 设定时, 更新Android是否应压制识别器为活动会话启动哔声 。 哔哩哔哩的压制是最佳的,是设备专用的;参见QQlink [语音识别启动选项. mute recognizerBiep](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-speechrecognitionstartoptions)曰. 师曰. |

#### 语音识别语言

| Prop | 类型 |
| --- | --- |
| **`languages`** | `string[]` |

#### 语音识别

| Prop | 类型 |
| --- | --- |
| **`listening`** | `boolean` |

#### 语音识别状态

权限映射返回 `checkPermissions` 财务报告和审定财务报表 `requestPermissions`。 。 。 .

Android上的州地图 `RECORD_AUDIO` 允许. 在iOS上,它结合语音识别和麦克风许可.

| Prop | 类型 |
| --- | --- |
| **`speechRecognition`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-permissionstate)` |

#### 插件听筒

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

#### 语音识别部分

每当产生分化结果(只有Android)时就会提高.

| Prop | 类型 |
| --- | --- |
| **`matches`** | `string[]` |

#### 语音识别

制作部分抄本时提高.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`matches`** | `string[]` | 当本地识别者报告时, 当前的识别匹配 。 对于被强迫或仅被累积的有效载荷,可以省略. |
| **`accumulated`** | `string` | 由早期连续的PTT周期所累积的转录. |
| **`accumulatedText`** | `string` | 最后累积案文,包括目前的结果. |
| **`isRestarting`** | `boolean` | `true` 当插件在连续的 PTT 会话内重新启动识别时. |
| **`forced`** | `boolean` | `true` 当有效载荷由 `forceStop()`。 。 。 . |

#### 语音识别

随听州变起起.

原画 `status` 字段为后向相容性保存并存在 二进制 `started` 编号 : `stopped` 各州.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`state`** | `[ListeningFiniteState](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-listeningfinitestate)` | 承认会议的有限状态. |
| **`sessionId`** | `number` | 当前收听会话的独特标识符 . |
| **`reason`** | `[ListeningReason](https://npmcn.com/package/%40capgo/capacitor-speech-recognition/#readme-listeningreason)` | 为何这一州过渡发生. |
| **`errorCode`** | `string` | 转换因出错而出错代码 . |
| **`status`** | `'started' | 'stopped'` | 后相相相二进制状态被更早的发行所使用. |

#### 语音识别错误事件

当本地识别报告错误时会提高.

| Prop | 类型 |
| --- | --- |
| **`code`** | `string` |
| **`message`** | `string` |
| **`sessionId`** | `number` |

#### 语音识别

在识别活动时使用现场麦克风级别 .

`level` 改为 `0..1` 方便波形/米UI.

只能通过iOS和Android接收. Web接受收听者注册,但不会放出事件.

| Prop | 类型 |
| --- | --- |
| **`level`** | `number` |

#### 语音识别

本地资源被撕毁后发送, 插件已准备好进行另一个会话 .

| Prop | 类型 |
| --- | --- |
| **`sessionId`** | `number` |

### 类型异名

#### 选择

从 T 中选择一组键在 C 中的属性

`{ [P in K]: T[P]; }`

#### 权限状态

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### 监听国家

识别会话生命周期的限定状态值 .

`'startingListening' | 'started' | 'stoppingListening' | 'stopped'`

#### 倾听Reason的声音

为什么发生了监听状态的转变.

`'userStart' | 'userStop' | 'forceStop' | 'results' | 'silence' | 'error' | 'unknown'`

## 常见问题

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

电容插件,用于在有活性部分结果的情况下进行综合在线语音识别\.

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

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

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

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

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

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

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

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

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

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

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

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