Porcupine - Java API

This document outlines how to integrate Porcupine wake word 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:porcupine-java:${version}

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

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

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

Usage

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

import ai.picovoice.porcupine.*;

try{
    Porcupine handle = new Porcupine.Builder()
                        .setKeyword("picovoice")
                        .build();
} catch (PorcupineException e) { }

handle is an instance of Porcupine that detects utterances of "Picovoice". The setKeyword() builder argument is a shorthand for accessing default keyword model files shipped with the package.

The list of default keywords can be retrieved by:

import ai.picovoice.porcupine.*;

for(String keyword : Porcupine.KEYWORDS){
    System.out.println(keyword);
}

Porcupine can detect multiple keywords concurrently:

import ai.picovoice.porcupine.*;

try{
    Porcupine handle = new Porcupine.Builder()
                        .setKeywords(new String[]{"bumblebee", "picovoice" }
                        .build();
} catch (PorcupineException e) { }

To detect non-default keywords use the setKeywordPaths() builder argument instead:

import ai.picovoice.porcupine.*;

String[] keywordPaths = new String[]{ "/absolute/path/to/keyword/one", "/absolute/path/to/keyword/two", ...}
try{
    Porcupine handle = new Porcupine.Builder()
                        .setKeywordPaths(keywordPaths)
                        .build();
} catch (PorcupineException e) { }

The sensitivity of the engine can be tuned per-keyword using the setSensitivities builder argument

import ai.picovoice.porcupine.*;

try{
    Porcupine handle = new Porcupine.Builder()
                        .setKeywords(new String[]{"grapefruit", "porcupine"})
                        .setSensitivities(new float[]{ 0.6f, 0.35f })
                        .build();
} catch (PorcupineException e) { }

Sensitivity is the parameter that enables trading miss rate for the false alarm rate. It is a floating-point number within [0, 1]. A higher sensitivity reduces the miss rate at the cost of increased false alarm rate.

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){
    int keywordIndex = handle.process(getNextAudioFrame());
    if(keywordIndex >= 0){
        // .. detection event logic/callback
    }
}

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

handle.delete();

Custom Wake Word

You can create custom Porcupine wake word models using Picovoice Console.

Non-English Wake Words

In order to detect non-English wake words you need to use the corresponding model file. The model files for all supported languages are available here.