vosk-speech-recognition-capacitor

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
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