Immersitech Logo Developer Home
immersitech.h
Go to the documentation of this file.
1#pragma once
2
21
22#ifndef IMMERSITECH_LIBRARY_H_
23#define IMMERSITECH_LIBRARY_H_
24
25#include <stdbool.h>
26
27#if HAVE_VISIBILITY
28#define IMMERSITECH_API __attribute__((__visibility__("default")))
29#elif defined _WIN32
30#define IMMERSITECH_API __declspec(dllexport)
31#else
32#define IMMERSITECH_API
33#endif
34
43typedef struct imm_position {
44 int x;
45 int y;
46 int z;
48
56typedef struct imm_heading {
60
69typedef struct imm_seat {
70 int id;
74
79typedef enum imm_audio_control {
97
103typedef enum imm_device_type {
109
123
126typedef enum imm_error_code {
149
164
177
183typedef void* imm_handle;
184
185#ifdef __cplusplus
186extern "C" {
187#endif
188
193
205 IMMERSITECH_API imm_handle imm_initialize_library(const char* license_file_name, const char* room_layout_file_name, const char* websocket_config_file_name, imm_library_configuration configuration, imm_error_code* error_code);
206
214
222
229
238
246
255 IMMERSITECH_API imm_error_code imm_add_participant(imm_handle handle, int room_id, int participant_id, const char* participant_name, imm_participant_configuration config);
256
263 IMMERSITECH_API imm_error_code imm_remove_participant(imm_handle handle, int room_id, int participant_id);
264
274
281
289
299 IMMERSITECH_API imm_error_code imm_get_room_layout(imm_handle handle, int room_id, int* layout_id);
300
312
323
334
344
351
358 IMMERSITECH_API imm_error_code imm_get_participant_count(imm_handle handle, int room_id, int* participant_count);
359
370 IMMERSITECH_API imm_error_code imm_get_participant_name(imm_handle handle, int room_id, int participant_id, char* value, int value_length);
371
379 IMMERSITECH_API imm_error_code imm_set_participant_name(imm_handle handle, int room_id, int participant_id, const char* participant_name);
380
391
401 IMMERSITECH_API imm_error_code imm_set_participant_seat(imm_handle handle, int room_id, int participant_id, int seat_id);
402
413 IMMERSITECH_API imm_error_code imm_get_participant_seat(imm_handle handle, int room_id, int participant_id, imm_seat* seat);
414
424
435 IMMERSITECH_API imm_error_code imm_input_audio_short(imm_handle handle, int room_id, int participant_id, const short* audio_data, int number_frames);
436
438 IMMERSITECH_API imm_error_code imm_input_audio_float(imm_handle handle, int room_id, int participant_id, const float* audio_data, int number_frames);
439
441 IMMERSITECH_API imm_error_code imm_input_audio_double(imm_handle handle, int room_id, int participant_id, const double* audio_data, int number_frames);
442
450 IMMERSITECH_API imm_error_code imm_output_audio_short(imm_handle handle, int room_id, int participant_id, short* output);
451
453 IMMERSITECH_API imm_error_code imm_output_audio_float(imm_handle handle, int room_id, int participant_id, float* output);
454
456 IMMERSITECH_API imm_error_code imm_output_audio_double(imm_handle handle, int room_id, int participant_id, double* output);
457
469 IMMERSITECH_API imm_error_code imm_set_participant_position(imm_handle handle, int room_id, int participant_id, imm_position position, imm_heading heading);
470
479 IMMERSITECH_API imm_error_code imm_get_participant_position(imm_handle handle, int room_id, int participant_id, imm_position* position, imm_heading* heading);
480
490 IMMERSITECH_API imm_error_code imm_set_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control_to_edit, int value);
491
500 IMMERSITECH_API imm_error_code imm_get_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control, int* value);
501
514 IMMERSITECH_API imm_error_code imm_get_participant_spherical(imm_handle handle, int room_id, int listener_id, int source_id, int* azimuth, int* elevation, int* distance);
515
524 IMMERSITECH_API imm_error_code imm_flush_data(imm_handle handle, int room_id, int participant_id);
525
532
540
548
555
556#ifdef __cplusplus
557}
558#endif
559
560#endif // IMMERSITECH_LIBRARY_H_
IMMERSITECH_API imm_error_code imm_destroy_room(imm_handle handle, int room_id)
Function to removes all remaining participants from a room and frees all the data allocated for a roo...
IMMERSITECH_API imm_error_code imm_set_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control_to_edit, int value)
Function to set the state of a given participant.
IMMERSITECH_API imm_error_code imm_output_audio_float(imm_handle handle, int room_id, int participant_id, float *output)
Duplicate of imm_output_audio_short except the output is a 32 bit float. See imm_output_audio_short f...
IMMERSITECH_API imm_error_code imm_set_log_level(int level)
Function to set the log level of the Immersitech logger.
IMMERSITECH_API imm_error_code imm_remove_participant(imm_handle handle, int room_id, int participant_id)
Function to remove a participant from a room.
IMMERSITECH_API imm_error_code imm_flush_data(imm_handle handle, int room_id, int participant_id)
Function to clear all data related to a particular participant.
IMMERSITECH_API int imm_string_to_participant_value(const char *value_string)
Convert string to specific participant value.
imm_error_code
All error codes that may be produced by the library.
Definition: immersitech.h:126
@ IMM_ERROR_LICENSE_VERSION_MISMATCH
This error code indicates your license files version requirements no longer match....
Definition: immersitech.h:144
@ IMM_ERROR_LICENSE_DATE_EXPIRED
This error code indicates your license files no longer matches the date requirements....
Definition: immersitech.h:143
@ IMM_ERROR_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:147
@ IMM_ERROR_NONE
This error code indicates the function worked successfully without error.
Definition: immersitech.h:128
@ IMM_ERROR_DATA_NULL
This error code indicates you tried to use a buffer or variable that wasn't allocated properly.
Definition: immersitech.h:130
@ IMM_ERROR_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:127
@ IMM_ERROR_INVALID_CONTROL
This error code indicates the control specified is not a valid one with the bounds of imm_audio_contr...
Definition: immersitech.h:137
@ IMM_ERROR_PARTICIPANT_TYPE
This error code matches the exceptions specified under imm_participant_type.
Definition: immersitech.h:141
@ IMM_ERROR_INVALID_VALUE
This error code indicates the value provided is outside the bounds specified for the various imm_audi...
Definition: immersitech.h:138
@ IMM_ERROR_DATA_LENGTH
This error code indicates there is a mismatch between the size of the data buffer you provided and th...
Definition: immersitech.h:131
@ IMM_ERROR_NO_INPUT_AUDIO
This error code indicates that there was no input audio to be processed, meaning an output buffer cou...
Definition: immersitech.h:140
@ IMM_ERROR_SPATIAL_QUALITY
This error code indicates that you specified an invalid spatial quality value. Allowable values are f...
Definition: immersitech.h:134
@ IMM_ERROR_INVALID_HEADING
This error code indicates you provide a heading that was outside the allowed values....
Definition: immersitech.h:139
@ IMM_ERROR_HANDLE_NULL
This error code indicates you have not initialized your imm_handle properly yet.
Definition: immersitech.h:129
@ IMM_ERROR_NUM_CHANNELS
This error code indicates that you tried to specify a number of channels outside the allowed bounds....
Definition: immersitech.h:132
@ IMM_ERROR_INVALID_ROOM_ID
This error code indicates that you requested a room with an ID that doesn't exist or tried to create ...
Definition: immersitech.h:135
@ IMM_ERROR_INVALID_PARTICIPANT_ID
This error code indicates that you requested a participant with an ID that doesn't exist or tried to ...
Definition: immersitech.h:136
@ IMM_ERROR_SAMPLE_RATE
This error code indicates that you tried to specify an output sampling rate that is unsupported or an...
Definition: immersitech.h:133
@ IMM_ERROR_LIBRARY_NOT_YET_INITIALIZED
This error code will be generated if you call any functions before initializing the library.
Definition: immersitech.h:142
@ IMM_ERROR_LICENSE_MISSING
This error code indicates the path to your license file is invalid. All audio effects will be bypasse...
Definition: immersitech.h:146
@ IMM_ERROR_LICENSE_TAMPERED
This error code indicates your license file has been corrupted. All audio effects will be bypassed.
Definition: immersitech.h:145
struct imm_participant_configuration imm_participant_configuration
A structure to describe the configuration of a participant.
IMMERSITECH_API imm_error_code imm_create_room(imm_handle handle, int room_id)
Function to allocate memory and initialize a new room.
IMMERSITECH_API imm_error_code imm_output_audio_double(imm_handle handle, int room_id, int participant_id, double *output)
Duplicate of imm_output_audio_short except the output is a 64 bit float. See imm_output_audio_short f...
IMMERSITECH_API imm_error_code imm_input_audio_short(imm_handle handle, int room_id, int participant_id, const short *audio_data, int number_frames)
Function to input audio data from a participant into a room.
IMMERSITECH_API const char * imm_get_json_all_room_layouts(imm_handle handle)
Function to view all the available room layouts as a JSON formatted string.
IMMERSITECH_API imm_error_code imm_add_event_manager(imm_handle handle, void *event_manager)
Function to link a custom event manager with the library.
IMMERSITECH_API imm_error_code imm_set_participant_position(imm_handle handle, int room_id, int participant_id, imm_position position, imm_heading heading)
Function to set the x,y,z position of a given participant.
IMMERSITECH_API imm_error_code imm_enable_websockets(imm_handle handle, bool enable)
Function to enable the websocket server for controlling settings via websockets.
IMMERSITECH_API imm_error_code imm_destroy_library(imm_handle handle)
Function to frees all memory associated with the immersitech library.
IMMERSITECH_API imm_error_code imm_input_audio_float(imm_handle handle, int room_id, int participant_id, const float *audio_data, int number_frames)
Duplicate of imm_input_audio_short except the input is a 32 bit float. See imm_input_audio_short for ...
IMMERSITECH_API imm_error_code imm_set_room_layout(imm_handle handle, int room_id, int layout_id)
Function to set a room's layout.
IMMERSITECH_API imm_error_code imm_set_participant_name(imm_handle handle, int room_id, int participant_id, const char *participant_name)
Function to set the name of a participant.
IMMERSITECH_API imm_error_code imm_get_participant_configuration(imm_handle handle, int room_id, int participant_id, imm_participant_configuration *config)
Function to get information about a participant's configuration.
#define IMMERSITECH_API
Definition: immersitech.h:32
IMMERSITECH_API imm_error_code imm_get_participant_name(imm_handle handle, int room_id, int participant_id, char *value, int value_length)
Function view the name of a particular participant.
IMMERSITECH_API imm_error_code imm_enable_logging(bool enable)
Function to turn on or off logging within the Immersitech Library.
IMMERSITECH_API imm_error_code imm_output_audio_short(imm_handle handle, int room_id, int participant_id, short *output)
Function to process audio data and return the output audio data for a participant.
IMMERSITECH_API const char * imm_error_code_to_string(imm_error_code error_code)
Get a human readable string for an error code.
IMMERSITECH_API imm_error_code imm_get_participant_count(imm_handle handle, int room_id, int *participant_count)
Function to learn how many participants are currently in a given room.
struct imm_position imm_position
A structure to describe a position within a three-dimensional space.
struct imm_heading imm_heading
A structure to describe the direction a participant is facing in three-dimensional space.
IMMERSITECH_API imm_audio_control imm_string_to_audio_control(const char *control_string)
Convert string to an imm_audio_control enum value that is compatible with various sound manager funct...
IMMERSITECH_API imm_error_code imm_get_room_count(imm_handle handle, int *room_count)
Function to learn how many rooms are currently active.
IMMERSITECH_API imm_error_code imm_input_audio_double(imm_handle handle, int room_id, int participant_id, const double *audio_data, int number_frames)
Duplicate of imm_input_audio_short except the input is a 64 bit float. See imm_input_audio_short for ...
struct imm_seat imm_seat
A structure to describe a seat within a room.
IMMERSITECH_API const char * imm_get_license_info(imm_handle handle)
Function to return information about your current license key.
IMMERSITECH_API imm_error_code imm_get_participant_seat(imm_handle handle, int room_id, int participant_id, imm_seat *seat)
Function get information about a participant's current seat.
IMMERSITECH_API imm_error_code imm_get_participant_position(imm_handle handle, int room_id, int participant_id, imm_position *position, imm_heading *heading)
Function to retrieve Location of a given participant.
IMMERSITECH_API const char * imm_get_version()
Function to return the current version of the immersitech library.
struct imm_library_configuration imm_library_configuration
A structure to describe the configuration of the Immersitech Library.
IMMERSITECH_API imm_error_code imm_add_participant(imm_handle handle, int room_id, int participant_id, const char *participant_name, imm_participant_configuration config)
Function to add a new pariticipant into a room.
imm_audio_control
Audio Controls you can change in real-time.
Definition: immersitech.h:79
@ IMM_CONTROL_WHISPER_ROOM
If a participant's whisper room is set to a non-zero value from 1-100, they will be rendered inside t...
Definition: immersitech.h:93
@ 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.h:92
@ IMM_CONTROL_AGC_ENABLE
If a participant has AGC enabled, their input audio will be automatically adjusted to match the volum...
Definition: immersitech.h:84
@ IMM_CONTROL_MIXING_3D_ENABLE
If a participant has 3D mixing enabled, they will hear all other participants spatially rendering in ...
Definition: immersitech.h:86
@ IMM_CONTROL_AUTO_EQ_ENABLE
If a participant has Auto EQ enabled, their input audio will automatically adjusted to maximize the c...
Definition: immersitech.h:85
@ IMM_CONTROL_MIXING_3D_ATTENUATION
If 3D mixing is enabled, this control will determine how the volume of a source drops off as they mov...
Definition: immersitech.h:87
@ IMM_CONTROL_SIDEBAR_ROOM
If a participant's sidebar room is set to a non-zero value from 1-100, they will be rendered inside t...
Definition: immersitech.h:94
@ IMM_CONTROL_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:80
@ IMM_CONTROL_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:95
@ IMM_CONTROL_MIXING_3D_MAX_DISTANCE
If 3D mixing is enabled, this control will determine the max distance up to which attenuation will ap...
Definition: immersitech.h:88
@ IMM_CONTROL_MIXING_3D_REVERB_ENABLE
If 3D mixing is enabled, this control will determine if reverb is applied to the 3D rendering....
Definition: immersitech.h:89
@ IMM_CONTROL_STEREO_BYPASS_ENABLE
If the stereo bypass is enabled, all effects will be bypassed, meaning no processing will occur....
Definition: immersitech.h:81
@ IMM_CONTROL_DEVICE
The device setting will help optimize 3D processing for a particular participant's listening device....
Definition: immersitech.h:90
@ IMM_CONTROL_ANC_ENABLE
If a participant has ANC enabled, all noise in their input audio will be automatically cancelled....
Definition: immersitech.h:83
@ IMM_CONTROL_HALF_SPAN_ANGLE
If the participant is using speakers, they should set the Half Span Angle from 1 to 90 to match the p...
Definition: immersitech.h:91
@ IMM_CONTROL_MUTE_ENABLE
If a participant's mute is enabled, their input audio will not be passed to the other participants....
Definition: immersitech.h:82
IMMERSITECH_API imm_error_code imm_set_all_participants_state(imm_handle handle, int room_id, imm_audio_control control_to_edit, int value)
Function to change an audio control for every participant in a room all at once.
IMMERSITECH_API imm_error_code imm_send_custom_websocket_event(imm_handle handle, int room_id, const char *message)
Function to broadcast any arbitrary message through the websocket server to all clients.
imm_participant_type
Types of participants you can instantiate.
Definition: immersitech.h:116
@ IMM_PARTICIPANT_LISTENER_ONLY
A listener only participant will only receive other participant's audio and will NOT input audio.
Definition: immersitech.h:120
@ IMM_PARTICIPANT_REGULAR
A regular participant will both input audio and receive other participant's audio.
Definition: immersitech.h:118
@ IMM_PARTICIPANT_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:117
@ IMM_PARTICIPANT_SOURCE_ONLY
A source only participant will only input audio and will NOT receive other participant's audio.
Definition: immersitech.h:119
@ IMM_PARTICIPANT_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:121
IMMERSITECH_API const char * imm_audio_control_to_string(imm_audio_control control)
Convert an imm_audio_control to a human-readable string description.
IMMERSITECH_API imm_error_code imm_set_participant_seat(imm_handle handle, int room_id, int participant_id, int seat_id)
Function move a participant to a new seat.
void * imm_handle
Immersitech Library API Handler.
Definition: immersitech.h:183
IMMERSITECH_API imm_error_code imm_get_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control, int *value)
Function to retrieve state of a given participant.
IMMERSITECH_API imm_error_code imm_get_participant_spherical(imm_handle handle, int room_id, int listener_id, int source_id, int *azimuth, int *elevation, int *distance)
Function to retrieve Spherical Coordinates of a given source of a given participant.
IMMERSITECH_API imm_error_code imm_get_room_layout(imm_handle handle, int room_id, int *layout_id)
Function to view which room layout a paritcular room is currently set to.
imm_device_type
Output Device Types you may be listening on.
Definition: immersitech.h:103
@ IMM_DEVICE_SPEAKER
The listening device is a stereo loudspeaker pair. If this is selected, the participant should also s...
Definition: immersitech.h:106
@ IMM_DEVICE_HEADPHONE
The listening device is a headphone, including in-ear, on-ear, and over-ear variants.
Definition: immersitech.h:105
@ IMM_DEVICE_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:107
@ IMM_DEVICE_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:104
IMMERSITECH_API imm_handle imm_initialize_library(const char *license_file_name, const char *room_layout_file_name, const char *websocket_config_file_name, imm_library_configuration configuration, imm_error_code *error_code)
Function to allocate memory for the immersitech library.
IMMERSITECH_API imm_library_configuration imm_get_library_configuration(imm_handle handle)
Function to get all the information about the way you configured the Immersitech Library.
A structure to describe the direction a participant is facing in three-dimensional space.
Definition: immersitech.h:56
int elevation_heading
Definition: immersitech.h:58
int azimuth_heading
Definition: immersitech.h:57
A structure to describe the configuration of the Immersitech Library.
Definition: immersitech.h:157
bool interleaved
Definition: immersitech.h:161
int output_sampling_rate
Definition: immersitech.h:158
int output_number_frames
Definition: immersitech.h:159
int output_number_channels
Definition: immersitech.h:160
int spatial_quality
Definition: immersitech.h:162
A structure to describe the configuration of a participant.
Definition: immersitech.h:172
int input_sampling_rate
Definition: immersitech.h:173
imm_participant_type type
Definition: immersitech.h:175
int input_number_channels
Definition: immersitech.h:174
A structure to describe a position within a three-dimensional space.
Definition: immersitech.h:43
int x
Definition: immersitech.h:44
int y
Definition: immersitech.h:45
int z
Definition: immersitech.h:46
A structure to describe a seat within a room.
Definition: immersitech.h:69
int id
Definition: immersitech.h:70
imm_position position
Definition: immersitech.h:71
imm_heading heading
Definition: immersitech.h:72