Welcome to the Hance APIs

Pushing the limits of audio enhancement

HANCE offers top-quality signal-processing techniques developed by machine learning specialists, sound engineers, and audio processing experts. Our technology is designed to provide users with the highest possible audio experience by removing noise, reverb, and other signal impairments. HANCE can also provide sound classification and signal recovery – all in realtime. 

The HANCE APIs are designed to make our cutting-edge algorithms accessible to everyone, regardless of their device or application. Our highly trainable and adaptable Web, Python, and C APIs, with more platforms to come, give developers all they need to get started. With CPU and memory efficiency in mind, the HANCE APIs allow easy access to our revolutionary audio algorithms without sacrificing performance.

The HANCE algorithms are built on a unique combination of deep learning and evolutionary computing techniques. This enables our systems to learn quickly, accurately, and efficiently from auditory data.

The HANCE team is excited to have you join us and looks forward to helping you get started. Please feel free to contact us with any questions or concerns about implementation. Our team is available to help as needed.

We thank you for your interest!

HANCE Web API

The HANCE Web API provides developers with a simple, programmatic interface to access HANCE’s powerful algorithms and processing capabilities. By making HTTP(S) requests to the HANCE Web API, developers can process audio files, explore the various processing modules HANCE offers, and find the best configuration for their needs.

The HANCE Web API offers developers a taste of the impressive results generated by the HANCE Audio Engine. However, it should be noted that this API does not demonstrate realtime processing. This is because files must be uploaded to the HANCE servers, processed, and downloaded to the user’s browser.

We recommend reviewing our <router-link to="/c">C++</router-link> and <router-link to="/python">Python</router-link> API documentation or contacting us directly if you are interested in exploring realtime audio processing or training custom models.

This document provides a comprehensive guide to the HANCE Web API, with endpoints, parameters, options, and JavaScript (ES6) code examples. It is designed to make learning the HANCE Web API quick, easy and fun.

Get Upload URL

To start uploading files from your code, request an upload ID and URL from the server. These will securely handle the file and ensure a successful upload.

Get Upload URL: JavaScript Code Example

// First, we store the address from "Important endpoint A" as a constant:
const URL_ID_ENDPOINT =
  "https://server.hance.ai/api/get_upload_url"

// Using ES6 syntax, this one-liner downloads and converts our data from JSON
// to native JavaScript objects.

const getData = async () => await (await fetch(URL_ID_ENDPOINT)).json()

getData()
  .then(({ upload_url, upload_id }) => {
    // Once the data is available, the .then() method will be called,
    // providing access to the upload_url and upload_id values. Here we would
    // typically place an upload function, passing in the now available data.

    // Do something here...

    // We are also returning the values so that they can be used in the next
    // steps.
    return { upload_url, upload_id }
  })
  .catch(console.error)

Get upload URL: query parameters

Get upload URL: setting the origin

// Alternative 1: Getting the origin from the current browser URL.
let origin = window.location.origin

// Alternative 2: Manually setting the origin.
let origin = "https://example.com"

// Add the origin defined in alternative 1 or 2 as a query parameter to the
// endpoint, using the encodeURI method for compatibility when used as a
// query parameter.
const URL_ID_ENDPOINT = `https://server.hance.ai/api/get_upload_url?origin=${encodeURI(origin)}`

Get upload URL: return values

Get models

The get_models endpoint provides a list of models you can select to process uploaded audio files. Each model addresses a certain audio-related problem, such as noise reduction, reverb attenuation, signal recovery and so forth.

Get models: example of returned JSON data

[
  {"model_description": "De-noise", "model_id": "speech-denoise"}, 
  {"model_description": "De-reverb", "model_id": "speech-dereverb"}
]

Get models: retrieving and selecting a model

// First, we store the address from Important endpoint B as a constant:
const MODELS_ENDPOINT =
  "https://server.hance.ai/api/get_models"

const getModelsData = async () => await (await fetch(MODELS_ENDPOINT)).json()

