Getting Started

Noise Cancellation

C-Library Documentation

Check out the C functions and data structures here.

Example

The following example shows how to use the exposed functions. For more details, please refer to the sample apps.


// Initialize the SDK v6.x
if (krispAudioGlobalInit(workingPath) != 0) {
    std::cerr << "Failed to initialize SDK" << std::endl;
    return -1;
}

// Initialize the SDK v5.x
if (krispAudioGlobalInit(workingPath, 1) != 0) {
    std::cerr << "Failed to initialize SDK" << std::endl;
    return -1;
}

// Set the neural network model path
if (krispAudioSetModel(weightConfFilePath)) {
    std::cout << "Faied to set the weight file: " << weight_str << std::endl;
    return -1;
}


// Create audio session
KrispAudioSessionID noiseCancellerSession = krispAudioNcCreateSession(inputSampleRate, 
                                                                      outputSampleRate, 
                                                                      frameDuration, 
                                                                      modelName);
if (noiseCancellerSession == nullptr) {
    std::cerr << "Failed to create noise cancellation session for channel" << std::endl;
    return -1;
}

// For every audio frame, call this function to remove noise
krispAudioNcCleanAmbientNoiseInt16(noiseCancellerSession, 
                                   pFrameIn, 
                                   frameInSize, 
                                   pFrameOut, frameOutSize);


// Close the session and uninitalize the SDK
krispAudioNcCloseSession(noiseCancellerSession);
// Uninitalize the SDK
krispAudioGlobalDestroy();

Background Voice Cancellation

Device Requirements

Implementing the BVC integration requires detecting the connected audio device, matching against the allow/block lists tested by Krisp, and optionally comparing it to the local allow list.

Device ListDescription
Krisp allow listThese devices have been tested and approved by Krisp. You may safely enable BVC automatically.
Krisp block listThese devices have been tested and rejected by Krisp as they showed poor performance and quality. You are not recommended to enable BVC on these devices.
Local allow listIf the connected device is not in the allow or block list, you may still want to allow the user to enable BVC manually. Then, the app may maintain a local allow list for devices to look up for enabling BVC.

Recommended Pipeline

Example

The C++ styled pseudocode demonstrates the recommended way to use Krisp Audio SDK with BVC and regular NC models.

A new Krisp Audio SDK session on each device change should be created, assuming the following parameters.

  • Compatibility with the BVC model
  • If incompatible with BVC then the right NC model should be chosen for the given sampling rate of the device
/// read Krisp allow and block list and the local allow list
preload_krisp_allow_list();
preload_local_allow_list();
preload_krisp_block_list();

// preload the models into the memory
// BVC model
krispAudioSetModel(“hs.c6.f.s.de56df.kw”, "bvc-model-alias");
// NC full band model
krispAudioSetModel(“c6.f.s.ced125.kw”, "nc-fb-model-alias");
// NC wide band model
krispAudioSetModel(“c5.s.w.c9ac8f.kw”, "nc-wb-model-alias");
// NC narrow band model
krispAudioSetModel(“c5.n.s.20949d.kw”, "nc-nb-model-alias");

void on_device_change(DeviceID device) {
		if (current_session) {
				krispAudioNcCloseSession(current_session);
				current_session = 0;
		}
		current_session = create_session_for_device(device);
}

KrispSession create_session_for_device(DeviceID device) {
		if (sampling_rate_below_wide_band(device))
				return create_nc_session(device);
		if (is_headset(device)) {
				if (in_krisp_block_list(device))
						return create_nc_session(device);
				if (in_krisp_allow_list(device))
						return create_bvc_session(device);
				if (in_local_allow_list(device))
						return create_bvc_session(device);
				else {
						bool added;
						consider_add_local_allow_list(device, &added);
						if (added) {
								return create_bvc_session(device);
						}
				}
		}
		return create_nc_session(device);
}

KrispSession create_bvc_session(DeviceID device) {
		// TODO: handle sampling rates, frame duration parameters
		auto s = krispAudioNcCreateSession("bvc-model-alias");
		// TODO: handle error checking
		return s;
}

KrispSession create_nc_session(DeviceID device) {
		auto model_alias_c_str = choose_nc_model(device);
		// TODO: handle sampling rates, frame duration parameters
		auto s = krispAudioNcCreateSession(model_alias_c_str);
		// TODO: handle error checking
		return s;
}

const char * choose_nc_model(DeviceID device) {
		if (sampling_rate(device) > 16000)
				return "nc-fb-model-alias";
		else if (sampling_rate(device > 8000))
				return "nc-wb-model-alias";
		else
				return "nc-nb-model-alias";
}

void consider_add_local_allow_list(DeviceID device, bool &added) {
		// Ask the user to add the device to the local allow list
		// this could be interactive
		bool ask = ask_for_user_input();
		if (ask) {
				add_to_local_allow_list(device);
				added = true;
		} else {
				added = false;
		}
}

Integration

Below are the high level steps required for technical integration:

SDK initializationthe SDK library should be loaded and initialized before being used. The SDK occupies resources that should be released once the SDK is no longer needed.
Model initializationKrisp SDK ships with NC and BVC models. Each model has specific requirements for the device and the sampling rate. Each model should be initialized and loaded into the memory before it can be used.
Session creationIn order to use Krisp Audio SDK to process the sound stream a Session object should created. The Session creation is coupled to the loaded AI model which should be specified during the session creation process. The session object also requires the specification of the sampling rate and frame duration.
Frame processingFrame processing is done using the Session object which works only for the given sampling rate for the given frame duration using the loaded AI model.
Releasing the resources used by the sessionthe resources occupied by the session should be released once the session is no longer used.
Unloading the SDKthe resources loaded by the Krisp Audio SDK should be released once the SDK is no longer needed

ℹ️ Multiple sessions can be created and used at the same time
ℹ️ Each session can be processed in a different thread on another audio stream
❗The SDK should be unloaded only after the release of all sessions

The technical integration of Krisp Audio SDK should have the following sequence of invocation of Krisp Audio SDK functions:

Krisp Audio SDK functionDescription
1. krispAudioGlobalInitload resources required for the SDK
2. krispAudioSetModelload AI model into the memory
3. krispAudioNcCreateSessioncreate a session object for the given AI model, sampling rate, and frame duration. Multiple sessions can be created for different sampling rates and frame durations.
4. krispAudioNcCleanAmbientNoiseInt16process PCM16(16-bit integer) based audio frame by frame using the session object
5. krispAudioNcCleanAmbientNoiseFloatprocess 32-bit float based audio frame by frame using the session object
6. krispAudioNcCloseSessionrelease the resources of the session once it is no longer needed
7. krispAudioGlobalDestroyrelease the resources used by the SDK once it is no longer needed