How to Add Wake Word Detection to Flutter: Porcupine Flutter Tutorial

🚀 Best-in-class Voice AI!

Build compliant and low-latency AI applications running entirely on mobile without sharing user data with 3rd parties.

Hands-free voice control is increasingly important for mobile apps, supporting use cases like accessibility features, smart home control, and in-car interactions. Flutter makes it easy to build cross-platform apps, but it doesn't include built-in wake word detection, and most open-source engines weren't designed for mobile performance. Cloud-based wake word detection solutions also have several drawbacks, including added latency, the need for a constant internet connection, and potential privacy issues, making them less suitable for many apps.

On-device wake word detection solves these challenges by running entirely on the user's device, enabling faster, more reliable response times and improved privacy. In this guide, you'll learn how to build a keyword detection application in Flutter using Porcupine Wake Word.

Key Takeaways

Cloud-based wake-word detection can be slow, unreliable, and raises privacy concerns.
Offline engines exist, but most aren't optimized for mobile performance.
Porcupine runs fully on-device, offering fast, accurate, and privacy-friendly wake-word recognition.

How to Add Wake Word Detection in Flutter

Prerequisites

Flutter SDK (2.8.1+)
Android SDK (21+)
JDK (11+)
Xcode (13+)

1. Install Dependencies

Add the flutter_voice_processor and porcupine_flutter plugins to your project's pubspec.yaml:

dependencies:
  flutter_voice_processor: ^{LATEST_VERSION}
  porcupine_flutter: ^{LATEST_VERSION}

2. Train a Custom Keyword Model

Create a Picovoice Console account and train a custom keyword.

Useful guides:

Written guide: Choosing a Wake Word
Video walkthrough: Picovoice Console Tutorial: Porcupine Wake Word

Once you have chosen your keyword, download the keyword files. You will need to download two keyword files—one for Android, and one for iOS. The files will have a .ppn extension.

3. Add Your Keyword File

Place your downloaded keyword files into your project's assets/ folder and add the file path to your pubspec.yaml:

flutter:
  assets:
    - assets/${KEYWORD_FILE_ANDROID} # e.g. assets/bumblebee_android.ppn
    - assets/${KEYWORD_FILE_IOS} # e.g. assets/bumblebee_ios.ppn

Using Non-English Model Files (Optional): If you created a non-English keyword, you will also need to add the corresponding model file for the language you chose. Also place the model file into your project's assets/ folder and add the file path to your pubspec.yaml:

flutter:
  assets:
    # ...
    - assets/${MODEL_FILE} # e.g. assets/porcupine_params_de.pv

4. Configure Microphone Permissions

iOS Setup

In Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Your app needs microphone access for wake word detection.</string>

Android Setup

In AndroidManifest.xml:

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

5. Define Keyword Detection Callback

Define a function to handle keyword detection. You can pass in more than one keyword when initializing Porcupine (see next step), and the detection callback function will give you the index of the keyword detected.

void _detectionCallback(int keywordIndex) {
  if (keywordIndex == 0) {
    print('Keyword detected');
  }
}

6. Initialize Keyword Detection Engine in Flutter

Copy your AccessKey from the Picovoice Console. The AccessKey is only required for authentication and authorization.

Create an instance of PorcupineManager. Replace {ACCESS_KEY} with your Picovoice AccessKey, keywordPath and modelPath with the correct paths, and pass in your _detectionCallback() function.

// import 'dart:io';
import 'package:porcupine_flutter/porcupine_manager.dart';

PorcupineManager? _porcupineManager;

// var platform = (Platform.isAndroid) ? "android" : "ios";
var keywordPath =
    "assets/{KEYWORD_FILE}"; // e.g. "assets/blueberry_$platform.ppn";
_porcupineManager = await PorcupineManager.fromKeywordPaths(
  "{ACCESS_KEY}",
  [keywordPath],
  _detectionCallback,
  modelPath: "assets/{MODEL_FILE}", // (if non-English keyword)
);

7. Start & Stop Keyword Detection

To start listening for wake words:

await _porcupineManager?.start();

To stop listening for wake words:

await _porcupineManager?.stop();

8. Clean Up Resources

Once you no longer need PorcupineManager, release the resources acquired:

await _porcupineManager?.delete();

Flutter Wake Word Complete Code Example

Below is a fully implemented widget you can add to your project to see Porcupine in action. Replace '{ACCESS_KEY}' with your own AccessKey from Picovoice Console, '{KEYWORD_FILE}' with your keyword file, and '{MODEL_FILE}' with your model file (if applicable).

import 'dart:io';

