README.md

Web Voice Processor

Made in Vancouver, Canada by Picovoice

A library for real-time voice processing in web browsers.

• Uses the Web Audio API to access microphone audio.

• Leverages Web Workers to offload compute-intensive tasks off of the main thread.

• Converts the microphone sampling rate to 16kHz, the de facto standard for voice processing engines.

• Provides a flexible interface to pass in arbitrary voice processing workers.

• Web Voice Processor

  • Browser compatibility
    • Browser features
  • Installation
  • How to use
    • Via ES Modules (Create React App, Angular, Webpack, etc.)
    • Via HTML script tag
    • Start listening
    • Stop listening
  • Build from source

Browser compatibility

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.

This library includes the utility function browserCompatibilityCheck which can be used to perform feature detection on the current browser and return an object indicating browser capabilities.

ESM:

import { browserCompatibilityCheck } from '@picovoice/web-voice-processor';
browserCompatibilityCheck();

IIFE:

window.WebVoiceProcessor.browserCompatibilityCheck();

Browser features

• '_picovoice' : whether all Picovoice requirements are met
• 'AudioWorklet' (not currently used; intended for the future)
• 'isSecureContext' (required for microphone permission for non-localhost)
• 'mediaDevices' (basis for microphone enumeration / access)
• 'WebAssembly' (required for all Picovoice engines)
• 'webKitGetUserMedia' (legacy predecessor to getUserMedia)
• 'Worker' (required for resampler and for all engine processing)

Installation

npm install @picovoice/web-voice-processor

(or)

yarn add @picovoice/web-voice-processor

How to use

Via ES Modules (Create React App, Angular, Webpack, etc.)

import { WebVoiceProcessor } from '@picovoice/web-voice-processor';

Via HTML script tag

Add the following to your HTML:

<script src="@picovoice/web-voice-processor/dist/iife/index.js"></script>

The IIFE version of the library adds WebVoiceProcessor to the window global scope.

Start listening

WebVoiceProcessor follows the subscribe/unsubscribe pattern. WebVoiceProcessor will automatically start recording audio as soon as an engine is subscribed.

const worker = new Worker('${WORKER_PATH}');
const engine = {
  onmessage: function(e) {
    /// ... handle inputFrame
  }
}

await WebVoiceProcessor.subscribe(engine);
await WebVoiceProcessor.subscribe(worker);
// or
await WebVoiceProcessor.subscribe([engine, worker]);

An engine is either a Web Workers or an object implementing the following interface within their onmessage method:

onmessage = function (e) {
    switch (e.data.command) {
        case 'process':
            process(e.data.inputFrame);
            break;
    }
};

where e.data.inputFrame is an Int16Array of frameLength audio samples.

For examples of using engines, look at src/engines.

This is async due to its Web Audio API microphone request. The promise will be rejected if the user refuses permission, no suitable devices are found, etc. Your calling code should anticipate the possibility of rejection. When the promise resolves, the WebVoiceProcessor is running.

Stop Listening

Unsubscribing the engines initially subscribed will stop audio recorder.

await WebVoiceProcessor.unsubscribe(engine);
await WebVoiceProcessor.unsubscribe(worker);
//or
await WebVoiceProcessor.unsubscribe([engine, worker]);

Reset

Use the reset function to remove all engines and stop recording audio.

await WebVoiceProcessor.reset();

Options

To update the audio settings in WebVoiceProcessor, use the setOptions function:

// Override default options
let options = {
  frameLength: 512,
  outputSampleRate: 16000,
  deviceId: null,
  filterOrder: 50,
};

WebVoiceProcessor.setOptions(options);

Custom Recorder Processor

NOTE: Issues related to custom recorder processor implementations are out of the scope of this repo.

Take a look at recorder_processor.js in this repo as a reference on how to create a simple recorder processor. To learn more about creating a recorder processor, check out AudioWorkletProcessor docs.

Add the option customRecorderProcessorURL to options object to use your own recorder processor. Enter the string to the custom recorder processor URL or leave it blank to use the default recorder processor.

// Override default options
let options = {
  frameLength: 512,
  outputSampleRate: 16000,
  deviceId: null,
  filterOrder: 50,
  customRecorderProcessorURL: "${URL_PATH_TO_RECORDER_PROCESSOR}"
};

WebVoiceProcessor.setOptions(options);

VuMeter

WebVoiceProcessor includes a built-in engine which returns the VU meter. To capture the VU meter value, create a VuMeterEngine instance and subscribe it to the engine:

function vuMeterCallback(dB) {
  console.log(dB)
}

const vuMeterEngine = new VuMeterEngine(vuMeterCallback);
WebVoiceProcessor.subscribe(vuMeterEngine);

The vuMeterCallback should expected a number in terms of dBFS within the range of [-96, 0].

Build from source

Use yarn or npm to build WebVoiceProcessor:

yarn
yarn build

(or)

npm install
npm run-script build

The build script outputs minified and non-minified versions of the IIFE and ESM formats to the dist folder. It also will output the TypeScript type definitions.