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

You can install the Porcupine Java binding by downloading and referencing the latest Porcupine JAR file.

Build

To build from source, we recommend using the IntelliJ IDE. Open the .iml file with IntelliJ and click "Build > Build Project" to build or "Build > Build Artifacts" to package as a JAR file.

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.