Picovoice Platform — Java API

This document outlines how to integrate Picovoice platform 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:picovoice-java:${version}

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

implementation 'ai.picovoice:picovoice-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:picovoice-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 picovoice/sdk/java
./gradlew build

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

Usage

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

import ai.picovoice.picovoice.*;

String keywordPath = "/absolute/path/to/keyword.ppn"

PicovoiceWakeWordCallback wakeWordCallback = () -> {..};

String contextPath = "/absolute/path/to/context.rhn"

PicovoiceInferenceCallback inferenceCallback = inference -> {
    // `inference` exposes three getters:
    // (1) `getIsUnderstood()`
    // (2) `getIntent()`
    // (3) `getSlots()`
    // ..
};

try{        
    Picovoice handle = new Picovoice.Builder()
                    .setKeywordPath(keywordPath)
                    .setWakeWordCallback(wakeWordCallback)
                    .setContextPath(contextPath)
                    .setInferenceCallback(inferenceCallback)
                    .build();
} catch (PicovoiceException e) { }

handle is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at keywordPath. Upon detection of wake word it starts inferring user's intent from the follow-on voice command within the context defined by the file located at contextPath. keywordPath is the absolute path to Porcupine wake word engine keyword file (with .ppn suffix). contextPath is the absolute path to Rhino Speech-to-Intent engine context file (with .rhn suffix). wakeWordCallback is invoked upon the detection of wake phrase and inferenceCallback is invoked upon completion of follow-on voice command inference.

When instantiated, valid sample rate can be obtained via handle.getSampleRate(). Expected number of audio samples per frame 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)
{
    handle.process(getNextAudioFrame());    
}

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

handle.delete();

Custom Wake Word & Context

You can create custom Porcupine wake word and Rhino context models using Picovoice Console

Non-English Models

In order to detect wake words and run inference in other languages you need to use the corresponding model file. The model files for all supported languages are available here and here.