@capgo/capacitor-speech-recognition 8.2.0 → 8.3.0

package/README.md

@@ -218,6 +218,7 @@ Add the following keys to your app `Info.plist`:
 * [`addListener('partialResults', ...)`](#addlistenerpartialresults-)
 * [`addListener('listeningState', ...)`](#addlistenerlisteningstate-)
 * [`addListener('error', ...)`](#addlistenererror-)
+* [`addListener('audioLevel', ...)`](#addlisteneraudiolevel-)
 * [`addListener('readyForNextSession', ...)`](#addlistenerreadyfornextsession-)
 * [`removeAllListeners()`](#removealllisteners)
 * [Interfaces](#interfaces)
@@ -517,6 +518,29 @@ Listen for recognition errors.
 --------------------
 
 
+### addListener('audioLevel', ...)
+
+```typescript
+addListener(eventName: 'audioLevel', listenerFunc: (event: SpeechRecognitionAudioLevelEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for live microphone input level while recognition is active.
+
+Emits roughly 10–20 times per second with a normalized `0..1` level.
+No events are emitted when recognition is idle.
+
+iOS and Android only. Web accepts listener registration but does not emit events.
+
+| Param              | Type                                                                                                              |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'audioLevel'</code>                                                                                         |
+| **`listenerFunc`** | <code>(event: <a href="#speechrecognitionaudiolevelevent">SpeechRecognitionAudioLevelEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
 ### addListener('readyForNextSession', ...)
 
 ```typescript
@@ -695,6 +719,19 @@ Raised whenever native recognition reports an error.
 | **`sessionId`** | <code>number</code> |
 
 
+#### SpeechRecognitionAudioLevelEvent
+
+Live microphone level while recognition is active.
+
+`level` is normalized to `0..1` for easy waveform / meter UI.
+
+Emitted on iOS and Android only. Web accepts listener registration but does not emit events.
+
+| Prop        | Type                |
+| ----------- | ------------------- |
+| **`level`** | <code>number</code> |
+
+
 #### SpeechRecognitionReadyEvent
 
 Emitted after native resources have been torn down and the plugin is ready for another session.

package/android/src/main/java/app/capgo/speechrecognition/Constants.java

@@ -14,6 +14,7 @@ public interface Constants {
     String PARTIAL_RESULTS_EVENT = "partialResults";
     String ERROR_EVENT = "error";
     String READY_FOR_NEXT_SESSION_EVENT = "readyForNextSession";
+    String AUDIO_LEVEL_EVENT = "audioLevel";
     String RECORD_AUDIO_PERMISSION = Manifest.permission.RECORD_AUDIO;
     String LANGUAGE_ERROR = "Could not get list of languages";
     String EXTRA_DICTATE_BEEP = "android.speech.extra.DICTATE_BEEP";

package/android/src/main/java/app/capgo/speechrecognition/SpeechRecognitionPlugin.java

@@ -9,6 +9,7 @@ import android.os.Build;
 import android.os.Bundle;
 import android.os.Handler;
 import android.os.Looper;
+import android.os.SystemClock;
 import android.speech.ModelDownloadListener;
 import android.speech.RecognitionListener;
 import android.speech.RecognitionSupport;
@@ -46,6 +47,8 @@ public class SpeechRecognitionPlugin extends Plugin implements Constants {
     private static final int FORCE_STOP_TIMEOUT_MS = 1500;
     private static final int STOP_FALLBACK_TIMEOUT_MS = 500;
     private static final int CONTINUOUS_RESTART_DELAY_MS = 100;
+    /** Target audioLevel emit rate (~15 Hz), matching the public docs. */
+    private static final long AUDIO_LEVEL_EMIT_INTERVAL_MS = 67;
 
     private enum ListeningState {
         IDLE,
@@ -60,6 +63,7 @@ public class SpeechRecognitionPlugin extends Plugin implements Constants {
     private final ReentrantLock lock = new ReentrantLock();
     private final Handler handler = new Handler(Looper.getMainLooper());
     private boolean listening = false;
+    private long lastAudioLevelEmitElapsedMs = 0;
     private JSONArray previousPartialResults = new JSONArray();
 
     private Runnable forceStopRunnable;
@@ -346,6 +350,8 @@ public class SpeechRecognitionPlugin extends Plugin implements Constants {
                 try {
                     speechRecognizer.stopListening();
                 } catch (Exception ignored) {}
+                // Stop metering immediately (onRmsChanged gated on listening).
+                listening(false);
             }
 
             forceStopRunnable = () -> {
@@ -1106,7 +1112,22 @@ public class SpeechRecognitionPlugin extends Plugin implements Constants {
         public void onBeginningOfSpeech() {}
 
         @Override
-        public void onRmsChanged(float rmsdB) {}
+        public void onRmsChanged(float rmsdB) {
+            // SpeechRecognizer reports approximate speech energy in dB, typically ~-2..10.
+            // Map that range into the documented audioLevel 0..1 scale.
+            if (isStale() || !listening) {
+                return;
+            }
+            long now = SystemClock.elapsedRealtime();
+            if (now - lastAudioLevelEmitElapsedMs < AUDIO_LEVEL_EMIT_INTERVAL_MS) {
+                return;
+            }
+            lastAudioLevelEmitElapsedMs = now;
+            double level = Math.max(0.0, Math.min(1.0, (rmsdB + 2.0) / 12.0));
+            JSObject payload = new JSObject();
+            payload.put("level", level);
+            notifyListeners(AUDIO_LEVEL_EVENT, payload);
+        }
 
         @Override
         public void onBufferReceived(byte[] buffer) {}

package/dist/docs.json

@@ -291,6 +291,30 @@
         ],
         "slug": "addlistenererror-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'audioLevel', listenerFunc: (event: SpeechRecognitionAudioLevelEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'audioLevel'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(event: SpeechRecognitionAudioLevelEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "Listen for live microphone input level while recognition is active.\n\nEmits roughly 10–20 times per second with a normalized `0..1` level.\nNo events are emitted when recognition is idle.\n\niOS and Android only. Web accepts listener registration but does not emit events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "SpeechRecognitionAudioLevelEvent"
+        ],
+        "slug": "addlisteneraudiolevel-"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'readyForNextSession', listenerFunc: (event: SpeechRecognitionReadyEvent) => void) => Promise<PluginListenerHandle>",
@@ -736,6 +760,22 @@
         }
       ]
     },
+    {
+      "name": "SpeechRecognitionAudioLevelEvent",
+      "slug": "speechrecognitionaudiolevelevent",
+      "docs": "Live microphone level while recognition is active.\n\n`level` is normalized to `0..1` for easy waveform / meter UI.\n\nEmitted on iOS and Android only. Web accepts listener registration but does not emit events.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "level",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
+    },
     {
       "name": "SpeechRecognitionReadyEvent",
       "slug": "speechrecognitionreadyevent",

package/dist/esm/definitions.d.ts

@@ -186,6 +186,16 @@ export interface SpeechRecognitionErrorEvent {
     message: string;
     sessionId: number;
 }
+/**
+ * Live microphone level while recognition is active.
+ *
+ * `level` is normalized to `0..1` for easy waveform / meter UI.
+ *
+ * Emitted on iOS and Android only. Web accepts listener registration but does not emit events.
+ */
+export interface SpeechRecognitionAudioLevelEvent {
+    level: number;
+}
 /**
  * Emitted after native resources have been torn down and the plugin is ready for another session.
  */
@@ -353,6 +363,15 @@ export interface SpeechRecognitionPlugin {
      * Listen for recognition errors.
      */
     addListener(eventName: 'error', listenerFunc: (event: SpeechRecognitionErrorEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for live microphone input level while recognition is active.
+     *
+     * Emits roughly 10–20 times per second with a normalized `0..1` level.
+     * No events are emitted when recognition is idle.
+     *
+     * iOS and Android only. Web accepts listener registration but does not emit events.
+     */
+    addListener(eventName: 'audioLevel', listenerFunc: (event: SpeechRecognitionAudioLevelEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for the recognizer becoming ready for another session.
      */

package/dist/esm/definitions.js.map

@@ -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 * 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 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"]}
+{"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"]}

package/ios/Sources/SpeechRecognitionPlugin/AudioLevelMetering.swift

@@ -0,0 +1,40 @@
+import AVFoundation
+import Foundation
+import QuartzCore
+
+/// Shared RMS→dB→0..1 metering used by both legacy SFSpeechRecognizer and
+/// modern SpeechAnalyzer recognition paths so calibration stays in sync.
+enum AudioLevelMetering {
+    /// Target emit rate (~15 Hz), matching the public audioLevel docs.
+    static let emitInterval: CFTimeInterval = 1.0 / 15.0
+
+    /// Map PCM buffer energy into a normalized 0..1 level.
+    /// Typical speech sits roughly between -50 dBFS and 0 dBFS.
+    static func normalizedAudioLevel(from buffer: AVAudioPCMBuffer) -> Float {
+        guard let channelData = buffer.floatChannelData?[0] else {
+            return 0
+        }
+        let frameLength = Int(buffer.frameLength)
+        guard frameLength > 0 else {
+            return 0
+        }
+
+        var sumSquares: Float = 0
+        for i in 0..<frameLength {
+            let sample = channelData[i]
+            sumSquares += sample * sample
+        }
+        let rms = sqrt(sumSquares / Float(frameLength))
+        let db = 20 * log10(max(rms, 1e-7))
+        return max(0, min(1, (db + 50) / 50))
+    }
+
+    /// Returns true when enough time has elapsed since `lastEmit`, and updates it.
+    static func shouldEmit(now: CFTimeInterval, lastEmit: inout CFTimeInterval) -> Bool {
+        guard now - lastEmit >= emitInterval else {
+            return false
+        }
+        lastEmit = now
+        return true
+    }
+}

package/ios/Sources/SpeechRecognitionPlugin/SpeechAnalyzerRecognitionSession.swift

@@ -52,6 +52,7 @@ final class SpeechAnalyzerRecognitionSession {
     typealias ResultHandler = @MainActor ([String], Bool) -> Void
     typealias VoidHandler = @MainActor () -> Void
     typealias ErrorHandler = @MainActor (Error) -> Void
+    typealias AudioLevelHandler = @MainActor (Float) -> Void
 
     private static let microphoneTapBufferSize: AVAudioFrameCount = 2048
 
@@ -75,6 +76,9 @@ final class SpeechAnalyzerRecognitionSession {
     var onListeningStopped: VoidHandler?
     var onResult: ResultHandler?
     var onError: ErrorHandler?
+    var onAudioLevel: AudioLevelHandler?
+    /// Touched from the audio tap thread for emit throttling; only this session writes it.
+    nonisolated(unsafe) private var lastAudioLevelEmitTime: CFTimeInterval = 0
 
     var isRunning: Bool {
         audioEngine.isRunning || resultTask != nil || isTearingDown
@@ -163,6 +167,7 @@ final class SpeechAnalyzerRecognitionSession {
         isAudioSessionActive = true
     }
 
+
     private func startAudioStreaming() throws {
         let inputNode = audioEngine.inputNode
         let inputFormat = inputNode.outputFormat(forBus: 0)
@@ -177,6 +182,16 @@ final class SpeechAnalyzerRecognitionSession {
                 return
             }
 
+            // Throttle on the tap thread first so we skip RMS/log and MainActor
+            // hops when emitting faster than ~15 Hz.
+            let now = CACurrentMediaTime()
+            if AudioLevelMetering.shouldEmit(now: now, lastEmit: &self.lastAudioLevelEmitTime) {
+                let level = AudioLevelMetering.normalizedAudioLevel(from: bufferCopy)
+                Task { @MainActor [weak self] in
+                    self?.onAudioLevel?(level)
+                }
+            }
+
             let sendableBuffer = SpeechAnalyzerSendablePCMBuffer(buffer: bufferCopy)
             Task {
                 do {
@@ -416,12 +431,14 @@ final class SpeechAnalyzerRecognitionSession: NSObject {
     typealias ResultHandler = @MainActor ([String], Bool) -> Void
     typealias VoidHandler = @MainActor () -> Void
     typealias ErrorHandler = @MainActor (Error) -> Void
+    typealias AudioLevelHandler = @MainActor (Float) -> Void
 
     var isRunning = false
     var onListeningStarted: VoidHandler?
     var onListeningStopped: VoidHandler?
     var onResult: ResultHandler?
     var onError: ErrorHandler?
+    var onAudioLevel: AudioLevelHandler?
 
     init(locale _: Locale, maxResults _: Int, includePartialResults _: Bool) {}
 

package/ios/Sources/SpeechRecognitionPlugin/SpeechRecognitionPlugin.swift

@@ -41,6 +41,7 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
     ]
 
     private let audioEngine = AVAudioEngine()
+    private var lastAudioLevelEmitTime: CFTimeInterval = 0
     private var recognitionRequest: SFSpeechAudioBufferRecognitionRequest?
     private var recognitionTask: SFSpeechRecognitionTask?
     private var speechRecognizer: SFSpeechRecognizer?
@@ -393,6 +394,7 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
         inputNode.removeTap(onBus: 0)
         inputNode.installTap(onBus: 0, bufferSize: 1024, format: recordingFormat) { [weak self] buffer, _ in
             self?.recognitionRequest?.append(buffer)
+            self?.emitAudioLevelIfNeeded(from: buffer, sessionId: sessionId)
         }
         hasInstalledTap = true
 
@@ -479,6 +481,13 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
         )
         modernRecognitionSession = session
 
+        session.onAudioLevel = { [weak self, weak session] level in
+            guard let self, let session, self.modernRecognitionSession === session, self.activeSessionId == sessionId else {
+                return
+            }
+            self.notifyListeners("audioLevel", data: ["level": level])
+        }
+
         session.onListeningStarted = { [weak self, weak session] in
             guard let self, let session, self.modernRecognitionSession === session, self.activeSessionId == sessionId else {
                 return
@@ -656,6 +665,21 @@ public final class SpeechRecognitionPlugin: CAPPlugin, CAPBridgedPlugin {
         finishSessionIfNeeded(sessionId: sessionId, reason: pendingStopReason ?? .error, errorCode: code)
     }
 
+
+    private func emitAudioLevelIfNeeded(from buffer: AVAudioPCMBuffer, sessionId: Int) {
+        let now = CACurrentMediaTime()
+        guard AudioLevelMetering.shouldEmit(now: now, lastEmit: &lastAudioLevelEmitTime) else {
+            return
+        }
+        let level = AudioLevelMetering.normalizedAudioLevel(from: buffer)
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.activeSessionId == sessionId else {
+                return
+            }
+            self.notifyListeners("audioLevel", data: ["level": level])
+        }
+    }
+
     private func buildMatches(from result: SFSpeechRecognitionResult, maxResults: Int) -> [String] {
         var matches: [String] = []
         for transcription in result.transcriptions where matches.count < maxResults {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-speech-recognition",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "Capacitor plugin for comprehensive on-device speech recognition with live partial results.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",