Porcupine Node.js Demos

This package provides two demonstration command-line applications for Porcupine: a file based demo, which scans a compatible WAV file for keywords, and a microphone demo, which listens for keywords and outputs detections live.

Introduction to Porcupine

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.

Compatibility

These demos run Porcupine on Node.js 12+ on the following platforms:

• Windows (x86_64)
• Linux (x86_64)
• macOS (x86_64, arm64)
• Raspberry Pi (3, 4, 5)

Web Browsers

These demos and the bindings upon which they are built are for Node.js and do not work in a browser. Looking to run Porcupine in-browser? See the @picovoice/porcupine-web-en-worker package.

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.

Microphone demo

The microphone demo allows you monitor microphone input for keywords using Porcupine.

Install NPM package

To install the demos and make them available on the command line, use either of the following yarn or npm commands:

yarn global add @picovoice/porcupine-node-demo

(or)

npm install -g @picovoice/porcupine-node-demo

Run the mic demo

Use ppn-mic-demo to run the mic demo. First select an input audio device to start recording audio:

ppn-mic-demo --show_audio_devices

This command prints a list of the available devices and its inputs:

index: 0, device name: USB Audio Device
index: 1, device name: MacBook Air Microphone

Specify the input audio device with --audio_device_index and either built-in keywords with --keywords or paths to Porcupine .ppn files with --keyword_file_paths. Provide your Picovoice AccessKey with --access_key.

Here is an example using Audio Device Index which will listen for "grapefruit" keyword:

ppn-mic-demo \
--access_key ${ACCESS_KEY} \
--keywords grapefruit \
--audio_device_index 0

Wake word detections will display in the console:

$ ppn-mic-demo --access_key ${ACCESS_KEY} --keywords grapefruit
Using device: USB Audio Device
Listening for wake word(s): grapefruit
Press ctrl+c to exit.

...

Detected 'grapefruit'

Run the file demo

The file-based demo allows you to scan a compatible wave file for keywords using Porcupine. Note: The demo requires 16KHz, 16-bit linear PCM, single-channel (mono) WAV files.

To run the file-based demo,

e.g. check the input wave file for the built-in keywords "grasshopper" and "bumblebee" against the audio sample that is included with the porcupine repository:

ppn-file-demo \
--access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords grasshopper,bumblebee

Detections of each keyword will be output in the terminal, along with their time location in the file:

ppn-file-demo \
--access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords grasshopper
Detected keyword 'bumblebee' @ 16.096s
Detected keyword 'grasshopper' @ 28.896s

Common Demo Options

The microphone and file demos both have additional options.

To see the full set of options, use --help:

ppn-mic-demo --help

ppn-file-demo --help

Usage: ppn-file-demo [options]

Options:
  -i, --input_audio_file_path <string>  input audio wave file in 16-bit 16KHz linear PCM format (mono)
  -a, --access_key <string>             AccessKey obtain from the Picovoice Console (https://console.picovoice.ai/)
  -k, --keyword_file_paths <string>     absolute path(s) to porcupine keyword files (.ppn)
  -b, --keywords <string>               built in keyword(s)
                                        (americano,blueberry,bumblebee,grapefruit,grasshopper,picovoice,porcupine,terminator)
  -l, --library_file_path <string>      absolute path to porcupine dynamic library
  -m, --model_file_path <string>        absolute path to porcupine model
  -s, --sensitivity <number>            sensitivity value between 0 and 1 (default: 0.5)
  -h, --help                            display help for command

Sensitivity

The sensitivity is a floating point value in the range [0,1] which specifies the tradeoff between miss rate and false alarm. The demo defaults to 0.5. You can override this with --sensitivity:

ppn-mic-demo \
--access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords bumblebee \
--sensitivity 0.65

Custom keyword (ppn) files

Porcupine includes several built-in keywords, which are stored as .ppn files. To train custom PPN files, see the Picovoice Console.

Unlike the built-in keywords, custom PPN files generated with the Picovoice Console carry restrictions including (but not limited to): training allowance, time limits, available platforms, and commercial usage.

Providing custom ppn files

You can specify non-builtin keywords as absolute paths to .ppn keyword files, using --keyword_file_paths. The PPN keyword files must be compatible with the platform you are running.

e.g. for Linux (x86_64), using two keywords: "bumblebee" and "grasshopper":

ppn-file-demo \
--access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keyword_file_paths ../../resources/keyword_files/linux/grasshopper_linux.ppn,../../resources/keyword_files/linux/bumblebee_linux.ppn

Custom library and model files

You may override the porcupine model and dynamic libraries by specifying their absolute paths with --model_file_path and --library_file_path, respectively. As with keyword files, the dynamic library is specific to the platform.

e.g. for macOS (x86_64, arm64):

ppn-file-demo \
--access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords terminator \
--library_file_path ../../lib/mac/x86_64/libpv_porcupine.dylib \
--model_file_path ../../lib/common/porcupine_params.pv

Running the demos from the GitHub repository

Use one of yarn or npm to install the package dependencies from the demo/nodejs folder:

cd demo/nodejs
yarn

(or)

cd demo/nodejs
npm install

Microphone demo

Use yarn mic (or npm run mic) to run the mic demo from the demos/nodejs directory. For npm run, note the extra -- needed before specifying commands. This is to disambiguate whether the options are intended for npm or for the demo script.

yarn mic --access_key ${ACCESS_KEY} --keywords grapefruit

(or)

npm run mic -- --access_key ${ACCESS_KEY} --keywords grapefruit

File demo

Use yarn file or npm run file from the demos/nodejs directory. For npm run, note the extra -- needed before specifying commands. This is to disambiguate whether the options are intended for npm or for the demo script.

yarn file --access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords grasshopper

(or)

npm run file -- --access_key ${ACCESS_KEY} \
--input_audio_file_path ../../resources/audio_samples/multiple_keywords.wav \
--keywords grasshopper