Bat Spoken Language Identification
C API

API Reference for the Bat C SDK.

pv_bat_t

typedef struct pv_bat pv_bat_t;

Container representing the Bat Spoken Language Identification object.

pv_bat_init()

pv_status_t pv_bat_init(
        const char *access_key,
        const char *model_path,
        const char *device,
        float voice_threshold,
        pv_bat_t **object);

Creates a Bat instance. Resources should be cleaned when you are done using the pv_bat_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).
• 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.
• voice_threshold float : Sensitivity threshold for detecting voice. The value should be a number within [0, 1]. A higher threshold increases detection confidence at the cost of potentially missing frames of voice.
• object pv_bat_t * * : Constructed instance of Bat.

Returns

• pv_status_t : Status code.

pv_bat_delete()

void pv_bat_delete(pv_bat_t *object);

Releases resources acquired by Bat.

Parameters

• object pv_bat_t * : Bat object.

pv_bat_process()

pv_status_t pv_bat_process(
    pv_bat_t *object,
    const int16_t *pcm,
    float **scores);

Processes a frame of the incoming audio.

Parameters

• object pv_bat_t * : Bat object.
• pcm int16_t : A frame of audio samples.
• scores float ** : Detection score for each supported language. The scores are in the range [0, 1] with 1 being maximum confidence in a detection. The index of each scores corresponds to the pv_bat_language_t enum value, and the length of the array is PV_BAT_LANGUAGE_NUM_LANGUAGES elements long. If NULL is returned for scores and the return status PV_STATUS_SUCCESS, Bat did not detect usable voice in the frame. scores must be freed using pv_bat_scores_delete().

Returns

• pv_status_t : Status code.

pv_bat_scores_delete()

void pv_bat_scores_delete(float *scores);

Deletes scores returned from pv_bat_process().

Parameters

• scores float * : Scores array returned from pv_bat_process().

pv_bat_frame_length()

int32_t pv_bat_frame_length(void);

Getter for number of audio samples per frame.

Returns

• int32_t : Frame length.

pv_bat_version()

const char *pv_bat_version(void);

Getter for version.

Returns

• const char * : Bat version.

pv_bat_language_t

typedef enum {
    PV_BAT_LANGUAGE_UNKNOWN = 0,
    PV_BAT_LANGUAGE_DE = 1,
    PV_BAT_LANGUAGE_EN = 2,
    PV_BAT_LANGUAGE_ES = 3,
    PV_BAT_LANGUAGE_FR = 4,
    PV_BAT_LANGUAGE_IT = 5,
    PV_BAT_LANGUAGE_JA = 6,
    PV_BAT_LANGUAGE_KO = 7,
    PV_BAT_LANGUAGE_PT = 8,
} pv_bat_language_t;

#define PV_BAT_LANGUAGE_NUM_LANGUAGES (9)

Bat language enum.

pv_bat_language_to_string()

const char *pv_bat_language_to_string(pv_bat_language_t language);

Parameters

• language pv_bat_language_t : pv_bat_language_t enum value.

Returns

• const char * : String representation of language.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Bat.

Returns

• int32_t : Sample rate.

pv_bat_list_hardware_devices()

pv_status_t pv_bat_list_hardware_devices(
        char ***hardware_devices,
        int32_t *num_hardware_devices);

Gets a list of hardware devices that can be specified when calling pv_bat_init().

Parameters

• hardware_devices const char * * * : Array of available hardware devices. Devices are NULL terminated strings. The array must be freed using pv_bat_free_hardware_devices().
• num_hardware_devices int32_t * : The number of devices in the hardware_devices array.

Returns

• pv_status_t : Returned status code.

pv_bat_free_hardware_devices()

void pv_bat_free_hardware_devices(
        char ***hardware_devices,
        int32_t *num_hardware_devices);

This function frees the memory allocated by pv_bat_list_hardware_devices().

Parameters

• hardware_devices const char * * * : Array of available hardware devices allocated by pv_bat_list_hardware_devices().
• num_hardware_devices int32_t * : The number of devices in the hardware_devices array

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.

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.