Porcupine Binding for Web

Porcupine wake word engine

Made in Vancouver, Canada by Picovoice

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

Compatibility

• Chrome / Edge
• Firefox
• Safari

Installation

Package

Using Yarn:

yarn add @picovoice/porcupine-web

or using npm:

npm install --save @picovoice/porcupine-web

AccessKey

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.

Usage

There are two methods to initialize Porcupine:

Public Directory

NOTE: Due to modern browser limitations of using a file URL, this method does not work if used without hosting a server.

This method fetches the model file from the public directory and feeds it to Porcupine. Copy the model file into the public directory:

cp ${PORCUPINE_MODEL_FILE} ${PATH_TO_PUBLIC_DIRECTORY}

Base64

NOTE: This method works without hosting a server, but increases the size of the model file roughly by 33%.

This method uses a base64 string of the model file and feeds it to Porcupine. Use the built-in script pvbase64 to base64 your model file:

npx pvbase64 -i ${PORCUPINE_MODEL_FILE} -o ${OUTPUT_DIRECTORY}/${MODEL_NAME}.js

The output will be a js file which you can import into any file of your project. For detailed information about pvbase64, run:

npx pvbase64 -h

Init options

Porcupine saves and caches your model file in IndexedDB to be used by Web Assembly. Use a different customWritePath variable to hold multiple model values and set the forceWrite value to true to force re-save the model file. Set processErrorCallback to handle errors if an error occurs while transcribing. If the model file (.pv) changes, version should be incremented to force the cached model to be updated.

// these are default
const options = {
  processErrorCallback: (error) => {
  },
  customWritePath: "porcupine_model",
  forceWrite: false,
  version: 1
}

Initialize in Main Thread

Create a keywordDetectionCallback function to get the results from the engine:

function keywordDetectionCallback(keyword) {
  console.log(`Porcupine detected keyword: ${keyword.label}`);
}

Add to the options object an processErrorCallback function if you would like to catch errors:

function processErrorCallback(error: string) {
...
}
options.processErrorCallback = processErrorCallback;

Use Porcupine to initialize from public directory:

const handle = await Porcupine.fromPublicDirectory(
  ${ACCESS_KEY},
  PorcupineWeb.BuiltInKeyword.Porcupine,
  ${MODEL_RELATIVE_PATH},
  options // optional options
);

or initialize using a base64 string:

import porcupineParams from "${PATH_TO_BASE64_PORCUPINE_PARAMS}";

const handle = await Porcupine.fromBase64(
  ${ACCESS_KEY},
  PorcupineWeb.BuiltInKeyword.Porcupine,
  porcupineParams,
  options // optional options
)

Process Audio Frames in Main Thread

The result is received from keywordDetectionCallback as mentioned above.

function getAudioData(): Int16Array {
... // function to get audio data
  return new Int16Array();
}

for (; ;) {
  await handle.process(getAudioData());
  // break on some condition
}

Initialize in Worker Thread

Create a keywordDetectionCallback function to get the streaming results from the worker:

function keywordDetectionCallback(keywordIndex) {
  console.log(`Porcupine detected keyword index: ${keyword}`);
}

Add to the options object an processErrorCallback function if you would like to catch errors:

function processErrorCallback(error: string) {
...
}

options.processErrorCallback = processErrorCallback;

Use PorcupineWorker to initialize from public directory:

const handle = await PorcupineWorker.fromPublicDirectory(
  ${ACCESS_KEY},
  PorcupineWeb.BuiltInKeyword.Porcupine,
  keywordDetectionCallback,
  ${MODEL_RELATIVE_PATH},
  options // optional options
);

or initialize using a base64 string:

import porcupineParams from "${PATH_TO_BASE64_PORCUPINE_PARAMS}";

const handle = await Porcupine.fromBase64(
  ${ACCESS_KEY},
  PorcupineWeb.BuiltInKeyword.Porcupine,
  keywordDetectionCallback,
  porcupineParams,
  options // optional options
)

Process Audio Frames in Worker Thread

In a worker thread, the process function will send the input frames to the worker.

The result is received from keywordDetectionCallback as mentioned above.

function getAudioData(): Int16Array {
... // function to get audio data
  return new Int16Array();
}

for (; ;) {
  handle.process(getAudioData());
  // break on some condition
}
handle.flush(); // runs transcriptCallback on remaining data.

Clean Up

Clean up used resources by Porcupine or PorcupineWorker:

await handle.release();

Terminate

Terminate PorcupineWorker instance:

await handle.terminate();

Custom Keywords

Create custom keywords using the Picovoice Console. Train the Porcupine keyword model for the target platform WebAssembly (WASM). Inside the downloaded .zip file, there are two files:

• .ppn file which is the keyword model file in binary format
• _b64.txt file which contains the same binary model encoded with Base64

Similar to the model file (.pv), there are two ways to use a custom keyword model:

Public Directory

This method fetches the keyword model file from the public directory and feeds it to Porcupine. Copy the binary keyword model file (.ppn) into the public directory and then define a customWakeword object, in which the label property is set to the name of the keyword and the publicPath property is set to the path to the keyword model file.

const customWakeWord = {
    publicPath: ${PPN_MODEL_RELATIVE_PATH},
    label: ${CUSTOM_KEYWORD_LABEL}
  }, 
}

const handle = await Porcupine.fromPublicDirectory(
  ${ACCESS_KEY},
  [customWakeWord],
  ${MODEL_RELATIVE_PATH},
  options // optional options
);

Base64

Copy the base64 string and pass it as the base64 property of a customWakeword object. The label property indicates the name of the keyword.

const customWakeWord = {
  base64: ${CUSTOM_KEYWORD_BASE64_STRING},
  label: ${CUSTOM_KEYWORD_LABEL},
}

const handle = await Porcupine.fromPublicDirectory(
  ${ACCESS_KEY},
  [customWakeWord],
  ${MODEL_RELATIVE_PATH},
  options // optional options
);

Non-English Languages

In order to detect non-English wake words you need to use the corresponding model file (.pv). The model files for all supported languages are available here.

Demo

For example usage refer to our Web demo application.