Custom Wake Word Detection for Flutter Apps

🚀 Best-in-class Voice AI!

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

One of Flutter's strengths is the ability to target multiple platforms with a single codebase, but sometimes integrating features that require low-level device capabilities can be tricky.

Wake word detection—recognizing a specific phrase to "wake up" an app—is one such feature. Fortunately, Picovoice's Porcupine Wake Word Detection SDK for Flutter provides an easy, on-device solution. Your Flutter app can respond instantly when a user says a custom wake word, without sending audio to the cloud. The SDK makes it easy to implement cross-platform wake word detection, ensuring both speed and privacy.

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

What you'll learn:

How to set up audio recording permissions for iOS and Android
How to add Porcupine Wake Word to your Flutter app

What you need:

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

Enable Microphone Permissions

This tutorial requires recording audio, so before we begin, you'll need to configure your Flutter project to request audio recording permissions from the user. Make sure the appropriate permissions are enabled for each platform:

iOS

Add the following block to Info.plist:

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

Android

Add the following block to AndroidManifest.xml:

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

Internet is required only for licensing and usage tracking. Audio remains on-device, and is not streamed. Once Porcupine has been initialized, it can run offline.

Add Wake Word Detection with Porcupine

Add Porcupine Flutter Plugins: To use Porcupine Wake Word in your Flutter project, add the flutter_voice_processor and porcupine_flutter plugins to your project's dependencies. Open your project's pubspec.yaml file and add the following:

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

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.
Train Custom Keyword: Create a custom keyword using the Picovoice Console. We've written a guide on choosing a wake word to help you choose a wake word that performs optimally.

If you'd like to see a video walkthrough for this step, check out Picovoice Console Tutorial: Porcupine Wake Word.

Add Keyword Files to Your Project: 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. Place the 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/${KEYWORD_FILE_ANDROID}
    - assets/${KEYWORD_FILE_IOS}
    - assets/${MODEL_FILE} # e.g. assets/porcupine_params_de.pv

Step-by-Step Code Walkthrough

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');
    }
  }

Create an instance of PorcupineManager. Be sure to replace the placeholders, 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)
  );

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

await _porcupineManager?.start();

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

await _porcupineManager?.stop();

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

await _porcupineManager?.delete();

Flutter Wake Word Code Example

Below is a fully implemented widget you can add to your project to see Porcupine in action. Be sure to replace '{ACCESS_KEY}' with your own AccessKey from Picovoice Console, '{KEYWORD_FILE}' with your keyword files, 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 that 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:

Start Building