How to Add Wake Word Detection to React Native Apps

As voice technology continues to advance, wake word detection has become a key part of how we interact with devices. Instead of continuously processing all speech, a wake word allows an app or device to "wake up" only when you say a specific phrase, like "Hey AppName". This approach makes interactions feel natural and responsive while conserving device resources and enhancing user privacy.

One of the biggest advances in technology today is on-device processing. Running wake word detection offline makes responses faster, keeps your audio private, and eliminates reliance on an internet connection. This is especially important for mobile devices, where connectivity can be spotty.

For developers, offline wake word detection unlocks exciting possibilities. Users can activate apps, smart devices, or workflows just by speaking a phrase—anywhere, anytime. It ensures voice interactions are reliable, consistent, and secure, no matter where you are.

This guide shows how to add custom, on-device wake word detection to a React Native app with Porcupine Wake Word.

What you'll learn:

• Setting up audio recording permissions for iOS and Android
• Adding custom wake word detection with Porcupine

What you need:

• React Native 0.62.2+
• Android 5.0+ (API 21+)
• iOS 13.0+

Configure Microphone Permissions

Before we begin—integrating wake word detection requires recording audio, which means the user must grant permission. Set up your project to request and handle these permissions:

iOS Permissions

Add the following block to Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>[Permission explanation]</string>

Android Permissions

Add the following block to AndroidManifest.xml:

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

Add Wake Word Detection with Porcupine

1. Install Porcupine React Native Dependencies: To use Porcupine Wake Word in your React Native project, install @picovoice/react-native-voice-processor and @picovoice/porcupine-react-native:

npm install @picovoice/react-native-voice-processor @picovoice/porcupine-react-native

2. Get Your Picovoice Access Key: Sign up for a free Picovoice Console account and obtain your AccessKey. The AccessKey is only required for authentication and authorization.

3. Train Custom Keywords: Create a custom wake word using the Picovoice Console. Be sure to read our guide on choosing a wake word to ensure optimal performance.

4. Add Keyword Files to Your Project: Once you have chosen your keyword, you will need to download two keyword files—one for Android, and one for iOS. The files will have a .ppn extension. In the Android subproject, add the Android keyword file to the assets folder (${ANDROID_APP}/src/main/assets). In the iOS subproject, add the iOS keyword file to the Copy Bundle Resources step. In the following code examples, this file will be referred to as ${KEYWORD_FILE_PATH}.

5. Using Non-English Model Files (Optional): The English model file is built into Porcupine, so if you trained an English keyword, you can skip this step. Otherwise, you will need the corresponding Porcupine model file. Similar to step 4, add this file to the assets folder for Android, and Copy Bundle Resources step for iOS. In the following code examples, this file will be referred to as ${MODEL_FILE_PATH}.

Step-by-Step Code Implementation

First, we'll break down the key components of the Porcupine React Native SDK. At the end is a fully implemented component that you can simply drop into your project for a quick proof of concept.

1. Define a function to handle keyword detection. You can pass in more than one keyword, and the detection callback function will give you the index of the keyword detected. Also define an error handler callback.

// ...
  let detectionCallback = (keywordIndex: number) => {
    if (keywordIndex === 0) {
      // detected `porcupine`
    }
  };
  
  const processErrorCallback = (error) => {
    console.error(`Error during process: ${error}`);
  };

2. Create an instance of PorcupineManager. Be sure to replace the placeholders, and pass in your detectionCallback() and processErrorCallback() functions.

import React, { useRef } from "react";
// import { Platform } from "react-native";
import { PorcupineManager } from '@picovoice/porcupine-react-native';

// ...
  const porcupineManager = useRef(null);

  porcupineManager.current = await PorcupineManager.fromKeywordPaths(
    "${ACCESS_KEY}", // Your Picovoice Console AccessKey
    ["${KEYWORD_FILE_PATH}"], // e.g. `ananas_${Platform.OS}.ppn`
    detectionCallback,
    processErrorCallback,
    "${MODEL_FILE_PATH}" // e.g. "porcupine_params_de.pv" (if non-English keyword)
  );

3. To start listening for wake words, call start().

await porcupineManager.current.start();

4. To stop listening for wake words, call stop().

await porcupineManager.current.stop();

5. Once you no longer need PorcupineManager, be sure to release the resources acquired by calling delete().

await porcupineManager.current.delete();

Complete Code Implementation

Below is a fully implemented component you can copy into your project to see Porcupine in action. Be sure to replace the placeholders ${ACCESS_KEY}, ${KEYWORD_FILE_PATH}, and ${MODEL_FILE_PATH} (if applicable).

import React, { useRef, useState } from "react";
import { Button, Platform, View } from "react-native";
import { PorcupineManager } from '@picovoice/porcupine-react-native';

const ACCESS_KEY = "${ACCESS_KEY}"; // Your Picovoice Console AccessKey
const KEYWORD_FILE_PATH = "${KEYWORD_FILE_PATH}" // e.g. `ananas_${Platform.OS}.ppn`
const MODEL_FILE_PATH = "${MODEL_FILE_PATH}" // e.g. "porcupine_params_de.pv" (if non-English keyword)

enum PorcupineState { Initial, Created, Listening }

export default function Porcupine() {
  const [porcupineState, setPorcupineState] = useState(PorcupineState.Initial);
  const porcupineManager = useRef(null);

  const detectionCallback = (keywordIndex: number) => {
    if (keywordIndex === 0) {
      console.log("Keyword detected")
    }
  };

  const processErrorCallback = (error) => {
    console.error(error);
  };
  
  const ppnCreate = async () => {
    try {
      porcupineManager.current = await PorcupineManager.fromKeywordPaths(
        ACCESS_KEY,
        [KEYWORD_FILE_PATH],
        detectionCallback,
        processErrorCallback,
        MODEL_FILE_PATH, // (if non-English keyword)
      );
      setPorcupineState(PorcupineState.Created);
    } catch (err) {
      console.error(err);
    }
  }

  const ppnStart = async () => {
    try {
      await porcupineManager.current.start();
      setPorcupineState(PorcupineState.Listening);
    } catch (err) {
      console.error(err);
    }
  }

  const ppnStop = async () => {
    try {
      await porcupineManager.current.stop();
      setPorcupineState(PorcupineState.Created);
    } catch (err) {
      console.error(err);
    }
  }

  const ppnDelete = async () => {
    try {
      await porcupineManager.current.delete();
      setPorcupineState(PorcupineState.Initial);
    } catch (err) {
      console.error(err);
    }
  }

  return (
    <View>
      <Button title="Create Porcupine" onPress={ppnCreate} disabled={porcupineState !== PorcupineState.Initial} />
      <Button title="Start Listening" onPress={ppnStart} disabled={porcupineState !== PorcupineState.Created} />
      <Button title="Stop Listening" onPress={ppnStop} disabled={porcupineState !== PorcupineState.Listening} />
      <Button title="Delete Porcupine" onPress={ppnDelete} disabled={porcupineState !== PorcupineState.Created} />
    </View>
  );
}

To see a complete working project, check out Porcupine's React Native demo on GitHub. For more in-depth information, refer to the Porcupine React Native SDK quick start guide.

Next Steps: Adding Voice Commands

You've built wake word detection—now make it truly useful by adding voice commands. Once users say the wake word, they can immediately give instructions, creating a natural, seamless way to interact with your app. By combining the two, you'll deliver a truly hands-free experience that feels effortless and intelligent from the first word to the last.

Frequently Asked Questions