Prerequisites

Installation of Linux

Immersitech Engage™ Adapter for Freeswitch V1.0 is developed for Freeswitch V1.10, which runs well inUbuntu 18.04.3. Debian 10 is also recommended for use with Freeswitch V1.10.

Installation of Freeswitch

Freeswitch V1.10.X is supported. Please find documentation of how to install Freeswitch in document below: https://freeswitch.org/confluence/display/FREESWITCH/Installation

Install Immersitech Engage™ Adapter for Freeswitch

1 Make a new directory called immersitech in your /usr/local/lib directory:

sudo mkdir /usr/local/lib/immersitech

2 Copy the following files from Immersitech into /usr/local/lib/immersitech :

immersitech_license_key.dat - This is the license file for the Immersitech Engage functionality. Note that if you do not have a license or your license expires, the program will still run except that features of the library will be permanently bypassed, effectively functioning like normal freeswitch without the Immersitech libraries.
room_config.json - This is the default room configuration file in JSON format. You can find more details about this file and how to customize your own room configurations later in the documentation.
imm_websocket_config.json - This is the default websocket configuration file. You can find more details about this file and how to custom it to work with your own server in the event manager documentation.
libimmersitech.so - The Immersitech library file

Note that the default search path for all Immersitech core libraries is set to be /usr/local/lib/immersitech, though you can manually change the runtime link path of a shared object.

3 Copy the following files from Immersitech into the folder /usr/local/freeswitch/mod/:

mod_conference.so - This is a modified mod_conference module that has the necessary modifications to connect Freeswitch to the Engage Core
mod_imm_adapter.so - This is the FreeSwitch Adapter library

4 Copy the following file to /usr/local/freeswitch/conf/autoload_configs:

imm_adapter.conf.xml - This is the configuration file for the Immersitech libraries. Learn more about it in the Immersitech Configuration File section of this documentation.

5 Enable the Immersitech Modules in Freeswitch:

By default, only a few freeswitch modules are enabled. You can enable/disable these modules, including the Immersitech modules, in a configuration file. Edit /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml and change as per your requirements. Please make sure the following Immersitech modules are loaded automatically by adding these calls to the file:

<load module="mod_conference"/> 
 
<load module="mod_imm_adapter"/>

6 Edit your Freeswitch Dial-plan:

Make sure that your freeswitch dial-plan uses conference profiles in conf/autoload_configs/conference.conf.xml that are set up to utilize 2 channels output and match the settings in your imm_adapter.conf.xml file.

The following are the settings you must guarantee will be used per your freeswitch dial-plan:

<param name="rate" value="48000"/>     <!-- Must match "imm_spatial_output_audio_sample_rate" -->
 
<param name="channels" value="2"/>     <!-- Must be two channel output to hear 3D audio -->
 
<param name="interval" value="20"/>    <!-- Must match "imm_spatial_output_audio_frames_per_buffer" -->

Run Freeswitch with Engage Freeswitch Adapter

1 Start Freeswitch, load the Adapter module if not loaded automatically:

cd /usr/local/freeswitch/bin
./freeswitch
load mod_imm_adapter

The following log will be shown if Freeswitch started and the Adapter module is loaded successfully:

Trying to load immersitech conference at: ../mod/libimmersitech.so
The Immersitech Conference library version is v0.08.012
2020-04-08 15:17:09.731354 [INFO] mod_imm_adapter.c:191 Subscribed to conference custom events!
2020-04-08 15:17:09.731354 [CONSOLE] switch_loadable_module.c:1804 Successfully Loaded [mod_imm_adapter]
2020-04-08 15:17:09.731354 [NOTICE] switch_loadable_module.c:412 Adding API Function 'imm_adapter'
+OK Reloading XML
+OK

2 Optionally, you can view Version information about your product by typing following command into a Freeswitch Command Line Interface:

imm_adapter get_version

The output from this command which look something like the following:

Engage Adapter Version: v0.01.014
Engage Core Version: v0.01.036
Sound Manager Version: v0.08.012

3 To configure SIP softphones (Linphone or Zoip) to register to Freeswitch and let softphones join to the same spatial conference, dial a number in the range of “3500 - 3599” (which is the default stereo conference number in the Freeswitch dial plan). Spatial audio should be heard once they have joined the conference successfully.

Default Behavior

By default, a new participant will enter a round table room with 8 fixed seats. You can view the Default room layout (labeled as “default”) by using following command:

