How to Implement Cross-Platform Wake Word Detection in C

🎯 Voice AI Consulting

Get dedicated support and consultation to ensure your specific needs are met.

Building reliable wake word detection in C presents unique challenges for developers working on voice-activated applications. Whether you're developing for Linux, Windows, macOS, or Raspberry Pi, your application needs to recognize custom wake words—like "Alexa," "Hey Siri," or your own branded keywords—with minimal latency and maximum reliability.

Many developers initially turn to cloud-based keyword spotting APIs, but these solutions introduce significant drawbacks. Sending audio streams to remote servers introduces network latency, raises privacy concerns with sensitive voice data, and can fail entirely when internet connectivity is unreliable or unavailable. For production voice applications, especially those in IoT devices, embedded systems, or privacy-sensitive environments, on-device wake word detection is essential.

This tutorial demonstrates how to implement cross-platform wake word detection in C using Porcupine Wake Word, a lightweight on-device keyword detection engine. You'll learn how to integrate real-time audio capture, process audio frames efficiently, and trigger custom callbacks when wake words are detected—all without requiring cloud connectivity.

By the end of this tutorial, you'll have a working C application that performs low-latency wake word detection across Linux, Windows, macOS, and Raspberry Pi.

Important: This tutorial builds on the steps in How to Record Audio in C. Follow that tutorial to set up audio capture first if you haven't done so already.

Prerequisites

C99-compatible compiler
Windows: MinGW

Supported Platforms

Linux (x86_64)
macOS (x86_64, arm64)
Windows (x86_64, arm64)
Raspberry Pi (Zero, 3, 4, 5)

Project Setup

The tutorial will use the following directory structure:

project_root/
├── porcupine_tutorial.c
├── pvrecorder/ # See "How to Record Audio in C" for setup instructions
│   ├── libpv_recorder.{so|dylib|dll}
│   └── include/
│       ├── pv_recorder.h
│       └── pv_circular_buffer.h
└── porcupine/
    ├── bumblebee.ppn
    ├── porcupine_params.pv
    ├── libpv_porcupine.{so|dylib|dll}
    └── include/
        ├── pv_porcupine.h
        └── picovoice.h

For instructions on setting up audio capture (with pvrecorder), see: How to Record Audio in C

Step 1: Add Porcupine library files

Create a folder named porcupine/.
Download the Porcupine header files from GitHub and place them in:

porcupine/include/

Download the Porcupine model file for your desired language and place it in:

porcupine/

Dynamic Loading Infrastructure

Porcupine Wake Word ships as a shared library (.so, .dylib, .dll). Instead of linking at compile time, we'll load the library at runtime.

We'll build helpers to:

open a shared library
fetch function pointers
close it gracefully

These helpers remain identical whether you're using PvRecorder, Cheetah Streaming Speech-to-Text, Porcupine Wake Word, Rhino Speech-to-Intent, or other Picovoice engines.

Step 2: Platform-specific headers

#if defined(_WIN32) || defined(_WIN64)
#include <windows.h>
#else
#include <dlfcn.h>
#endif

#include <signal.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>

#include "pv_porcupine.h"
#include "pv_recorder.h"

Explaining the headers

On Windows systems, windows.h provides the LoadLibrary function to load a shared library and GetProcAddress to retrieve individual function pointers.
On Unix-based systems, dlopen and dlsym from the dlfcn.h header provide the same functionality.
Lastly, signal.h allows us to handle Ctrl-C later in this example.

Step 3. Define dynamic loading helper functions

3a. Open the shared library

static void *open_dl(const char *dl_path) {
#if defined(_WIN32) || defined(_WIN64)
    return LoadLibrary(dl_path);
#else
    return dlopen(dl_path, RTLD_NOW);
#endif
}

3b. Load function symbols

static void *load_symbol(void *handle, const char *symbol) {
#if defined(_WIN32) || defined(_WIN64)
    return GetProcAddress((HMODULE) handle, symbol);
#else
    return dlsym(handle, symbol);
#endif
}

3c. Close the library

