Picovoice Platform
Android API

API Reference for the Android Picovoice SDK (picovoice-android)

package: ai.picovoice.picovoice

Picovoice

public class Picovoice { }

Class for the Picovoice engine.

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

Picovoice.delete()

public void delete()

Releases resources acquired by Picovoice.

Picovoice.getFrameLength()

public int getFrameLength()

Getter for number of audio samples per frame.

Returns

• int: Number of audio samples per frame.

Picovoice.getSampleRate()

public int getSampleRate()

Getter for audio sample rate accepted by Picovoice.

Returns

• int: Audio sample rate accepted by Picovoice.

Picovoice.getVersion()

public String getVersion()

Getter for version.

Returns

• String: Current Picovoice version.

Picovoice.getPorcupineVersion()

public String getPorcupineVersion()

Getter for the version of Porcupine.

Returns

• String: Current Porcupine version.

Picovoice.getRhinoVersion()

public String getRhinoVersion()

Getter for the version of Rhino.

Returns

• String: Current Rhino version.

Picovoice.getContextInformation()

public String getContextInformation()

Getter for Rhino context information.

Returns

• String: Returns the context information.

Picovoice.process()

public void process(short[] pcm) throws PicovoiceException

Processes a frame of the incoming audio stream. Upon detection of wake word and completion of follow-on command inference invokes user-defined callbacks.

Parameters

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

Throws

• PicovoiceException: If there is an error while processing the audio frame.

Picovoice.reset()

public void reset() throws PicovoiceException

Resets the internal state of Picovoice. It should be called before processing a new stream of audio or when process was stopped while processing a stream of audio.

Throws

• PicovoiceException: If there is an error while resetting.

Picovoice.Builder

public static class Builder { }

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

Picovoice.Builder.build()

public Picovoice build() throws PicovoiceException

Creates an instance of the Picovoice platform.

Returns

• Picovoice: An instance of the Picovoice platform.

Throws

• PicovoiceException: If an error occurs while creating an instance of the Picovoice engine.

Picovoice.Builder.setAccessKey()

public Picovoice.Builder setAccessKey(String accessKey)

Sets the AccessKey of the builder.

Parameters

• accessKey String : AccessKey obtained from Picovoice Console.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setPorcupineModelPath()

public Picovoice.Builder setPorcupineModelPath(String porcupineModelPath)

Sets the Porcupine model path of the builder.

Parameters

• porcupineModelPath String : Path to the file containing the Porcupine 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

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setKeywordPath()

public Picovoice.Builder setKeywordPath(String keywordPath)

Sets the Porcupine keyword path of the builder.

Parameters