getModelsData()
  .then((models) => {
    // The array of objects is now available to the getModelData function
    // and ready to be utilized.

    // We can do something with the models data here. To check if we have
    // received the data, we log it to the console.
    console.dir(models)

    // We also return the models data so the values can be used in the next
    // .then() call, like in the example below.
    return models
  })
  .then((models) => console.log(models[1].model_id))//real_time_noise_reverb_v1
  .catch(console.error)

Get models: return values

Processing audio files

Once you have obtained the upload URL and unique ID, as explained in the Get upload URL section, and selected the appropriate model, we can upload audio files to HANCE’s servers. To do this, make a POST request to the generated upload URL and include some of the query parameters described below with the request.

Processing audio files: query parameters

Processing audio files: return values

The HANCE Web API will return a redirect to the enhanced file once it has completed processing. If the redirect argument is not specified or set to false, the API will return a URL pointing to the processed file instead. The request may take a while to complete, depending on how large and complex the file is.

HANCE C API

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 such as noise reduction and de-reverberation.

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.0 or later is required to build the example. To build ProcessFile, open the Terminal (on Mac and Linux) or the Command Line Prompt (on Windows) and locate the Examples/ProcessFile subfolder in the HANCE API. 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 the HANCE Engine 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:

Creating a HANCE Processor Instance

// 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:

Adding Channel Interleaved Audio to a HANCE Processor

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

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

Getting Processed Audio from a HANCE Processor

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:

Deleting the HANCE Processor and Free Memory

hanceDeleteProcessor (processorHandle);

Performance Considerations

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

• Intel Performance Primitives
• Apple vDSP

Datatypes

HanceProcessorHandle

typedef void* HanceProcessorHandle;

The processor handle refers to an audio processor that can process PCM audio in 32-bit floating point using a specified inference model. The handle created using hanceCreateProcessor.

HanceProcessorInfo

struct HanceProcessorInfo
{
    double sampleRate;
    int32_t numOfModelChannels;
    int32_t latencyInSamples;
};

The HanceProcessorInfo contains information about a neural network based audio processor.

Functions

hanceAddAudio

void hanceAddAudio (HanceProcessorHandle processorHandle,
                    const float **pcmChannels,
                    int32_t numOfSamples)

Adds floating point PCM encoded audio from separate channels to the HANCE audio processor.

hanceAddAudioInterleaved

void hanceAddAudioInterleaved (HanceProcessorHandle processorHandle,
                               const float* interleavedPCM,
                               int32_t numOfSamples)

Adds floating point PCM encoded audio from a single channel-interleaved buffer to the HANCE audio processor.

hanceAddLicense

bool hanceAddLicense (const char* licenseString)

Adds a license key to the HANCE engine to remove audio watermarking on the output.

hanceCreateProcessor

HanceProcessorHandle hanceCreateProcessor (const char* modelFilepath,
                                           int32_t numOfChannels,
                                           double sampleRate)

Creates an audio processor, loads a model file and returns a handle to the processor instance if successful.

hanceCreateStemSeparator

hanceCreateStemSeparator()
HanceProcessorHandle hanceCreateStemSeparator (int32_t  numOfModels,
                                               const char ** modelFilepaths,
                                               int32_t numOfChannels,
                                               double sampleRate)       

Creates a processor that performs stem separation, loads a set of model files and returns a handle to the processor instance if successful.

hanceDeleteProcessor

void hanceDeleteProcessor (HanceProcessorHandle processorHandle)

Deletes a processor instance.

hanceGetAudio

bool hanceGetAudio (HanceProcessorHandle processorHandle,
                    float* const* pcmChannels,
                    int32_t numOfSamples)

Gets floating point PCM encoded audio in separate channels after processing. The number of requested samples must be less or equal to the number of available samples as returned by /ref hanceGetNumOfPendingSamples.

hanceGetAudioInterleaved

bool hanceGetAudioInterleaved (HanceProcessorHandle processorHandle,
                               float* interleavedPCM,
                               int32_t  numOfSamples)

