Porcupine is a highly accurate and lightweight wake word engine. It enables building always-listening voice-enabled applications using cutting edge voice AI.
Porcupine is:
- private and offline
- accurate
- resource efficient (runs even on microcontrollers)
- data efficient (wake words can be easily generated by simply typing them, without needing thousands of hours of bespoke audio training data and manual effort)
- scalable to many simultaneous wake-words / always-on voice commands
- cross-platform
To learn more about Porcupine, see the product, documentation, and GitHub pages.
Porcupine unity package is for running Porcupine on Unity 2021.3+ on the following platforms:
- Android 5.0+ (API 21+) (ARM only)
- iOS 13.0+
- Windows (x86_64)
- macOS (x86_64, arm64)
- Linux (x86_64)
The easiest way to install the Porcupine Unity SDK is to import porcupine-3.0.1.unitypackage into your Unity projects by either dropping it into the Unity editor or going to Assets>Import Package>Custom Package...
NOTE: On macOS, the Porcupine library may get flagged as having come from an unverified source if you've downloaded the .unitypackage directly from GitHub. This should only come up when running your project in the Editor. To disable this warning, go to Security & Preferences and choose to allow pv_porcupine.dylib to run.
Porcupine requires a valid Picovoice AccessKey at initialization. AccessKey acts as your credentials when using Porcupine SDKs.
You can get your AccessKey for free. Make sure to keep your AccessKey secret.
Signup or Login to Picovoice Console to get your AccessKey.
To build the package from source, first you have to clone the repo with submodules:
git clone --recurse-submodules git@github.com:Picovoice/porcupine.git
# or
git clone --recurse-submodules https://github.com/Picovoice/porcupine.gitYou then have to run the copy.sh file to copy the package resources from various locations in the repo to the Unity project located at /binding/unity (NOTE: on Windows, Git Bash or another bash shell is required, or you will have to manually copy the resources into the project.). Then, open the Unity project, right-click the Assets folder and select Export Package. The resulting Unity package can be imported into other Unity projects as desired.
The module provides you with two levels of API to choose from depending on your needs.
PorcupineManager provides a high-level API that takes care of audio recording. This class is the quickest way to get started.
NOTE: If running on iOS, you must fill in the Microphone Usage Description under Project Settings>Other Settings in order to enable audio recording.
Using the constructor PorcupineManager.FromBuiltInKeywords will create an instance of the PorcupineManager using one or more of the built-in keywords.
using Pv.Unity;
string accessKey = "${ACCESS_KEY}"; // // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
try {
List<Porcupine.BuiltInKeywords> keywords = new List<BuiltInKeywords>(){ Porcupine.BuiltInKeyword.PICOVOICE, Porcupine.BuiltInKeyword.PORCUPINE };
PorcupineManager _porcupineManager = PorcupineManager.FromBuiltInKeywords(
accessKey,
keywords,
OnWakeWordDetected);
}
catch (Exception ex)
{
// handle porcupine init error
}The wakeWordCallback parameter is a function that you want to execute when Porcupine has detected one of the keywords.
The function should accept a single integer, keywordIndex, which specifies which wake word has been detected.
private void OnWakeWordDetected(int keywordIndex){
if(keywordIndex == 0){
// picovoice detected
}
else if (keywordIndex === 1){
// porcupine detected
}
}Available built-in keywords are stored in the constants Porcupine.BuiltInKeyword.
To create an instance of PorcupineManager that detects custom keywords, you can use the PorcupineManager.FromKeywordPaths
static constructor and provide the paths to the .ppn file(s).
string accessKey = "${ACCESS_KEY}"; // // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
List<string> keywordPaths = new List<string>(){ "/path/to/keyword.ppn" };
PorcupineManager _porcupineManager = PorcupineManager.FromKeywordPaths(
accessKey,
keywordPaths,
OnWakeWordDetected);In addition to custom keywords, you can override the default Porcupine model file and/or keyword sensitivities, as well as add an error callback you want to trigger if there's a problem encountered while Porcupine is processing frames.
These optional parameters can be passed in like so:
string accessKey = "${ACCESS_KEY}"; // // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
List<string> keywordPaths = new List<string>()
{
"/path/to/keyword/file/one.ppn",
"/path/to/keyword/file/two.ppn"
};
string modelPath = "path/to/model/file.pv";
List<float> sensitivities = new List<float>(){ 0.25f, 0.6f };
PorcupineManager _porcupineManager = PorcupineManager.FromKeywordPaths(
accessKey,
keywordPaths,
OnWakeWordDetected,
modelPath: modelPath,
sensitivities: sensitivities,
errorCallback: OnError);
void OnError(Exception ex){
Debug.LogError(ex.ToString());
}Once you have instantiated a PorcupineManager, you can start audio capture and wake word detection by calling:
_porcupineManager.Start();And then stop it by calling:
_porcupineManager.Stop();Once the app is done with using an instance of PorcupineManager, you can explicitly release the audio resources and the resources allocated to Porcupine:
_porcupineManager.Delete();There is no need to deal with audio capture to enable wake word detection with PorcupineManager. This is because it uses our unity-voice-processor Unity package to capture frames of audio and automatically pass it to the wake word engine.
Porcupine provides low-level access to the wake word engine for those who want to incorporate wake word detection into an already existing audio processing pipeline.
To create an instance of Porcupine, use the .Create static constructor. You can pass a list of built-in keywords as its keywords argument or a list or paths to custom keywords using its keywordPaths argument.
using Pv.Unity;
string accessKey = "${ACCESS_KEY}"; // // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
try
{
List<Porcupine.BuiltInKeyword> keywords = new List<Porcupine.BuiltInKeyword>(){ Porcupine.BuiltInKeyword.PORCUPINE, Porcupine.BuiltInKeyword.PICOVOICE };
Porcupine _porcupine = Porcupine.FromBuiltInKeywords(accessKey: accessKey, keywords: keywords);
}
catch (Exception ex)
{
// handle porcupine init error
}To search for a keyword in audio, you must pass frames of audio to Porcupine using the Process function. The keywordIndex returned will either be -1 if no detection was made or an integer specifying which keyword was detected.
short[] frame = getAudioFrame();
try
{
int keywordIndex = _porcupine.Process(frame);
if (keywordIndex >= 0)
{
// detection made!
}
}
catch (Exception ex)
{
Debug.LogError(ex.ToString());
}For process to work correctly, the audio data must be in the audio format required by Picovoice.
The required sample rate is specified by the SampleRate property and the required number of audio samples in each frame is specified by the FrameLength property. Audio must be single-channel and 16-bit linearly-encoded.
Porcupine implements the IDisposable interface, so you can use Porcupine in a using block. If you don't use a using block, resources will be released by the garbage collector automatically, or you can explicitly release the resources like so:
_porcupine.Dispose();To add a custom wake word to your Unity app, you'll need to add it to your project root under /StreamingAssets. Then, in a script, retrieve them like so:
string keywordPath = Path.Combine(Application.streamingAssetsPath, "keyword.ppn");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.
The Porcupine Unity demo can be imported along with the SDK when you import the Porcupine Unity package. Browse the source of the demo here.