static void close_dl(void *handle) {
#if defined(_WIN32) || defined(_WIN64)
    FreeLibrary((HMODULE) handle);
#else
    dlclose(handle);
#endif
}

3d. Print platform-correct errors

static void print_dl_error(const char *message) {
#if defined(_WIN32) || defined(_WIN64)
    fprintf(stderr, "%s with code '%lu'.\n", message, GetLastError());
#else
    fprintf(stderr, "%s with `%s`.\n", message, dlerror());
#endif
}

Implement Wake Word Detection

Now that loading infrastructure is in place, it's time to initialize Porcupine Wake Word, start capturing audio, and pass frames into the engine.

Step 4: Load the Porcupine library

Downloaded the correct library file for your OS and point library_path to the file.

const char *library_path = "./porcupine/libpv_porcupine.so"; // adjust per platform
void *porcupine_library = open_dl(library_path);

Step 5. Initialize Porcupine

Sign up for an account on Picovoice Console for free and obtain your AccessKey
Replace ${ACCESS_KEY} with your AccessKey
Download a keyword file and point keyword_path to the file.

You can also train your own custom keyword (like "Hey Jarvis" or "Start Engine") instead of using one of the default keywords.

Call pv_porcupine_init to create a Porcupine instance:

pv_status_t (*pv_porcupine_init_func)(
    const char *,
    const char *,
    int32_t,
    const char *const *,
    const float *,
    pv_porcupine_t **) = load_symbol(porcupine_library, "pv_porcupine_init");

static const char* access_key = "${ACCESS_KEY}"; // replace with your AccessKey
const char *model_path = "./porcupine/porcupine_params.pv"; // replace with your chosen model file
int32_t num_keywords = 1;
const char *const *keyword_paths = "./porcupine/bumblebee.ppn"; // replace with your chosen keyword file
float sensitivity = 0.5f;

pv_porcupine_t *porcupine = NULL;
pv_status_t porcupine_status = pv_porcupine_init_func(
    access_key,
    model_path,
    num_keywords,
    &keyword_paths,
    &sensitivity,
    &porcupine);

Refer to pv_porcupine_init for detailed explanation of parameters.

Step 6: Start keyword detection

Porcupine expects int16 PCM frames of a specific size. Retrieve that size and start listening for the keyword:

pv_status_t (*pv_porcupine_process_func)(
    pv_porcupine_t *,
    const int16_t *,
    int32_t *) = load_symbol(porcupine_library, "pv_porcupine_process");

int32_t (*pv_porcupine_frame_length_func)() = load_symbol(porcupine_library, "pv_porcupine_frame_length");

const int32_t frame_length = pv_porcupine_frame_length_func();
int16_t *frame = malloc(frame_length * sizeof(int16_t));

while (true) {
    recorder_status = pv_recorder_read_func(recorder, frame);

    int32_t keyword_index = -1;
    porcupine_status = pv_porcupine_process_func(porcupine, frame, &keyword_index);
    if (keyword_index != -1) {
        fprintf(stdout, "keyword detected\n");
        fflush(stdout);
    }
}
free(frame);

pv_porcupine_process_func processes a frame of the incoming audio stream and emits the detection result.

Incoming audio needs to have pv_porcupine_frame_length samples per frame. If you are not using PvRecorder for audio streaming, ensure the sample rate is equal to pv_sample_rate, 16-bit linearly-encoded, and single-channel.

Step 7: Cleanup

When done, delete Porcupine to free memory and close the library:

void (*pv_porcupine_delete_func)(pv_porcupine_t *) =
    load_symbol(porcupine_library, "pv_porcupine_delete");

pv_porcupine_delete_func(porcupine);
close_dl(porcupine_library);

Complete Example: On-device Wake Word Detection in C

Here is the complete porcupine_tutorial.c you can copy, build, and run, complete with proper error handling and PvRecorder implementation:

Replace ${ACCESS_KEY} with your AccessKey from Picovoice Console
update model_path to point to the Porcupine model file (.pv)
update library_path to point to the correct Porcupine library for your OS
update keyword_paths: to point to your chosen keyword file (.ppn)
update pv_recorder_library_path to point to the correct PvRecorder library for your OS

