@capgo/capacitor-speech-recognition 8.3.3 → 8.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +8 -6
  2. package/dist/docs.json +1 -1
  3. package/dist/esm/definitions.d.ts +5 -1
  4. package/dist/esm/definitions.js.map +1 -1
  5. package/ios/Sources/SpeechRecognitionPlugin/SpeechAnalyzerRecognitionSession.swift +10 -2
  6. package/ios/Sources/SpeechRecognitionPlugin/SpeechRecognitionPlugin.swift +2 -1
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -17,10 +17,10 @@ Turn speech into text in your Capacitor app with low latency, live partial resul
17
17
 
18
18
  ## Key features
19
19
 
20
- - **Live transcription**: `start()` streams `partialResults` while the user speaks, `stop()` and `forceStop()` end it.
21
- - **Languages**: `getSupportedLanguages()` and `isOnDeviceRecognitionAvailable()` for offline recognition.
20
+ - **Live transcription**: with `partialResults: true`, `start()` streams updates while the user speaks. `stop()` and `forceStop()` end the session.
21
+ - **Languages and on-device mode**: `getSupportedLanguages()` lists locales, `isOnDeviceRecognitionAvailable()` checks on-device support and `useOnDeviceRecognition: true` opts in.
22
22
  - **Accuracy options**: punctuation on iOS 16 and later and contextual strings for domain words.
23
- - **Push to talk**: `setPTTState()` keeps a session going while the button is held.
23
+ - **Push to talk**: `setPTTState()` reports whether the button is held, for use with `continuousPTT` or your own hold-to-talk flow.
24
24
  - **Events and permissions**: `listeningState`, `audioLevel` and `error` events, plus microphone and speech permission helpers.
25
25
  - **Platforms**: iOS and Android. iOS uses the Speech framework, Android uses `SpeechRecognizer`. Segmented results are Android only. Not available on web.
26
26
 
@@ -103,8 +103,10 @@ Set `useOnDeviceRecognition: true` only when you want the iOS 26+
103
103
  `SpeechAnalyzer` path and `isOnDeviceRecognitionAvailable()` reports support.
104
104
  If that newer path is unavailable, the plugin falls back to `SFSpeechRecognizer`.
105
105
 
106
- Use `contextualStrings` to bias recognition toward app-specific terms on the
107
- `SFSpeechRecognizer` path:
106
+ Use `contextualStrings` to bias recognition toward app-specific terms. On the
107
+ legacy path they are passed to `SFSpeechRecognizer`; on iOS 26+ with
108
+ `useOnDeviceRecognition`, they are passed through `AnalysisContext` on the
109
+ `SpeechAnalyzer` path:
108
110
 
109
111
  ```ts
110
112
  await SpeechRecognition.start({
@@ -608,7 +610,7 @@ Configure how the recognizer behaves when calling {@link SpeechRecognitionPlugin
608
610
  | **`popup`** | <code>boolean</code> | When `true`, Android shows the OS speech dialog instead of running inline recognition. Defaults to `false`. | | |
609
611
  | **`partialResults`** | <code>boolean</code> | Emits partial transcription updates through the `partialResults` listener while audio is captured. | | |
610
612
  | **`addPunctuation`** | <code>boolean</code> | Enables native punctuation handling where supported (iOS 16+). | | |
611
- | **`contextualStrings`** | <code>string[]</code> | Words or phrases that should be recognized more accurately by native speech APIs. On iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings` when the plugin uses the legacy `SFSpeechRecognizer` path. That path is the default on all iOS versions, the fallback below iOS 26, and still available on iOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting `preferLegacyRecognizer` — so contextual strings and on-device recognition can be used together. Ignored by Android and by the iOS 26+ `SpeechAnalyzer` path. | | |
613
+ | **`contextualStrings`** | <code>string[]</code> | Words or phrases that should be recognized more accurately by native speech APIs. On iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings` when the plugin uses the legacy `SFSpeechRecognizer` path. That path is the default on all iOS versions, the fallback below iOS 26, and still available on iOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting `preferLegacyRecognizer` — so contextual strings and on-device recognition can be used together. On iOS 26+, when the plugin uses the `SpeechAnalyzer` path, the same strings are passed through `AnalysisContext.contextualStrings` via `SpeechAnalyzer.setContext(_:)`. Ignored by Android. | | |
612
614
  | **`useOnDeviceRecognition`** | <code>boolean</code> | 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. On iOS, leaving this disabled keeps `SFSpeechRecognizer` on every supported OS version. On the legacy `SFSpeechRecognizer` path, enabling this rejects with `ON_DEVICE_RECOGNITION_UNAVAILABLE` when on-device recognition is not supported for the locale. On iOS 26+, enabling this without `preferLegacyRecognizer` uses the modern `SpeechAnalyzer` path when available; otherwise recognition falls back to the legacy path with the same rejection rule. 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`. | | |
