Immersitech SDK Documentation
Engage SDK documentation
Quick Start


The Immersitech SDK is a C/C++ library that functions as an audio mixer and audio processor featuring 3D spatial audio processing, noise cancellation, and speech enhancement.
The Immersitech SDK is currently made for people who have direct access to raw audio data. If you can access this, the SDK can collect them and return to you a raw audio output buffer that has been processed. Additionally, the Immersitech SDK allows you to change the audio settings in real time for any participant.


Before diving into how to utilize the library, be sure to check out Key Concepts for All Modules to get an understanding of terminology that will be used throughout the documentation.

Psuedo Example

Let's take a high level look at the small number of simple steps needed to utilize the library:

The first step in your code will be to initialize the Immersitech library. This step will allow Immersitech to set everything up internally for audio processing. To do so, create an imm_library_configuration which allows you to specify the sampling rate, number of channels, etc. Also note that we send an imm_error_code value. This value will store whether or not the initialization was a success, and if not, why. For now we will disable the room layout and websocket features by sending NULL to those configuration files.

library_config.output_sampling_rate = 48000;
library_config.output_number_frames = 480;
library_config.output_number_channels = 2;
library_config.interleaved = true;
library_config.spatial_quality = 5;
imm_error_code error_code;
imm_handle handle = imm_initialize_library(license_file_path, NULL, NULL, library_config &error_code);

Optionally, check the version of your library to ensure you are up to date. You can also check to see if your license is valid and other details like when it may expire.

printf("The Immersitech library version is %s\n", imm_get_version());
printf("Your Immersitech license key details: %s\n", imm_get_license_info());

Now that the library is initialized, we can begin to create rooms. You can pick any room id that you'd like as long as you haven't already used it to create a different room.

int room_id = 0;
imm_create_room(handle, room_id);

Let's add two participants into this room, both with 1 channel input. We can again pick any id as long as there aren't duplicates in the same room. Note that you can have different participant configurations for each participant.

// We will arbitrarily pick these new participant IDs
int ID_1 = 1;
int ID_2 = 2;
// This structure will allow you to specify each participant's configuration
immersitech_participant_configuration participant_config;
participant_config.input_sampling_rate = 48000;
participant_config.input_number_channels = 1;
participant_config.type = IMM_PARTICIPANT_REGULAR;
// Add the participants
imm_add_participant( handle, room_id, ID_1, "participant_1", participant_config);
imm_add_participant( handle, room_id, ID_2, "participant_2", participant_config);

Now that we have some participants in our room, let us start processing audio

This happens in two steps, first input all the Participants audio, then process and generate the output for each participant

The first of the two steps is to add each Participant's audio into the engine when you receive it. Do this once for each participant, as we are establishing this the participant's input audio and this is the audio that should be used when considering this participant as a source.

Please ensure that your input buffer has the correct number of samples and that you enter the number of FRAMES into the function call and not the number of samples. For more clarification on buffer sizes please refer to Understanding Audio Buffer Sizes .

imm_input_audio_short( handle, room_id, ID_1, my_audio_data_1, num_frames);
imm_input_audio_short( handle, room_id, ID_2, my_audio_data_2, num_frames);

The second step of audio processing is to generate the output for each participant as a listener. This means call the process function once for each participant to generate the stereo output of what that participant should hear.

To do so, simply provide an output buffer in which to store the results. The output buffer data will be formatted the way you specified upon initializing the library. Find more information about the different output formats under imm_library_configuration. Once again, you will want to ensure that the output buffer you provide has enough memory allocated for the number of frames and number of output channels you selected.

imm_output_audio_short( handle, room_id, ID_1, participant_1_output);
imm_output_audio_short( handle, room_id, ID_2, participant_2_output);

And that's it! You can now adjust the features of the audio processing for each participant by using the set state function. There is a full list of the available audio effects and their default states at imm_audio_control

imm_set_participant_state( handle, room_id, ID_2, IMM_CONTROL_MASTER_GAIN, 70 );
imm_set_participant_state( handle, room_id, ID_2, IMM_CONTROL_HALF_SPAN, 30 );

To move a participant in 3D space, you can manually place them in 3D space by setting their position:

imm_position position = { 10, 30, 20 }; // x, y, z coordinates
imm_heading heading = { 0, 0 }; // azimuth and elevation heading
imm_set_participant_position( handle, room_id, ID_2, position, heading );

If you'd prefer to have the library take care of where to place participants for you, set the room layout of a room and move participants to seats instead. New participants will then be placed in the next best unoccupied seat. Note to use seats and automatic room layouts, you will have to use a room layout configuration file and point to it during the initialization step with imm_initialize_library where we used NULL in this example.

imm_set_room_layout( handle, room_id, 2 ); // set the room to layout 2
imm_set_participant_seat( handle, room_id, ID_2, 3 ); // move the participant to seat 3

If at any point a participant chooses to leave the call, remove them from the conference:

imm_remove_participant( handle, room_id, ID_1);
imm_remove_participant( handle, room_id, ID_2);

