Cobra Voice Activity Detection
Microcontroller API

This document outlines how to use the Cobra Voice Activity Detection engine on a microcontroller.

pv_cobra_t

typedef struct pv_cobra pv_cobra_t;

Container representing the Cobra VAD engine.

pv_cobra_init()

pv_status_t pv_cobra_init(
        const char *access_key,
        const char *device,
        pv_cobra_t **object);

Creates a Cobra instance. Resources should be cleaned when you are done using the pv_cobra_delete() function.

Parameters

• access_key const char * : AccessKey obtained from Picovoice Console.
• device char * : String representation of the device (e.g., CPU or GPU) to use. If set to best, the most suitable device is selected automatically. If set to gpu, the engine uses the first available GPU device. To select a specific GPU device, set this argument to gpu:${GPU_INDEX}, where ${GPU_INDEX} is the index of the target GPU. If set to cpu, the engine will run on the CPU with the default number of threads. To specify the number of threads, set this argument to cpu:${NUM_THREADS}, where ${NUM_THREADS} is the desired number of threads.
• object pv_cobra_t * * : Constructed instance of Cobra.

Returns

• pv_status_t : Returned status code.

pv_cobra_get_min_memory_buffer_size()

pv_status_t pv_cobra_get_min_memory_buffer_size(
        void *preliminary_memory_buffer,
        int32_t preliminary_memory_size,
        int32_t *min_memory_buffer_size
);

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

Parameters

• preliminary_memory_buffer void * : Memory; needs to be 8-byte aligned.
• preliminary_memory_size int32_t : Memory size in bytes.
• min_memory_buffer_size int32_t * : minimum required memory buffer size in bytes.

Returns

• pv_status_t : Returned status code.

pv_cobra_delete()

void pv_cobra_delete(pv_cobra_t *object);

Releases resources acquired by Cobra.

Parameters

• object pv_cobra_t * : Picovoice object.

pv_cobra_process()

pv_status_t pv_cobra_process(
    pv_cobra_t *object,
    const int16_t *pcm,
    float *is_voiced);

Processes a frame of the incoming audio stream and emits the probability of voice activity.

The number of samples per frame can be attained by calling pv_cobra_frame_length(). The incoming audio needs to have a sample rate equal to pv_sample_rate() and be 16-bit linearly-encoded. Cobra operates on single-channel audio.

Parameters

• object pv_cobra_t * : Cobra object.
• pcm int16_t : A frame of audio samples.
• is_voiced float * : Probability of voice activity. It is a floating-point number within [0, 1].

Returns

• pv_status_t : Status code.

pv_cobra_frame_length()

int32_t pv_cobra_frame_length(void);

Getter for number of audio samples per frame.

Returns

• int32_t : Frame length.

pv_cobra_version()

const char *pv_cobra_version(void);

Getter for version.

Returns

• const char * : Cobra version.

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.

pv_get_error_stack()

pv_status_t pv_get_error_stack(
        char ***message_stack,
        int32_t *message_stack_depth);

If a function returns a failure (any pv_status_t other than PV_STATUS_SUCCESS), this function can be called to get a series of error messages related to the failure. This function can only be called only once per failure status on another function. The memory for message_stack must be freed using pv_free_error_stack.

Regardless of the return status of this function, if message_stack is not NULL, then message_stack contains valid memory. However, a failure status on this function indicates that future error messages may not be reported.

Parameters

• message_stack const char * * * : Array of messages relating to the failure. Messages are NULL terminated strings. The array and messages must be freed using pv_free_error_stack().
• message_stack_depth int32_t * : The number of messages in the message_stack array.

pv_free_error_stack()

void pv_free_error_stack(char **message_stack);

This function frees the memory used by error messages allocated by pv_get_error_stack().

Parameters

• message_stack const char * * * : Array of messages relating to the failure.