NativeScript Speech Recognition

This is the plugin demo in action..

| ..while recognizing Dutch 🇳🇱 | .. after recognizing American-English 🇺🇸 | | --- | --- | | | |

Installation

From the command prompt go to your app's root folder and execute:

NativeScript 7+:

ns plugin add nativescript-speech-recognition

NativeScript < 7:

tns plugin add [email protected]

Testing

You'll need to test this on a real device as a Simulator/Emulator doesn't have speech recognition capabilities.

API

available

Depending on the OS version a speech engine may not be available.

JavaScript

// require the plugin
var SpeechRecognition = require("nativescript-speech-recognition").SpeechRecognition;

// instantiate the plugin
var speechRecognition = new SpeechRecognition();

speechRecognition.available().then(
  function(available) {
    console.log(available ? "YES!" : "NO");
  }
);

TypeScript

// import the plugin
import { SpeechRecognition } from "nativescript-speech-recognition";

class SomeClass {
  private speechRecognition = new SpeechRecognition();
  
  public checkAvailability(): void {
    this.speechRecognition.available().then(
      (available: boolean) => console.log(available ? "YES!" : "NO"),
      (err: string) => console.log(err)
    );
  }
}

requestPermission

You can either let startListening handle permissions when needed, but if you want to have more control over when the permission popups are shown, you can use this function:

this.speechRecognition.requestPermission().then((granted: boolean) => {
  console.log("Granted? " + granted);
});

startListening

On iOS this will trigger two prompts:

The first prompt requests to allow Apple to analyze the voice input. The user will see a consent screen which you can extend with your own message by adding a fragment like this to app/App_Resources/iOS/Info.plist:

<key>NSSpeechRecognitionUsageDescription</key>
<string>My custom recognition usage description. Overriding the default empty one in the plugin.</string>

The second prompt requests access to the microphone:

<key>NSMicrophoneUsageDescription</key>
<string>My custom microphone usage description. Overriding the default empty one in the plugin.</string>

TypeScript

// import the options
import { SpeechRecognitionTranscription } from "nativescript-speech-recognition";

this.speechRecognition.startListening(
  {
    // optional, uses the device locale by default
    locale: "en-US",
    // set to true to get results back continuously
    returnPartialResults: true,
    // set to true to keep listening after each speech utterance (Android only)
    // when enabled, the recognizer automatically restarts after recognition completes
    listenContinuously: false,
    // this callback will be invoked repeatedly during recognition
    onResult: (transcription: SpeechRecognitionTranscription) => {
      console.log(`User said: ${transcription.text}`);
      console.log(`User finished?: ${transcription.finished}`);
    },
    onError: (error: string | number) => {
      // because of the way iOS and Android differ, this is either:
      // - iOS: A 'string', describing the issue. 
      // - Android: A 'number', referencing an 'ERROR_*' constant from https://developer.android.com/reference/android/speech/SpeechRecognizer.
      //            When listenContinuously is enabled, the recognizer will automatically restart
      //            after errors, providing hands-free continuous voice input.
    }
  }
).then(
  (started: boolean) => { console.log(`started listening`) },
  (errorMessage: string) => { console.log(`Error: ${errorMessage}`); }
).catch((error: string | number) => {
  // same as the 'onError' handler, but this may not return if the error occurs after listening has successfully started (because that resolves the promise,
  // hence the' onError' handler was created.
});

Angular tip

If you're using this plugin in Angular, then note that the onResult callback is not part of Angular's lifecycle. So either update the UI in an ngZone as shown here, or use ChangeDetectorRef as shown here.

stopListening

TypeScript

this.speechRecognition.stopListening().then(
  () => { console.log(`stopped listening`) },
  (errorMessage: string) => { console.log(`Stop error: ${errorMessage}`); }
);

Continuous Listening Mode

Using listenContinuously Option

You can enable continuous listening mode on Android by setting the listenContinuously option to true:

this.speechRecognition.startListening({
  locale: "en-US",
  returnPartialResults: true,
  listenContinuously: true,  // Enable continuous listening
  onResult: (transcription: SpeechRecognitionTranscription) => {
    console.log(`User said: ${transcription.text}`);
    // transcription.finished will be true after each utterance,
    // but listening continues automatically
  },
  onError: (error: string | number) => {
    console.log(`Error: ${error}`);
    // Recognizer will automatically restart after errors
  }
});

When listenContinuously is enabled:

• Automatic restart: After each speech utterance completes, listening automatically restarts
• Continuous operation: The recognizer keeps running until you explicitly call stopListening()
• Error recovery: Automatically restarts after errors (including speech timeout)
• Text accumulation: Recognized text accumulates across multiple utterances
• Hands-free experience: Ideal for voice assistants and applications requiring continuous voice input

To stop continuous listening, call stopListening():

this.speechRecognition.stopListening().then(() => {
  console.log('Stopped continuous listening');
});

Note: This feature is currently available on Android only. iOS support may be added in future versions.

Demo app (Angular)

This plugin is part of the plugin showcase app I built using Angular.

Angular video tutorial

Rather watch a video? Check out this tutorial on YouTube.