Immersitech SDK Documentation
Engage SDK documentation
Sound Manager Quick Start

Immersitech Sound Manager SDK to process and mix 3D spatial audio.

Overview

The Immersitech Sound Manager SDK is a C/C++ library that functions as an audio mixer and audio processor featuring 3D spatial audio processing, noise reduction, and speech enhancement.
The Sound Manager 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 Sound Manager SDK allows you to edit or query the audio settings in real time for any listener or speaker.

Concepts

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.

imm_initialize_library(license_file_path, SAMPLE_RATE, FRAMES_PER_BUFFER, IMM_OUTPUT_TYPE_STEREO_INTERLEAVED, IMPULSE_LENGTH);

Optionally, check the version of your library to ensure you are up to date

imm_get_version(version_string, 30);
printf("The Immersitech library version is %s\n", version_string);

Now that the library is initialized, we can begin to create conferences. Note that if you haven't initialized the Immersitech library the returned library will be NULL.

Let's add two participants into this conference, both with 1 channel input

We can store the return IDs to access them later and edit their settings

ID_1 = imm_add_participant(my_conference , SAMPLE_RATE, NUM_CHANNELS, IMM_PARTICIPANT_REGULAR);
ID_2 = imm_add_participant(my_conference , SAMPLE_RATE, NUM_CHANNELS, IMM_PARTICIPANT_REGULAR);

Now that we have some participants in our conference, 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( my_conference , my_audio_data_1, num_frames, ID_1);
imm_input_audio( my_conference , my_audio_data_2, num_frames, ID_2);

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 immersitech_output_format. 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( my_conference, ID_1, participant_1_output);
imm_output_audio( my_conference, 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 edit state function. There is a full list of the available audio effects and their default states at immersitech_audio_controls

imm_edit_participant_state( my_conference, ID_2, IMM_CONTROL_HALF_SPAN, 30);

To move a participant in 3D space, simply adjust their location:

imm_edit_participant_location( my_conference, ID_2, 10, 30, 20);

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

imm_remove_participant( my_conference, ID_1);
imm_remove_participant( my_conference, ID_2);

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

imm_destroy_conference( my_conference );

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 file.

Installation

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

  • immersitech_sound_manager.h
  • license_file.dat
  • libimmersitech-sound-manager.dll (.dylib for mac or .so for linux)
  • libimmersitech-sound-manager.lib (only necessary for windows)

To use the Immersitech Sound Manger Library, include immersitech_sound_manager.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_sound_manager.h

imm_input_audio
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_input_audio(Immersitech_Conference conference, short *audio_data, int number_frames, int participant_ID)
Function to add audio data from a participant into the conference.
imm_create_conference
IMMERSITECH_SOUND_MANAGER_API Immersitech_Conference imm_create_conference()
Function to allocate memory and initialize a conference.
IMM_DEVICE_SPEAKER
@ IMM_DEVICE_SPEAKER
The listening device is a stereo loudspeaker pair. If this is selected, the participant should also s...
Definition: immersitech_sound_manager.h:90
imm_remove_participant
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_remove_participant(Immersitech_Conference conference, int participant_ID)
Function to remove a participant from a conference.
IMM_CONTROL_DEVICE
@ IMM_CONTROL_DEVICE
The device setting will help optimize 3D processing for a particular participant's listening device....
Definition: immersitech_sound_manager.h:74
imm_output_audio
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_output_audio(Immersitech_Conference conference, int participant_ID, short *output)
Function to process audio data and return the output audio data for a participant.
imm_destroy_conference
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_destroy_conference(Immersitech_Conference conference)
Function to removes all remaining participants from a conference and frees all the data for the confe...
Immersitech_Conference
void * Immersitech_Conference
Immersitech Library API Handler.
Definition: immersitech_sound_manager.h:155
imm_add_participant
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_add_participant(Immersitech_Conference conference, int sampling_rate, int num_channels, immersitech_participant_types participant_type, int *new_id)
Function to add a new pariticipant into a conference.
IMM_PARTICIPANT_REGULAR
@ IMM_PARTICIPANT_REGULAR
A regular participant will both input audio and receive other participant's audio.
Definition: immersitech_sound_manager.h:102
imm_destroy_library
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_destroy_library()
Function to frees all memory associated with the immersitech library.
IMM_CONTROL_ANC_ENABLE
@ IMM_CONTROL_ANC_ENABLE
If a participant has ANC enabled, all noise in their input audio will be automatically cancelled....
Definition: immersitech_sound_manager.h:67
imm_initialize_library
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_initialize_library(const char *license_file_name, int sampling_rate, int num_frames_per_buffer, immersitech_output_format output_format, int impulse_length)
Function to allocate memory for the immersitech library.
imm_edit_participant_state
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_edit_participant_state(Immersitech_Conference conference, int participant_ID, immersitech_audio_controls control_to_edit, int value)
Function to edit state of a given participant.
IMM_CONTROL_MASTER_GAIN
@ IMM_CONTROL_MASTER_GAIN
The master gain setting will adjust the volume for a participant's output audio. It is given as a per...
Definition: immersitech_sound_manager.h:76
imm_get_version
IMMERSITECH_SOUND_MANAGER_API immersitech_error_codes imm_get_version(char *character_buffer, int buffer_len)
Function to return the current version of the immersitech library.