capacitor-native-speech-recognition 1.0.1

package/README.md

@@ -0,0 +1,380 @@
+# capacitor-native-speech-recognition
+
+Natural, low-latency speech recognition for Capacitor apps with parity across iOS and Android, streaming partial results, and permission helpers baked in.
+
+## Why this plugin?
+
+This package starts from the excellent [`capacitor-community/speech-recognition`](https://github.com/capacitor-community/speech-recognition) plugin, but folds in the most requested pull requests from that repo (punctuation support, segmented sessions, crash fixes) and keeps them maintained under the Capgo umbrella. You get the familiar API plus:
+
+- ✅ **Merged community PRs** – punctuation toggles on iOS (PR #74), segmented results & silence handling on Android (PR #104), and the `recognitionRequest` safety fix (PR #105) ship out-of-the-box.
+- 🚀 **New Capgo features** – configurable silence windows, streaming segment listeners, consistent permission helpers, and a refreshed example app.
+- 🛠️ **Active maintenance** – same conventions as all Capgo plugins (SPM, Podspec, workflows, example app) so it tracks Capacitor major versions without bit-rot.
+- 📦 **Drop-in migration** – TypeScript definitions remain compatible with the community plugin while exposing the extra options (`addPunctuation`, `allowForSilence`, `segmentResults`, etc.).
+
+## Documentation
+
+This repository is prepared to be published as a new npm package. Update the package name placeholders
+(`capacitor-native-speech-recognition`, `rahmanimorteza/capgo-speech-recognition`) before publishing.
+
+## Install
+
+```bash
+npm install capacitor-native-speech-recognition
+npx cap sync
+```
+
+## Usage
+
+```ts
+import { SpeechRecognition } from 'capacitor-native-speech-recognition';
+
+await SpeechRecognition.requestPermissions();
+
+const { available } = await SpeechRecognition.available();
+if (!available) {
+  console.warn('Speech recognition is not supported on this device.');
+}
+
+const partialListener = await SpeechRecognition.addListener('partialResults', (event) => {
+  console.log('Partial:', event.matches?.[0]);
+});
+
+await SpeechRecognition.start({
+  language: 'en-US',
+  maxResults: 3,
+  partialResults: true,
+});
+
+// Later, when you want to stop listening
+await SpeechRecognition.stop();
+await partialListener.remove();
+```
+
+### iOS usage descriptions
+
+Add the following keys to your app `Info.plist`:
+
+- `NSSpeechRecognitionUsageDescription`
+- `NSMicrophoneUsageDescription`
+
+## API
+
+<docgen-index>
+
+* [`available()`](#available)
+* [`start(...)`](#start)
+* [`stop()`](#stop)
+* [`getSupportedLanguages()`](#getsupportedlanguages)
+* [`isListening()`](#islistening)
+* [`checkPermissions()`](#checkpermissions)
+* [`requestPermissions()`](#requestpermissions)
+* [`getPluginVersion()`](#getpluginversion)
+* [`addListener('endOfSegmentedSession', ...)`](#addlistenerendofsegmentedsession-)
+* [`addListener('segmentResults', ...)`](#addlistenersegmentresults-)
+* [`addListener('partialResults', ...)`](#addlistenerpartialresults-)
+* [`addListener('listeningState', ...)`](#addlistenerlisteningstate-)
+* [`removeAllListeners()`](#removealllisteners)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### available()
+
+```typescript
+available() => Promise<SpeechRecognitionAvailability>
+```
+
+Checks whether the native speech recognition service is usable on the current device.
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionavailability">SpeechRecognitionAvailability</a>&gt;</code>
+
+--------------------
+
+
+### start(...)
+
+```typescript
+start(options?: SpeechRecognitionStartOptions | undefined) => Promise<SpeechRecognitionMatches>
+```
+
+Begins capturing audio and transcribing speech.
+
+When `partialResults` is `true`, the returned promise resolves immediately and updates are
+streamed through the `partialResults` listener until {@link stop} is called.
+
+| Param         | Type                                                                                    |
+| ------------- | --------------------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#speechrecognitionstartoptions">SpeechRecognitionStartOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionmatches">SpeechRecognitionMatches</a>&gt;</code>
+
+--------------------
+
+
+### stop()
+
+```typescript
+stop() => Promise<void>
+```
+
+Stops listening and tears down native resources.
+
+--------------------
+
+
+### getSupportedLanguages()
+
+```typescript
+getSupportedLanguages() => Promise<SpeechRecognitionLanguages>
+```
+
+Gets the locales supported by the underlying recognizer.
+
+Android 13+ devices no longer expose this list; in that case `languages` is empty.
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionlanguages">SpeechRecognitionLanguages</a>&gt;</code>
+
+--------------------
+
+
+### isListening()
+
+```typescript
+isListening() => Promise<SpeechRecognitionListening>
+```
+
+Returns whether the plugin is actively listening for speech.
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionlistening">SpeechRecognitionListening</a>&gt;</code>
+
+--------------------
+
+
+### checkPermissions()
+
+```typescript
+checkPermissions() => Promise<SpeechRecognitionPermissionStatus>
+```
+
+Gets the current permission state.
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionpermissionstatus">SpeechRecognitionPermissionStatus</a>&gt;</code>
+
+--------------------
+
+
+### requestPermissions()
+
+```typescript
+requestPermissions() => Promise<SpeechRecognitionPermissionStatus>
+```
+
+Requests the microphone + speech recognition permissions.
+
+**Returns:** <code>Promise&lt;<a href="#speechrecognitionpermissionstatus">SpeechRecognitionPermissionStatus</a>&gt;</code>
+
+--------------------
+
+
+### getPluginVersion()
+
+```typescript
+getPluginVersion() => Promise<{ version: string; }>
+```
+
+Returns the native plugin version bundled with this package.
+
+Useful when reporting issues to confirm that native and JS versions match.
+
+**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+
+--------------------
+
+
+### addListener('endOfSegmentedSession', ...)
+
+```typescript
+addListener(eventName: 'endOfSegmentedSession', listenerFunc: () => void) => Promise<PluginListenerHandle>
+```
+
+Listen for segmented session completion events (Android only).
+
+| Param              | Type                                 |
+| ------------------ | ------------------------------------ |
+| **`eventName`**    | <code>'endOfSegmentedSession'</code> |
+| **`listenerFunc`** | <code>() =&gt; void</code>           |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('segmentResults', ...)
+
+```typescript
+addListener(eventName: 'segmentResults', listenerFunc: (event: SpeechRecognitionSegmentResultEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for segmented recognition results (Android only).
+
+| Param              | Type                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'segmentResults'</code>                                                                                           |
+| **`listenerFunc`** | <code>(event: <a href="#speechrecognitionsegmentresultevent">SpeechRecognitionSegmentResultEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('partialResults', ...)
+
+```typescript
+addListener(eventName: 'partialResults', listenerFunc: (event: SpeechRecognitionPartialResultEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for partial transcription updates emitted while `partialResults` is enabled.
+
+| Param              | Type                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'partialResults'</code>                                                                                           |
+| **`listenerFunc`** | <code>(event: <a href="#speechrecognitionpartialresultevent">SpeechRecognitionPartialResultEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('listeningState', ...)
+
+```typescript
+addListener(eventName: 'listeningState', listenerFunc: (event: SpeechRecognitionListeningEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for changes to the native listening state.
+
+| Param              | Type                                                                                                            |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'listeningState'</code>                                                                                   |
+| **`listenerFunc`** | <code>(event: <a href="#speechrecognitionlisteningevent">SpeechRecognitionListeningEvent</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Removes every registered listener.
+
+--------------------
+
+
+### Interfaces
+
+
+#### SpeechRecognitionAvailability
+
+| Prop            | Type                 |
+| --------------- | -------------------- |
+| **`available`** | <code>boolean</code> |
+
+
+#### SpeechRecognitionMatches
+
+| Prop          | Type                  |
+| ------------- | --------------------- |
+| **`matches`** | <code>string[]</code> |
+
+
+#### SpeechRecognitionStartOptions
+
+Configure how the recognizer behaves when calling {@link SpeechRecognitionPlugin.start}.
+
+| Prop                  | Type                 | Description                                                                                                                                                                 |
+| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`language`**        | <code>string</code>  | Locale identifier such as `en-US`. When omitted the device language is used.                                                                                                |
+| **`maxResults`**      | <code>number</code>  | Maximum number of final matches returned by native APIs. Defaults to `5`.                                                                                                   |
+| **`prompt`**          | <code>string</code>  | Prompt message shown inside the Android system dialog (ignored on iOS).                                                                                                     |
+| **`popup`**           | <code>boolean</code> | When `true`, Android shows the OS speech dialog instead of running inline recognition. Defaults to `false`.                                                                 |
+| **`partialResults`**  | <code>boolean</code> | Emits partial transcription updates through the `partialResults` listener while audio is captured.                                                                          |
+| **`addPunctuation`**  | <code>boolean</code> | Enables native punctuation handling where supported (iOS 16+).                                                                                                              |
+| **`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. |
+
+
+#### SpeechRecognitionLanguages
+
+| Prop            | Type                  |
+| --------------- | --------------------- |
+| **`languages`** | <code>string[]</code> |
+
+
+#### SpeechRecognitionListening
+
+| Prop            | Type                 |
+| --------------- | -------------------- |
+| **`listening`** | <code>boolean</code> |
+
+
+#### SpeechRecognitionPermissionStatus
+
+Permission map returned by `checkPermissions` and `requestPermissions`.
+
+On Android the state maps to the `RECORD_AUDIO` permission.
+On iOS it combines speech recognition plus microphone permission.
+
+| Prop                    | Type                                                        |
+| ----------------------- | ----------------------------------------------------------- |
+| **`speechRecognition`** | <code><a href="#permissionstate">PermissionState</a></code> |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### SpeechRecognitionSegmentResultEvent
+
+Raised whenever a segmented result is produced (Android only).
+
+| Prop          | Type                  |
+| ------------- | --------------------- |
+| **`matches`** | <code>string[]</code> |
+
+
+#### SpeechRecognitionPartialResultEvent
+
+Raised whenever a partial transcription is produced.
+
+| Prop          | Type                  |
+| ------------- | --------------------- |
+| **`matches`** | <code>string[]</code> |
+
+
+#### SpeechRecognitionListeningEvent
+
+Raised when the listening state changes.
+
+| Prop         | Type                                |
+| ------------ | ----------------------------------- |
+| **`status`** | <code>'started' \| 'stopped'</code> |
+
+
+### Type Aliases
+
+
+#### PermissionState
+
+<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,57 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "app.capgo.speechrecognition"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+</manifest>

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

@@ -0,0 +1,17 @@
+package app.capgo.speechrecognition;
+
+import android.Manifest;
+
+public interface Constants {
+    int REQUEST_CODE_PERMISSION = 2001;
+    int REQUEST_CODE_SPEECH = 2002;
+    int MAX_RESULTS = 5;
+    String NOT_AVAILABLE = "Speech recognition service is not available.";
+    String MISSING_PERMISSION = "Missing permission";
+    String SEGMENT_RESULTS_EVENT = "segmentResults";
+    String END_OF_SEGMENT_EVENT = "endOfSegmentedSession";
+    String LISTENING_EVENT = "listeningState";
+    String PARTIAL_RESULTS_EVENT = "partialResults";
+    String RECORD_AUDIO_PERMISSION = Manifest.permission.RECORD_AUDIO;
+    String LANGUAGE_ERROR = "Could not get list of languages";
+}

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

@@ -0,0 +1,50 @@
+package app.capgo.speechrecognition;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Bundle;
+import android.speech.RecognizerIntent;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.PluginCall;
+import java.util.List;
+
+public class Receiver extends BroadcastReceiver implements Constants {
+
+    private List<String> supportedLanguagesList;
+    private String languagePref;
+    private final PluginCall call;
+
+    public Receiver(PluginCall call) {
+        super();
+        this.call = call;
+    }
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        Bundle extras = getResultExtras(true);
+
+        if (extras.containsKey(RecognizerIntent.EXTRA_LANGUAGE_PREFERENCE)) {
+            languagePref = extras.getString(RecognizerIntent.EXTRA_LANGUAGE_PREFERENCE);
+        }
+
+        if (extras.containsKey(RecognizerIntent.EXTRA_SUPPORTED_LANGUAGES)) {
+            supportedLanguagesList = extras.getStringArrayList(RecognizerIntent.EXTRA_SUPPORTED_LANGUAGES);
+
+            JSArray languagesList = new JSArray(supportedLanguagesList);
+            call.resolve(new JSObject().put("languages", languagesList));
+            return;
+        }
+
+        call.reject(LANGUAGE_ERROR);
+    }
+
+    public List<String> getSupportedLanguages() {
+        return supportedLanguagesList;
+    }
+
+    public String getLanguagePreference() {
+        return languagePref;
+    }
+}