Event Manager API Reference

custom_event

The custom event command will take any message you provide and broadcast it to all connected clients.
This can be useful for you to put additional functionality into your application with adding a different messaging system.

{
"Command": "custom_event",
"room_id": "your_room_id"
}

Any additional key-value pairs that are added to the request will also be broadcast to all connected clients.

get_version

The get version function will return the versions of the Immersitech Library.

{
"Command": "get_version"
}

A successful response will be formatted as follows:

{
"version": "v1.0.0"
}

get_license_info

The get license info function will return detailed information about your license key in JSON format.

{
"Command": "get_license_info"
}

An Example Response would be:

{ 
"license_info": {
   "valid": true, 
   "name": "Immersitech_Engineering_sound_manager_license_key.dat", 
   "department": "Engineering", 
   "minimum_version": "v0.7.0", 
   "maximum_version": "v0.15.999", 
   "creation_date": "4/5/2021", 
   "expiration_date": "7/15/2021" 
   }
}

get_library_configuration

This command will return information about the current library configuration.

{
"Command": "get_library_configuration"
}

Returned parameters will include:

{
"interleaved": bool,
"output_number_channels": integer,
"output_number_frames": integer,
"output_sampling_rate": integer,
"spatial_quality": integer
}

get_json_all_room_layouts

This command will return a JSON packet detailing all the available room layouts.

{
"Command": "get_json_all_room_layouts"
}

The response will be an exact replica of your provided room layout json file.
Reference your room layout json file for the format of the response.

get_room_layout

This command will return the id of the layout a given room is current using.
This integer id can be related to the list of room layouts found with get_json_all_room_layouts

{
"Command": "get_room_layout",
"room_id": integer_room_id
}

The response will contain the following parameters

{
"layout_id": integer_layout_id
}

get_room_count

This command will return the number of rooms that currently exist

{
"Command": "get_room_count"
}

The response will contain the following parameters

{
"room_count": integer_number_of_rooms
}

get_participant_count

This command will return the number of participants that are currently in a given room

{
"Command": "get_participant_count",
"room_id": integer_room_id
}

The response will contain the following parameters

{
"participant_count": integer_number_of_participants
}

get_participant_position

You can retrieve the current position of a participant. Note that you must have already set the position of the participant otherwise the response will return with an error.

{
"Command": "get_participant_position",
"room_id": integer_room_id,
"participant_id": integer_participant_id
}

The response to this message will contain the following parameters:

{
"x": integer,
"y": integer,
"z": integer,
"azimuth_heading": integer,
"elevation_heading": integer
}

set_participant_position

If the room layout that is currently set is set up as an open room then you can set the position and heading for each participant. You will need provide the x, y, and z coordinates as well as the azimuth and elevation headings.

{
"Command": "set_participant_position",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"x": integer,
"y": integer,
"z": integer,
"azimuth_heading": integer,
"elevation_heading": integer
}

set_participant_seat

This command will move a participant to a new seat that you specify.
The return message will include the position and heading of the new seat.
Recall that seats are 1 indexed from the array in the room layout.

{
"Command": "set_participant_seat",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"seat_id": integer_value
}

The response to this command will include the following parameters:

{
"new_seat_id": integer,
"new_seat_x": integer,
"new_seat_y": integer,
"new_seat_z": integer,
"new_seat_azimuth_heading": integer,
"new_seat_elevation_heading": integer
}

get_participant_seat

This command will get information about a participant's current seat

{
"Command": "get_participant_seat",
"room_id": integer_room_id,
"participant_id": integer_participant_id
}

The response to this command will include the following parameters:

{
"seat_id": integer,
"seat_x": integer,
"seat_y": integer,
"seat_z": integer,
"seat_azimuth_heading": integer,
"seat_elevation_heading": integer
}

set_room_layout

This command will change the layout of a room.
This means the participants in the room will likely be re-positioned.
Recall that layouts are 1 indexed from the "room_list" in the room layout file.

Take a look at our example room layout json for how to designate a room as an open room.

{
"Command": "set_room_layout",
"room_id": integer_room_id,
"layout_id": integer_value
}

get_participant_name

This command will get the name of a given participant.

{
"Command": "get_participant_name",
"room_id": integer_room_id,
"participant_id": integer_participant_id
}

The response will contain the following parameters

{
"name": "participant's name"
}

set_participant_name

You can use this command to change the display name of a participant in the call, real time:

{
"Command": "set_participant_name",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"participant_name": "the new display name you'd like them to have"
}

get_participant_configuration

This command will get information about the configuration for a participant.

{
"Command": "get_participant_configuration",
"room_id": integer_room_id,
"participant_id": integer_participant_id
}

The response to this command will include the following parameters:

{
"input_number_channels": integer,
"input_sampling_rate": integer,
"type": integer
}

set_all_participants_state

This command will set the state of every participant in a room.
Please view imm_audio_control for a list of all available controls you can adjust, including the allowed ranges and defaults for each control.

{
"Command": "set_all_participants_state",
"room_id": integer_room_id,
"control_to_edit": "String or integer for the audio control",
"value": "String or integer for the new state of the audio control"
}

Example command to turn noise cancellation on:

{
"Command": "set_all_participants_state",
"room_id": "1",
"control_to_edit": "IMM_CONTROL_ANC_ENABLE",
"value": 1
}

get_participant_state

This command will find the state of an audio control for a single participant.

"Command": "get_participant_state",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"control_to_edit": "String or integer for the audio control"

Please view imm_audio_control for a list of all available controls you can adjust, including the allowed ranges and defaults for each control.
The response will contain the following parameters

{
"value": integer_control_state
}

set_participant_state

The command will set the state of an audio control for a single participant.

"Command": "set_participant_state",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"control_to_edit": "String or integer for the audio control",
"value": "String or integer for the new state of the audio control"

Please view imm_audio_control for a list of all available controls you can adjust, including the allowed ranges and defaults for each control.
Example command to turn noise cancellation on:

{
"Command": "set_participant_state",
"room_id": 2,
"participant_id": 1,
"control_to_edit": "IMM_CONTROL_ANC_ENABLE",
"value": true
}

get_participant_spherical

This command will get the angle from one participant to another in spherical coordinates.
The coordinates represent the direction the listener participant hears the source participant.

{
"Command": "get_participant_spherical",
"room_id": 1,
"listener_id": 1,
"source_id": 2
}

The response to this command will have the following parameters:

{
"azimuth": integer,
"elevation": integer,
"distance": integer
}