• keywordPath String : Path to the file containing the Porcupine keyword model (.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

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setPorcupineSensitivity()

public Picovoice.Builder setPorcupineSensitivity(float porcupineSensitivity)

Sets Porcupine's keyword 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.

Parameters

• porcupineSensitivity float : Sensitivity for detecting keyword.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setWakeWordCallback()

public Picovoice.Builder setWakeWordCallback(PicovoiceWakeWordCallback wakeWordCallback)

Sets the wake word callback object of the builder.

Parameters

• wakeWordCallback PicovoiceWakeWordCallback : Invoked when Porcupine has detected the wake word.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setRhinoModelPath()

public Picovoice.Builder setRhinoModelPath(String rhinoModelPath)

Sets the Rhino model path of the builder.

Parameters

• rhinoModelPath String : Path to the file containing the Rhino 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

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setContextPath()

public Picovoice.Builder setContextPath(String contextPath)

Sets the Rhino context path of the builder.

Parameters

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

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setRhinoSensitivity()

public Picovoice.Builder setRhinoSensitivity(float rhinoSensitivity)

Sets Rhino's 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.

Parameters

• rhinoSensitivity float : Sensitivity for intent inference.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setInferenceCallback()

public Picovoice.Builder setInferenceCallback(PicovoiceInferenceCallback inferenceCallback)

Sets the inference callback object of the builder.

Parameters

• inferenceCallback PicovoiceInferenceCallback : Invoked when Rhino has made an inference.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setEndpointDurationSec()

public Picovoice.Builder setEndpointDurationSec(float endpointDurationSec)

Sets the endpoint duration in seconds. An endpoint is a chunk of silence at the end of an utterance that marks the end of spoken command. It should be a positive number within [0.5, 5]. A lower endpoint duration reduces delay and improves responsiveness. A higher endpoint duration ensures Rhino doesn't return inference pre-emptively in case the user pauses before finishing the request.

Parameters

• endpointDurationSec float: Endpoint duration in seconds.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

Picovoice.Builder.setRequireEndpoint()

public Picovoice.Builder setRequireEndpoint(boolean requireEndpoint)

Sets requireEndpoint of the Builder. If set to true, Rhino requires an endpoint (a chunk of silence) after the spoken command. If set to false, Rhino tries to detect silence, but if it cannot, it still will provide inference regardless. Set to false only if operating in an environment with overlapping speech (e.g. people talking in the background).

Parameters

• requireEndpoint boolean: Indicates whether an endpoint is required for Rhino to finish inference.

Returns

• Picovoice.Builder: Modified Picovoice.Builder object.

PicovoiceException

public class PicovoiceException extends Exception { }

Exception thrown if an error occurs within the Picovoice engine.

Exceptions:

public class PicovoiceActivationException           extends PicovoiceException { }
public class PicovoiceActivationLimitException      extends PicovoiceException { }
public class PicovoiceActivationRefusedException    extends PicovoiceException { }
public class PicovoiceActivationThrottledException  extends PicovoiceException { }
public class PicovoiceIOException                   extends PicovoiceException { }
public class PicovoiceInvalidArgumentException      extends PicovoiceException { }
public class PicovoiceInvalidStateException         extends PicovoiceException { }
public class PicovoiceKeyException                  extends PicovoiceException { }
public class PicovoiceMemoryException               extends PicovoiceException { }
public class PicovoiceRuntimeException              extends PicovoiceException { }
public class PicovoiceStopIterationException        extends PicovoiceException { }

PicovoiceManager

public class PicovoiceManager { }

High-level Android binding for Picovoice platform. It handles recording audio from microphone, processes it in real-time, and notifies the client upon detection of the wake word or completion of in voice command inference.

PicovoiceManager.delete()

public void delete()

Releases resources acquired by PicovoiceManager.

PicovoiceManager.getVersion()

public String getVersion()

Getter for version.

Returns

• String: Current Picovoice version.

PicovoiceManager.getPorcupineVersion()

public String getPorcupineVersion()

Getter for the version of Porcupine.

Returns

• String: Current Porcupine version.

PicovoiceManager.getRhinoVersion()

public String getRhinoVersion()

Getter for the version of Rhino.

Returns

• String: Current Rhino version.

PicovoiceManager.getContextInformation()

public String getContextInformation()

Getter for Rhino context information.

Returns

• String: Returns the context information.

PicovoiceManager.start()

public void start() throws PicovoiceException

Starts recording audio from the microphone and processes using Picovoice.

Throws

• PicovoiceException : If an error occurs while starting audio capture.

PicovoiceManager.stop()

public void stop() throws PicovoiceException

Stops recording audio from the microphone.

Throws

• PicovoiceException : If an error occurs while stopping audio capture.

PicovoiceManager.reset()

public void reset() throws PicovoiceException

Resets the internal state of PicovoiceManager. It can be called to return to the wake word detection state before an inference has completed.

Throws

• PicovoiceException : If an error occurs while resetting.

PicovoiceManager.getContextInformation()

public String getContextInformation()

Getter for context information.

Returns

• String: Returns the context information.

PicovoiceManager.Builder

public static class Builder { }

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

PicovoiceManager.Builder.build()

public PicovoiceManager build(Context context) throws PicovoiceException

Creates an instance of PicovoiceManager.

Parameters

• context Context : The Android app context.

Returns

• PicovoiceManager: An instance of PicovoiceManager.

Throws

• PicovoiceException : If an error occurs while initializing.

PicovoiceManager.Builder.setAccessKey()

public PicovoiceManager.Builder setAccessKey(String accessKey)

Sets the AccessKey of the builder.

Parameters

• accessKey String : AccessKey obtained from Picovoice Console.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setPorcupineModelPath()

public PicovoiceManager.Builder setPorcupineModelPath(String porcupineModelPath)

Sets the Porcupine model path of the builder.

Parameters

• porcupineModelPath String : Path to the file containing the Porcupine 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

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setKeywordPath()

public PicovoiceManager.Builder setKeywordPath(String keywordPath)

Sets the Porcupine keyword path of the builder.

Parameters

• keywordPath String : Path to the file containing the Porcupine keyword model (.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

• PicovoiceManager.Builder: The instance of PicovoiceManager.Builder object.

PicovoiceManager.Builder.setPorcupineSensitivity()

public PicovoiceManager.Builder setPorcupineSensitivity(float porcupineSensitivity)

Sets Porcupine's keyword 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.

Parameters

• porcupineSensitivity float : Sensitivity for detecting keyword.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setWakeWordCallback()

public PicovoiceManager.Builder setWakeWordCallback(PicovoiceWakeWordCallback wakeWordCallback)

Sets the wake word callback object of the builder.

Parameters

• wakeWordCallback PicovoiceWakeWordCallback : Invoked when Porcupine has detected the wake word.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setRhinoModelPath()

public PicovoiceManager.Builder setRhinoModelPath(String rhinoModelPath)

Sets the Rhino model path of the builder.

Parameters

• rhinoModelPath String : Path to the file containing the Rhino 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

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setContextPath()

public PicovoiceManager.Builder setContextPath(String contextPath)

Sets the Rhino context path of the builder.

Parameters

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

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setRhinoSensitivity()

public PicovoiceManager.Builder setRhinoSensitivity(float rhinoSensitivity)

Sets Rhino's 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.

Parameters

• rhinoSensitivity float : Sensitivity for intent inference.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setInferenceCallback()

public PicovoiceManager.Builder setInferenceCallback(PicovoiceInferenceCallback inferenceCallback)

Sets the inference callback object of the builder.

Parameters

• inferenceCallback PicovoiceInferenceCallback : Invoked when Rhino has made an inference.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setEndpointDurationSec()

public Picovoice.Builder setEndpointDurationSec(float endpointDurationSec)

Sets the endpoint duration in seconds. An endpoint is a chunk of silence at the end of an utterance that marks the end of spoken command. It should be a positive number within [0.5, 5]. A lower endpoint duration reduces delay and improves responsiveness. A higher endpoint duration ensures Rhino doesn't return inference pre-emptively in case the user pauses before finishing the request.

Parameters

• endpointDurationSec float: Endpoint duration in seconds.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setRequireEndpoint()

public Picovoice.Builder setRequireEndpoint(boolean requireEndpoint)

Sets requireEndpoint of the Builder. If set to true, Rhino requires an endpoint (a chunk of silence) after the spoken command. If set to false, Rhino tries to detect silence, but if it cannot, it still will provide inference regardless. Set to false only if operating in an environment with overlapping speech (e.g. people talking in the background).

Parameters

• requireEndpoint boolean: Indicates whether an endpoint is required for Rhino to finish inference.

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceManager.Builder.setProcessErrorCallback()

public PicovoiceManager.Builder setProcessErrorCallback(PicovoiceManagerErrorCallback errorCallback)

Sets errorCallback of the builder.

Parameters

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

Returns

• PicovoiceManager.Builder: Modified PicovoiceManager.Builder object.

PicovoiceWakeWordCallback

public interface PicovoiceWakeWordCallback {
    void invoke();
}

Callback interface invoked when a keyword has been detected.

PicovoiceInferenceCallback

public interface PicovoiceInferenceCallback {
    void invoke(RhinoInference inference);
}

Callback interface invoked when inference has been finalized.

Parameters

• inference RhinoInference : Object containing Rhino inference data.

PicovoiceManagerErrorCallback

public interface PicovoiceManagerErrorCallback {
    void invoke(PicovoiceException error);
}

Callback interface invoked when an error occurs while processing audio.