Immersitech Logo Developer Home
 
Loading...
Searching...
No Matches
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#include <stdint.h>
27#include <stddef.h>
28
29#if HAVE_VISIBILITY
30#define IMMERSITECH_API __attribute__((__visibility__("default")))
31#elif defined _WIN32
32#define IMMERSITECH_API __declspec(dllexport)
33#else
34#define IMMERSITECH_API
35#endif
36
45typedef struct imm_position {
46 int x;
47 int y;
48 int z;
50
58typedef struct imm_heading {
62
71typedef struct imm_seat {
72 int id;
76
81typedef enum imm_audio_control {
100
106typedef enum imm_device_type {
112
126
129typedef enum imm_error_code {
155
170
183
189typedef void* imm_handle;
190
191#ifdef __cplusplus
192extern "C" {
193#endif
194
199
211 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);
212
225 IMMERSITECH_API imm_handle imm_initialize_library_from_memory(uint8_t* license_file_data, size_t license_file_data_size, const char* room_layout_file_name, const char* websocket_config_file_name, imm_library_configuration configuration, imm_error_code* error_code);
226
234
242
249
258
266
275 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);
276
283 IMMERSITECH_API imm_error_code imm_remove_participant(imm_handle handle, int room_id, int participant_id);
284
294
301
309
319 IMMERSITECH_API imm_error_code imm_get_room_layout(imm_handle handle, int room_id, int* layout_id);
320
332
343
354
364
371
378 IMMERSITECH_API imm_error_code imm_get_participant_count(imm_handle handle, int room_id, int* participant_count);
379
390 IMMERSITECH_API imm_error_code imm_get_participant_name(imm_handle handle, int room_id, int participant_id, char* value, int value_length);
391
399 IMMERSITECH_API imm_error_code imm_set_participant_name(imm_handle handle, int room_id, int participant_id, const char* participant_name);
400
411
421 IMMERSITECH_API imm_error_code imm_set_participant_seat(imm_handle handle, int room_id, int participant_id, int seat_id);
422
433 IMMERSITECH_API imm_error_code imm_get_participant_seat(imm_handle handle, int room_id, int participant_id, imm_seat* seat);
434
444
455 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);
456
458 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);
459
461 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);
462
470 IMMERSITECH_API imm_error_code imm_output_audio_short(imm_handle handle, int room_id, int participant_id, short* output);
471
473 IMMERSITECH_API imm_error_code imm_output_audio_float(imm_handle handle, int room_id, int participant_id, float* output);
474
476 IMMERSITECH_API imm_error_code imm_output_audio_double(imm_handle handle, int room_id, int participant_id, double* output);
477
489 IMMERSITECH_API imm_error_code imm_set_participant_position(imm_handle handle, int room_id, int participant_id, imm_position position, imm_heading heading);
490
499 IMMERSITECH_API imm_error_code imm_get_participant_position(imm_handle handle, int room_id, int participant_id, imm_position* position, imm_heading* heading);
500
510 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);
511
520 IMMERSITECH_API imm_error_code imm_get_participant_state(imm_handle handle, int room_id, int participant_id, imm_audio_control control, int* value);
521
534 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);
535
544 IMMERSITECH_API imm_error_code imm_flush_data(imm_handle handle, int room_id, int participant_id);
545
552
560
568
575
576#ifdef __cplusplus
577}
578#endif
579
580#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:129
@ IMM_ERROR_LICENSE_VERSION_MISMATCH
This error code indicates your license files version requirements no longer match....
Definition: immersitech.h:148
@ IMM_ERROR_LICENSE_DATE_EXPIRED
This error code indicates your license files no longer matches the date requirements....
Definition: immersitech.h:147
@ IMM_ERROR_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:153
@ IMM_ERROR_NONE
This error code indicates the function worked successfully without error.
Definition: immersitech.h:131
@ IMM_ERROR_MISSING_OR_INVALID_PARAMETER
This error code indicates that a parameter is either missing or invalid.
Definition: immersitech.h:152
@ IMM_ERROR_DATA_NULL
This error code indicates you tried to use a buffer or variable that wasn't allocated properly.
Definition: immersitech.h:133
@ IMM_ERROR_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:130
@ IMM_ERROR_FILE_DOES_NOT_EXIST
This error code indicates that an invalid file path was provided (invalid path or invalid filename).
Definition: immersitech.h:151
@ 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:140
@ IMM_ERROR_INVALID_JSON_FILE
This error code indicates a syntax error in the provided JSON file (parameter, formating).
Definition: immersitech.h:143
@ IMM_ERROR_PARTICIPANT_TYPE
This error code matches the exceptions specified under imm_participant_type.
Definition: immersitech.h:145
@ IMM_ERROR_INVALID_VALUE
This error code indicates the value provided is outside the bounds specified for the various imm_audi...
Definition: immersitech.h:141
@ 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:134
@ 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:144
@ IMM_ERROR_SPATIAL_QUALITY
This error code indicates that you specified an invalid spatial quality value. Allowable values are f...
Definition: immersitech.h:137
@ IMM_ERROR_INVALID_HEADING
This error code indicates you provide a heading that was outside the allowed values....
Definition: immersitech.h:142
@ IMM_ERROR_HANDLE_NULL
This error code indicates you have not initialized your imm_handle properly yet.
Definition: immersitech.h:132
@ IMM_ERROR_NUM_CHANNELS
This error code indicates that you tried to specify a number of channels outside the allowed bounds....
Definition: immersitech.h:135
@ 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:138
@ 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:139
@ 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:136
@ IMM_ERROR_LIBRARY_NOT_YET_INITIALIZED
This error code will be generated if you call any functions before initializing the library.
Definition: immersitech.h:146
@ 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:150
@ IMM_ERROR_LICENSE_TAMPERED
This error code indicates your license file has been corrupted. All audio effects will be bypassed.
Definition: immersitech.h:149
IMMERSITECH_API imm_handle imm_initialize_library_from_memory(uint8_t *license_file_data, size_t license_file_data_size, 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_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:34
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.
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 ...
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.
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:81
@ 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:96
@ 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:95
@ IMM_CONTROL_AGC_ENABLE
If a participant has AGC enabled, their input audio will be automatically adjusted to match the volum...
Definition: immersitech.h:87
@ IMM_CONTROL_MIXING_3D_ENABLE
If a participant has 3D mixing enabled, they will hear all other participants spatially rendering in ...
Definition: immersitech.h:89
@ 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:88
@ 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:90
@ 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:97
@ IMM_CONTROL_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:82
@ IMM_CONTROL_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:98
@ 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:91
@ IMM_CONTROL_ANC_MIX
If a participant has ANC enabled, this value determines the level of cancellation desired as a percen...
Definition: immersitech.h:86
@ 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:92
@ IMM_CONTROL_STEREO_BYPASS_ENABLE
If the stereo bypass is enabled, all effects will be bypassed, meaning no processing will occur....
Definition: immersitech.h:83
@ IMM_CONTROL_DEVICE
The device setting will help optimize 3D processing for a particular participant's listening device....
Definition: immersitech.h:93
@ IMM_CONTROL_ANC_ENABLE
If a participant has ANC enabled, all noise in their input audio will be automatically cancelled....
Definition: immersitech.h:85
@ 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:94
@ 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:84
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:119
@ IMM_PARTICIPANT_LISTENER_ONLY
A listener only participant will only receive other participant's audio and will NOT input audio.
Definition: immersitech.h:123
@ IMM_PARTICIPANT_REGULAR
A regular participant will both input audio and receive other participant's audio.
Definition: immersitech.h:121
@ IMM_PARTICIPANT_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:120
@ IMM_PARTICIPANT_SOURCE_ONLY
A source only participant will only input audio and will NOT receive other participant's audio.
Definition: immersitech.h:122
@ IMM_PARTICIPANT_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:124
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:189
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:106
@ IMM_DEVICE_SPEAKER
The listening device is a stereo loudspeaker pair. If this is selected, the participant should also s...
Definition: immersitech.h:109
@ IMM_DEVICE_HEADPHONE
The listening device is a headphone, including in-ear, on-ear, and over-ear variants.
Definition: immersitech.h:108
@ IMM_DEVICE_END
This value allows you to identify the end of the enum.
Definition: immersitech.h:110
@ IMM_DEVICE_START
This value allows you to identify the start of the enum.
Definition: immersitech.h:107
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:58
int elevation_heading
Definition: immersitech.h:60
int azimuth_heading
Definition: immersitech.h:59
A structure to describe the configuration of the Immersitech Library.
Definition: immersitech.h:163
bool interleaved
Definition: immersitech.h:167
int output_sampling_rate
Definition: immersitech.h:164
int output_number_frames
Definition: immersitech.h:165
int output_number_channels
Definition: immersitech.h:166
int spatial_quality
Definition: immersitech.h:168
A structure to describe the configuration of a participant.
Definition: immersitech.h:178
int input_sampling_rate
Definition: immersitech.h:179
imm_participant_type type
Definition: immersitech.h:181
int input_number_channels
Definition: immersitech.h:180
A structure to describe a position within a three-dimensional space.
Definition: immersitech.h:45
int x
Definition: immersitech.h:46
int y
Definition: immersitech.h:47
int z
Definition: immersitech.h:48
A structure to describe a seat within a room.
Definition: immersitech.h:71
int id
Definition: immersitech.h:72
imm_position position
Definition: immersitech.h:73
imm_heading heading
Definition: immersitech.h:74