@capgo/capacitor-speech-recognition 8.1.2 → 8.1.4
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.
package/README.md
CHANGED
|
@@ -66,6 +66,24 @@ await SpeechRecognition.stop();
|
|
|
66
66
|
await partialListener.remove();
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
+
### iOS fallback and contextual strings
|
|
70
|
+
|
|
71
|
+
iOS uses `SFSpeechRecognizer` by default, including on versions below iOS 26.
|
|
72
|
+
Set `useOnDeviceRecognition: true` only when you want the iOS 26+
|
|
73
|
+
`SpeechAnalyzer` path and `isOnDeviceRecognitionAvailable()` reports support.
|
|
74
|
+
If that newer path is unavailable, the plugin falls back to `SFSpeechRecognizer`.
|
|
75
|
+
|
|
76
|
+
Use `contextualStrings` to bias recognition toward app-specific terms on the
|
|
77
|
+
`SFSpeechRecognizer` path:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
await SpeechRecognition.start({
|
|
81
|
+
language: 'en-US',
|
|
82
|
+
partialResults: true,
|
|
83
|
+
contextualStrings: ['Capgo', 'Live Update', 'channel override'],
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
69
87
|
## On-device recognition mode
|
|
70
88
|
|
|
71
89
|
This plugin now supports an opt-in on-device recognition path behind the explicit
|
|
@@ -77,6 +95,7 @@ The default path keeps the long-standing recognizer flow for backward compatibil
|
|
|
77
95
|
`useOnDeviceRecognition` switches to a newer local speech pipeline when the platform supports it:
|
|
78
96
|
|
|
79
97
|
- On iOS 26+, it uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` stack.
|
|
98
|
+
- On older iOS versions, unsupported iOS 26+ locales, or when the flag is disabled, it uses `SFSpeechRecognizer`.
|
|
80
99
|
- On recent Android versions, it uses the on-device `SpeechRecognizer` path.
|
|
81
100
|
|
|
82
101
|
### Why you might want it
|
|
@@ -522,17 +541,18 @@ Removes every registered listener.
|
|
|
522
541
|
|
|
523
542
|
Configure how the recognizer behaves when calling {@link SpeechRecognitionPlugin.start}.
|
|
524
543
|
|
|
525
|
-
| Prop | Type
|
|
526
|
-
| ---------------------------- |
|
|
527
|
-
| **`language`** | <code>string</code>
|
|
528
|
-
| **`maxResults`** | <code>number</code>
|
|
529
|
-
| **`prompt`** | <code>string</code>
|
|
530
|
-
| **`popup`** | <code>boolean</code>
|
|
531
|
-
| **`partialResults`** | <code>boolean</code>
|
|
532
|
-
| **`addPunctuation`** | <code>boolean</code>
|
|
533
|
-
| **`
|
|
534
|
-
| **`
|
|
535
|
-
| **`
|
|
544
|
+
| Prop | Type | Description |
|
|
545
|
+
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
546
|
+
| **`language`** | <code>string</code> | Locale identifier such as `en-US`. When omitted the device language is used. |
|
|
547
|
+
| **`maxResults`** | <code>number</code> | Maximum number of final matches returned by native APIs. Defaults to `5`. |
|
|
548
|
+
| **`prompt`** | <code>string</code> | Prompt message shown inside the Android system dialog (ignored on iOS). |
|
|
549
|
+
| **`popup`** | <code>boolean</code> | When `true`, Android shows the OS speech dialog instead of running inline recognition. Defaults to `false`. |
|
|
550
|
+
| **`partialResults`** | <code>boolean</code> | Emits partial transcription updates through the `partialResults` listener while audio is captured. |
|
|
551
|
+
| **`addPunctuation`** | <code>boolean</code> | Enables native punctuation handling where supported (iOS 16+). |
|
|
552
|
+
| **`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+ by leaving `useOnDeviceRecognition` disabled. Ignored by Android and by the iOS 26+ `SpeechAnalyzer` path. |
|
|
553
|
+
| **`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. Enabling it on older iOS versions or unsupported locales falls back to `SFSpeechRecognizer`. 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`. |
|
|
554
|
+
| **`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. |
|
|
555
|
+
| **`continuousPTT`** | <code>boolean</code> | 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. |
|
|
536
556
|
|
|
537
557
|
|
|
538
558
|
#### SpeechRecognitionMatches
|
package/dist/docs.json
CHANGED
|
@@ -394,10 +394,17 @@
|
|
|
394
394
|
"complexTypes": [],
|
|
395
395
|
"type": "boolean | undefined"
|
|
396
396
|
},
|
|
397
|
+
{
|
|
398
|
+
"name": "contextualStrings",
|
|
399
|
+
"tags": [],
|
|
400
|
+
"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\non iOS 26+ by leaving `useOnDeviceRecognition` disabled.\n\nIgnored by Android and by the iOS 26+ `SpeechAnalyzer` path.",
|
|
401
|
+
"complexTypes": [],
|
|
402
|
+
"type": "string[] | undefined"
|
|
403
|
+
},
|
|
397
404
|
{
|
|
398
405
|
"name": "useOnDeviceRecognition",
|
|
399
406
|
"tags": [],
|
|
400
|
-
"docs": "Opt in to the platform's newer on-device recognition path when available.\n\nOn iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.\nOn recent Android versions, this uses the on-device `SpeechRecognizer` path.\n\nIt is intentionally opt-in so existing apps keep the legacy flow unless they choose\nto roll out the new behavior.\n\nUse {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.\n\nPlatform SDK docs:\niOS: [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)\nAndroid: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n\nDefaults to `false`.",
|
|
407
|
+
"docs": "Opt in to the platform's newer on-device recognition path when available.\n\nOn iOS 26+, this uses Apple's `SpeechAnalyzer` / `SpeechTranscriber` pipeline.\nOn recent Android versions, this uses the on-device `SpeechRecognizer` path.\n\nIt is intentionally opt-in so existing apps keep the legacy flow unless they choose\nto roll out the new behavior.\nOn iOS, leaving this disabled keeps `SFSpeechRecognizer` on every supported OS version.\nEnabling it on older iOS versions or unsupported locales falls back to `SFSpeechRecognizer`.\n\nUse {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.\n\nPlatform SDK docs:\niOS: [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)\nAndroid: [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)\n\nDefaults to `false`.",
|
|
401
408
|
"complexTypes": [],
|
|
402
409
|
"type": "boolean | undefined"
|
|
403
410
|
},
|
|
@@ -37,6 +37,17 @@ export interface SpeechRecognitionStartOptions {
|
|
|
37
37
|
* Enables native punctuation handling where supported (iOS 16+).
|
|
38
38
|
*/
|
|
39
39
|
addPunctuation?: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Words or phrases that should be recognized more accurately by native speech APIs.
|
|
42
|
+
*
|
|
43
|
+
* On iOS, these are passed to `SFSpeechRecognitionRequest.contextualStrings`
|
|
44
|
+
* when the plugin uses the legacy `SFSpeechRecognizer` path. That path is the
|
|
45
|
+
* default on all iOS versions, the fallback below iOS 26, and still available
|
|
46
|
+
* on iOS 26+ by leaving `useOnDeviceRecognition` disabled.
|
|
47
|
+
*
|
|
48
|
+
* Ignored by Android and by the iOS 26+ `SpeechAnalyzer` path.
|
|
49
|
+
*/
|
|
50
|
+
contextualStrings?: string[];
|
|
40
51
|
/**
|
|
41
52
|
* Opt in to the platform's newer on-device recognition path when available.
|
|
42
53
|
*
|
|
@@ -45,6 +56,8 @@ export interface SpeechRecognitionStartOptions {
|
|
|
45
56
|
*
|
|
46
57
|
* It is intentionally opt-in so existing apps keep the legacy flow unless they choose
|
|
47
58
|
* to roll out the new behavior.
|
|
59
|
+
* On iOS, leaving this disabled keeps `SFSpeechRecognizer` on every supported OS version.
|
|
60
|
+
* Enabling it on older iOS versions or unsupported locales falls back to `SFSpeechRecognizer`.
|
|
48
61
|
*
|
|
49
62
|
* Use {@link SpeechRecognitionPlugin.isOnDeviceRecognitionAvailable} before enabling it in production.
|
|
50
63
|
*
|
|
@@ -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 * 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 *\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 * 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\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 * 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\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 the platform's newer on-device recognition path is available for the selected locale.\n *\n * This is the capability check you should use before enabling `useOnDeviceRecognition`.\n * A `true` result means the current device, OS version, and locale can use the newer\n * on-device path for that platform.\n *\n * Returns `false` when the device only supports the legacy recognizer path.\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'>,\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 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\n * on iOS 26+ by leaving `useOnDeviceRecognition` disabled.\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 * Enabling it on older iOS versions or unsupported locales falls back to `SFSpeechRecognizer`.\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 * 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\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 * 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\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 the platform's newer on-device recognition path is available for the selected locale.\n *\n * This is the capability check you should use before enabling `useOnDeviceRecognition`.\n * A `true` result means the current device, OS version, and locale can use the newer\n * on-device path for that platform.\n *\n * Returns `false` when the device only supports the legacy recognizer path.\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'>,\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 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"]}
|
|
@@ -19,6 +19,7 @@ private enum ListeningReason: String {
|
|
|
19
19
|
case unknown
|
|
20
20
|
}
|
|
21
21
|
|
|
22
|
+
// swiftlint:disable type_body_length
|
|
22
23
|
@objc(SpeechRecognitionPlugin)
|
|
23
24
|
public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
24
25
|
private let pluginVersion = "8.0.10"
|
|
@@ -90,11 +91,16 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
|
90
91
|
return
|
|
91
92
|
}
|
|
92
93
|
|
|
94
|
+
let contextualStrings = (call.getArray("contextualStrings", String.self) ?? [])
|
|
95
|
+
.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
|
|
96
|
+
.filter { !$0.isEmpty }
|
|
97
|
+
|
|
93
98
|
let options = RecognitionOptions(
|
|
94
99
|
language: call.getString("language") ?? Locale.current.identifier,
|
|
95
100
|
maxResults: call.getInt("maxResults") ?? maxDefaultResults,
|
|
96
101
|
partialResults: call.getBool("partialResults") ?? false,
|
|
97
102
|
addPunctuation: call.getBool("addPunctuation") ?? false,
|
|
103
|
+
contextualStrings: contextualStrings,
|
|
98
104
|
useOnDeviceRecognition: call.getBool("useOnDeviceRecognition") ?? false,
|
|
99
105
|
continuousPTT: call.getBool("continuousPTT") ?? false
|
|
100
106
|
)
|
|
@@ -322,6 +328,9 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
|
322
328
|
|
|
323
329
|
let recognitionRequest = SFSpeechAudioBufferRecognitionRequest()
|
|
324
330
|
recognitionRequest.shouldReportPartialResults = options.partialResults
|
|
331
|
+
if !options.contextualStrings.isEmpty {
|
|
332
|
+
recognitionRequest.contextualStrings = options.contextualStrings
|
|
333
|
+
}
|
|
325
334
|
if #available(iOS 16.0, *) {
|
|
326
335
|
recognitionRequest.addsPunctuation = options.addPunctuation
|
|
327
336
|
}
|
|
@@ -836,12 +845,14 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
|
836
845
|
return .granted
|
|
837
846
|
}
|
|
838
847
|
}
|
|
848
|
+
// swiftlint:enable type_body_length
|
|
839
849
|
|
|
840
850
|
private struct RecognitionOptions {
|
|
841
851
|
let language: String
|
|
842
852
|
let maxResults: Int
|
|
843
853
|
let partialResults: Bool
|
|
844
854
|
let addPunctuation: Bool
|
|
855
|
+
let contextualStrings: [String]
|
|
845
856
|
let useOnDeviceRecognition: Bool
|
|
846
857
|
let continuousPTT: Bool
|
|
847
858
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@capgo/capacitor-speech-recognition",
|
|
3
|
-
"version": "8.1.
|
|
3
|
+
"version": "8.1.4",
|
|
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",
|
|
@@ -48,8 +48,11 @@
|
|
|
48
48
|
"prepare": "npm run build",
|
|
49
49
|
"clean": "rimraf ./dist",
|
|
50
50
|
"watch": "tsc --watch",
|
|
51
|
-
"prepublishOnly": "
|
|
52
|
-
"check:wiring": "node scripts/check-capacitor-plugin-wiring.mjs"
|
|
51
|
+
"prepublishOnly": "bun run build",
|
|
52
|
+
"check:wiring": "node scripts/check-capacitor-plugin-wiring.mjs",
|
|
53
|
+
"example:install": "cd example-app && bun install --frozen-lockfile",
|
|
54
|
+
"example:build": "bun run build && cd example-app && bun install --frozen-lockfile && bun run build",
|
|
55
|
+
"example:capgo:deploy": "bun run example:build && bun scripts/deploy-example-capgo.mjs"
|
|
53
56
|
},
|
|
54
57
|
"devDependencies": {
|
|
55
58
|
"@capacitor/android": "^8.0.0",
|