@picovoice/porcupine-angular
v3.0.3
Published
Angular service for Porcupine Web SDK
Downloads
221
Readme
Porcupine Binding for Angular
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
Restrictions
IndexedDB and WebWorkers are required to use Porcupine Angular
. Browsers without support (i.e. Firefox Incognito Mode)
should use the PorcupineWeb binding
main thread method.
Installation
Package
Using Yarn
:
yarn add @picovoice/porcupine-angular @picovoice/web-voice-processor
or using npm
:
npm install --save @picovoice/porcupine-angular @picovoice/web-voice-processor
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 pass model files and 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}
The same procedure can be used for the custom keyword files (.ppn
) files.
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 ${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
The same procedure can be used for the custom keyword files (.ppn
) files.
Porcupine Model
Porcupine saves and caches your parameter model file (.pv
) 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.
If the model file changes, version
should be incremented to force the cached models to be updated.
Either base64
or publicPath
must be set to instantiate Porcupine. If both are set, Porcupine will use the base64
model.
// Model (.pv)
const porcupineModel = {
publicPath: ${MODEL_RELATIVE_PATH},
// or
base64: ${MODEL_BASE64_STRING},
// Optional
customWritePath: 'custom_model',
forceWrite: true,
version: 1,
}
Initialize Porcupine
First subscribe to the events from PorcupineService
. There are four
subscription events:
keywordDetection$
: Returns the detected keyword.isLoaded$
: Returns true ifPorcupine
has loaded successfully.isListening$
: Returns true ifWebVoiceProcessor
has started successfully.error$
: Returns any errors occurred.
import { Subscription } from "rxjs"
import { PorcupineService } from "@picovoice/porcupine-angular"
...
constructor(private porcupineService: PorcupineService) {
this.keywordSubscription = porcupineService.keywordDetection$.subscribe(
porcupineDetection => {
console.log(`Porcupine Detected "${porcupineDetection.label}"`)
});
this.isLoadedSubscription = porcupineService.isLoaded$.subscribe(
isLoaded => {
console.log(isLoaded);
});
this.isListeningSubscription = porcupineService.isListening$.subscribe(
isListening => {
console.log(isListening);
});
this.errorSubscription = porcupineService.error$.subscribe(
error => {
console.error(error);
});
}
After setting up the subscriber events, initialize Porcupine
:
import {BuiltInKeyword} from '@picovoice/porcupine-web';
async ngOnInit() {
await this.porcupineService.init(
${ACCESS_KEY},
[BuiltInKeyword.Porcupine],
porcupineModel,
);
}
Process Audio Frames
Run the following to start wake word detection:
await this.porcupineService.start();
The results are available on porcupineService.keywordDetection$
as mentioned above.
To stop wake word detection run:
await this.porcupineService.stop();
Clean Up
Clean up used resources with:
ngOnDestroy(): void {
this.keywordSubscription.unsubscribe();
this.isLoadedSubscription.unsubscribe();
this.isListeningSubscription.unsubscribe();
this.errorSubscription.unsubscribe();
this.porcupineService.release();
}
Custom Keywords
Create custom keywords using the Picovoice Console.
Train and download a Porcupine keyword model (.ppn
) for the target platform Web (WASM)
.
This model file can be used directly with publicPath
, but, if base64
is preferable, convert the .ppn
file to a base64
JavaScript variable using the built-in pvbase64
script:
npx pvbase64 -i ${KEYWORD_FILE}.ppn -o ${KEYWORD_BASE64}.js -n ${KEYWORD_BASE64_VAR_NAME}
Similar to the model file (.pv
), keyword files (.ppn
) are saved in IndexedDB to be used by Web Assembly.
Either base64
or publicPath
must be set for each keyword to instantiate Porcupine.
If both are set, Porcupine will use the base64
model.
An arbitrary label
is required to identify the keyword once the detection occurs.
// custom keyword (.ppn)
const keywordModel = {
publicPath: ${KEYWORD_RELATIVE_PATH},
// or
base64: ${KEYWORD_BASE64_STRING},
label: ${KEYWORD_LABEL},
// Optional
customWritePath: 'custom_keyword',
forceWrite: true,
version: 1,
}
Then, initialize porcupineService
:
await this.porcupineService.init(
${ACCESS_KEY},
keywordModel,
porcupineModel,
);
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 Angular Demo application.