Gets floating point PCM encoded audio in a single channel-interleaved buffer after processing. The number of requested samples must be less or equal to the number of available samples as returned by /ref hanceGetNumOfPendingSamples.

hanceGetNumOfPendingSamples

int32_t hanceGetNumOfPendingSamples (HanceProcessorHandle processorHandle)

Returns the number of samples that are ready after model inference. If the end of the stream has been reached, endOfStream can can be set to true to retrieve the number of remaining samples in the processing queue.

hanceGetParameterValue

void hanceGetParameterValue (HanceProcessorHandle processorHandle,
                            int32_t parameterIndex)

Returns a parameter value.

hanceGetProcessorInfo

void hanceGetProcessorInfo (HanceProcessorHandle processorHandle,
                            HanceProcessorInfo* processorInfo)

Fills a the HanceProcessorInfo structure with information about the HANCE processor.

hanceResetProcessorState

void hanceResetProcessorState (HanceProcessorHandle processorHandle)

Resets the processor state and clears all delay lines.

hanceSetParameterValue

void hanceSetParameterValue (HanceProcessorHandle processorHandle,
                             int32_t parameterIndex,
                             float parameterValue)

Sets a parameter value.

HANCE Python API

HANCE is a powerful audio enhancement engine that can drastically improve the quality of audio signals in your Python projects. This document explains how to install and use the HANCE Python wrapper.

To learn more about HANCE and its capabilities, visit HANCE.ai.

Installation

Installing the HANCE Python wrapper is easy:

• Use pip, the standard Python package installer.
• Run the command in the example below from the terminal on macOS or the command line on Windows.

Install HANCE with Pip

python -m pip install hance

How to use

The HANCE Python API is essentially a wrapper around the underlying C++ library. To use the API, you can import it and then list the available models:

Importing HANCE

import hance
models = hance.list_models()
print(models)

Basic audio processing

To process an audio file using HANCE, use the process_file function, as shown below.

File processing

import hance
models = hance.list_models()
hance.process_file(models[0], input_file_path, output_file_path)

The HANCE engine works without a license but it will leave a watermark on the sound. You can obtain a license for the HANCE engine here.
This is an example of processing a file using a license.

Using with a license

import hance

license_string = "example_license"

models = hance.list_models()
hance.process_file(models[0], input_file_path, output_file_path,
                    license_string=license_string)

Stem Separation

For advanced audio processing, HANCE provides stem separation features. This allows you to isolate and manipulate individual components of an audio track, such as vocals, instruments, etc.

Using StemSeparator for Advanced Stem Separation

The StemSeparator class enables more complex stem separation tasks, using multiple models for different stems. Here’s how you can use it:

 # We capture the input of your microphone and process it in real-time. 
 # We then send it to the output device.
import hance
import soundfile as sf
import numpy as np
import os

def separate_stems(input_file_path):
    """
    Separates the stems from an input audio file using selected models with the StemSeparator class.
    """
    print("Stem separation using Hance engine with StemSeparator class.")
    models = ['vocals_separation.hance', 'drums_separation.hance', 'piano_separation.hance', 'bass_separation.hance']
    print("Available models for separation:")
    for i, model in enumerate(models):
        print(f"{i+1}. {model}")

    selected_models = input("Select models to use by entering their numbers separated by commas (e.g., 1,3): ")
    selected_models_indices = [int(index) - 1 for index in selected_models.split(',')]
    
    model_paths = [models[index] for index in selected_models_indices]

    input_audio, sr = sf.read(input_file_path, dtype='float32')
    if input_audio.ndim == 1:  # Mono to Stereo if needed
        input_audio = np.tile(input_audio[:, np.newaxis], (1, 2))

    sample_rate = sr
    num_of_channels = input_audio.ndim

    engine = hance.HanceEngine()
    stem_separator = engine.StemSeparator(engine.hance_engine, model_paths, num_of_channels, sample_rate)
    
    separated_stems = stem_separator.process(input_audio)

    path, fn = os.path.split(input_file_path)
    for i, model_path in enumerate(model_paths):
        stem_name = model_path.split('_')[0]
        output_file_path = os.path.join(path, f"{fn.split('.')[0]}_{stem_name}_separated.wav")
        sf.write(output_file_path, separated_stems[:, i*num_of_channels:(i+1)*num_of_channels], sr)
        print(f"Stem {stem_name} saved to {output_file_path}")

    print("Stem separation completed.")

