cPorcupine - C API

  • Wake Word Engine
  • Offline Voice Commands
  • Local Speech Recognition
  • Always Listening
  • Raspberry Pi
  • ARM
  • iOS
  • Linux
  • macOS
  • Windows
  • C

This document outlines how to use the Porcupine wake word engine within a C/C++ application.


Porcupine is implemented in ANSI C and is shipped as a precompiled library accompanied by corresponding header files. To integrate within a C/C++ application the following items are needed

  • Precompiled library for your target platform (e.g. Ubuntu x86_64 or Raspberry Pi 4)
  • Header files
  • The model file. The standard model is freely available on Porcupine's GitHub repository. Enterprises who are commercially engaged with Picovoice can access compressed and standard models as well.
  • Keyword file(s) for your use case. A set of freely-available keyword files can be found on Porcupine's GitHub repository. Enterprises who are engaged with Picovoice can create custom wake word models using Picovoice Console.


Porcupine is implemented in ANSI C and therefore can be directly linked to C applications. Its public header file contains relevant information. An instance of the Porcupine object can be constructed as follows.

const char *model_file_path = ...
const char *keyword_file_path = ...
const float sensitivity = 0.5f;
pv_porcupine_t *handle;
const pv_status_t status = pv_porcupine_init(
if (status != PV_STATUS_SUCCESS) {
// error handling logic

Sensitivity is the parameter that enables developers to trade miss rate for false alarm. It is a floating-point number within [0, 1]. A higher sensitivity reduces miss rate (false reject rate) at cost of increased false alarm rate.

Now the handle can be used to monitor incoming audio stream. Porcupine accepts single channel, 16-bit PCM audio. The sample rate can be retrieved using pv_sample_rate(). Finally, Porcupine accepts input audio in consecutive chunks (aka frames) the length of each frame can be retrieved using pv_porcupine_frame_length().

extern const int16_t *get_next_audio_frame(void);
while (true) {
const int16_t *pcm = get_next_audio_frame();
int32_t keyword_index;
const pv_status_t status = pv_porcupine_process(handle, pcm, &keyword_index);
if (status != PV_STATUS_SUCCESS) {
// error handling logic
if (keyword_index != -1) {
// detection event logic/callback

Finally, when done be sure to release the acquired resources.


Non-English Wake Words

In order to detect non-English wake words you need to use the corresponding model file. The model files for all supported languages are available here.

Issue with this doc? Please let us know.