pv_porcupine.h

/*
    Copyright 2018-2023 Picovoice Inc.

    You may not use this file except in compliance with the license. A copy of the license is located in the "LICENSE"
    file accompanying this source.

    Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
    an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
    specific language governing permissions and limitations under the License.
*/

#ifndef PV_PORCUPINE_H
#define PV_PORCUPINE_H

#include <stdbool.h>
#include <stdint.h>

#include "picovoice.h"

#ifdef __cplusplus

extern "C" {

#endif

/**
 * Forward declaration for Porcupine wake word engine. It detects utterances of given keywords within an incoming stream
 * of audio in real-time. It processes incoming audio in consecutive frames and for each frame 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.
 */
typedef struct pv_porcupine pv_porcupine_t;

/**
 * Constructor.
 *
 * @param access_key AccessKey obtained from Picovoice Console (https://console.picovoice.ai/).
 * @param model_path Absolute path to the file containing model parameters.
 * @param num_keywords Number of keywords to monitor.
 * @param keyword_paths Absolute paths to keyword model files.
 * @param sensitivities 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.
 * @param[out] object Constructed instance of Porcupine.
 * @return Status code. Returns 'PV_STATUS_INVALID_ARGUMENT', 'PV_STATUS_IO_ERROR', or 'PV_STATUS_OUT_OF_MEMORY' on
 * failure.
 */
PV_API pv_status_t pv_porcupine_init(
        const char *access_key,
        const char *model_path,
        int32_t num_keywords,
        const char *const *keyword_paths,
        const float *sensitivities,
        pv_porcupine_t **object);

/**
 * Destructor.
 *
 * @param object Porcupine object.
 */
PV_API void pv_porcupine_delete(pv_porcupine_t *object);

/**
 * Processes a frame of the incoming audio stream and emits the detection result.
 *
 * @param object Porcupine object.
 * @param pcm A frame of audio samples. 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.
 * @param[out] keyword_index 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.
 * @return Status code. Returns 'PV_STATUS_INVALID_ARGUMENT' or 'PV_STATUS_OUT_OF_MEMORY' on failure.
 */
PV_API pv_status_t pv_porcupine_process(pv_porcupine_t *object, const int16_t *pcm, int32_t *keyword_index);

/**
 * Getter for version.
 *
 * @return Version.
 */
PV_API const char *pv_porcupine_version(void);

/**
 * Getter for number of audio samples per frame.
 *
 * @return Frame length.
 */
PV_API int32_t pv_porcupine_frame_length(void);

#ifdef __cplusplus
}

#endif

#endif // PV_PORCUPINE_H