Rhino - C API

API Reference for the Rhino C SDK.

pv_rhino_init()

PV_API pv_status_t pv_rhino_init(
        const char *access_key,
        const char *model_path,
        const char *context_path,
        float sensitivity,
        bool require_endpoint,
        pv_rhino_t **object);

Create a Rhino instance. Resources should be cleaned when you are done using the pv_rhino_delete() function.

Parameters

access_key char * : AccessKey obtained from Picovoice Console.
model_path char * : Absolute path to file containing model parameters (.pv).
context_path char * : Absolute path to file containing context parameters. A context represents the set of expressions (spoken commands), intents, and intent arguments (slots) within a domain of interest (.rhn).
sensitivity float : Inference sensitivity. It should be a number within [0, 1]. A higher sensitivity value results in fewer misses at the cost of (potentially) increasing the erroneous inference rate.
require_endpoint bool : If set to true, Rhino requires an endpoint (chunk of silence) before finishing inference.
object pv_rhino_t * * : Constructed instance of Rhino.

Returns

pv_status_t : Returned status code.

pv_rhino_delete()

void pv_rhino_delete(pv_rhino_t *object);

Releases resources acquired by Rhino.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.

pv_rhino_process()

pv_status_t pv_rhino_process(pv_rhino_t *object, const int16_t *pcm, bool *is_finalized);

Processes a frame of audio and emits a flag indicating if the inference is finalized. When finalized, pv_rhino_is_understood()[#pv_rhino_is_understood] should be called to check if the spoken command is considered valid. The number of samples per frame can be attained by calling pv_rhino_frame_length(). The incoming audio needs to have a sample rate equal to pv_sample_rate() and be 16-bit linearly-encoded. Picovoice operates on single-channel audio.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.
pcm int16_t * : A frame of audio samples.
is_finalized bool * : A flag indicating if the inference is finalized.

Returns

pv_status_t : Returned status code.

pv_rhino_is_understood()

PV_API pv_status_t pv_rhino_is_understood(const pv_rhino_t *object, bool *is_understood);

Indicates if the spoken command is valid, is within the domain of interest (context), and the engine understood it. Upon success pv_rhino_get_intent() may be called to retrieve inferred intent. If not understood, pv_rhino_reset() should be called.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.
is_understood bool * : A flag indicating if the spoken command is understood.

Returns

pv_status_t : Returned status code.

pv_rhino_get_intent()

pv_status_t pv_rhino_get_intent(
        const pv_rhino_t *object,
        const char **intent,
        int32_t *num_slots,
        const char ***slots,
        const char ***values);

Getter for the intent. The intent is stored as an intent string and pairs of slots and values. It should be called only after intent inference is finalized, and it is verified that the spoken command is understood via calling pv_rhino_is_understood().

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.
intent bool ** : Inferred intent.
num_slots int32_t * : Number of slots.
slots const char *** : Array of inferred slots. Its memory needs to be freed by calling pv_rhino_free_slots_and_values().
values const char *** : Array of inferred slot values. Its memory needs to be freed by calling pv_rhino_free_slots_and_values().

Returns

pv_status_t : Returned status code.

pv_rhino_free_slots_and_values()

PV_API pv_status_t pv_rhino_free_slots_and_values(const pv_rhino_t *object, const char **slots, const char **values);

Frees memory resources allocated to slots and values after calling pv_rhino_get_intent(). One should not free these resources via standard C library 'free()'.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.
slots const char ** : Slots.
values const char ** : Slot values.

Returns

pv_status_t : Returned status code.

pv_rhino_reset()

pv_status_t pv_rhino_reset(pv_rhino_t *object);

Resets the internal state of the engine. It should be called before the engine can be used to infer intent from a new stream of audio.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.

Returns

pv_status_t : Returned status code.

pv_rhino_context_info()

pv_status_t pv_rhino_context_info(const pv_rhino_t *object, const char **context_info);

Getter for context information.

Parameters

object pv_rhino_t * : Rhino Speech-to-Intent object.
context char * * : A frame of audio samples.

Returns

pv_status_t : Returned status code.

pv_rhino_version()

const char *pv_rhino_version(void);

Getter for version.

Returns

char * : Rhino version.

pv_rhino_frame_length()

int32_t pv_rhino_frame_length(void);

Getter for number of audio samples per frame.

Returns

int32_t : Frame length.

pv_sample_rate()

int32_t pv_sample_rate(void);

Audio sample rate accepted by Rhino.

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.