Koala Noise Suppression
C API

API Reference for the Koala C SDK.

pv_koala_t

typedef struct pv_koala pv_koala_t;

Container representing the Koala Noise Suppression engine.

pv_koala_init()

pv_status_t pv_koala_init(const char *access_key, const char *model_path, pv_koala_t **object);

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

Parameters

• access_key const char * : AccessKey obtained from Picovoice Console.
• model_path const char * : Absolute path to the file containing model parameters (.pv).
• object pv_koala_t * * : Constructed instance of Koala.

Returns

• pv_status_t : Status code.

pv_koala_delete()

void pv_koala_delete(pv_koala_t *object);

Releases resources acquired by Koala.

Parameters

• object pv_koala_t * : Koala object.

pv_koala_process()

pv_status_t pv_koala_process(
    pv_koala_t *object,
    const int16_t *pcm,
    int16_t *enhanced_pcm);

Processes a frame of the incoming audio stream and returns a frame of enhanced audio. The output is not necessarily in sync with the input frame; instead, the output audio will contain the enhancement result for audio that has been passed to previous calls of this function. The total delay in samples can be obtained by pv_koala_delay_sample(). The number of samples per frame can be attained by calling pv_koala_frame_length(). The incoming audio needs to have a sample rate equal to pv_sample_rate() and be 16-bit linearly-encoded. Koala operates on single-channel audio.

Parameters

• object pv_koala_t * : Koala object.
• pcm int16_t : A frame of audio samples.
• enhanced_pcm int16_t : A frame of enhanced audio samples. Needs to point to an allocated block of memory of the same size as the pcm input argument.

Returns

• pv_status_t : Status code.

pv_koala_reset()

pv_status_t pv_koala_reset(pv_koala_t *object);

Finalizes the enhancement process and resets the internal state of the Koala object. Subsequent calls to pv_koala_process() will not return any delayed samples from previous calls; that data will be lost. Instead, the result will be the same as if the Koala object were newly created.

Parameters

• object pv_koala_t * : Koala object.

Returns

• pv_status_t : Status code.

pv_koala_delay_sample()

pv_status_t pv_koala_delay_sample(
    const pv_koala_t *object, 
    int32_t *delay_sample);

Getter for the delay in samples. If the input and output of sequential calls to pv_koala_process are viewed as two contiguous streams of audio data, this delay specifies the time shift between the input and output stream.

Parameters

• object pv_koala_t * : Koala object.
• delay_sample int32_t * : Delay in samples.

Returns

• pv_status_t : Status code.

pv_koala_frame_length()

int32_t pv_koala_frame_length(void);

Getter for number of audio samples per frame.

Returns

• int32_t : Frame length.

pv_koala_version()

const char *pv_koala_version(void);

Getter for version.

Returns

• const char * : Koala version.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Koala.

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

• status int32_t : Status code.

Returns

• const char * : String representation of status code.

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.

Returns

• pv_status_t : Returned status code.

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.