613
615
  | **`preferLegacyRecognizer`** | <code>boolean</code> | iOS only: skip the modern `SpeechAnalyzer` path even when it is available, so that `useOnDeviceRecognition` applies to `SFSpeechRecognizer` (`requiresOnDeviceRecognition`) instead. Useful on iOS 26 devices where the modern path starts and stops a session without ever emitting `partialResults`. | <code>false</code> | 8.1.11 |
614
616
  | **`allowForSilence`** | <code>number</code> | 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. | | |
package/dist/docs.json CHANGED
@@ -421,7 +421,7 @@
421
421
  {
422
422
  "name": "contextualStrings",
423
423
  "tags": [],
424
- "docs": "Words or phrases that should be recognized more accurately by native speech APIs.\n\nOn iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings`\nwhen the plugin uses the legacy `SFSpeechRecognizer` path. That path is the\ndefault on all iOS versions, the fallback below iOS 26, and still available on\niOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting\n`preferLegacyRecognizer` — so contextual strings and on-device recognition can\nbe used together.\n\nIgnored by Android and by the iOS 26+ `SpeechAnalyzer` path.",
424
+ "docs": "Words or phrases that should be recognized more accurately by native speech APIs.\n\nOn iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings`\nwhen the plugin uses the legacy `SFSpeechRecognizer` path. That path is the\ndefault on all iOS versions, the fallback below iOS 26, and still available on\niOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting\n`preferLegacyRecognizer` — so contextual strings and on-device recognition can\nbe used together.\n\nOn iOS 26+, when the plugin uses the `SpeechAnalyzer` path, the same strings\nare passed through `AnalysisContext.contextualStrings` via\n`SpeechAnalyzer.setContext(_:)`.\n\nIgnored by Android.",
425
425
  "complexTypes": [],
426
426
  "type": "string[] | undefined"
427
427
  },
