Picovoice Platform - C API
This document outlines how to use Picovoice platform within a C/C++ application.
Prerequisites
Picovoice 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. Linux x86_64 or Raspberry Pi 4)
- Header files
- The model files. The standard models are freely available on Porcupine and Rhino's GitHub repository. Enterprises who are commercially engaged with Picovoice can access the compressed model as well as the standard one.
- Keyword and Context files for your use case. A set of freely-available keyword and Context files can be found on the GitHub repository of Porcupine and Rhino, respectively. Enterprises who are engaged with Picovoice can create custom wake word models using Picovoice Console.
Integration
Picovoice 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 Picovoice object can be constructed as follows.
const char *porcupine_model_path = ...const char *keyword_path = ...const float porcupine_sensitivity = 0.5fvoid wake_word_callback(void) {// logic to execute upon detection of wake word}const char *rhino_model_path = ...const char *context_path = ...const float rhino_sensitivity = 0.75fvoid inference_callback(pv_inference_t *inference) {// `inference` exposes three immutable properties:// (1) `IsUnderstood`// (2) `Intent`// (3) `Slots`// ..pv_inference_delete_func(inference);}pv_picovoice_t *handle = NULL;const pv_status_t status = pv_picovoice_init_func(porcupine_model_path,keyword_path,porcupine_sensitivity,wake_word_callback,rhino_model_path,context_path,rhino_sensitivity,inference_callback,&handle);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.
handle
is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at
keyword_path
. Upon detection of wake word it starts inferring user's intent from the follow-on voice command within
the context defined by the file located at context_path
. keyword_path
is the absolute path to
Porcupine wake word engine keyword file (with .ppn
suffix).
context_path
is the absolute path to Rhino Speech-to-Intent engine context file
(with .rhn
suffix). wake_word_callback
is invoked upon the detection of wake phrase and inference_callback
is
invoked upon completion of follow-on voice command inference.
Picovoice accepts single channel, 16-bit PCM audio. The sample rate can be retrieved using pv_sample_rate()
. Finally, Picovoice 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();const pv_status_t status = pv_picovoice_process_func(handle, pcm);if (status != PV_STATUS_SUCCESS) {// error handling logic}}
Finally, when done be sure to release the acquired resources.
pv_picovoice_delete_func(handle);