Porcupine Wake Word
Android API

API Reference for the Android Porcupine SDK (porcupine-android)

package: ai.picovoice.porcupine

Porcupine

public class Porcupine { }

Class for the Porcupine Wake Word engine.

Porcupine must be initialized using the Builder() Class. Resources should be cleaned when you are done using the delete() function.

Porcupine.BuiltInKeyword

public enum BuiltInKeyword { }

Enum of available built-in keywords for Porcupine Wake Word engine.

Values:

• ALEXA
• AMERICANO
• BLUEBERRY
• BUMBLEBEE
• COMPUTER
• GRAPEFRUIT
• GRASSHOPPER
• HEY_GOOGLE
• HEY_SIRI
• JARVIS
• OK_GOOGLE
• PICOVOICE
• PORCUPINE
• TERMINATOR

Porcupine.delete()

public void delete()

Releases resources acquired by Porcupine.

Porcupine.getFrameLength()

public int getFrameLength()

Getter for number of audio samples per frame.

Returns

• int: Number of audio samples per frame.

Porcupine.getSampleRate()

public int getSampleRate()

Getter for audio sample rate accepted by Picovoice.

Returns

• int: Audio sample rate accepted by Picovoice.

Porcupine.getVersion()

public String getVersion()

Getter for version.

Returns

• String: Current Porcupine version.

Porcupine.process()

public int process(short[] pcm) throws PorcupineException

Processes a frame of the incoming audio stream and emits the detection result. The number of samples per frame can be attained by calling getFrameLength(). The incoming audio needs to have a sample rate equal to getSampleRate()and be 16-bit linearly-encoded. Porcupine operates on single-channel audio.

Parameters

• pcm short[] : A frame of audio samples.

Returns

• int: Index of observed keyword at the end of the current frame. Indexing is 0-based and matches the ordering of keyword models provided to the constructor. If no keyword is detected then it returns -1.

Throws

• PorcupineException: if there is an error while processing the audio frame.

Porcupine.Builder

public static class Builder { }

Builder for creating an instance of Porcupine with a mixture of default arguments.

Porcupine.Builder.build()

public Porcupine build(Context context) throws PorcupineException

Creates an instance of Porcupine Wake Word engine.

Parameters

• context Context : The Android app context

Returns

• Porcupine: An instance of Porcupine Wake Word engine.

Throws

• PorcupineException: If an error occurs while creating an instance of Porcupine Wake Word engine.

Porcupine.Builder.setAccessKey()

public Porcupine.Builder setAccessKey(String accessKey)

Sets the AccessKey of the builder.

Parameters

• accessKey String : AccessKey obtained from Picovoice Console.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setKeyword()

public Porcupine.Builder setKeyword(BuiltInKeyword keyword)

Sets one keyword of the builder. This will replace the keywords set with setKeywords().

build() will throw a PorcupineException if set together with setKeywordPath() or setKeywordPaths().

Parameters

• keyword BuiltinKeyword : A keyword used for detection.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setKeywordPath()

public Porcupine.Builder setKeywordPath(String keywordPath)

Sets one keywordPath of the builder. This will replace the keywordPaths set with setKeywordPaths().

build() will throw a PorcupineException if set together with setKeyword() or setKeywords().

Parameters

• keywordPath String : Path to a keyword file (.ppn). Can be either a path that is relative to the project's assets folder or an absolute path to the file on device.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setKeywordPaths()

public Porcupine.Builder setKeywordPaths(String[] keywordPaths)

Sets keywordPaths of the builder. This will replace the keywordPath set with setKeywordPath().

build() will throw a PorcupineException if set together with setKeyword() or setKeywords().

Parameters

• keywordPaths String : Paths to keyword model files (.ppn). Can be either paths that are relative to the project's assets folder or absolute paths to the files on device.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setKeywords()

public Porcupine.Builder setKeywords(BuiltInKeyword[] keywords)

Sets keywords of the builder. This will replace the keyword set with setKeyword().

build() will throw a PorcupineException if set together with setKeywordPath() or setKeywordPaths().

Parameters

• keywords BuiltInKeyword[] : List of keywords for detection.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setModelPath()

public Porcupine.Builder setModelPath(String modelPath)

Sets the model path of the builder. If not set it will be set to the default location.

Parameters

• modelPath String : Path to the file containing model parameters (.pv). Can be either a path that is relative to the project's assets folder or an absolute path to the file on device.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setSensitivities()

public Porcupine.Builder setSensitivities(float[] sensitivities)

Sets sensitivities of the builder. Each value should be a number within [0, 1]. A higher sensitivity results in fewer misses at the cost of increasing the false alarm rate.

This should be the same size as the number of keywords or keywordPaths set by setKeywords() setKeywordPaths(). If not set, each will be set to 0.5. This will replace the sensitivity set with setSensitivity().

Parameters

• sensitivities float[] : Sensitivities for detecting keywords.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

Porcupine.Builder.setSensitivity()

public Porcupine.Builder setSensitivity(float sensitivity)

Sets sensitivity of the builder. Value should be a number within [0, 1]. A higher sensitivity results in fewer misses at the cost of increasing the false alarm rate. This will replace the sensitivities set with setSensitivities().

This should be used if setKeyword() or setKeywordPath() was used.

Parameters

• sensitivity float: Sensitivity for detecting keyword.

Returns

• Porcupine.Builder: Modified Porcupine.Builder object.

PorcupineException

public class PorcupineException extends Exception { }

Exception thrown if an error occurs within Porcupine Wake Word engine.

Exceptions:

