Rhino Speech-to-Intent
Microcontroller API

This document outlines how to use the Rhino Speech-to-Intent engine on a microcontroller.

pv_rhino_t

typedef struct pv_rhino pv_rhino_t;

Container representing the Rhino Speech-to-Intent engine.

pv_rhino_init()

pv_status_t pv_rhino_init(
        const char *access_key,
        void *memory_buffer,
        int32_t memory_size,
        const void *context,
        int32_t context_size,
        float sensitivity,
        float endpoint_duration_sec,
        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.
• memory_buffer void * : Memory; needs to be 8-byte aligned.
• memory_size int32_t : Memory size in bytes. The optimal size for given context models can be computed using pv_rhino_get_min_memory_buffer_size()
• context const void * : Context parameters. A context represents the set of expressions (spoken commands), intents, and intent arguments (slots) within a domain of interest.
• context_size int32_t : Size of the context in bytes.
• 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.
• endpoint_duration_sec float : Endpoint duration in seconds. An endpoint is a chunk of silence at the end of an utterance that marks the end of spoken command. It should be a positive number within [0.5, 5]. A lower endpoint duration reduces delay and improves responsiveness. A higher endpoint duration assures Rhino doesn't return inference pre-emptively in case the user pauses before finishing the request.
• require_endpoint bool : If set to true, Rhino requires an endpoint (a chunk of silence) after the spoken command. If set to false, Rhino tries to detect silence, but if it cannot, it still will provide inference regardless. Set to false only if operating in an environment with overlapping speech (e.g. people talking in the background).
• object pv_rhino_t * * : Constructed instance of Rhino.

Returns

• pv_status_t : Returned status code.

pv_rhino_get_min_memory_buffer_size()

pv_status_t pv_rhino_get_min_memory_buffer_size(
        int32_t preliminary_memory_size,
        void *preliminary_memory_buffer,
        const void *context_model,
        int32_t context_model_size,
        int32_t *min_memory_buffer_size
);

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

Parameters

• preliminary_memory_size int32_t : Memory size in bytes.
• preliminary_memory_buffer void * : Memory; needs to be 8-byte aligned.
• context_model void * : Context parameters.
• context_model_size int32_t : Size of the context in bytes.
• min_memory_buffer_size int32_t * : minimum required memory buffer size in bytes.

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 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 the incoming audio stream and emits a flag indicating if the inference is finalized. 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. Rhino operates on single-channel audio. When finalized, pv_rhino_is_understood() should be called to check if the spoken command is considered valid.

Parameters

• object pv_rhino_t * : Rhino object.
• pcm int16_t : A frame of audio samples.
• is_finalized bool * : Flag indicating if the inference is finalized.

Returns

• pv_status_t : Returned status code.

pv_rhino_is_understood()

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 object.
• is_understood bool * : 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 object.
• intent const char ** : 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_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 shouldn't free these resources via standard C library free().

Parameters

• object pv_rhino_t * : Rhino 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 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 object.
• context_info const char ** : Context information.

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_picovoice_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 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.