package/dist/esm/definitions.d.ts CHANGED
@@ -47,7 +47,11 @@ export interface SpeechRecognitionStartOptions {
47
47
  * `preferLegacyRecognizer` — so contextual strings and on-device recognition can
48
48
  * be used together.
49
49
  *
50
- * Ignored by Android and by the iOS 26+ `SpeechAnalyzer` path.
50
+ * On iOS 26+, when the plugin uses the `SpeechAnalyzer` path, the same strings
51
+ * are passed through `AnalysisContext.contextualStrings` via
52
+ * `SpeechAnalyzer.setContext(_:)`.
53
+ *
54
+ * Ignored by Android.
51
55
  */
52
56
  contextualStrings?: string[];
53
57
  /**
package/dist/esm/definitions.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Permission map returned by `checkPermissions` and `requestPermissions`.\n *\n * On Android the state maps to the `RECORD_AUDIO` permission.\n * On iOS it combines speech recognition plus microphone permission.\n */\nexport interface SpeechRecognitionPermissionStatus {\n speechRecognition: PermissionState;\n}\n\n/**\n * Configure how the recognizer behaves when calling {@link SpeechRecognitionPlugin.start}.\n */\nexport interface SpeechRecognitionStartOptions {\n /**\n * Locale identifier such as `en-US`. When omitted the device language is used.\n */\n language?: string;\n /**\n * Maximum number of final matches returned by native APIs. Defaults to `5`.\n */\n maxResults?: number;\n /**\n * Prompt message shown inside the Android system dialog (ignored on iOS).\n */\n prompt?: string;\n /**\n * When `true`, Android shows the OS speech dialog instead of running inline recognition.\n * Defaults to `false`.\n */\n popup?: boolean;\n /**\n * Emits partial transcription updates through the `partialResults` listener while audio is captured.\n */\n partialResults?: boolean;\n /**\n * Enables native punctuation handling where supported (iOS 16+).\n */\n addPunctuation?: boolean;\n /**\n * Words or phrases that should be recognized more accurately by native speech APIs.\n *\n * On iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings`\n * when the plugin uses the legacy `SFSpeechRecognizer` path. That path is the\n * default on all iOS versions, the fallback below iOS 26, and still available on\n * iOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting\n * `preferLegacyRecognizer` — so contextual strings and on-device recognition can\n * be used together.\n *\n * Ignored by Android and by the iOS 26+ `SpeechAnalyzer` path.\n */\n contextualStrings?: string[];\n /**\n * Opt in to the platform's newer on-device recognition path when available.\n *\n * On iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.\n * On recent Android versions, this uses the on-device `SpeechRecognizer` path.\n *\n * It is intentionally opt-in so existing apps keep the legacy flow unless they choose\n * to roll out the new behavior.\n * On iOS, leaving this disabled keeps `SFSpeechRecognizer` on every supported OS version.\n * On the legacy `SFSpeechRecognizer` path, enabling this rejects with\n * `ON_DEVICE_RECOGNITION_UNAVAILABLE` when on-device recognition is not supported for the locale.\n * On iOS 26+, enabling this without `preferLegacyRecognizer` uses the modern `SpeechAnalyzer` path\n * when available; otherwise recognition falls back to the legacy path with the same rejection rule.\n *\n * Use {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.\n *\n * Platform SDK docs:\n * iOS: [Speech](https://developer.apple.com/documentation/speech),\n * [SpeechAnalyzer](https://developer.apple.com/documentation/speech/speechanalyzer),\n * [SpeechTranscriber](https://developer.apple.com/documentation/speech/speechtranscriber)\n * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n *\n * Defaults to `false`.\n */\n useOnDeviceRecognition?: boolean;\n /**\n * iOS only: skip the modern `SpeechAnalyzer` path even when it is available,\n * so that `useOnDeviceRecognition` applies to `SFSpeechRecognizer`\n * (`requiresOnDeviceRecognition`) instead.\n *\n * Useful on iOS 26 devices where the modern path starts and stops a session\n * without ever emitting `partialResults`.\n *\n * @default false\n * @since 8.1.11\n */\n preferLegacyRecognizer?: boolean;\n /**\n * Allow a number of milliseconds of silence before splitting the recognition session into segments.\n * Required to be greater than zero and currently supported on Android only.\n */\n allowForSilence?: number;\n /**\n * EXPERIMENTAL: Keep a PTT session alive across silence by restarting recognition while the button stays held.\n *\n * This restart behavior is implemented for Android inline recognition and iOS native recognition.\n */\n continuousPTT?: boolean;\n /**\n * Suppresses the Android system beep when inline recognition starts or restarts.\n *\n * Uses a best-effort combination of an undocumented recognizer intent extra and\n * temporary notification/system stream volume muting. Some devices ignore the\n * intent extra; the volume fallback is the portable path.\n *\n * Defaults to `true` when `continuousPTT` is enabled.\n */\n muteRecognizerBeep?: boolean;\n}\n\n/**\n * Raised whenever a partial transcription is produced.\n */\nexport interface SpeechRecognitionPartialResultEvent {\n /**\n * Current recognition matches when the native recognizer reports them.\n *\n * This can be omitted for forced or accumulated-only payloads.\n */\n matches?: string[];\n /**\n * Accumulated transcription from earlier continuous PTT cycles.\n */\n accumulated?: string;\n /**\n * Final accumulated text including the current result.\n */\n accumulatedText?: string;\n /**\n * `true` when the plugin is restarting recognition inside a continuous PTT session.\n */\n isRestarting?: boolean;\n /**\n * `true` when the payload was emitted by `forceStop()`.\n */\n forced?: boolean;\n}\n\n/**\n * Raised whenever a segmented result is produced (Android only).\n */\nexport interface SpeechRecognitionSegmentResultEvent {\n matches: string[];\n}\n\n/**\n * Finite state values for the recognition session lifecycle.\n */\nexport type ListeningFiniteState = 'startingListening' | 'started' | 'stoppingListening' | 'stopped';\n\n/**\n * Why a listening state transition happened.\n */\nexport type ListeningReason = 'userStart' | 'userStop' | 'forceStop' | 'results' | 'silence' | 'error' | 'unknown';\n\n/**\n * Raised when the listening state changes.\n *\n * The original `status` field is preserved for backward compatibility and is present\n * on the binary `started` / `stopped` states.\n */\nexport interface SpeechRecognitionListeningEvent {\n /**\n * Finite state of the recognition session.\n */\n state?: ListeningFiniteState;\n /**\n * Unique identifier for the current listening session.\n */\n sessionId?: number;\n /**\n * Why this state transition occurred.\n */\n reason?: ListeningReason;\n /**\n * Error code when the transition is caused by an error.\n */\n errorCode?: string;\n /**\n * Backward-compatible binary state used by earlier releases.\n */\n status?: 'started' | 'stopped';\n}\n\n/**\n * Raised whenever native recognition reports an error.\n */\nexport interface SpeechRecognitionErrorEvent {\n code: string;\n message: string;\n sessionId: number;\n}\n\n/**\n * Live microphone level while recognition is active.\n *\n * `level` is normalized to `0..1` for easy waveform / meter UI.\n *\n * Emitted on iOS and Android only. Web accepts listener registration but does not emit events.\n */\nexport interface SpeechRecognitionAudioLevelEvent {\n level: number;\n}\n\n/**\n * Emitted after native resources have been torn down and the plugin is ready for another session.\n */\nexport interface SpeechRecognitionReadyEvent {\n sessionId: number;\n}\n\nexport interface SpeechRecognitionAvailability {\n available: boolean;\n}\n\nexport interface SpeechRecognitionMatches {\n matches?: string[];\n}\n\nexport interface SpeechRecognitionLanguages {\n languages: string[];\n}\n\nexport interface SpeechRecognitionListening {\n listening: boolean;\n}\n\n/**\n * Options for {@link SpeechRecognitionPlugin.forceStop}.\n */\nexport interface ForceStopOptions {\n /**\n * Android only: timeout in milliseconds before forcing stop via destroy/recreate.\n *\n * On iOS, the current session is stopped immediately and this value is ignored.\n *\n * Defaults to `1500`.\n */\n timeout?: number;\n}\n\n/**\n * Result from {@link SpeechRecognitionPlugin.getLastPartialResult}.\n */\nexport interface LastPartialResult {\n /**\n * Whether a partial result is currently cached.\n */\n available: boolean;\n /**\n * The most recent transcript text known to the native recognizer.\n */\n text: string;\n /**\n * All current match alternatives when available.\n */\n matches?: string[];\n}\n\n/**\n * Options for {@link SpeechRecognitionPlugin.setPTTState}.\n */\nexport interface PTTStateOptions {\n /**\n * Whether the PTT button is currently held.\n */\n held: boolean;\n /**\n * When set, updates whether Android should suppress the recognizer start beep for the active session.\n *\n * Beep suppression is best-effort and device-specific; see {@link SpeechRecognitionStartOptions.muteRecognizerBeep}.\n */\n mute?: boolean;\n}\n\nexport interface SpeechRecognitionPlugin {\n /**\n * Checks whether the native speech recognition service is usable on the current device.\n */\n available(): Promise<SpeechRecognitionAvailability>;\n /**\n * Checks whether on-device speech recognition is available for the selected locale.\n *\n * This is the capability check you should use before enabling `useOnDeviceRecognition`.\n * On iOS, the result depends on which recognizer path `start()` will use:\n *\n * - When `preferLegacyRecognizer` is `false` (default) on iOS 26+, this checks the modern\n * `SpeechAnalyzer` path.\n * - On older iOS versions, or when `preferLegacyRecognizer` is `true`, this checks\n * `SFSpeechRecognizer.supportsOnDeviceRecognition` for the legacy path.\n *\n * Pass the same `preferLegacyRecognizer` value here and in `start()` so the availability\n * check matches the route that recognition will take.\n *\n * Platform SDK docs:\n * iOS: [Speech](https://developer.apple.com/documentation/speech)\n * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n */\n isOnDeviceRecognitionAvailable(\n options?: Pick<SpeechRecognitionStartOptions, 'language' | 'preferLegacyRecognizer'>,\n ): Promise<SpeechRecognitionAvailability>;\n /**\n * Begins capturing audio and transcribing speech.\n *\n * When `partialResults` is `true`, the returned promise resolves immediately and updates are\n * streamed through the `partialResults` listener until the session ends.\n *\n * The default path keeps the legacy recognizer behavior for backward compatibility.\n * Pass `useOnDeviceRecognition: true` only after checking\n * {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable}.\n */\n start(options?: SpeechRecognitionStartOptions): Promise<SpeechRecognitionMatches>;\n /**\n * Stops listening and tears down native resources.\n */\n stop(): Promise<void>;\n /**\n * Force stops the current session.\n *\n * On Android, this first tries a normal stop and then falls back to destroy/recreate after `timeout`.\n * On iOS, the current session is stopped immediately.\n *\n * If a partial transcript is cached, it is emitted through the `partialResults` listener with `forced: true`.\n */\n forceStop(options?: ForceStopOptions): Promise<void>;\n /**\n * Gets the last cached partial transcription result.\n */\n getLastPartialResult(): Promise<LastPartialResult>;\n /**\n * Updates the current push-to-talk button state.\n *\n * Use this together with `continuousPTT` or with a custom hold-to-talk flow.\n */\n setPTTState(options: PTTStateOptions): Promise<void>;\n /**\n * Gets the locales supported by the underlying recognizer.\n *\n * Android 13+ devices no longer expose this list; in that case `languages` is empty.\n */\n getSupportedLanguages(): Promise<SpeechRecognitionLanguages>;\n /**\n * Returns whether the plugin is actively listening for speech.\n */\n isListening(): Promise<SpeechRecognitionListening>;\n /**\n * Gets the current permission state.\n */\n checkPermissions(): Promise<SpeechRecognitionPermissionStatus>;\n /**\n * Requests the microphone + speech recognition permissions.\n */\n requestPermissions(): Promise<SpeechRecognitionPermissionStatus>;\n /**\n * Returns the native plugin version bundled with this package.\n *\n * Useful when reporting issues to confirm that native and JS versions match.\n */\n getPluginVersion(): Promise<{ version: string }>;\n /**\n * Listen for segmented session completion events (Android only).\n */\n addListener(eventName: 'endOfSegmentedSession', listenerFunc: () => void): Promise<PluginListenerHandle>;\n /**\n * Listen for segmented recognition results (Android only).\n */\n addListener(\n eventName: 'segmentResults',\n listenerFunc: (event: SpeechRecognitionSegmentResultEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for partial transcription updates emitted while `partialResults` is enabled.\n */\n addListener(\n eventName: 'partialResults',\n listenerFunc: (event: SpeechRecognitionPartialResultEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for changes to the native listening state.\n */\n addListener(\n eventName: 'listeningState',\n listenerFunc: (event: SpeechRecognitionListeningEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for recognition errors.\n */\n addListener(\n eventName: 'error',\n listenerFunc: (event: SpeechRecognitionErrorEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for live microphone input level while recognition is active.\n *\n * Emits roughly 10–20 times per second with a normalized `0..1` level.\n * No events are emitted when recognition is idle.\n *\n * iOS and Android only. Web accepts listener registration but does not emit events.\n */\n addListener(\n eventName: 'audioLevel',\n listenerFunc: (event: SpeechRecognitionAudioLevelEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for the recognizer becoming ready for another session.\n */\n addListener(\n eventName: 'readyForNextSession',\n listenerFunc: (event: SpeechRecognitionReadyEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Removes every registered listener.\n */\n removeAllListeners(): Promise<void>;\n}\n"]}
1
+ {"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Permission map returned by `checkPermissions` and `requestPermissions`.\n *\n * On Android the state maps to the `RECORD_AUDIO` permission.\n * On iOS it combines speech recognition plus microphone permission.\n */\nexport interface SpeechRecognitionPermissionStatus {\n speechRecognition: PermissionState;\n}\n\n/**\n * Configure how the recognizer behaves when calling {@link SpeechRecognitionPlugin.start}.\n */\nexport interface SpeechRecognitionStartOptions {\n /**\n * Locale identifier such as `en-US`. When omitted the device language is used.\n */\n language?: string;\n /**\n * Maximum number of final matches returned by native APIs. Defaults to `5`.\n */\n maxResults?: number;\n /**\n * Prompt message shown inside the Android system dialog (ignored on iOS).\n */\n prompt?: string;\n /**\n * When `true`, Android shows the OS speech dialog instead of running inline recognition.\n * Defaults to `false`.\n */\n popup?: boolean;\n /**\n * Emits partial transcription updates through the `partialResults` listener while audio is captured.\n */\n partialResults?: boolean;\n /**\n * Enables native punctuation handling where supported (iOS 16+).\n */\n addPunctuation?: boolean;\n /**\n * Words or phrases that should be recognized more accurately by native speech APIs.\n *\n * On iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings`\n * when the plugin uses the legacy `SFSpeechRecognizer` path. That path is the\n * default on all iOS versions, the fallback below iOS 26, and still available on\n * iOS 26+ either by leaving `useOnDeviceRecognition` disabled or by setting\n * `preferLegacyRecognizer` — so contextual strings and on-device recognition can\n * be used together.\n *\n * On iOS 26+, when the plugin uses the `SpeechAnalyzer` path, the same strings\n * are passed through `AnalysisContext.contextualStrings` via\n * `SpeechAnalyzer.setContext(_:)`.\n *\n * Ignored by Android.\n */\n contextualStrings?: string[];\n /**\n * Opt in to the platform's newer on-device recognition path when available.\n *\n * On iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.\n * On recent Android versions, this uses the on-device `SpeechRecognizer` path.\n *\n * It is intentionally opt-in so existing apps keep the legacy flow unless they choose\n * to roll out the new behavior.\n * On iOS, leaving this disabled keeps `SFSpeechRecognizer` on every supported OS version.\n * On the legacy `SFSpeechRecognizer` path, enabling this rejects with\n * `ON_DEVICE_RECOGNITION_UNAVAILABLE` when on-device recognition is not supported for the locale.\n * On iOS 26+, enabling this without `preferLegacyRecognizer` uses the modern `SpeechAnalyzer` path\n * when available; otherwise recognition falls back to the legacy path with the same rejection rule.\n *\n * Use {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.\n *\n * Platform SDK docs:\n * iOS: [Speech](https://developer.apple.com/documentation/speech),\n * [SpeechAnalyzer](https://developer.apple.com/documentation/speech/speechanalyzer),\n * [SpeechTranscriber](https://developer.apple.com/documentation/speech/speechtranscriber)\n * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n *\n * Defaults to `false`.\n */\n useOnDeviceRecognition?: boolean;\n /**\n * iOS only: skip the modern `SpeechAnalyzer` path even when it is available,\n * so that `useOnDeviceRecognition` applies to `SFSpeechRecognizer`\n * (`requiresOnDeviceRecognition`) instead.\n *\n * Useful on iOS 26 devices where the modern path starts and stops a session\n * without ever emitting `partialResults`.\n *\n * @default false\n * @since 8.1.11\n */\n preferLegacyRecognizer?: boolean;\n /**\n * Allow a number of milliseconds of silence before splitting the recognition session into segments.\n * Required to be greater than zero and currently supported on Android only.\n */\n allowForSilence?: number;\n /**\n * EXPERIMENTAL: Keep a PTT session alive across silence by restarting recognition while the button stays held.\n *\n * This restart behavior is implemented for Android inline recognition and iOS native recognition.\n */\n continuousPTT?: boolean;\n /**\n * Suppresses the Android system beep when inline recognition starts or restarts.\n *\n * Uses a best-effort combination of an undocumented recognizer intent extra and\n * temporary notification/system stream volume muting. Some devices ignore the\n * intent extra; the volume fallback is the portable path.\n *\n * Defaults to `true` when `continuousPTT` is enabled.\n */\n muteRecognizerBeep?: boolean;\n}\n\n/**\n * Raised whenever a partial transcription is produced.\n */\nexport interface SpeechRecognitionPartialResultEvent {\n /**\n * Current recognition matches when the native recognizer reports them.\n *\n * This can be omitted for forced or accumulated-only payloads.\n */\n matches?: string[];\n /**\n * Accumulated transcription from earlier continuous PTT cycles.\n */\n accumulated?: string;\n /**\n * Final accumulated text including the current result.\n */\n accumulatedText?: string;\n /**\n * `true` when the plugin is restarting recognition inside a continuous PTT session.\n */\n isRestarting?: boolean;\n /**\n * `true` when the payload was emitted by `forceStop()`.\n */\n forced?: boolean;\n}\n\n/**\n * Raised whenever a segmented result is produced (Android only).\n */\nexport interface SpeechRecognitionSegmentResultEvent {\n matches: string[];\n}\n\n/**\n * Finite state values for the recognition session lifecycle.\n */\nexport type ListeningFiniteState = 'startingListening' | 'started' | 'stoppingListening' | 'stopped';\n\n/**\n * Why a listening state transition happened.\n */\nexport type ListeningReason = 'userStart' | 'userStop' | 'forceStop' | 'results' | 'silence' | 'error' | 'unknown';\n\n/**\n * Raised when the listening state changes.\n *\n * The original `status` field is preserved for backward compatibility and is present\n * on the binary `started` / `stopped` states.\n */\nexport interface SpeechRecognitionListeningEvent {\n /**\n * Finite state of the recognition session.\n */\n state?: ListeningFiniteState;\n /**\n * Unique identifier for the current listening session.\n */\n sessionId?: number;\n /**\n * Why this state transition occurred.\n */\n reason?: ListeningReason;\n /**\n * Error code when the transition is caused by an error.\n */\n errorCode?: string;\n /**\n * Backward-compatible binary state used by earlier releases.\n */\n status?: 'started' | 'stopped';\n}\n\n/**\n * Raised whenever native recognition reports an error.\n */\nexport interface SpeechRecognitionErrorEvent {\n code: string;\n message: string;\n sessionId: number;\n}\n\n/**\n * Live microphone level while recognition is active.\n *\n * `level` is normalized to `0..1` for easy waveform / meter UI.\n *\n * Emitted on iOS and Android only. Web accepts listener registration but does not emit events.\n */\nexport interface SpeechRecognitionAudioLevelEvent {\n level: number;\n}\n\n/**\n * Emitted after native resources have been torn down and the plugin is ready for another session.\n */\nexport interface SpeechRecognitionReadyEvent {\n sessionId: number;\n}\n\nexport interface SpeechRecognitionAvailability {\n available: boolean;\n}\n\nexport interface SpeechRecognitionMatches {\n matches?: string[];\n}\n\nexport interface SpeechRecognitionLanguages {\n languages: string[];\n}\n\nexport interface SpeechRecognitionListening {\n listening: boolean;\n}\n\n/**\n * Options for {@link SpeechRecognitionPlugin.forceStop}.\n */\nexport interface ForceStopOptions {\n /**\n * Android only: timeout in milliseconds before forcing stop via destroy/recreate.\n *\n * On iOS, the current session is stopped immediately and this value is ignored.\n *\n * Defaults to `1500`.\n */\n timeout?: number;\n}\n\n/**\n * Result from {@link SpeechRecognitionPlugin.getLastPartialResult}.\n */\nexport interface LastPartialResult {\n /**\n * Whether a partial result is currently cached.\n */\n available: boolean;\n /**\n * The most recent transcript text known to the native recognizer.\n */\n text: string;\n /**\n * All current match alternatives when available.\n */\n matches?: string[];\n}\n\n/**\n * Options for {@link SpeechRecognitionPlugin.setPTTState}.\n */\nexport interface PTTStateOptions {\n /**\n * Whether the PTT button is currently held.\n */\n held: boolean;\n /**\n * When set, updates whether Android should suppress the recognizer start beep for the active session.\n *\n * Beep suppression is best-effort and device-specific; see {@link SpeechRecognitionStartOptions.muteRecognizerBeep}.\n */\n mute?: boolean;\n}\n\nexport interface SpeechRecognitionPlugin {\n /**\n * Checks whether the native speech recognition service is usable on the current device.\n */\n available(): Promise<SpeechRecognitionAvailability>;\n /**\n * Checks whether on-device speech recognition is available for the selected locale.\n *\n * This is the capability check you should use before enabling `useOnDeviceRecognition`.\n * On iOS, the result depends on which recognizer path `start()` will use:\n *\n * - When `preferLegacyRecognizer` is `false` (default) on iOS 26+, this checks the modern\n * `SpeechAnalyzer` path.\n * - On older iOS versions, or when `preferLegacyRecognizer` is `true`, this checks\n * `SFSpeechRecognizer.supportsOnDeviceRecognition` for the legacy path.\n *\n * Pass the same `preferLegacyRecognizer` value here and in `start()` so the availability\n * check matches the route that recognition will take.\n *\n * Platform SDK docs:\n * iOS: [Speech](https://developer.apple.com/documentation/speech)\n * Android: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n */\n isOnDeviceRecognitionAvailable(\n options?: Pick<SpeechRecognitionStartOptions, 'language' | 'preferLegacyRecognizer'>,\n ): Promise<SpeechRecognitionAvailability>;\n /**\n * Begins capturing audio and transcribing speech.\n *\n * When `partialResults` is `true`, the returned promise resolves immediately and updates are\n * streamed through the `partialResults` listener until the session ends.\n *\n * The default path keeps the legacy recognizer behavior for backward compatibility.\n * Pass `useOnDeviceRecognition: true` only after checking\n * {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable}.\n */\n start(options?: SpeechRecognitionStartOptions): Promise<SpeechRecognitionMatches>;\n /**\n * Stops listening and tears down native resources.\n */\n stop(): Promise<void>;\n /**\n * Force stops the current session.\n *\n * On Android, this first tries a normal stop and then falls back to destroy/recreate after `timeout`.\n * On iOS, the current session is stopped immediately.\n *\n * If a partial transcript is cached, it is emitted through the `partialResults` listener with `forced: true`.\n */\n forceStop(options?: ForceStopOptions): Promise<void>;\n /**\n * Gets the last cached partial transcription result.\n */\n getLastPartialResult(): Promise<LastPartialResult>;\n /**\n * Updates the current push-to-talk button state.\n *\n * Use this together with `continuousPTT` or with a custom hold-to-talk flow.\n */\n setPTTState(options: PTTStateOptions): Promise<void>;\n /**\n * Gets the locales supported by the underlying recognizer.\n *\n * Android 13+ devices no longer expose this list; in that case `languages` is empty.\n */\n getSupportedLanguages(): Promise<SpeechRecognitionLanguages>;\n /**\n * Returns whether the plugin is actively listening for speech.\n */\n isListening(): Promise<SpeechRecognitionListening>;\n /**\n * Gets the current permission state.\n */\n checkPermissions(): Promise<SpeechRecognitionPermissionStatus>;\n /**\n * Requests the microphone + speech recognition permissions.\n */\n requestPermissions(): Promise<SpeechRecognitionPermissionStatus>;\n /**\n * Returns the native plugin version bundled with this package.\n *\n * Useful when reporting issues to confirm that native and JS versions match.\n */\n getPluginVersion(): Promise<{ version: string }>;\n /**\n * Listen for segmented session completion events (Android only).\n */\n addListener(eventName: 'endOfSegmentedSession', listenerFunc: () => void): Promise<PluginListenerHandle>;\n /**\n * Listen for segmented recognition results (Android only).\n */\n addListener(\n eventName: 'segmentResults',\n listenerFunc: (event: SpeechRecognitionSegmentResultEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for partial transcription updates emitted while `partialResults` is enabled.\n */\n addListener(\n eventName: 'partialResults',\n listenerFunc: (event: SpeechRecognitionPartialResultEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for changes to the native listening state.\n */\n addListener(\n eventName: 'listeningState',\n listenerFunc: (event: SpeechRecognitionListeningEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for recognition errors.\n */\n addListener(\n eventName: 'error',\n listenerFunc: (event: SpeechRecognitionErrorEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for live microphone input level while recognition is active.\n *\n * Emits roughly 10–20 times per second with a normalized `0..1` level.\n * No events are emitted when recognition is idle.\n *\n * iOS and Android only. Web accepts listener registration but does not emit events.\n */\n addListener(\n eventName: 'audioLevel',\n listenerFunc: (event: SpeechRecognitionAudioLevelEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Listen for the recognizer becoming ready for another session.\n */\n addListener(\n eventName: 'readyForNextSession',\n listenerFunc: (event: SpeechRecognitionReadyEvent) => void,\n ): Promise<PluginListenerHandle>;\n /**\n * Removes every registered listener.\n */\n removeAllListeners(): Promise<void>;\n}\n"]}
package/ios/Sources/SpeechRecognitionPlugin/SpeechAnalyzerRecognitionSession.swift CHANGED
@@ -59,6 +59,7 @@ final class SpeechAnalyzerRecognitionSession {
59
59
  private let locale: Locale
60
60
  private let maxResults: Int
61
61
  private let includePartialResults: Bool
62
+ private let contextualStrings: [String]
62
63
  private let processingActor = SpeechAnalyzerAudioProcessingActor()
63
64
  private let modelManager = SpeechAnalyzerModelManager()
64
65
 
@@ -84,10 +85,11 @@ final class SpeechAnalyzerRecognitionSession {
84
85
  audioEngine.isRunning || resultTask != nil || isTearingDown
85
86
  }
86
87
 
87
- init(locale: Locale, maxResults: Int, includePartialResults: Bool) {
88
+ init(locale: Locale, maxResults: Int, includePartialResults: Bool, contextualStrings: [String] = []) {
88
89
  self.locale = locale
89
90
  self.maxResults = maxResults
90
91
  self.includePartialResults = includePartialResults
92
+ self.contextualStrings = contextualStrings
91
93
  }
92
94
 
93
95
  func start() async throws {
@@ -122,6 +124,12 @@ final class SpeechAnalyzerRecognitionSession {
122
124
  let analyzer = SpeechAnalyzer(modules: modules)
123
125
  self.analyzer = analyzer
124
126
 
127
+ if !contextualStrings.isEmpty {
128
+ let analysisContext = AnalysisContext()
129
+ analysisContext.contextualStrings[.general] = contextualStrings
130
+ try await analyzer.setContext(analysisContext)
131
+ }
132
+
125
133
  let (inputSequence, inputContinuation) = AsyncStream<AnalyzerInput>.makeStream()
126
134
  analyzerInputContinuation = inputContinuation
127
135
 
@@ -440,7 +448,7 @@ final class SpeechAnalyzerRecognitionSession: NSObject {
440
448
  var onError: ErrorHandler?
441
449
  var onAudioLevel: AudioLevelHandler?
442
450
 
443
- init(locale _: Locale, maxResults _: Int, includePartialResults _: Bool) {}
451
+ init(locale _: Locale, maxResults _: Int, includePartialResults _: Bool, contextualStrings _: [String] = []) {}
444
452
 
445
453
  func start() async throws {
446
454
  throw SpeechAnalyzerRecognitionError.unavailable
package/ios/Sources/SpeechRecognitionPlugin/SpeechRecognitionPlugin.swift CHANGED
@@ -477,7 +477,8 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
477
477
  let session = SpeechAnalyzerRecognitionSession(
478
478
  locale: locale,
479
479
  maxResults: options.maxResults,
480
- includePartialResults: options.partialResults
480
+ includePartialResults: options.partialResults,
481
+ contextualStrings: options.contextualStrings
481
482
  )
482
483
  modernRecognitionSession = session
483
484
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capgo/capacitor-speech-recognition",
3
- "version": "8.3.3",
3
+ "version": "8.4.0",
4
4
  "description": "Capacitor plugin for comprehensive on-device speech recognition with live partial results.",
5
5
  "main": "dist/plugin.cjs.js",
6
6
  "module": "dist/esm/index.js",