#if defined(_WIN32) || defined(_WIN64)
#include <windows.h>
#else
#include <dlfcn.h>
#endif

#include <getopt.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>

#include "pv_porcupine.h"
#include "pv_recorder.h"

static volatile bool is_interrupted = false;

void interrupt_handler(int _) {
    (void) _;
    is_interrupted = true;
}

static void *open_dl(const char *dl_path) {
#if defined(_WIN32) || defined(_WIN64)
    return LoadLibrary(dl_path);
#else
    return dlopen(dl_path, RTLD_NOW);
#endif
}

static void *load_symbol(void *handle, const char *symbol) {
#if defined(_WIN32) || defined(_WIN64)
    return GetProcAddress((HMODULE) handle, symbol);
#else
    return dlsym(handle, symbol);
#endif
}

static void close_dl(void *handle) {
#if defined(_WIN32) || defined(_WIN64)
    FreeLibrary((HMODULE) handle);
#else
    dlclose(handle);
#endif
}

static void print_dl_error(const char *message) {
#if defined(_WIN32) || defined(_WIN64)
    fprintf(stderr, "%s with code '%lu'.\n", message, GetLastError());
#else
    fprintf(stderr, "%s with `%s`.\n", message, dlerror());
#endif
}

int main (void) {
    signal(SIGINT, interrupt_handler);

    // PvRecorder dynamic loading
    const char *pv_recorder_library_path = "./pvrecorder/libpv_recorder.so";
    void *recorder_library = open_dl(pv_recorder_library_path);
    if (!recorder_library) {
        fprintf(stderr, "failed to load dynamic library at `%s`.\n", pv_recorder_library_path);
        exit(1);
    }

    const char *(*pv_recorder_status_to_string_func)(pv_recorder_status_t) =
        load_symbol(recorder_library, "pv_recorder_status_to_string");
    if (!pv_recorder_status_to_string_func) {
        print_dl_error("failed to load `pv_recorder_status_to_string`");
        exit(1);
    }

    pv_recorder_status_t (*pv_recorder_init_func)(const int32_t, const int32_t, const int32_t, pv_recorder_t **) =
        load_symbol(recorder_library, "pv_recorder_init");
    if (!pv_recorder_init_func) {
        print_dl_error("failed to load `pv_recorder_init`");
        exit(1);
    }

    pv_recorder_status_t (*pv_recorder_start_func)(pv_recorder_t *) =
        load_symbol(recorder_library, "pv_recorder_start");
    if (!pv_recorder_start_func) {
        print_dl_error("failed to load `pv_recorder_start`");
        exit(1);
    }

    pv_recorder_status_t (*pv_recorder_read_func)(pv_recorder_t *, int16_t *) =
    load_symbol(recorder_library, "pv_recorder_read");
    if (!pv_recorder_read_func) {
        print_dl_error("failed to load `pv_recorder_read`");
        exit(1);
    }

    pv_recorder_status_t (*pv_recorder_stop_func)(pv_recorder_t *) = load_symbol(recorder_library, "pv_recorder_stop");
    if (!pv_recorder_stop_func) {
        print_dl_error("failed to load `pv_recorder_stop`");
        exit(1);
    }

    void (*pv_recorder_delete_func)(pv_recorder_t *) = load_symbol(recorder_library, "pv_recorder_delete");
    if (!pv_recorder_delete_func) {
        print_dl_error("failed to load `pv_recorder_delete`");
        exit(1);
    }

    // Porcupine dynamic loading
    const char *library_path = "./porcupine/libpv_porcupine.so"; // adjust per platform
    void *porcupine_library = open_dl(library_path);
    if (!porcupine_library) {
        fprintf(stderr, "failed to load dynamic library at `%s`.\n", library_path);
        exit(1);
    }

    const char *(*pv_status_to_string_func)(pv_status_t) = load_symbol(porcupine_library, "pv_status_to_string");
    if (!pv_status_to_string_func) {
        print_dl_error("failed to load `pv_status_to_string`");
        exit(1);
    }

    pv_status_t (*pv_porcupine_init_func)(
        const char *,
        const char *,
        int32_t,
        const char *const *,
        const float *,
        pv_porcupine_t **) = load_symbol(porcupine_library, "pv_porcupine_init");
    if (!pv_porcupine_init_func) {
        print_dl_error("failed to load `pv_porcupine_init`");
        exit(1);
    }

    void (*pv_porcupine_delete_func)(pv_porcupine_t *) = load_symbol(porcupine_library, "pv_porcupine_delete");
    if (!pv_porcupine_delete_func) {
        print_dl_error("failed to load `pv_porcupine_delete`");
        exit(1);
    }

    pv_status_t (*pv_porcupine_process_func)(pv_porcupine_t *, const int16_t *, int32_t *) =
        load_symbol(porcupine_library, "pv_porcupine_process");
    if (!pv_porcupine_process_func) {
        print_dl_error("failed to load `pv_porcupine_process`");
        exit(1);
    }

    int32_t (*pv_porcupine_frame_length_func)() = load_symbol(porcupine_library, "pv_porcupine_frame_length");
    if (!pv_porcupine_frame_length_func) {
        print_dl_error("failed to load `pv_porcupine_frame_length`");
        exit(1);
    }

    static const char* access_key = "${ACCESS_KEY}"; // replace with your AccessKey
    const char *model_path = "./porcupine/porcupine_params.pv"; // replace with your chosen model file
    int32_t num_keywords = 1;
    const char *keyword_paths = "./porcupine/bumblebee_linux.ppn"; // replace with your chosen keyword file
    float sensitivity = 0.5f;

    pv_porcupine_t *porcupine = NULL;
    pv_status_t status = pv_porcupine_init_func(
            access_key,
            model_path,
            num_keywords,
            &keyword_paths,
            &sensitivity,
            &porcupine);
    if (status != PV_STATUS_SUCCESS) {
        fprintf(stderr, "Failed to init with `%s`", pv_status_to_string_func(status));
    }

    const int32_t frame_length = pv_porcupine_frame_length_func();
    const int32_t device_index = -1; // -1 == default device
    const int32_t buffered_frame_count = 100;

    pv_recorder_t *recorder = NULL;
    pv_recorder_status_t recorder_status = pv_recorder_init_func(
            frame_length,
            device_index,
            buffered_frame_count,
            &recorder);
    if (recorder_status != PV_RECORDER_STATUS_SUCCESS) {
        fprintf(stderr, "Failed to initialize device with %s.\n", pv_recorder_status_to_string_func(recorder_status));
        exit(1);
    }

    recorder_status = pv_recorder_start_func(recorder);
    if (recorder_status != PV_RECORDER_STATUS_SUCCESS) {
        fprintf(stderr, "Failed to start device with %s.\n", pv_recorder_status_to_string_func(recorder_status));
        exit(1);
    }

    int16_t *frame = malloc(frame_length * sizeof(int16_t));

    printf("Listening... Press Ctrl+C to stop.\n");
    while (!is_interrupted) {
        pv_recorder_status_t recorder_status = pv_recorder_read_func(recorder, frame);
        if (recorder_status != PV_RECORDER_STATUS_SUCCESS) {
            fprintf(
                    stderr,
                    "Failed to read audio frames with %s.\n",
                    pv_recorder_status_to_string_func(recorder_status));
            exit(1);
        }

        int32_t keyword_index = -1;
        status = pv_porcupine_process_func(porcupine, frame, &keyword_index);
        if (status != PV_STATUS_SUCCESS) {
            fprintf(stderr, "'pv_porcupine_process' failed with '%s'", pv_status_to_string_func(status));
            exit(1);
        }
        if (keyword_index != -1) {
            fprintf(stdout, "keyword detected\n");
            fflush(stdout);
        }
    }
    free(frame);
    fprintf(stdout, "\n");

    recorder_status = pv_recorder_stop_func(recorder);
    if (recorder_status != PV_RECORDER_STATUS_SUCCESS) {
        fprintf(stderr, "Failed to stop device with %s.\n", pv_recorder_status_to_string_func(recorder_status));
        exit(1);
    }

    printf("Stopped.\n");
    pv_recorder_delete_func(recorder);
    pv_porcupine_delete_func(porcupine);
    close_dl(recorder_library);
    close_dl(porcupine_library);
}