import 'package:flutter/material.dart';
import 'package:porcupine_flutter/porcupine_manager.dart';
import 'package:porcupine_flutter/porcupine_error.dart';

enum AppState { initial, loading, ready, listening }

class PorcupineWidget extends StatefulWidget {
  const PorcupineWidget({super.key});

  @override
  State<PorcupineWidget> createState() => _PorcupineWidgetState();
}

class _PorcupineWidgetState extends State<PorcupineWidget> {
  PorcupineManager? _porcupineManager;
  AppState _appState = AppState.initial;

  // Handle detected keywords
  void _detectionCallback(int keywordIndex) {
    if (keywordIndex == 0) {
      print('Keyword detected');
    }
  }

  void _processErrorCallback(PorcupineException err) {
    print('Porcupine error: ${err.message}');
  }

  // 1. Initialize Porcupine
  Future<void> _init() async {
    setState(() => _appState = AppState.loading);

    if (_porcupineManager == null) {
      try {
        var platform = (Platform.isAndroid) ? "android" : "ios";
        var keywordPath =
            "assets/{KEYWORD_FILE}"; // e.g. "assets/blueberry_$platform.ppn";
        _porcupineManager = await PorcupineManager.fromKeywordPaths(
          "{ACCESS_KEY}",
          [keywordPath],
          _detectionCallback,
          errorCallback: _processErrorCallback,
          // modelPath: "assets/{MODEL_FILE}", // (if non-English keyword)
        );

        setState(() => _appState = AppState.ready);
      } on PorcupineException catch (err) {
        print('Porcupine initialization failed: ${err.message}');
        setState(() => _appState = AppState.initial);
      }
    }
  }

  // 2. Start listening for keywords
  Future<void> _start() async {
    if (_porcupineManager == null) return;
    setState(() => _appState = AppState.loading);

    try {
      await _porcupineManager?.start();
      setState(() => _appState = AppState.listening);
    } on PorcupineException catch (err) {
      print('Error starting voice processor: ${err.message}');
      setState(() => _appState = AppState.ready);
    }
  }

  // 3. Stop listening for keywords
  Future<void> _stop() async {
    setState(() => _appState = AppState.loading);

    try {
      await _porcupineManager?.stop();
      setState(() => _appState = AppState.ready);
    } on PorcupineException catch (err) {
      print('Error stopping voice processor: ${err.message}');
      setState(() => _appState = AppState.listening);
    }
  }

  // 4. Clean up resources
  Future<void> _delete() async {
    setState(() => _appState = AppState.loading);

    await _stop();

    await _porcupineManager?.delete();
    _porcupineManager = null;

    setState(() => _appState = AppState.initial);
  }

  @override
  void dispose() {
    _porcupineManager?.delete();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: _appState == AppState.initial ? _init : null,
          child: const Text('Init'),
        ),
        ElevatedButton(
          onPressed: _appState == AppState.ready ? _start : null,
          child: const Text('Start'),
        ),
        ElevatedButton(
          onPressed: _appState == AppState.listening ? _stop : null,
          child: const Text('Stop'),
        ),
        ElevatedButton(
          onPressed: _appState == AppState.ready ? _delete : null,
          child: const Text('Delete'),
        ),
      ],
    );
  }
}

This is a simplified example but includes all the essential code to get you started. If you'd like to see a complete working app, check out the Porcupine Flutter demo on our GitHub repository.

This tutorial uses the following packages:

You can also explore our documentation for more details:

Next Steps

Now that you have wake word detection set up, combine it with Rhino Speech-to-Intent to handle voice commands immediately after the wake word, enabling a fully hands-free voice experience.

Start Building

Conclusion

With Porcupine and Flutter, you can build offline voice-activated applications that work reliably on both Android and iOS. Whether you're building accessibility tools, hands-free interfaces, or voice-controlled hardware, this guide gives you everything you need to integrate accurate wake-word detection into your app.

Frequently Asked Questions

Can I use multiple wake words at the same time?

Yes, Porcupine supports multiple keywords. You just need to pass an array of keyword paths when initializing PorcupineManager.

Can I use wake word detection offline in Flutter?

Porcupine runs keyword detection entirely on-device. Internet is only required for licensing and usage tracking.

Can I use non-English wake words?

Yes, Porcupine supports multiple languages. You will need the corresponding model file for your chosen language.

What's the best wake word library for Flutter?

The best wake word library for Flutter depends on your app's needs, but porcupine_flutter is a popular choice for its accurate, offline, and privacy-friendly detection, support for custom keywords, and easy Flutter integration.

Does flutter_porcupine work on both iOS and Android?

Yes, Porcupine Flutter supports both platforms, but you need separate keyword files for each.