angularPorcupine - Angular API

  • Wake Word Engine
  • Offline Voice Commands
  • Local Speech Recognition
  • Always Listening
  • npm

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

Requirements

  • yarn (or npm)

Compatibility

  • Chrome, Edge
  • Firefox
  • Safari

The Picovoice SDKs for Web are powered by WebAssembly (WASM), the Web Audio API, and Web Workers.

All modern browsers (Chrome/Edge/Opera, Firefox, Safari) are supported, including on mobile. Internet Explorer is not supported.

Using the Web Audio API requires a secure context (HTTPS connection), with the exception of localhost, for local development.

Installation

Use npm or yarn to install the package and its peer dependencies. Each spoken language (e.g. 'en', 'de') is a separate package. For this example we'll use English:

yarn add @picovoice/porcupine-web-angular @picovoice/porcupine-web-en-worker

(or)

npm install @picovoice/porcupine-web-angular @picovoice/porcupine-web-en-worker

Language-specific Porcupine web worker packages

These worker packages are compatible with the Angular SDK:

Usage

The Porcupine SDK for Angular is based on the Porcupine SDK for Web. The library provides an Angular service called PorcupineService. The package will take care of microphone access and audio downsampling (via @picovoice/web-voice-processor) and provide a wake word detection event to which your application can subscribe.

In your Angular component, add the PorcupineService. The PorcupineService has a detection event to which you can subscribe:

import { Subscription } from "rxjs"
import { PorcupineService } from "@picovoice/porcupine-web-angular"
...
constructor(private porcupineService: PorcupineService) {
// Subscribe to Porcupine Keyword detections
// Store each detection so we can display it in an HTML list
this.porcupineDetection = porcupineService.detection$.subscribe(
keywordLabel => console.log(`Porcupine Detected "${keywordLabel}"`))
}

We need to initialize Porcupine to tell it which keywords we want to listen to (and at what sensitivity). We can use the Angular lifecycle hooks ngOnInit and ngOnDestroy to start up and later tear down the Porcupine engine.

Imports

You can use Porcupine by importing the worker package statically or dynamically. Static is more straightforward to implement, but will impact your initial bundle size with an additional ~2MB. Depending on your requirements, this may or may not be feasible. If you require a small bundle size, see dynamic importing below.

Static Import

import { PorcupineWorkerFactory as PorcupineWorkerFactoryEn } from "@picovoice/porcupine-web-en-worker"
async ngOnInit() {
// Initialize Porcupine Service
try {
await this.porcupineService.init(
PorcupineWorkerFactoryEn,
{ keywords: [
{ builtin: "Okay Google", sensitivity: 0.65 },
{ builtin: "Picovoice" }
]
})
console.log("Porcupine is now loaded and listening")
}
catch (error) {
console.error(error)
}
}
ngOnDestroy() {
this.porcupineDetection.unsubscribe()
this.porcupineService.release()
}

Dynamic Import

async ngOnInit() {
// Load Porcupine worker chunk with specific language model (large ~1-2MB chunk; dynamically imported)
const porcupineFactoryEn = (await import('@picovoice/porcupine-web-en-worker')).PorcupineWorkerFactory
// Initialize Porcupine Service
try {
await this.porcupineService.init(porcupineFactoryEn,
{ keywords: [
{ builtin: "Okay Google", sensitivity: 0.65 },
{ builtin: "Picovoice" }
]
})
console.log("Porcupine is now loaded and listening")
}
catch (error) {
console.error(error)
}
}
ngOnDestroy() {
this.porcupineDetection.unsubscribe()
this.porcupineService.release()
}

Upon mounting, the component will request microphone permission from the user, instantiate the audio stream, start up an instance of Porcupine, and listen for both "Picovoice" and "Okay Google". When the words are detected, they will be logged to the console.

The "Okay Google" word is listening at a sensitivity of 0.65, whereas "Picovoice" is using the default (0.5). Sensitivity is a value in the range [0,1] which controls the tradeoff between miss rate and false alarm.

Porcupine Service Parameters

Porcupine accepts an array of (or a single) PorcupineKeyword object argument(s) via the PorcupineServiceArgs

export type PorcupineServiceArgs = {
/** Keywords to listen for */
keywords: Array<PorcupineKeyword | string> | PorcupineKeyword | string;
/** Immediately start the microphone upon initialization? (defaults to true) */
start?: boolean;
};

PorcupineKeyword can be either PorcupineKeywordBuiltin or PorcupineKeywordCustom:

export type PorcupineKeywordBuiltin = {
/** Name of a builtin keyword for the specific language (e.g. "Grasshopper" for English, or "Ananas" for German) */
builtin: string
/** Value in range [0,1] that trades off miss rate for false alarm */
sensitivity?: number
}
EnglishFrenchGermanSpanish
  • "Americano"
  • "Blueberry"
  • "Bumblebee"
  • "Grapefruit"
  • "Grasshopper"
  • "Hey Google"
  • "Hey Siri"
  • "Jarvis"
  • "Okay Google"
  • "Picovoice"
  • "Porcupine"
  • "Terminator"
  • "Framboise"
  • "Mon Chouchou"
  • "Parapluie"
  • "Perroquet"
  • "Tournesol"
  • "Ananas"
  • "Heuschrecke"
  • "Himbeere"
  • "Leguan"
  • "Stachelschwein"
  • "Emparedado"
  • "Leopardo"
  • "Manzana"
  • "Murcielago"

If you simply pass a string of a builtin keyword instead of an object, that will also work.

Use PorcupineKeywordCustom for custom keywords:

export type PorcupineKeywordCustom = {
/** Base64 representation of a trained Porcupine keyword (`.ppn` file) */
base64: string
/** An arbitrary label that you want Porcupine to report when the detection occurs */
custom: string
/** Value in range [0,1] that trades off miss rate for false alarm */
sensitivity?: number
}

Custom Wake Words

You can create custom wake word models using Picovoice Console. Making Porcupine wake word models for the Web platform requires an Enterprise account.


Issue with this doc? Please let us know.