This is a simplified example but includes all the necessary components to get started. Check out the Porcupine C demo on GitHub for a complete demo application.

Build & Run

Build and run the application:

Linux (gcc) and Raspberry Pi (gcc)

gcc -std=c99 -O2 -Wall -Wextra -I./pvrecorder/include -I./porcupine/include -o porcupine_tutorial porcupine_tutorial.c -ldl

./porcupine_tutorial

macOS (clang)

clang -std=c99 -O2 -Wall -Wextra -I./pvrecorder/include -I./porcupine/include -o porcupine_tutorial porcupine_tutorial.c

./porcupine_tutorial

Windows (MinGW)

gcc -std=c99 -O2 -Wall -Wextra -I./pvrecorder/include -I./porcupine/include -o porcupine_tutorial.exe porcupine_tutorial.c

./porcupine_tutorial.exe

Troubleshooting Common Issues

1. Wake Word Never Triggers

Verify that your audio is coming from the intended microphone. If you're using PvRecorder for audio capture, validate that it's working properly first.

Tips:

Confirm the microphone is not muted.
Make sure your application is reading audio frames at the exact size returned by pv_porcupine_frame_length.
Check that your sample rate and PCM format match the engine's requirements (pv_sample_rate, single-channel).

2. False Rejections or Missed Detections

