vosk-speech-recognition-capacitor

Speech recognition module for capacitor.js using Vosk library

Installation

npm install vosk-speech-recognition-capacitor
npx cap sync

Models

Vosk uses prebuilt models to perform speech recognition offline. You have to download the model(s) that you need on Vosk official website Avoid using too heavy models, because the computation time required to load them into your app could lead to bad user experience. Then, unzip the model in your app folder. If you just need to use the iOS version, put the model folder wherever you want, and import it as described below. If you need both iOS and Android to work, you can avoid to copy the model twice for both projects by importing the model from the Android assets folder in XCode.

Experimental: Loading a model dynamically into the app storage, aside from the main bundle is a new and experimental feature. Would love for you all to test, and let us know if it is a viable option. If you choose to download a model to your app’s storage (preferably internal), you can pass the model directory path when calling vosk.loadModel(path).

To download and load a model as part of an app's Main Bundle, just do as follows:

Android

In Android Studio, open the project manager, right-click on your project folder, and go to New > Folder > Assets folder.

Then, put the model folder inside the assets folder created. In your file tree, it should be located in android/app/src/main/assets. So, if you downloaded the French model named model-fr-fr, you should access the model by going to android/app/src/main/assets/model-fr-fr. In Android Studio, your project structure should look like this:

You can import as many models as you want.

Permissions

To use the microphone for speech recognition, you need to request the appropriate permissions in your Android app. Make sure to add the following permissions in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.RECORD_AUDIO"/>

API

Methods

| Method | Argument | Return | Description | |----------|-------------------|----------------|--------------------------------------------------------------------------| | loadModel | options: { modelName: string } | Promise<void> | Loads the voice model for recognition; required before using start(). | | unload | none | Promise<void> | Unloads the model and stops the recognizer. | | start | options?: VoskOptions | Promise<void> | Starts the recognizer; triggers onResult() event. | | stop | none | Promise<void> | Stops the recognizer; listener receives the final result if available. | | pause | none | Promise<void> | Pauses the recognizer. | | resume | none | Promise<void> | Resumes the recognizer. | | addListener | eventName: 'onPartialResults' | 'onFinalResults' | 'onResult', listenerFunc | Promise<PluginListenerHandle> | Adds a listener for specific events. | | removeAllListeners | none | Promise<void> | Removes all listeners for the plugin. |

Event Listeners

| Method | Promise return | Description | |---|---|---| | onPartialResults | The recognized word as a string | Called when partial recognition result is available.| | onResult | The recognized word as a string | Called after silence occured. | | onFinalResults | The recognized word as a string | Called after stream end, like a stop() call |

VoskOptions

interface VoskOptions {
  grammar?: string[];  // Set of phrases the recognizer will seek
  timeout?: number;    // Timeout in milliseconds to listen
}

Example Usage

Here’s how to use the API:

import { Vosk } from 'vosk-speech-recognition-capacitor';

// Create a new Vosk instance
const vosk = new Vosk();

// Load the model
vosk.loadModel({ modelName: 'model-en-us' }).then(() => {
  // Start the recognizer
  vosk.start({
    grammar: ['left', 'right', '[unk]'],
    timeout: 5000,
  }).then(() => {
    console.log('Recognizer started successfully');
    
    // Add listener for results
    vosk.addListener('onResult', (data) => {
      console.log('Recognized result:', data.result);
    });
  });
});

Complete example

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT