快速入门

安装

你可以使用我们的 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-recognition` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-speech-recognition
npx cap sync

导入

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

快速入门

请求麦克风权限，添加一个 partialResults 监听器，然后开启支持流式更新的会话。

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

await SpeechRecognition.requestPermissions();

const partialListener = await SpeechRecognition.addListener('partialResults', ({ matches }) => {
  setTranscript(matches?.[0] ?? '');
});

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

// When leaving the screen:
await SpeechRecognition.stop();
await partialListener.remove();

常见坑点

• 清理: 离开页面时移除监听器。
• 语言区域: 使用与 UI 一致的 BCP 47 标签。
• Web 端: 不支持；如果仅需 Web 端听写，请单独使用浏览器语音 API。

API 概览

available

检查原生语音识别服务在当前设备上是否可用。

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

const result = await SpeechRecognition.available();
console.log(result);

isOnDeviceRecognitionAvailable

检查所选语言区域是否支持平台较新的设备端识别路径。

这是启用前应使用的能力检查 useOnDeviceRecognition。 A true 结果表示当前设备、操作系统版本和语言区域可以使用该平台较新的 设备端识别路径。

返回 false 当设备仅支持旧版识别器路径时。

平台 SDK 文档： iOS: 语音 Android： SpeechRecognizer

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

const result = await SpeechRecognition.isOnDeviceRecognitionAvailable();
console.log(result);

start

开始采集音频并进行语音转写。

当 partialResults 为 true，返回的 Promise 会立即 resolve，随后更新将通过 partialResults 监听器进行流式传输，直到会话结束。

默认路径保留了旧版识别器的行为以确保向后兼容。 请传入 useOnDeviceRecognition: true ，并在检查后执行。

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

const result = await SpeechRecognition.start();
console.log(result);

stop

停止监听并释放原生资源。

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

await SpeechRecognition.stop();

forceStop

强制停止当前会话。

在 Android 上，此操作会先尝试正常停止，随后回退到销毁/重建 timeout. 在 iOS 上，当前会话会立即停止。

如果缓存了部分转写结果，它会通过 partialResults 监听器发出，并带有 forced: true.

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

await SpeechRecognition.forceStop();

getLastPartialResult

获取最近一次缓存的部分转写结果。

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

const result = await SpeechRecognition.getLastPartialResult();
console.log(result);

setPTTState

更新当前的按键通话 (push-to-talk) 按钮状态。

配合使用 continuousPTT 或用于自定义的按住通话流程。

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

await SpeechRecognition.setPTTState({ held: true });

getSupportedLanguages

获取底层识别器支持的语言区域 (locales)。

Android 13+ 设备不再公开此列表；在这种情况下， languages 返回为空。

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

const result = await SpeechRecognition.getSupportedLanguages();
console.log(result);

isListening

返回插件当前是否正在监听语音。

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

const result = await SpeechRecognition.isListening();
console.log(result);

checkPermissions

获取当前的权限状态。

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

const result = await SpeechRecognition.checkPermissions();
console.log(result);

requestPermissions

请求麦克风与语音识别权限。

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

const result = await SpeechRecognition.requestPermissions();
console.log(result);

类型参考

SpeechRecognitionAvailability

export interface SpeechRecognitionAvailability {
  available: boolean;
}

SpeechRecognitionStartOptions

配置识别器在调用 . 时的行为。

export interface SpeechRecognitionStartOptions {
  /**
   * Locale identifier such as `en-US`. When omitted the device language is used.
   */
  language?: string;
  /**
   * Maximum number of final matches returned by native APIs. Defaults to `5`.
   */
  maxResults?: number;
  /**
   * Prompt message shown inside the Android system dialog (ignored on iOS).
   */
  prompt?: string;
  /**
   * When `true`, Android shows the OS speech dialog instead of running inline recognition.
   * Defaults to `false`.
   */
  popup?: boolean;
  /**
   * Emits partial transcription updates through the `partialResults` listener while audio is captured.
   */
  partialResults?: boolean;
  /**
   * Enables native punctuation handling where supported (iOS 16+).
   */
  addPunctuation?: boolean;
  /**
   * Opt in to the platform's newer on-device recognition path when available.
   *
   * On iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.
   * On recent Android versions, this uses the on-device `SpeechRecognizer` path.
   *
   * It is intentionally opt-in so existing apps keep the legacy flow unless they choose
   * to roll out the new behavior.
   *
   * Use {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.
   *
   * Platform SDK docs:
   * iOS: [Speech](https://developer.apple.com/documentation/speech),
   * [SpeechAnalyzer](https://developer.apple.com/documentation/speech/speechanalyzer),
   * [SpeechTranscriber](https://developer.apple.com/documentation/speech/speechtranscriber)
   * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)
   *
   * Defaults to `false`.
   */
  useOnDeviceRecognition?: boolean;
  /**
   * Allow a number of milliseconds of silence before splitting the recognition session into segments.
   * Required to be greater than zero and currently supported on Android only.
   */
  allowForSilence?: number;
  /**
   * EXPERIMENTAL: Keep a PTT session alive across silence by restarting recognition while the button stays held.
   *
   * This restart behavior is implemented for Android inline recognition and iOS native recognition.
   */
  continuousPTT?: boolean;
}

SpeechRecognitionMatches

export interface SpeechRecognitionMatches {
  matches?: string[];
}

ForceStopOptions

用于 . 的选项

export interface ForceStopOptions {
  /**
   * Android only: timeout in milliseconds before forcing stop via destroy/recreate.
   *
   * On iOS, the current session is stopped immediately and this value is ignored.
   *
   * Defaults to `1500`.
   */
  timeout?: number;
}

LastPartialResult

来自 . 的结果

export interface LastPartialResult {
  /**
   * Whether a partial result is currently cached.
   */
  available: boolean;
  /**
   * The most recent transcript text known to the native recognizer.
   */
  text: string;
  /**
   * All current match alternatives when available.
   */
  matches?: string[];
}

PTTStateOptions

用于 . 的选项

export interface PTTStateOptions {
  /**
   * Whether the PTT button is currently held.
   */
  held: boolean;
}

SpeechRecognitionLanguages

export interface SpeechRecognitionLanguages {
  languages: string[];
}

SpeechRecognitionListening

export interface SpeechRecognitionListening {
  listening: boolean;
}

SpeechRecognitionPermissionStatus

由...返回的权限映射 checkPermissions 以及 requestPermissions.

export interface SpeechRecognitionPermissionStatus {
  speechRecognition: PermissionState;
}

SpeechRecognitionSegmentResultEvent

每当产生分段结果时触发（仅限 Android）。

export interface SpeechRecognitionSegmentResultEvent {
  matches: string[];
}

SpeechRecognitionPartialResultEvent

每当产生部分转录结果时触发。

export interface SpeechRecognitionPartialResultEvent {
  /**
   * Current recognition matches when the native recognizer reports them.
   *
   * This can be omitted for forced or accumulated-only payloads.
   */
  matches?: string[];
  /**
   * Accumulated transcription from earlier continuous PTT cycles.
   */
  accumulated?: string;
  /**
   * Final accumulated text including the current result.
   */
  accumulatedText?: string;
  /**
   * `true` when the plugin is restarting recognition inside a continuous PTT session.
   */
  isRestarting?: boolean;
  /**
   * `true` when the payload was emitted by `forceStop()`.
   */
  forced?: boolean;
}

SpeechRecognitionListeningEvent

当监听状态发生变化时触发。

export interface SpeechRecognitionListeningEvent {
  /**
   * Finite state of the recognition session.
   */
  state?: ListeningFiniteState;
  /**
   * Unique identifier for the current listening session.
   */
  sessionId?: number;
  /**
   * Why this state transition occurred.
   */
  reason?: ListeningReason;
  /**
   * Error code when the transition is caused by an error.
   */
  errorCode?: string;
  /**
   * Backward-compatible binary state used by earlier releases.
   */
  status?: 'started' | 'stopped';
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

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