Rhino - C API

This document outlines how to use the Rhino Speech-to-Intent engine within a C/C++ application.

Prerequisites

Rhino is implemented in ANSI C and is shipped as a precompiled library accompanied by corresponding header files. To integrate within a C/C++ application the following items are needed

• Precompiled library for your target platform (e.g. Ubuntu x86_64 or Raspberry Pi 4)
• Header files
• The model file. The standard model is freely available on Rhino's GitHub repository. Enterprises who are commercially engaged with Picovoice can access compressed and standard models as well.
• Context model file for your use case. A set of freely-available context files can be found on Rhino's GitHub repository. Enterprises who are engaged with Picovoice can create custom NLU models using Picovoice Console.

Integration

Rhino is implemented in ANSI C and therefore can be directly linked to C applications. Its header file contains relevant information. An instance of the Rhino object can be constructed as follows.

const char *model_file_path = ...
const char *context_file_path = ...

pv_rhino_t *rhino;
const pv_status_t status = pv_rhino_init(
    model_file_path,
    context_file_path,
    &rhino);
if (status != PV_STATUS_SUCCESS) {
    // add error handling code
}

Now the handle rhino can be used to infer intent from an incoming audio stream. Rhino accepts single channel, 16-bit PCM audio. The sample rate can be retrieved using pv_sample_rate(). Finally, Rhino accepts input audio in consecutive chunks (frames); the length of each frame can be retrieved using pv_rhino_frame_length().

extern const int16_t *get_next_audio_frame(void);

while (true) {
    const int16_t *pcm = get_next_audio_frame();

    bool is_finalized;
    pv_status_t status = pv_rhino_process(rhino, pcm, &is_finalized);
    if (status != PV_STATUS_SUCCESS) {
        // add error handling code
    }

    if (is_finalized) {
        bool is_understood;
        status = pv_rhino_is_understood(rhino, &is_understood);
        if (status != PV_STATUS_SUCCESS) {
            // add error handling code
        }

        if (is_understood) {
            const char *intent;
            int num_slots;
            const char **slots;
            const char **values;
            status = pv_rhino_get_intent(
                rhino,
                &intent,
                &num_slots,
                &slots,
                &values);
            if (status != PV_STATUS_SUCCESS) {
                // add error handling code
            }

            // add code to take action based on inferred intent and slot values


            pv_rhino_free_slots_and_values(rhino, slots, values);
        } else {
            // add code to handle unsupported commands
        }

        pv_rhino_reset(rhino);
    }
}

When done, remember to release the resources acquired.

pv_rhino_delete(rhino);

Non-English Contexts

In order to run inference on non-English contexts you need to use the corresponding model file. The model files for all supported languages are available here.