public class PorcupineActivationException           extends PorcupineException { }
public class PorcupineActivationLimitException      extends PorcupineException { }
public class PorcupineActivationRefusedException    extends PorcupineException { }
public class PorcupineActivationThrottledException  extends PorcupineException { }
public class PorcupineIOException                   extends PorcupineException { }
public class PorcupineInvalidArgumentException      extends PorcupineException { }
public class PorcupineInvalidStateException         extends PorcupineException { }
public class PorcupineKeyException                  extends PorcupineException { }
public class PorcupineMemoryException               extends PorcupineException { }
public class PorcupineRuntimeException              extends PorcupineException { }
public class PorcupineStopIterationException        extends PorcupineException { }

PorcupineManager

public class PorcupineManager { }

High-level Android binding for Porcupine Wake Word engine. It handles recording audio from microphone, processes it in real-time using Porcupine, and notifies the client when any of the given keywords are detected.

PorcupineManager.delete()

public void delete()

Releases resources acquired by PorcupineManager.

PorcupineManager.start()

public void start()

Starts recording audio from the microphone and monitors it for the utterances of the given set of keywords.

PorcupineManager.stop()

public void stop()

Stops recording audio from the microphone.

Throws

• PorcupineException: If there is an error while stopping microphone.

PorcupineManager.Builder

public static class Builder { }

Builder for creating an instance of PorcupineManager with a mixture of default arguments.

PorcupineManager.Builder.build()

public PorcupineManager build(Context context, PorcupineManagerCallback callback) throws PorcupineException

Creates an instance of PorcupineManager.

Parameters

• context Context : The Android app context.
• callback PorcupineManagerCallback : A callback function that is invoked upon detection of the keywords. The callback must be an instance of PorcupineManagerCallback.

Returns

• PorcupineManager: An instance of PorcupineManager.

Throws

• PorcupineException: If an error occurs while creating an instance of PorcupineManager.

PorcupineManager.Builder.setAccessKey()

public PorcupineManager.Builder setAccessKey(String accessKey)

Sets the AccessKey of the builder.

Parameters

• accessKey String : AccessKey obtained from Picovoice Console.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setKeyword()

public PorcupineManager.Builder setKeyword(BuiltInKeyword keyword)

Sets one keyword of the builder. This will replace the keywords set with setKeywords().

build() will throw a PorcupineException if set together with setKeywordPath() or setKeywordPaths().

Parameters

• keyword BuiltInKeyword : A keyword used for detection.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setKeywordPath()

public PorcupineManager.Builder setKeywordPath(String keywordPath)

Sets one keywordPath of the builder. This will replace the keywordPaths set with setKeywordPaths().

build() will throw a PorcupineManagerException if set together with setKeyword() or setKeywords().

Parameters

• keywordPath String : Path to a keyword file (.ppn). Can be either a path that is relative to the project's assets folder or an absolute path to the file on device.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setKeywordPaths()

public PorcupineManager.Builder setKeywordPaths(String[] keywordPaths)

Sets keywordPaths of the builder. This will replace the keywordPath set with setKeywordPath().

build() will throw a PorcupineException if set together with setKeyword() or setKeywords().

Parameters

• keywordPaths String : Paths to keyword model files (.ppn). Can be either paths that are relative to the project's assets folder or absolute paths to the file on device.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setKeywords()

public PorcupineManager.Builder setKeywords(BuiltInKeyword[] keywords)

Sets keywords of the builder. This will replace the keyword set with setKeyword().

build() will throw a PorcupineException if set together with setKeywordPath() or setKeywordPaths().

Parameters

• keywords BuiltInKeyword[]: List of keywords for detection.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setModelPath()

public PorcupineManager.Builder setModelPath(String modelPath)

Sets the model path of the builder. If not set it will be set to the default location.

Parameters

• modelPath String : Path to the file containing model parameters (.pv). Can be either a path that is relative to the project's assets folder or an absolute path to the file on device.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setSensitivities()

public PorcupineManager.Builder setSensitivities(float[] sensitivities)

Sets sensitivities of the builder. Each value should be a number within [0, 1]. A higher sensitivity results in fewer misses at the cost of increasing the false alarm rate.

This should be the same size as the number of keywords or keywordPaths set by setKeywords() setKeywordPaths(). If not set, each will be set to 0.5. This will replace the sensitivity set with setSensitivity().

Parameters

• sensitivities float[] : Sensitivities for detecting keywords.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setSensitivity()

public PorcupineManager.Builder setSensitivity(float sensitivity)

Sets sensitivity of the builder. Value should be a number within [0, 1]. A higher sensitivity results in fewer misses at the cost of increasing the false alarm rate. This will replace the sensitivities set with setSensitivities().

This should be used if setKeyword() or setKeywordPath() was used.

Parameters

• sensitivity float : Sensitivity for detecting keyword.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManager.Builder.setErrorCallback()

public PorcupineManager.Builder setErrorCallback(PorcupineManagerErrorCallback errorCallback)

Sets errorCallback of the builder.

Parameters

• errorCallback PorcupineManagerErrorCallback : A function to run if errors occur while processing audio frames.

Returns

• PorcupineManager.Builder: Modified PorcupineManager.Builder object.

PorcupineManagerCallback

public interface PorcupineManagerCallback {
    void invoke(int keywordIndex);
}

Callback interface invoked when a keyword has been detected.

PorcupineManagerErrorCallback

public interface PorcupineManagerErrorCallback {
    void invoke(PorcupineException error);
}

Callback interface invoked when an error occurs while processing audio.