Rhino - Java API

This document outlines how to integrate Rhino Speech-to-Intent engine within an application using its Java API.

Requirements

• Java 11+

Compatibility

• Linux (x86_64)
• macOS (x86_64)
• Windows (x86_64)

Installation

The latest Java bindings are available from the Maven Central Repository at:

ai.picovoice:rhino-java:${version}

If you're using Gradle for your Java project, include the following line in your build.gradle file to add Rhino:

implementation 'ai.picovoice:rhino-java:${version}'

If you're using IntelliJ, open the Project Structure dialog (File > Project Structure) and go to the Libraries section. Click the plus button at the top to add a new project library and select From Maven.... Search for ai.picovoice:rhino-java in the search box and add the latest version to your project.

Build

To build from source, invoke the Gradle build task from the command-line:

cd rhino/binding/java
./gradlew build

Once the task is complete, the output JAR can be found in rhino/binding/java/build/libs.

Usage

The easiest way to create an instance of the engine is with the Rhino Builder:

import ai.picovoice.rhino.*;

try{
    Rhino handle = new Rhino.Builder()
                    .setContextPath("/absolute/path/to/context")
                    .build();
} catch (RhinoException e) { }

Where the setContextPath() builder argument sets the absolute path to the Rhino Speech-to-Intent context.

The sensitivity of the engine can be tuned using the setSensitivity builder argument. It is a floating-point number within [0, 1]. A higher sensitivity value results in fewer misses at the cost of (potentially) increasing the erroneous inference rate.

import ai.picovoice.rhino.*;

try{
    Rhino handle = new Rhino.Builder()
                    .setContextPath("/absolute/path/to/context")
                    .setSensitivity(0.25f)
                    .build();
} catch (RhinoException e) { }

When initialized, the valid sample rate is given by handle.getSampleRate(). Expected frame length (number of audio samples in an input array) is handle.getFrameLength(). The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio.

short[] getNextAudioFrame(){
    // .. get audioFrame
    return audioFrame;
}

while(true) {
    boolean isFinalized = handle.process(getNextAudioFrame());   
    if(isFinalized){
        RhinoInference inference = handle.getInference();
        if(inference.getIsUnderstood()){
            String intent = inference.getIntent();
            Map<string, string> slots = inference.getSlots();
            // .. code to take action based on inferred intent and slot values              
        } else {
            // .. code to handle unsupported commands
        }        
    }
}

Once you're done with Rhino, ensure you release its resources explicitly:

handle.delete();

Custom Context

You can create custom Rhino context models using Picovoice Console.

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.