@capgo/capacitor-speech-recognition 7.0.0

package/CapgoCapacitorSpeechRecognition.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapgoCapacitorSpeechRecognition'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Capgo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapgoCapacitorSpeechRecognition",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "CapgoCapacitorSpeechRecognition",
+            targets: ["SpeechRecognitionPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+    ],
+    targets: [
+        .target(
+            name: "SpeechRecognitionPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/SpeechRecognitionPlugin"),
+        .testTarget(
+            name: "SpeechRecognitionPluginTests",
+            dependencies: ["SpeechRecognitionPlugin"],
+            path: "ios/Tests/SpeechRecognitionPluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,360 @@
+# @capgo/capacitor-speech-recognition
+ <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin_speech_recognition"> ➡️ Get Instant updates for your App with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin_speech_recognition"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
+</div>
+
+Natural, low-latency speech recognition for Capacitor apps with parity across iOS and Android, streaming partial results, and permission helpers baked in.
+
+## Documentation
+
+The most complete doc is available here: https://capgo.app/docs/plugins/speech-recognition/
+
+## Install
+
+```bash
+npm install @capgo/capacitor-speech-recognition
+npx cap sync
+```
+
+## Usage
+
+```ts
+import { SpeechRecognition } from '@capgo/capacitor-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)
+* [`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>
+
+--------------------
+
+
+### 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.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "app.capgo.speechrecognition"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        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,49 @@
+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;
+    }
+}