separate_stems(path_to_file)

This function demonstrates how to select specific models for stem separation, process an audio file to separate the stems, and save each stem as a separate audio file.

Process a stream

In addition to processing audio files, HANCE can also be used on audio streams in real-time. Here is an example using pyaudio to record the microphone, process it in real time, and output it to headphones.

 # We capture the input of your microphone and process it in real-time. 
 # We then send it to the output device.
import pyaudio
engine = hance.HanceEngine()
p = pyaudio.PyAudio()

FORMAT = pyaudio.paFloat32
CHANNELS = 1
RATE = 44100
CHUNK = 512


print("\nRecord audio from a microphone and process it in realtime with HANCE.")
print("To prevent feedback, make sure you are wearing headphones.")
print("PyAudio will induce some latency with the roundtrip to the soundcard,\nbut the HANCE engine runs in realtime.")
print("")

# Get a list of available input devices
input_devices = []
for i in range(p.get_device_count()):
    device_info = p.get_device_info_by_index(i)
    if device_info["maxInputChannels"] > 0:
        input_devices.append(device_info)

# Print the list of available input devices and ask the user to select one
print("Available input devices:")
for i, device in enumerate(input_devices):
    print(f"{i}: {device['name']}")
input_device_index = int(input("\nSelect an input device by entering its number: "))
input_device_info = input_devices[input_device_index]

# Get a list of available output devices
output_devices = []
for i in range(p.get_device_count()):
    device_info = p.get_device_info_by_index(i)
    if device_info["maxOutputChannels"] > 0:
        output_devices.append(device_info)

# Print the list of available output devices and ask the user to select one
print("\nAvailable output devices:")
for i, device in enumerate(output_devices):
    print(f"{i}: {device['name']}")
output_device_index = int(input("\nSelect an output device by entering its number: "))
output_device_info = output_devices[output_device_index]

models = hance.list_models()
processor = engine.create_processor(models[0], CHANNELS, RATE)

stop_thread = False
processor_active = True
def record_and_playback_thread():
    stream_record = p.open(format=FORMAT, channels=CHANNELS,
                rate=RATE, input=True,
                input_device_index=input_device_info['index'],
                frames_per_buffer=CHUNK)

    stream_play = p.open(format=pyaudio.paFloat32,
                channels=1,
                rate=RATE,
                frames_per_buffer=CHUNK,
                output=True,
                output_device_index=output_device_info['index']
                )
    while not stop_thread:
        data = stream_record.read(CHUNK, exception_on_overflow = False)
        audio_buffer = np.frombuffer(data, dtype=np.float32)
        if processor_active:
            audio_buffer = processor.process(audio_buffer)
        stream_play.write(audio_buffer.astype(np.float32).tobytes())
        
    # stop Recording
    stream_record.stop_stream()
    stream_record.close()
    
    stream_play.stop_stream()
    stream_play.close()
    
    

t = threading.Thread(target=record_and_playback_thread)
t.start()

print("\nThe microphone and processing is active")
while True:
    user_input = input("Enter 'p' to toggle processing on and off or 'x' to exit the thread: ")
    if user_input.lower() == "p":
        # Bypass processing and continue the loop
        if processor_active:
            processor_active = False
            print("The processing is bypassed")
        else:
            processor_active = True
            print("The processing is active")
    elif user_input.lower() == "x":
        # Stop the thread
        stop_thread = True
        break

t.join()
p.terminate()

Realtime processing

In addition to processing audio files, HANCE can also be used on realtime audio streams. The following example demonstrates how to use HANCE with PyAudio to record audio from a microphone, process it in realtime, and output it to headphones. At the very bottom you can find a minimal example of this with only the HANCE related parts.

