HANCE API – C Interface

The C interface for the HANCE Audio Engine provides developers with simple access to HANCE's powerful algorithms and processing capabilities from all languages that offer bindings for standard C compatible libraries. The HANCE Audio Engine is a light-weight and cross-platform library, and it should be very easy to integrate it into your application. The library can load pre-trained AI models and use these for audio processing to perform various tasks.

The HANCE Audio Engine is delivered with general purpose models for noise reduction, de-reverberation and stem separation. These are designed to meet common requirements in terms of latency and CPU usage. However, we can train custom models for specific customer requirements. Please contact us for more information.

Getting Started

The HANCE API is designed to be as simple as possible. The ProcessFile example (see the Examples folder in the API) illustrates how to create a HANCE processor and process audio with it. CMake 3.22 or later is required to build the example. To build ProcessFile, open the terminal / command line prompt and locate the Examples/ProcessFile subfolder in the HANCE API. Now, please type "./Build.sh" on Mac or Linux, or "Build.bat" on Windows.

To use the HANCE API, we first need to make sure the "Include" in the HANCE API is added to the header search path and include the HanceEngine header file:

#include "HanceEngine.h"

Now we can create an instance of a HANCE processor by specifying a path to a HANCE model file along with the number of channels and sample rate to use:

// Create a HANCE processor that loads the pre-trained model from file
processorHandle = hanceCreateProcessor (modelFilePath, numOfChannels, sampleRate);
if (processorHandle == nullptr)
    handleError ("Unable to create the HANCE audio processor.");

The processor handle will be nullptr if the processor couldn't be created, e.g., because the model file path is invalid.

Now, we can add audio in floating point format to the HANCE processor. The HANCE API supports audio stored either as channel interleaved audio (hanceAddAudioInterleaved and hanceGetAudioInterleaved) or as separate channel vectors (hanceAddAudio and hanceGetAudio). We demonstrate how to add audio from a std::vector containing channel interleaved float values below:

// We read PCM audio from the file in the 32-bit floating point format
hanceAddAudioInterleaved (processorHandle, audioBuffer.data(),
                          audioBuffer.size() / numOfChannels);

The processing introduces latencies, so we need to query how many samples (if any) that are available before we can pick up the processed audio using hanceGetAudioInterleaved:

int numOfPendingSamples = hanceGetNumOfPendingSamples (processorHandle);
vector<float> processedBuffer (numOfChannels * numOfPendingSamples);
if (!hanceGetAudioInterleaved (processorHandle,
                               processedBuffer.data(),
                               numOfPendingSamples))
{
    handleError ("Unable to get audio from the HANCE audio processor.");
}

You can add silent audio (all values set to zero) to get the processing tail caused by the model's latency. When you have completed the processing of the audio stream, please make sure to delete the HANCE processor to free its memory:

hanceDeleteProcessor (processorHandle);

Busses and Parameter Settings

HANCE Engine models typically have two or more output busses that can be mixed together with adjustable gain and sensitivity settings. A typical noise or reverb reduction model will have clean speech as one output and noise or reverb as the second output bus. Stem separation models will have a separate output bus for each stem.

You can query the number of output busses that a model offers using hanceGetNumOfOutputBusses:

int numOfOutputBusses = hanceGetNumOfOutputBusses (g_processorHandle);

Furthermore, you can query the names of the individual output busses using the bus index ranging from 0 to the number of output busses minus one:

vector<char> nameBuffer (255, '\0');
hanceGetOutputBusName (g_processorHandle, busIndex, (char*) nameBuffer.data(), nameBuffer.size());
string outputBusName = nameBuffer.data();

You can set and get the gain or sensitivity of an output bus using hanceSetParameterValue or hanceGetParameterValue. Parameters are assigned to IDs and the parameter ID for the linear gain of the first output bus is HANCE_PARAM_BUS_GAINS. For the second output bus, the ID is HANCE_PARAM_BUS_GAINS + 1 and so forth.

The sensitivities are handled identically with ID of the sensitivity for the first output bus being HANCE_PARAM_BUS_SENSITIVITIES. Here's how to set the gain of the bus specified by busIndex to 1.f (no change in gain):

hanceSetParameterValue (g_processorHandle, HANCE_PARAM_BUS_GAINS + busIndex, 1.f);

Considerations

The HANCE Audio Engine is a light-weight and cross-platform library, and it can use the following libraries for vector arithmetic if available:

• Intel Performance Primitives
• Apple vDSP
• NEON Intrinsics

The HANCE Audio Engine reverts to pure C++ when no compatible vector arithmetic library is available.

Copyright (c) 2024 HANCE AS.