rustPorcupine - Rust API

  • End-to-End Voice Platform
  • Offline Voice Recognition
  • Local Speech Recognition
  • Speech-to-Intent
  • Domain-Specific NLU
  • Wake Word Detection
  • Raspberry Pi
  • BeagleBone
  • NVIDIA Jetson
  • Linux
  • macOS
  • Windows
  • Rust

This document outlines how to integrate the Porcupine wake word engine within an application using its Rust API.

Requirements

  • Rust 1.54+
  • Cargo

Compatibility

  • Linux (x86_64)
  • macOS (x86_64)
  • Windows (x86_64)
  • Raspberry Pi (all variants)
  • NVIDIA Jetson (Nano)
  • BeagleBone.

Installation

You can install the latest version of Porcupine into your Rust crate by adding pv_porcupine into your Cargo.toml:

[dependencies]
pv_porcupine = "*"

Usage

To create an instance of the engine you first create a PorcupineBuilder instance with the configuration parameters for the wake word engine and then make a call to .init():

use porcupine::{BuiltinKeywords, PorcupineBuilder};
let porcupine: Porcupine = PorcupineBuilder::new_with_keywords(&[BuiltinKeywords::Porcupine]).init().expect("Unable to create Porcupine");

In the above example, we've initialized the engine to detect the built-in wake word "Porcupine". Built-in keywords are contained in the package with the BuiltinKeywords enum type.

Porcupine can detect multiple keywords concurrently:

let porcupine: Porcupine = PorcupineBuilder::new_with_keywords(&[BuiltinKeywords::Porcupine, BuiltinKeywords::Blueberry, BuiltinKeywords::Bumblebee])
.init().expect("Unable to create Porcupine");

To detect custom keywords, use PorupineBuilder's new_with_keyword_paths method to pass in *.ppn file paths instead:

let porcupine: Porcupine = PorcupineBuilder::new_with_keyword_paths(&["/absolute/path/to/keyword/one.ppn", "/absolute/path/to/keyword/two.ppn"])
.init().expect("Unable to create Porcupine");

The language can be changed by passing in an appropriate *.pv file path into the model_path method:

let porcupine: Porcupine = PorcupineBuilder::new_with_keyword_paths(&["/absolute/path/to/keyword/one.ppn"])
.model_path("/path/to/another/language_params.pv")
.init().expect("Unable to create Porcupine");

The sensitivity of the engine can be tuned per keyword using the sensitivities method:

let porcupine: Porcupine = PorcupineBuilder::new_with_keywords(&[BuiltinKeywords::Porcupine, BuiltinKeywords::Bumblebee])
.sensitivities(&[0.2f32, 0.42f32])
.init().expect("Unable to create Porcupine");

Sensitivity is the parameter that enables trading miss rate for the false alarm rate. It is a floating point number within [0, 1]. A higher sensitivity reduces the miss rate at the cost of increased false alarm rate.

When initialized, the valid sample rate is given by sample_rate(). Expected frame length (number of audio samples in an input array) is given by frame_length().

To feed audio into Porcupine, use the process function in your capture loop:

fn next_audio_frame() -> Vec<i16> {
// get audio frame
}
loop {
if let Ok(keyword_index) = porcupine.process(&next_audio_frame()) {
if keyword_index >= 0 {
// wake word detected!
}
}
}

Custom Wake Word

You can create custom Porcupine wake word models using Picovoice Console.

Non-English Wake Words

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.


Issue with this doc? Please let us know.