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 audioFramereturn 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.