imm_adapter get_json_all_room_layouts

The spatial position of any participant can be viewed by using the get_participant_position commands. All new participants will be assigned to specific seat one by one starting from index 1. The following example gets the exact position of participant 2 in room 3500. You can also just get which seat the participant is in as well.

imm_adapter get_participant_position 3500 2

imm_adapter get_participant_seat 3500 2

Any participant can be moved to any seat, resulting in a change in their spatial sound field. You can move a participant to a new seat with the set_participant_seat command. The following is an example of a participant with id 1 that will be moved to the seat with index 2 in conference 3500:

imm_adapter set_participant_seat 3500 1 2

You can change or view the state of any participant in real time. There are several state changes you can make detailed further at imm_audio_control. For example, let us use the set_participant_state function to turn on Automatic Gain Control for participant 2 in conference 3500:

imm_adapter set_participant_state 3500 2 IMM_CONTROL_AGC_ENABLE 1

For detailed API commands explanation, please refer to the following API commands chapter.

Immersitech Configuration File

You will notice above you moved an xml configuration file imm_adapter.conf.xml for freeswitch to setup the immersitech libraries with. Below we will explain what each configuration option can do for you, although it is recommended to leave both the immersitech and freeswitch configuration as our default recommendations.

License_file_path

This parameter allows you to tell the immersitech library where to find your license file. Note if you use a relative path, it will be relative to the location of mod_imm_adapater.so.

room_layout_file_path

This parameter allows you to tell the immersitech library where to find your room layout file. Note if you use a relative path, it will be relative to the location of mod_imm_adapater.so.

websocket_config_file_path

This parameter allows you to specific where your websocket config file is located. Note if you use a relative path, it will be relative to the location of mod_imm_adapter.so.

websocket_enabled

This parameter specifies whether or not the websocket event management system will be active or not. If you want to use the websocket server to send and receive events, then you should set this parameter to 1. If you do not want to have the websocket server active then you should set this parameter to 0.

imm_output_audio_sample_rate

This parameter describes the sampling rate of the audio coming out of the immersitech libraries. Currently Immersitech only supports 48 kHz output sampling rates.

imm_spatial_quality

This parameter allows you to make a tradeoff between CPU and the accuracy of 3D rendering. The smaller the value, the less CPU that is used, but the less accurately the 3D image is rendered. You can pick between 1 and 5.

imm_output_audio_frames_per_buffer

This parameter relates directly to the “interval” parameter defined in your mod_conference configuration. If you have the mod_conference parameter “interval” set to 10, then you want to set this parameter to 480 because 480 frames at 48 kHz sampling rate is 10 milliseconds. If you have the mod_conference parameter “interval” set to 20, then you want to set this to 960 because 960 frames at 48 kHz is 20 milliseconds. Currently, the Immersitech libraries only support either 480 or 960, please send us a request if you need a different interval.

Engage Freeswitch Adapter API commands:

Once the Immersitech Engage Freeswitch Adapter is running, you can apply several API commands in real-time to change the state of the audio effects. You can apply these commands manually through the freeswitch command line (fs_cli) or programmatically through a freeswitch interface. To display a list of all commands available to you in the Immersitech Engage Freeswitch Adapter, enter the command “imm_adapter” and the list of API commands within the adapter will be listed as below:

imm_adapter

Usage:

get_version
get_license_info
get_library_configuration
get_json_all_room_layouts
get_room_count
get_room_layout <room_id>
get_participant_count <room_id>
get_participant_position <room_id> <participant_id>
get_participant_seat <room_id> <participant_id>
get_participant_state <room_id> <participant_id> <control>
get_participant_configuration <room_id> <participant_id>
get_participant_name <room_id> <participant_id>
get_participant_spherical <room_id> <listener_id> <source_id>
set_room_layout <room_id> <layout_id>
set_participant_name <room_id> <participant_id> <name>
set_all_participants_state <room_id> <control> <value>
set_participant_state <room_id> <participant_id> <control> <value>
set_participant_position <room_id> <participant_id> <x> <y> <z> <azimuth_heading> <elevation_heading>
set_participant_seat <room_id> <participant_id> <seat_id>
set_log_level <log_level>

The above set of functions exactly mirrors the functions in immersitech.h (without the imm_ prefix) and the functions in Full Event Manager API. To learn the details of these functions or parameters, visit either of the linked locations.

Table of Contents