mcuPorcupine Wake Word Engine - Microcontroller API

This document outlines how to use the Porcupine wake word engine on a microcontroller.


pv_porcupine_t

typedef struct pv_porcupine pv_porcupine_t;

Container representing the Porcupine wake word engine.


pv_porcupine_init()

pv_status_t pv_porcupine_init(
const char *access_key,
int32_t memory_size,
void *memory_buffer,
int32_t num_keywords,
const int32_t *keyword_model_sizes,
const void *const *keyword_models,
const float *sensitivities,
pv_porcupine_t **object
);

Create a Porcupine instance. Resources should be cleaned when you are done using the pv_porcupine_delete() function.

Parameters

  • access_key char * : AccessKey obtained from Picovoice Console (https://console.picovoice.ai/).
  • memory_size int32_t : Memory size in bytes. The optimal size for given keyword models can be computed using pv_porcupine_get_min_memory_buffer_size()
  • memory_buffer void * : Memory; needs to be 8-byte aligned.
  • num_keywords int32_t : Number of keywords to monitor.
  • keyword_model_size int32_t * : Size of each keyword model in bytes.
  • keyword_model void * * : Keyword models.
  • sensitivities float * : Sensitivities for detecting keywords. Each value should be a number within [0, 1]. A higher sensitivity results in fewer misses at the cost of increasing the false alarm rate.
  • object pv_porcupine_t * * : Constructed instance of Porcupine.

Returns


pv_porcupine_get_min_memory_buffer_size()

pv_status_t pv_porcupine_get_min_memory_buffer_size(
int32_t preliminary_memory_size,
void *preliminary_memory_buffer,
int32_t num_keywords,
const int32_t *keyword_model_sizes,
const void *const *keyword_models,
int32_t *min_memory_buffer_size
);

Computes the minimum required memory buffer size, in bytes, for the given keyword model. A relatively large value for ' preliminary_memory_buffer' is suggested (e.g., 30 kilobytes). Then, 'pv_porcupine_init' can be called optimally passing a memory buffer with the size of 'min_memory_buffer_size'.

Parameters

  • preliminary_memory_size int32_t : Memory size in bytes.
  • preliminary_memory_buffer void * : Memory; needs to be 8-byte aligned.
  • num_keywords int32_t : Number of keywords to monitor.
  • keyword_model_size int32_t * : Size of each keyword model in bytes.
  • keyword_model void * * : Keyword models.
  • min_memory_buffer_size int32_t * : minimum required memory buffer size in bytes.

Returns


pv_porcupine_delete()

void pv_porcupine_delete(pv_porcupine_t *object);

Releases resources acquired by Porcupine.

Parameters


pv_porcupine_process()

pv_status_t pv_porcupine_process(pv_porcupine_t *object, const int16_t *pcm, int32_t *keyword_index);

Processes a frame of the incoming audio stream and emits the detection result. The number of samples per frame can be attained by calling pv_porcupine_frame_length(). The incoming audio needs to have a sample rate equal to pv_sample_rate() and be 16-bit linearly-encoded. Porcupine operates on single-channel audio.

Parameters

  • object pv_porcupine_t * : Porcupine object.
  • pcm int16_t : A frame of audio samples.
  • keyword_index int32_t * : Index of observed keyword at the end of the current frame. Indexing is 0-based and matches the ordering of keyword models provided to 'pv_porcupine_init()'. If no keyword is detected then it is set to -1.

Returns


pv_porcupine_version()

const char *pv_porcupine_version(void);

Getter for version.

Returns

  • char * : Porcupine version.

pv_porcupine_frame_length()

int32_t pv_picovoice_frame_length(void);

Getter for number of audio samples per frame.

Returns

  • int32_t : Frame length.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Picovoice.

Returns

  • int32_t : Sample rate.

pv_status_t

typedef enum {
PV_STATUS_SUCCESS = 0,
PV_STATUS_OUT_OF_MEMORY,
PV_STATUS_IO_ERROR,
PV_STATUS_INVALID_ARGUMENT,
PV_STATUS_STOP_ITERATION,
PV_STATUS_KEY_ERROR,
PV_STATUS_INVALID_STATE,
PV_STATUS_RUNTIME_ERROR,
PV_STATUS_ACTIVATION_ERROR,
PV_STATUS_ACTIVATION_LIMIT_REACHED,
PV_STATUS_ACTIVATION_THROTTLED,
PV_STATUS_ACTIVATION_REFUSED
} pv_status_t;

Status code enum.


pv_status_to_string()

const char *pv_status_to_string(pv_status_t status);

Parameters

  • int32_t : Returned status code.

Returns

  • char * : String representation.


Issue with this doc? Please let us know.