When a conference is finished, free all the memory for that room:

imm_destroy_room( handle, room_id );

When you are finished using the Immersitech library, be sure to destroy the library to free the memory allocated during initialization. Do not call this function before you are completely finished using the library:

Real Example

If you are now looking to examine a fully functional piece of code using the Immersitech Library, please reference the included immersitech_example.c or noise_cancellation_example.c.


The Immersitech Library does not require you to have any special dependencies for Mac or Windows.

If you are using Linux, it does however require that you have your C / C++ libraries up to at least:

Ubuntu: GLIBC_2.27

Debian: GLIBC_2.29

If you plan on using the websocket server feature of the library, you will need to install and link the following libraries to your program:

-lcrypto -lssl


In order to use the Immersitech Sound Manager libraries, you will need these files:

  • immersitech.h
  • license_file.dat
  • libimmersitech.dll (.dylib for mac or .so for linux)
  • libimmersitech.lib (only necessary for windows)

The following files are optional for more advanced feature usage:

  • immersitech_logger.h (optional if you want to implement a custom logger)
  • immersitech_event_manager.h (optional if you want to implement a custom even manager)
  • room_layout.json (optional if you want to use custom room layouts)
  • websocket_config.json (optional if you want to use the websocket server)

To use the Immersitech Library, include immersitech.h in your projects and add the functions to your code. You will also need to make sure to link the dynamic library to your project and ensure it is in the location you linked it to. Make sure also in your code that the path you supply to your license file matches the path you gave to the Immersitech Library.

API Reference

For the full detailed API description, please visit immersitech.h

IMMERSITECH_API imm_handle imm_initialize_library(const char *license_file_name, const char *room_layout_file_name, const char *websocket_config_file_name, imm_library_configuration configuration, imm_error_code *error_code)
Function to allocate memory for the immersitech library.
IMMERSITECH_API imm_error_code imm_output_audio_short(imm_handle handle, int room_id, int participant_id, short *output)
Function to process audio data and return the output audio data for a participant.
bool interleaved
Definition: immersitech.h:161
IMMERSITECH_API imm_error_code imm_set_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control_to_edit, int value)
Function to set the state of a given participant.
A regular participant will both input audio and receive other participant's audio.
Definition: immersitech.h:118
const IMMERSITECH_API char * imm_get_version()
Function to return the current version of the immersitech library.
IMMERSITECH_API imm_error_code imm_destroy_library(imm_handle handle)
Function to frees all memory associated with the immersitech library.
IMMERSITECH_API imm_error_code imm_input_audio_short(imm_handle handle, int room_id, int participant_id, const short *audio_data, int number_frames)
Function to input audio data from a participant into a room.
The listening device is a stereo loudspeaker pair. If this is selected, the participant should also s...
Definition: immersitech.h:106
int output_number_frames
Definition: immersitech.h:159
A structure to describe the configuration of the Immersitech Library.
Definition: immersitech.h:157
int output_number_channels
Definition: immersitech.h:160
const IMMERSITECH_API char * imm_get_license_info(imm_handle handle)
Function to return information about your current license key.
IMMERSITECH_API imm_error_code imm_set_room_layout(imm_handle handle, int room_id, int layout_id)
Function to set a room's layout.
int spatial_quality
Definition: immersitech.h:162
If a participant has ANC enabled, all noise in their input audio will be automatically cancelled....
Definition: immersitech.h:83
The master gain setting will adjust the volume for a participant's output audio. It is given as a per...
Definition: immersitech.h:92
IMMERSITECH_API imm_error_code imm_create_room(imm_handle handle, int room_id)
Function to allocate memory and initialize a new room.
void * imm_handle
Immersitech Library API Handler.
Definition: immersitech.h:183
IMMERSITECH_API imm_error_code imm_set_participant_seat(imm_handle handle, int room_id, int participant_id, int seat_id)
Function move a participant to a new seat.
A structure to describe a position within a three-dimensional space.
Definition: immersitech.h:43
The device setting will help optimize 3D processing for a particular participant's listening device....
Definition: immersitech.h:90
IMMERSITECH_API imm_error_code imm_remove_participant(imm_handle handle, int room_id, int participant_id)
Function to remove a participant from a room.
IMMERSITECH_API imm_error_code imm_add_participant(imm_handle handle, int room_id, int participant_id, const char *participant_name, imm_participant_configuration config)
Function to add a new pariticipant into a room.
A structure to describe the direction a participant is facing in three-dimensional space.
Definition: immersitech.h:56
IMMERSITECH_API imm_error_code imm_set_participant_position(imm_handle handle, int room_id, int participant_id, imm_position position, imm_heading heading)
Function to set the x,y,z position of a given participant.
IMMERSITECH_API imm_error_code imm_destroy_room(imm_handle handle, int room_id)
Function to removes all remaining participants from a room and frees all the data allocated for a roo...
All error codes that may be produced by the library.
Definition: immersitech.h:126
int output_sampling_rate
Definition: immersitech.h:158