If Porcupine rarely detects the keyword or fails in noisy environments, the sensitivity settings may be too low.

Solution:

Increase the sensitivity value (range 0.0–1.0) when initializing the engine. Higher sensitivity leads to more detections in noisy conditions but may slightly increase false alarms.

3. Too Many False Alarms

If wake word detection triggers too often or reacts to background speech, sensitivity may be set too high, or the keyword file may not be appropriate for the target environment.

Solution:

Lower the sensitivity during pv_porcupine_init.
Train a custom keyword designed for your specific wake phrase.

4. Porcupine Fails to Initialize

Initialization errors usually indicate mismatched files or platform issues. Common causes include using the wrong library, model, or keyword file for your system.

Solution:

Download the correct binaries for your OS and architecture from the Porcupine repository.
Match the keyword file (.ppn) and model file (.pv) to the same language.
Ensure the keyword file and shared library (.so, .dylib, .dll) are compatible with your target platform.

Example (English "bumblebee" keyword on Linux x86_64):

Keyword file: bumblebee_linux.ppn
Model file: porcupine_params.pv
Library file: libpv_porcupine.so

Start Building

Frequently Asked Questions

Can I run multiple wake words at once?

Yes. Porcupine supports multiple keywords simultaneously. Pass additional keyword file paths when initializing the engine and set a sensitivity value for each one.

What frame size should I read from the microphone?

Use the exact number returned by pv_porcupine_frame_length. Porcupine requires fixed-size frames, and incorrect sizes will stop detection from working.

Can I create my own custom wake word?

Absolutely. Use Picovoice Console to train personalized keywords such as "Hey Robot" or "Lights On" and then download the generated .ppn file.

How to Implement Cross-Platform Wake Word Detection in C

Prerequisites

Supported Platforms

Project Setup

Step 1: Add Porcupine library files

Dynamic Loading Infrastructure

Step 2: Platform-specific headers

Explaining the headers

Step 3. Define dynamic loading helper functions

3a. Open the shared library

3b. Load function symbols

3c. Close the library

3d. Print platform-correct errors

Implement Wake Word Detection

Step 4: Load the Porcupine library

Step 5. Initialize Porcupine

Step 6: Start keyword detection

Step 7: Cleanup

Complete Example: On-device Wake Word Detection in C

Build & Run

Linux (gcc) and Raspberry Pi (gcc)

macOS (clang)

Windows (MinGW)

Troubleshooting Common Issues

1. Wake Word Never Triggers

2. False Rejections or Missed Detections

3. Too Many False Alarms

4. Porcupine Fails to Initialize

Frequently Asked Questions

More from Picovoice