Documentation

Background Voice Cancellation Integration

Suggest Edits

For more information about the BVC Technology, please refer to our SDK Features section.

BVC Integration in JS

Once Krisp JS SDK is setup, there are a few steps to follow in order to start using BVC.

Step 1. Configure KrispSDK to use BVC

To use BVC you should adjust KrispSDK params on creation. There are few options to configure:

const sdk = new KrispSDK({
  params: {
    useBVC: true, // This flag indicates if you want to use BVC or not**
    models: {
      // Please find the models in the Krisp SDK Portal (https://sdk.krisp.ai)
      modelBVC: "/dist/models/model_bvc.kef", // Add BVC model url (provided with the sdk)**
      model8: "/dist/models/model_8.kef",
      modelNC: "/dist/models/model_nc.kef",
    },
    // specify the url of the bvc allowed device list (provided with the sdk)**
    bvc: {
      allowedDevices: "/dist/assets/bvc-allowed.txt", // This is mandatory
    },
  },
});

Step 2. Pass audio stream while creating noiseFilterNode

After configuring KrispSDK you have to pass an audio stream while creating the noise filter

const audioSettings = {
  audio: {
    echoCancellation: false,
    noiseSuppression: false,
    autoGainControl: false
  }
};

const stream = await navigator.mediaDevices.getUserMedia(audioSettings);

const noiseFilterNode = await krispSDK.createNoiseFilter(
  {
    audioContext,
    stream
  },
  () => {}, // onReady: triggered when Noise Filter initialzied
  () => {}  // onDispose: triggered when Noise Filter disposed
);

Additional APIs

Modify BVC allowed device list if necessary

In case you want to use BVC with devices, which are out of the default allowed list, you can add them in two ways:

  1. By passing external txt file containing allowed devices list
  2. By adding devices in runtime

Adding external file

Creating an external file of allowed devices and passing it trough configuration during initialization under the params.bvc.allowedDevicesExt property.

This option is good for cases, when you have some devices, that should always run with BVC prior your business needs. 

const krispSDK = new KrispSDK({
  params: {
    //...
    bvc: {
      allowedDevices: "/dist/assets/bvc-allowed.txt", // This is mandatory
      allowedDevicesExt: "/dist/assets/bvc-allowed-ext.txt" //This is optional
    },
  },
});

Adding devices in runtime

The other option is adding allowed devices in the runtime. For that you can use KrispSDK.BVC.add(deviceName: string, force?: boolean)

krispSDK.BVC.add("Device name", true);

The force argument will ensure that the usage of BVC with the added device is forced.

You can also remove the added device from the allow list in the runtime using KrispSDK.BVC.remove(deviceName: string)

krispSDK.BVC.remove("Device name");

This option can be used in cases, when you have to temporarily allow the remove a device to use BVC.

Check if BVC is enabled

You can check the state of BVC calling isBVCEnabled() method on the noiseFilterNode.

noiseFilterNode.isBVCEnabled()

This will return a boolean value indicating whether BVC is enabled or not.

Auto Mode (UserMedia class)

The auto mode feature has been introduced to simplify the integration process. Generally auto mode is an all-in-one UserMedia class which handles stream loading related functionality. In most cases, there is no need to deal with AudioContext and under the hood interfaces. This feature provides a new layer for those who simply need MediaStream for connecting dots together.

UserMedia class provides dynamic device switching: By calling the loadUserMedia function with different device parameters, you can dynamically switch between audio/video devices. The userMedia.stream object will automatically update to the corresponding tracks, eliminating the need to create a new stream. Additionally it will switch to default microphone in case selected device was unplugged or not available.

In case you need to obtain new stream every time you can switch singleStream flag to false. By setting it false you need to listen for ******************streamchange****************** event. You can find reference in autoMode example.

UserMedia class automatically enables Noise Cancellation: While calling userMedia.loadUserMedia(constraints, { enableOnceReady: boolean }) you can set enableOnceReady flag to automatically enable NC filter once filterNode is loaded.

Below is a simple usage of the UserMedia that you can copy/paste into your application and immediately start using


import UserMedia from '/dist/usermedia.mjs';

const userMedia = new UserMedia({
  singleStream: true,
});

await userMedia.initSDK({
    params: {
      useBVC: true,
      models: {
        // Pleease find the models in the Krisp SDK Portal (https://sdk.krisp.ai)
        modelBVC: {
          url: "/dist/models/model_bvc.kef",
          preload: true, // in case you want to preload model upfront you can use this structure
        },
        model8: "/dist/models/model_8.kef",
        modelNC: "/dist/models/model_nc.kef",
      },
      bvc: {
        allowedDevices: "/dist/assets/bvc-allowed.txt", // This is mandatory
      },
    },
});

await userMedia.loadUserMedia({ audio: true }, { enableOnceReady: true });

const audio = new Audio();
audio.srcObject = userMedia.stream; // contains noise-cancelled default microphone stream

userMedia.stream is a continuous stream that will contain the requested media source based on the props passed to the loadUserMedia function. You can call loadUserMedia per user request to switch through devices, and the userMedia.stream object will automatically update to the corresponding tracks. You do not need to recreate a new stream.

Cache SDK models

While initializing SDK instance there is a preload option, which tells SDK to preload and cache model during initialization. If you are planning to use BVC, this could be handy as BVC model is bigger than NC models and to save on network download time you can cache model upfront. Preloading is a one-time requirement, and subsequent model usage will rely on the cached version, unless caching functionality is explicitly disabled in the browser configuration.

const sdk = new KrispSDK({
  params: {
    models: {
      // Please find the models in the Krisp SDK Portal (https://sdk.krisp.ai)
      modelBVC: {
        url: "/dist/models/model_bvc.kef",
        preload: true // in case you want to preload model upfront you can use this structure
      }
    }
  },
});

Known Issues

  • (Only in Chrome) When "Echo Cancellation" option is selected, in some Chrome versions it’s processing aggressively and muffles speech. For better quality in case you are using headphones we recommend switching it off.
  • (Only in Chrome) When using the AudioElement playback method, there may be voice degradation (sounding cartoon-like) for about 10 seconds when switching between devices. In a real use case, no voice degradation was noticed while using WebRTC.
  • Randomly, after switching between built-in device microphones and headsets, there may be BVC quality degradation with secondary voices passing.

Updated 2 months ago