Websocket API

Table of Contents

• Usage
• Configuring your Event Manager
• Connecting Your Client to Event Manager
• Making a Request and Receiving a Response with Your Client
• Receiving an Event from the Host
• Full Event Manager API
  • custom_event
  • get_version
  • get_license_info
  • get_library_configuration
  • get_json_all_room_layouts
  • get_room_layout
  • get_room_count
  • get_participant_count
  • get_participant_position
  • set_participant_position
  • set_participant_seat
  • get_participant_seat
  • set_room_layout
  • get_participant_name
  • set_participant_name
  • get_participant_configuration
  • set_all_participants_state
  • get_participant_state
  • set_participant_state
  • get_participant_spherical
  • add_demo_participant
  • remove_demo_participant
  • play_audio_file
  • stop_audio_file

Usage

To use the Event Manager Websocket library you only need to follow very simple steps. On the server side, first make sure you have a valid websocket configuration file and it is pointed to properly by imm_initialize_library. Seconly simply call the following function to start up the websocket server:

imm_handle handle = imm_initialize_library( license, room_layout, websocket_config_path, library_config, error_code );
imm_enable_websockets( handle, true );

The server will run perpetually allowing clients to connect, send, and receive messages until you call the following function to stop it:

imm_enable_websockets( handle, false );     // stop manually
imm_destroy_library( handle );          // stop automatically upon destroying the library 

And that is it! The server will take care of the rest.

Configuring your Event Manager

When first call imm_initialize_library, you provide a path to your websocket configuration file, imm_websocket_config.json. In this file, there are several parameter you can edit that will allow the server to work under your preferences and utilize your specific keys to ensure a secure connection.

{
   "port": 9002,
   "certificate_file": "none",
   "certificate_chain_file": "/usr/src/server.pem",
   "private_key_file": "/usr/src/server.pem",
   "rsa_private_key_file": "none",
   "tmp_dh_file": "/usr/src/dh.pem",
   "authentification_key": "Immersitech",
   "authentification_value": "I_am_valid_immersitech_please_accept_me"
}

There are 5 different options for certificates you can provide. You do not need to provide all or any of them, only the ones you want to use. If you do not want to use an option, just provide "none" in the field. The two authentication fields can be any key-value pair that you desire to require in your custom handshake header.

Now to learn how to interact with the server using a web client, proceed to the next section.

Connecting Your Client to Event Manager

If there is an Event Manager Websocket server running somewhere, you can now connect to it to send and receive events. Let us see how to do so.

In order to connect your client to event manager, you must follow a few steps. First you should use the standard websocket connection method of calling wss://example.com:9002 where you replace example.com with the IP address to your server and 9002 with the port number you specified in the websocket-config file on the server. The event manager always utilizes TLS security, so ensure your provided keys are correct and match for the server and client. In order for event manager to authorize any client, it requires that a special key is added to the websocket handshake header. This ensures the safety of all incoming connections. You will need to add the following to your header: "Immersitech": "I_am_valid_immersitech_please_accept_me" (or whichever values you set for authentification_key and authentification_value). At any given point while trying to establish a connection, watch your terminal on the server for helpful debugging messages.

Making a Request and Receiving a Response with Your Client

For a client to make a request, they must simply create a JSON message and pass it to the websocket server.

When the server receives your request, it will be processed and a JSON response with the following key-value pairs will be returned to you:

{
"Status": "string - either OK or ERROR. OK indicates a success while ERROR indicates a failure to fulfill request",
 
"Error Code": "imm_error_code - an enum value from the imm_error_code enumeration",
 
"Error Description": "string - a description of what went wrong if there was an error",
 
"Request": JSON - the JSON object that was originally requested,
 
"value": string / int - additional information you requested, such as get participant state
}

Note that if you receive "Status": "OK", then you will not see a key-value pair for "Error Description" in your response JSON. Additionally, you will only receive "Value" or other key-value pairs if your original request was asking for a value. Your request may provide additional output parameters if they are relevant, and would be described in the full API below.

Receiving an Event from the Host

Sometimes a host program may perform actions without the request of a client. In this case, the server will want to keep the client up to date by sending a message to the client about an event that occurred. If an event occurred, you will see a JSON formatted message with the following key-value pairs:

{
"Event": "string - describing what event occurred",
 
"values": "string / integer_value - providing additional information about the event"
}

To see a full list of events that may be triggered, view imm_event_type

Full Event Manager API

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"
 }

Note that anything else in additional to what is described about is also broadcast with the JSON. So feel free to add your custom message as a JSON packet, a string, or anything you'd like.

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 existing

 {
"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 with:

 {
"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

You can change the x, y, z position of a particular participant using the following. You also must include a heading to manually set the direction they will be facing.

 {
"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.

 {
"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 way a participant was configured.

 {
"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 their allowed ranges and defaults.

 {
"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 their allowed ranges and defaults.

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 their allowed ranges and defaults.

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
}

add_demo_participant

This command allows you to add a demo participant into a room. Audio files can later be played through this demo participant and be rendered in 3D. Note that demo participants may only have an ID that is a negative integer to protect from confusing demo participants and real ones.

"Command": "add_demo_participant",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"sampling_rate": sampling_rate_of_the_files_you_want_to_play_through_this_participant,
"number_channels": number_of_channels_of_files_you_want_to_play_through_this_participant,
"demo_name": "display name associated with this demo participant"

remove_demo_participant

If you want to later remove a demo participant, you can use the following syntax. Be careful not to use the ID of a real participant, as it will remove them instead and likely break your application.

"Command": "remove_demo_participant",
"room_id": integer_room_id,
"participant_id": integer_participant_id

play_audio_file

This function is used to play audio through a demo participant. Be careful not to accidentally send the ID of a real participant, as it will play the audio through them instead.

"Command": "play_audio_file",
"room_id": integer_room_id,
"participant_id": integer_participant_id,
"file_path": "path to the audio file you'd like to play"

stop_audio_file

If you want to stop playback of a file you read into a particular demo participant, you can use the following:

"Command": "stop_audio_file",
"room_id": integer_room_id
"participant_id": integer_participant_id