DOCSEARCHbyAlgolia
Submit Docs

Picovoice Web Voice Processor

repository·master·Indexed 42 days ago

https://github.com/picovoice/web-voice-processor

A library for real-time voice processing in web browsers (version 4.0.10). It manages microphone access via the Web Audio API, resamples audio to 16kHz using a WASM-based engine, and offloads computation to Web Workers. Features include a built-in VuMeterEngine for volume visualization, browser compatibility checks, and the ability to capture raw signed 16-bit PCM audio dumps.

Tokens
4.2K
Snippets
21
Records
28
Agent score
53%

What's inside Web Voice Processor

  2. Dump and download raw PCM audio data

    master

    The WebVoiceProcessor includes an audio dump feature that allows you to capture the raw PCM data processed by the resampler.

    To use this feature in the demo:

    1. Click the "Start Audio Dump" button.
    2. Once the processor is ready, click "Download raw PCM" to save the captured data.

    File Specifications:

    • Format: Signed 16-bit PCM
    • Sample Rate: 16000Hz
    • Recommended Tool: Audacity (or similar audio editors) to open and inspect the file.

  3. Start listening to audio

    master

    WebVoiceProcessor uses a subscribe/unsubscribe pattern. Audio recording starts automatically as soon as an engine is subscribed.

    An engine can be a Web Worker or an object implementing an onmessage method that handles a process command. The inputFrame provided in the message is an Int16Array of audio samples.

    Note: subscribe is asynchronous because it requests microphone access via the Web Audio API. You should handle potential rejections (e.g., user denied permission).

    const worker = new Worker('${WORKER_PATH}');
const engine = {
  onmessage: function(e) {
    switch (e.data.command) {
        case 'process':
            process(e.data.inputFrame);
            break;
    }
  }
}

// Subscribe a single engine and a worker
await WebVoiceProcessor.subscribe(engine);
await WebVoiceProcessor.subscribe(worker);

// Or subscribe multiple engines at once
await WebVoiceProcessor.subscribe([engine, worker]);

  4. Install and run the WebVoiceProcessor demo

    master

    To run the local demonstration environment, use yarn or npm to install dependencies and then execute the start script. The demo hosts a local web server that provides a real-time VU meter responding to microphone volume.

    1. Install dependencies: yarn or npm install
    2. Start the server: yarn start or npm start
    3. Access the demo at http://localhost:5000 (or the address specified in your terminal output).
    yarn
yarn start

  5. Configure WebVoiceProcessor options

    master

    Use setOptions to override default audio settings.

    Available options include:

    • frameLength: The length of the audio frame.
    • outputSampleRate: The target sampling rate (default is 16000).
    • deviceId: The specific microphone device ID to use.
    • filterOrder: The order of the filter.
    • customRecorderProcessorURL: A string URL to a custom AudioWorkletProcessor.
    // Override default options
let options = {
  frameLength: 512,
  outputSampleRate: 16000,
  deviceId: null,
  filterOrder: 50,
  customRecorderProcessorURL: "${URL_PATH_TO_RECORDER_PROCESSOR}"
};

WebVoiceProcessor.setOptions(options);

  6. Use the built-in VuMeter engine

    master

    The library provides a VuMeterEngine to capture real-time volume levels. The callback receives a number representing the level in dBFS within the range of [-96, 0].

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

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

  7. Stop listening and reset the processor

    master

    To stop recording, unsubscribe the engines that were previously subscribed. To completely remove all engines and stop the audio recorder, use the reset method.

    // Stop listening by unsubscribing specific engines
await WebVoiceProcessor.unsubscribe(engine);
await WebVoiceProcessor.unsubscribe([engine, worker]);

// Stop everything and remove all engines
await WebVoiceProcessor.reset();

  8. Check browser compatibility

    master

    Use the browserCompatibilityCheck utility to perform feature detection. This returns an object indicating whether the current browser meets the requirements for Picovoice engines, such as WebAssembly, Worker, and isSecureContext (required for microphone access on non-localhost origins).

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

    If using the IIFE version:

    window.WebVoiceProcessor.browserCompatibilityCheck();

  9. Configure WebVoiceProcessorOptions

    master

    When initializing the Web Voice Processor, you can provide a WebVoiceProcessorOptions object to customize audio processing parameters.

    Key options include:

    • frameLength: The size of PCM frames. Defaults to 512.
    • outputSampleRate: The target sample rate for conversion. Defaults to 16000.
    • deviceId: The specific microphone ID to use. This can be retrieved using mediaDevices.enumerateDevices(). Pass null to use the default device.
    • filterOrder: The order of the filter used for resampling. Defaults to 50.
    • customRecorderProcessorURL: A URL pointing to a custom-made recorder processor.
    const options: WebVoiceProcessorOptions = {
  frameLength: 512,
  outputSampleRate: 16000,
  deviceId: 'some-device-id',
  filterOrder: 50,
  customRecorderProcessorURL: '/path/to/processor.js'
};

  10. Handle WebVoiceProcessor errors

    master

    The library throws WvpError instances for specific failure scenarios. You can catch these to provide user-friendly feedback regarding microphone permissions or hardware issues.

    Common error names:

    • PermissionError: Microphone permissions were denied by the user.
    • DeviceMissingError: No audio recording device was found.
    • DeviceReadError: The audio recording device is not working correctly.
    • DeviceDisabledError: Audio recording is not allowed or disabled in the browser (e.g., navigator.mediaDevices is undefined).
    • InvalidEngine: The provided engine does not meet the required interface (missing postMessage or onmessage).
    try {
  await WebVoiceProcessor.subscribe(engine);
} catch (error) {
  if (error instanceof WvpError) {
    if (error.name === 'PermissionError') {
      console.error('Please enable microphone access.');
    } else if (error.name === 'DeviceMissingError') {
      console.error('No microphone found.');
    }
  }
}

  11. Record an audio dump for a specific duration

    master

    Use WebVoiceProcessor.audioDump(durationMs) to record a raw signed 16-bit PCM audio clip for a specified number of milliseconds. This method returns a Blob containing the recorded data. This is useful for capturing samples for debugging or external processing.

    // Record for 5 seconds
const audioBlob = await WebVoiceProcessor.audioDump(5000);