Complete Python example of realtime processing

 # We capture the input of your microphone and process it in real-time. 
 # We then send it to the output device.

import threading
import numpy as np
import hance
import pyaudio

engine = hance.HanceEngine()
p = pyaudio.PyAudio()

FORMAT = pyaudio.paFloat32
CHANNELS = 1
RATE = 44100
CHUNK = 512

print("\nRecord audio from a microphone and process it in realtime with HANCE.")
print("PyAudio will induce some latency with the roundtrip to the soundcard,")
print("but the HANCE engine runs in realtime.\n")

# We get a list of available input devices.
input_devices = []
for i in range(p.get_device_count()):
    device_info = p.get_device_info_by_index(i)
    if device_info["maxInputChannels"] > 0:
        input_devices.append(device_info)

# Print the list of available input devices and ask the user to select one.
print("Available input devices:")
for i, device in enumerate(input_devices):
    print(f"{i}: {device['name']}")
input_device_index = int(input("\nSelect an input device by entering its number: "))
input_device_info = input_devices[input_device_index]

# We get a list of available output devices.
output_devices = []
for i in range(p.get_device_count()):
    device_info = p.get_device_info_by_index(i)
    if device_info["maxOutputChannels"] > 0:
        output_devices.append(device_info)

# We print the list of available input devices and ask the user to select one.
print("\nAvailable output devices:")
print("To prevent feedback, select a headphones output.\n")

for i, device in enumerate(output_devices):
    print(f"{i}: {device['name']}")
output_device_index = int(input("\nSelect an output device by entering its number: "))
output_device_info = output_devices[output_device_index]

models = hance.list_models()
processor = engine.create_processor(models[0], CHANNELS, RATE)

stop_thread = False
processor_active = True

def record_and_playback_thread():
    stream_record = p.open(format=FORMAT, channels=CHANNELS,
                           rate=RATE, input=True,
                           input_device_index=input_device_info['index'],
                           frames_per_buffer=CHUNK)

    stream_play = p.open(format=pyaudio.paFloat32,
                         channels=1,
                         rate=RATE,
                         frames_per_buffer=CHUNK,
                         output=True,
                         output_device_index=output_device_info['index']
                         )
    while not stop_thread:
        data = stream_record.read(CHUNK, exception_on_overflow=False)
        audio_buffer = np.frombuffer(data, dtype=np.float32)
        if processor_active:
            audio_buffer = processor.process(audio_buffer)
        stream_play.write(audio_buffer.astype(np.float32).tobytes())

    # We stop recording.
    stream_record.stop_stream()
    stream_record.close()

    stream_play.stop_stream()
    stream_play.close()

t = threading.Thread(target=record_and_playback_thread)
t.start()

print("\nThe microphone and processing is active")
while True:
    user_input = input("Enter 'p' to toggle processing on and off or 'q' to quit: ")
    if user_input.lower() == "p":
        # Bypass processing and continue the loop
        if processor_active:
            processor_active = False
            print("The processing is bypassed")
        else:
            processor_active = True
            print("The processing is active")
    elif user_input.lower() == "q":
        # Stop the thread
        stop_thread = True
        break

t.join

Here is a minimal example of the HANCE-related code for you to look at:

Minimal Python example

import hance
import numpy as np

engine = hance.HanceEngine()
models = hance.list_models()
processor = engine.create_processor(models[0], CHANNELS, RATE)
audio_buffer = np.frombuffer(PCM_AUDIO_DATA, dtype=np.float32)
audio_buffer = processor.process(audio_buffer)

The HANCE Python wrapper is a powerful tool for audio processing and enhancement. With the ability to remove noise, decrease reverb, and be highly CPU and memory-efficient, HANCE stands at the cutting edge of audio enhancement technology.

We hope this guide has helped get you started with the HANCE Python wrapper, and we encourage you to visit the HANCE website to learn more about HANCE and its capabilities.