Quick Start

Initializing the Immersitech Library

Before using any of the Immersitech audio effects you will need to configure and initialize the library.

#include <stdio.h>
#include "immersitech.h"

int main(int argc, char **argv) {
  imm_library_configuration library_config;
  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("Immersitech_Engineering_sound_manager_license_key.dat", NULL, NULL, library_config, &error_code);
}

For further reference see:

- imm_initialize_library for parameters to pass when initializing the library.

- imm_library_configuration for more details on configuration options for the audio output

To ensure that you've setup the library correctly you can check the library version and get details about the license.

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

If you're getting a response back that is similar to the below response then you should be okay to move forward.

The Immersitech library version is v1.0.9
Your Immersitech license key details: { "valid": true, "name": "Immersitech_Engineering_sound_manager_license_key.dat", "department": "Engineering", "minimum_version": "v0.8.0", "maximum_version": "v1.9.999", "creation_date": "3/9/2022", "expiration_date": "8/21/2022" }

When you are finished using the Immersitech library, be sure to destroy the library to free the memory allocated during initialization.

imm_destroy_library( handle );

Creating a Room

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

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

imm_destroy_room( handle, room_id );

Adding/Removing Participants

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
imm_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);

To remove a participant from the conference:

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

For further reference see:

- imm_participant_configuration for more details on the settings that can be applied for a participant

- imm_participant_type for the full list of possible participant types

Processing Audio

1. Pass an audio stream as input to the Immersitech engine for each participant in the room that is producing audio.

imm_input_audio_short( handle, room_id, ID_1, input_buffer_1, num_frames);
imm_input_audio_short( handle, room_id, ID_2, input_buffer_2, num_frames);

For further reference see:

- Understanding Audio Buffer Sizes for clarification on buffer sizes

2. Process and generate the stereo output for each participant

imm_output_audio_short( handle, room_id, ID_1, participant_1_output_buffer);
imm_output_audio_short( handle, room_id, ID_2, participant_2_output_buffer);

The Immersitech library will write the processed data to the output buffers that you provide for each participant. Please ensure that the output buffers you provide have enough memory allocated for the number of frames and number of output channels that you specified during initialization. For a more detailed example of buffering see our example on Github or go through the Noise Cancellation Tutorial

For further reference see:

- imm_library_configuration for more details on configuration options for the audio output

Using Library Features

You can now adjust the features of the audio processing for each participant by using the `imm_set_participant_state` function.

imm_set_participant_state( handle, room_id, ID_1, IMM_CONTROL_ANC_ENABLE, 1 );
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_DEVICE, IMM_DEVICE_SPEAKER );
imm_set_participant_state( handle, room_id, ID_2, IMM_CONTROL_HALF_SPAN_ANGLE, 30 );

For further reference see:

- imm_audio_control for a complete list of audio controls

Spatial Audio

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

// enable 3D mixing
imm_set_participant_state( handle, room_id, ID_2, IMM_CONTROL_MIXING_3D_ENABLE, 1 );

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 );

Alternatively, you can setup a room configuration file and set the layout for the room. The Immersitech library will then place participants in the next unoccupied seat.

imm_handle handle = imm_initialize_library("Immersitech_Engineering_sound_manager_license_key.dat", "room_layout.json", NULL, library_config, &error_code);

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

For further reference see:

- imm_audio_control for a full list of the available audio effects and their default states

- Example config file for room layout