#include <stdbool.h>#include <stdint.h>#include <stddef.h>Go to the source code of this file.
Classes | |
| struct | imm_position |
| A structure to describe a position within a three-dimensional space. More... | |
| struct | imm_heading |
| A structure to describe the direction a participant is facing in three-dimensional space. More... | |
| struct | imm_seat |
| A structure to describe a seat within a room. More... | |
| struct | imm_library_configuration |
| A structure to describe the configuration of the Immersitech Library. More... | |
| struct | imm_participant_configuration |
| A structure to describe the configuration of a participant. More... | |
Macros | |
| #define | IMMERSITECH_LIBRARY_H_ |
| #define | IMMERSITECH_API |
Typedefs | |
| typedef struct imm_position | imm_position |
| A structure to describe a position within a three-dimensional space. More... | |
| typedef struct imm_heading | imm_heading |
| A structure to describe the direction a participant is facing in three-dimensional space. More... | |
| typedef struct imm_seat | imm_seat |
| A structure to describe a seat within a room. More... | |
| typedef enum imm_audio_control | imm_audio_control |
| Audio Controls you can change in real-time. More... | |
| typedef enum imm_device_type | imm_device_type |
| Output Device Types you may be listening on. More... | |
| typedef enum imm_participant_type | imm_participant_type |
| Types of participants you can instantiate. More... | |
| typedef enum imm_error_code | imm_error_code |
| All error codes that may be produced by the library. More... | |
| typedef struct imm_library_configuration | imm_library_configuration |
| A structure to describe the configuration of the Immersitech Library. More... | |
| typedef struct imm_participant_configuration | imm_participant_configuration |
| A structure to describe the configuration of a participant. More... | |
| typedef void * | imm_handle |
| Immersitech Library API Handler. More... | |
Functions | |
| IMMERSITECH_API const char * | imm_get_version () |
| Function to return the current version of the immersitech library. More... | |
| 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. More... | |
| 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. More... | |
| IMMERSITECH_API imm_error_code | imm_destroy_library (imm_handle handle) |
| Function to frees all memory associated with the immersitech library. More... | |
| IMMERSITECH_API const char * | imm_get_license_info (imm_handle handle) |
| Function to return information about your current license key. More... | |
| 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. More... | |
| IMMERSITECH_API imm_error_code | imm_create_room (imm_handle handle, int room_id) |
| Function to allocate memory and initialize a new room. More... | |
| 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 room. More... | |
| 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. More... | |
| 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. More... | |
| IMMERSITECH_API imm_error_code | imm_enable_logging (bool enable) |
| Function to turn on or off logging within the Immersitech Library. More... | |
| IMMERSITECH_API imm_error_code | imm_set_log_level (int level) |
| Function to set the log level of the Immersitech logger. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| IMMERSITECH_API imm_error_code | imm_enable_websockets (imm_handle handle, bool enable) |
| Function to enable the websocket server for controlling settings via websockets. More... | |
| 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. More... | |
| IMMERSITECH_API imm_error_code | imm_get_room_count (imm_handle handle, int *room_count) |
| Function to learn how many rooms are currently active. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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 more details. More... | |
| 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 more details. More... | |
| 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. More... | |
| 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 for more details. More... | |
| 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 for more details. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| IMMERSITECH_API const char * | imm_audio_control_to_string (imm_audio_control control) |
| Convert an imm_audio_control to a human-readable string description. More... | |
| 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 functions. More... | |
| IMMERSITECH_API int | imm_string_to_participant_value (const char *value_string) |
| Convert string to specific participant value. More... | |
| IMMERSITECH_API const char * | imm_error_code_to_string (imm_error_code error_code) |
| Get a human readable string for an error code. More... | |
| #define IMMERSITECH_API |
| #define IMMERSITECH_LIBRARY_H_ |
Copyright (C) Immersitech 2021 The use of this code is bound by the Immersitech Terms of Use at: https://immersitech.io/terms-of-use/
DESCRIPTION Immersitech Library Interface definition file
NOTES
This is the Immersitech Library API To learn more please send an email to info@.nosp@m.imme.nosp@m.rsite.nosp@m.ch.i.nosp@m.o or visit https://www.immersitech.io/
Author: Isaac Mosebrook Date Created: August 14, 2019 Date Modified: July 7, 2021
| typedef enum imm_audio_control imm_audio_control |
Audio Controls you can change in real-time.
A list of all the audio effects available in the Immersitech Library. For any control that ends with ENABLE, the only two possible values are 1 or 0 (enabled or disabled respectively).
| typedef enum imm_device_type imm_device_type |
Output Device Types you may be listening on.
The type of device a participant is listening to the output on. Note that speaker refers to a stereo loudspeaker pair. If a participant isn't sure what type of device they have, it is always advised to default to IMM_DEVICE_HEADPHONE.
| typedef enum imm_error_code imm_error_code |
All error codes that may be produced by the library.
| typedef void* imm_handle |
Immersitech Library API Handler.
This handle will help keep a pointer to the instance of the Immersitech Library you generate using the imm_initialize_library function. You must have a valid imm_handle to use almost every function in the Immersitech API. It therefore follows you should always call imm_initialize_library before any other function and check the error_code indicates it was a success before any other actions.
| typedef struct imm_heading imm_heading |
A structure to describe the direction a participant is facing in three-dimensional space.
The azimuth angle is with respect to the x and z plane. The elevation angle is with respect to the y and z plane.
| azimuth_heading | The azimuth angle the participant is facing. Allowable azimuth headings are from -180 to 180. |
| elevation_heading | The elevation angle the participant is facing. Allowable elevation headings are from -90 to 90. |
| typedef struct imm_library_configuration imm_library_configuration |
A structure to describe the configuration of the Immersitech Library.
| output_sampling_rate | The output sampling rate of the library. Currently the library only supports output sampling rates of 48000, 32000, 24000, 16000, 8000. |
| output_number_frames | The number of frames generated in the output. Currently the library supports values of 480 (10 milliseconds), 512, 960 (20 milliseconds), and 1024. |
| output_num_channels | The number of channels the library will output. Note if you are using any 3D effects, you must have at least 2 channels. Currently the library only supports 1 or 2 channel output. |
| interleaved | If set to true, any multi-channel audio input or output from the library will be interleaved. If set to false, it will be de-intereleaved. For quick reference, a left right stereo signal that is interleaved would appear [ L R L R ] while it would appear [ L L R R] if deinterleaved. |
| spatial_quality | This value describes the tradeof with 3D rendering between CPU speed and audio quality. A smaller value (1) gives better CPU / RAM performance but lesser 3D accuracy while a higher value (5) gives better audio quality with worse CPU / RAM performance. Acceptable integer values range from 1 to 5. |
| typedef struct imm_participant_configuration imm_participant_configuration |
A structure to describe the configuration of a participant.
Note that these settings will apply to the participant's input while the library configuration will determine their output sampling rate, channels, etc.. The library will resample an input with a different input sampling rate to match the library's output sampling rate.
| input_sampling_rate | The input sampling rate of the new participant. |
| input_num_channels | The number of channels that this participant will input. Currently only supports 1 or 2 channels input. |
| type | An imm_participant_type value that will describe whether this participant will input audio, output audio, or both. |
| typedef enum imm_participant_type imm_participant_type |
Types of participants you can instantiate.
The rules will be enforced stricly. For example, if you create a source only participant and try to output audio, a error code will be returned and no processing will occur. One possible benefit of source only participants would be sound effect audio or audio from a video being shown in a conference. One possible benefit of listener only participants would be recording a conference.
| typedef struct imm_position imm_position |
A structure to describe a position within a three-dimensional space.
Note that the coordinate system uses centimeters. Check the documentation section on the coordinate system to see the alignment of the axes.
| x | The position of a participant along the x-axis. |
| y | The position of a participant along the y-axis. |
| z | The position of a participant along the z-axis. |
A structure to describe a seat within a room.
A participant in a room can occupy one seat which is located in a position. Its heading describes the direction it will automatically turn to face the center point of the room.
| id | A unique identifier for this seat. |
| position | The position of the seat in three-dimensional space. |
| heading | The direction a participant will face when they are placed in this seat. |
| enum imm_audio_control |
Audio Controls you can change in real-time.
A list of all the audio effects available in the Immersitech Library. For any control that ends with ENABLE, the only two possible values are 1 or 0 (enabled or disabled respectively).
| enum imm_device_type |
Output Device Types you may be listening on.
The type of device a participant is listening to the output on. Note that speaker refers to a stereo loudspeaker pair. If a participant isn't sure what type of device they have, it is always advised to default to IMM_DEVICE_HEADPHONE.
| enum imm_error_code |
All error codes that may be produced by the library.
| Enumerator | |
|---|---|
| IMM_ERROR_START | This value allows you to identify the start of the enum. |
| IMM_ERROR_NONE | This error code indicates the function worked successfully without error. |
| IMM_ERROR_HANDLE_NULL | This error code indicates you have not initialized your imm_handle properly yet. |
| IMM_ERROR_DATA_NULL | This error code indicates you tried to use a buffer or variable that wasn't allocated properly. |
| IMM_ERROR_DATA_LENGTH | This error code indicates there is a mismatch between the size of the data buffer you provided and the size required. |
| IMM_ERROR_NUM_CHANNELS | This error code indicates that you tried to specify a number of channels outside the allowed bounds. Currently only 1 or 2 channels are allowed. |
| IMM_ERROR_SAMPLE_RATE | This error code indicates that you tried to specify an output sampling rate that is unsupported or an input sampling rate that doesn't work with the output sampling rate. |
| IMM_ERROR_SPATIAL_QUALITY | This error code indicates that you specified an invalid spatial quality value. Allowable values are from 1 to 5. |
| 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 a room with an ID that already existed. |
| IMM_ERROR_INVALID_PARTICIPANT_ID | This error code indicates that you requested a participant with an ID that doesn't exist or tried to add a participant with an ID that already existed. |
| IMM_ERROR_INVALID_CONTROL | This error code indicates the control specified is not a valid one with the bounds of imm_audio_control. |
| IMM_ERROR_INVALID_VALUE | This error code indicates the value provided is outside the bounds specified for the various imm_audio_control. It can also indicate you provided an invalid function parameter in general. |
| IMM_ERROR_INVALID_HEADING | This error code indicates you provide a heading that was outside the allowed values. Please reference imm_heading for allowed values. |
| IMM_ERROR_INVALID_JSON_FILE | This error code indicates a syntax error in the provided JSON file (parameter, formating). |
| IMM_ERROR_NO_INPUT_AUDIO | This error code indicates that there was no input audio to be processed, meaning an output buffer could not be generated. Instead the output buffer will be zeroed. |
| IMM_ERROR_PARTICIPANT_TYPE | This error code matches the exceptions specified under imm_participant_type. |
| IMM_ERROR_LIBRARY_NOT_YET_INITIALIZED | This error code will be generated if you call any functions before initializing the library. |
| IMM_ERROR_LICENSE_DATE_EXPIRED | This error code indicates your license files no longer matches the date requirements. All audio effects will be bypassed. |
| IMM_ERROR_LICENSE_VERSION_MISMATCH | This error code indicates your license files version requirements no longer match. All audio effects will be bypassed. |
| IMM_ERROR_LICENSE_TAMPERED | This error code indicates your license file has been corrupted. All audio effects will be bypassed. |
| IMM_ERROR_LICENSE_MISSING | This error code indicates the path to your license file is invalid. All audio effects will be bypassed. |
| IMM_ERROR_FILE_DOES_NOT_EXIST | This error code indicates that an invalid file path was provided (invalid path or invalid filename). |
| IMM_ERROR_MISSING_OR_INVALID_PARAMETER | This error code indicates that a parameter is either missing or invalid. |
| IMM_ERROR_END | This value allows you to identify the end of the enum. |
| enum imm_participant_type |
Types of participants you can instantiate.
The rules will be enforced stricly. For example, if you create a source only participant and try to output audio, a error code will be returned and no processing will occur. One possible benefit of source only participants would be sound effect audio or audio from a video being shown in a conference. One possible benefit of listener only participants would be recording a conference.
| 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.
You can create a custom event manager by implementing the abstract IMM_EVENT_manager class. This custom class will define what code you'd like to be triggered when certain events happen. In order for the Immersitech Library to call your custom actions after an event, you must add it using this function. Note that you must manually initialize and free your own object, the immersitech library will NOT free the memory for you.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | event_manager | A pointer to your initiated custom event manager object. |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room you'd like to add the new participant to. |
| [in] | participant_id | The ID you'd like to give to the new participant. Note that it cannot be the same as the id of a participant already in this specific room. |
| [in] | participant_name | A human readable string name for the participant. This will allow easier developer identification of each participant's purpose. |
| [in] | config | The various configuration settings for the participant. |
| IMMERSITECH_API const char * imm_audio_control_to_string | ( | imm_audio_control | control | ) |
Convert an imm_audio_control to a human-readable string description.
For example, instead of viewing an enum value such as 3, you may rather see "IMM_CONTROL_AGC_ENABLE"
| [in] | control | The audio control enum value |
| IMMERSITECH_API imm_error_code imm_create_room | ( | imm_handle | handle, |
| int | room_id | ||
| ) |
Function to allocate memory and initialize a new room.
Creates a new room that you can begin adding participants to. Note that this new room will be automatically set to your default room layout.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID you'd like to give your new room. Note that it must be a unique id and cannot be shared with another room. |
| IMMERSITECH_API imm_error_code imm_destroy_library | ( | imm_handle | handle | ) |
Function to frees all memory associated with the immersitech library.
This function needs to be called only once at the very end of your program when everything else is finished. Once this function is called, you won't be able to call any other functions unless you reinitialize the library.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| 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 room.
Once you have destroyed the room, you can reuse the room_id for a new room if you'd like.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room you'd like to destroy. |
| IMMERSITECH_API imm_error_code imm_enable_logging | ( | bool | enable | ) |
Function to turn on or off logging within the Immersitech Library.
If you disable logging by sending false to this function, nothing will ever be logged. No messages will be printed. If you enable logging by sending true to this function. The Immersitech Library will log all messages equal to or above the set logging level. By default, Immersitech Library will log all messages to the standard output. By default, Immersitech Library will set the log level to Warnings and above only.
| [in] | enable | This bool dictates whether you'd like to enable logging or not |
| IMMERSITECH_API imm_error_code imm_enable_websockets | ( | imm_handle | handle, |
| bool | enable | ||
| ) |
Function to enable the websocket server for controlling settings via websockets.
Note: All websocket functionality is disabled on the client side version of the library If never call this function, the websocket server features will remain entirely disabled through your whole usage. Once you enable the websocket server through this function, clients may begin connecting and sending commands. See the client websocket API documentation for details on client commands
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | enable | A bool to indicate if you would like to turn the websocket server on |
| IMMERSITECH_API const char * imm_error_code_to_string | ( | imm_error_code | error_code | ) |
Get a human readable string for an error code.
This function allows you to print an error code enum value as its human readable equivalent by returning a string
| [in] | error_code | The error code you'd like to get human readable form for |
| 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.
This function will remove all audio data that was input for this participant. It will also clear all data that was on the output path to this participant.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID of the participant whose data you would like to flush. |
| 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.
The returned string will be a duplicate of the JSON in your room layout file you provided. If you did not provide a room layout file, the JSON will show the default room layout.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_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.
Note that this function will return invalid information (-1) until you initialize the library.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| IMMERSITECH_API const char * imm_get_license_info | ( | imm_handle | handle | ) |
Function to return information about your current license key.
Note that the returned string will be formatted as JSON so that you can easily parse information programmatically You must call imm_initialize_library successfully before this function will work.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| 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.
Note if you provide an invalid participant ID, the returned information will be invalid (-1).
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID you'd like to get information about |
| [out] | config | The configuration of the given participant. If you provided an invalid conference or participant ID, the returned configuration will be -1 for all values. |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participants are in |
| [out] | participant_count | This variable will store the number of participants currently in the given room |
| 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.
You must initialize your value buffer to a reasonable length based on how long the names you allow are. If your buffer is not long enough to store the full name, an error will be returned.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participant is in |
| [in] | participant_id | The ID of the participant whose name is to be learned |
| [out] | value | The name will be written to this value buffer that you provide |
| [in] | value_length | The size of the buffer that you allocated value to |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID of the participant you want to know the position of |
| [out] | position | A pointer to an imm_position object that you allocated. The position information you requested will be stored in this object. |
| [out] | heading | A pointer to an imm_heading object that you allocated. The heading information you requested will be stored in this object. |
| 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.
Note that if the seat's ID is -1, this means the participant is currently not in a seat. This is only possible in an open room layout where participants can move to an arbitrary x, y, z position. You must initialize the seat object before calling this function as the information will be written directly to it.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participant is in |
| [in] | participant_id | The ID of the participant |
| [out] | seat | The seat the participant is currently in. View imm_seat to learn about all the properties of a seat object. |
| 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.
This function can give detailed information about the current 3D rendering between two participants. The returned angles are the spherical coordinates that represent where the listner (listener_ID) will hear the source (source_ID) rendered.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participants are in |
| [in] | listener_id | The ID of the participant who is listening to the source. |
| [in] | source_id | The ID of the participant who is generated the sound heard by the listener. |
| [out] | azimuth | The azimuth angle from the source to the listener. |
| [out] | elevation | The elevation angle from the source to the listener. |
| [out] | distance | The distance from the source to the listener. |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID of the participant you want to view the settings for |
| [in] | control | The control you want to learn the state of. |
| [out] | value | If the call is a success, value is the value of the control of the requested participant in the requested conference. |
| IMMERSITECH_API imm_error_code imm_get_room_count | ( | imm_handle | handle, |
| int * | room_count | ||
| ) |
Function to learn how many rooms are currently active.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [out] | room_count | This parameters will store the number of active rooms |
| 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.
The integer value refers to the position of the layout in the room_list array in the room layout file. For example, if you have three layouts in your room layout file, a returned value of 1 would indicate this room's layout is set to the first room layout in the room_list array.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room you would like to know the layout of |
| [out] | layout_id | The ID of the room layout the room is currently set to |
| IMMERSITECH_API const char * imm_get_version | ( | ) |
Function to return the current version of the immersitech library.
| 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.
This function only needs to be called once, but must be called before any other function is called. If you want to change any of these settings, you must first call imm_destroy_library, then call this function again. Neither this function nor imm_destroy_library are thread safe and so you should halt other operations while changing settings
| [in] | license_file_name | The path to your immersitech license file including the file name ("/path/my_license.dat"). |
| [in] | room_layout_file_name | The path to your room layout file including the file name ("/path/my_license.dat"). You may send NULL instead of a path if you do not wish to use any room layout features. |
| [in] | websocket_config_file_name | The path to your websocket configuration file including the file name ("/path/my_license.dat"). You may send NULL instead of a path if you do not wish to use any websockets features. |
| [in] | configuration | The settings for the initialization of the Immersitech library. |
| [out] | error_code | An imm_error_code indicating if the call was a success or not. |
| 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.
This function only needs to be called once, but must be called before any other function is called. If you want to change any of these settings, you must first call imm_destroy_library, then call this function again. Neither this function nor imm_destroy_library are thread safe and so you should halt other operations while changing settings
| [in] | license_file_data | A pointer to the license file data. |
| [in] | license_file_data_size | The size of the license file data measured in number of bytes. |
| [in] | room_layout_file_name | The path to your room layout file including the file name ("/path/my_license.dat"). You may send NULL instead of a path if you do not wish to use any room layout features. |
| [in] | websocket_config_file_name | The path to your websocket configuration file including the file name ("/path/my_license.dat"). You may send NULL instead of a path if you do not wish to use any websockets features. |
| [in] | configuration | The settings for the initialization of the Immersitech library. |
| [out] | error_code | An imm_error_code indicating if the call was a success or not. |
| 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 more details.
| 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 more details.
| 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.
Every participant in a room should use this function to provide their individual inputs to the room. Later when calling the output audio function, the different inputs will be mixed according to the various settings.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room you'd like to add the participant's audio to. |
| [in] | participant_id | The ID you'd like to input audio for |
| [in] | audio_data | The buffer that has the audio data you'd like to input stored in it. |
| [in] | number_frames | The number of frames allocated in the audio_data buffer. Note number of frames is a channel insensitive value as described earlier. |
| 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 for more details.
| 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 for more details.
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room corresponding to the participant whose output you'd like to generate. |
| [in] | participant_id | The ID of the participant whose output stream will be generated. In other words, this is the output data this participant will hear. |
| [out] | output | This is an audio data buffer that you have initialized. The output data will be written to this buffer. Ensure its allocated size matches the output number of frames and channels specified upon initializing the library. |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room you'd like to remove the participant from. |
| [in] | participant_id | The ID of the participant you'd like to remove. |
| 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.
This function will send any string you provide and broadcast it to all clients connected to the websocket server. If you are using the client side version of the library, this function will be disabled.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the custom message is related to |
| [in] | message | A string containing the message you'd like to broadcase |
| 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.
If you plan to change a settings for everyone in a room, you can use this as a convenience instead of looping through all the participants and calling imm_set_participant_state For example, maybe a host in your conference call sets noise cancellation active for all participants.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participants are in |
| [in] | control_to_edit | The imm_audio_control you'd like to change the setting of |
| [in] | value | The new value of the given control |
| IMMERSITECH_API imm_error_code imm_set_log_level | ( | int | level | ) |
Function to set the log level of the Immersitech logger.
The logger will only log messages that are equal to or greater than the currently set log level.
| [in] | level | The log level you'd like to set. check the imm_log_level enum for details on which integer value corresponds to which log level |
| 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.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participant is in |
| [in] | participant_id | The ID of the participant whose name you'd like to change |
| [in] | participant_name | The new name for the participant |
| 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.
Change both the position and heading of a participant. These two values fully quanitify the participant's 3D experience. Note that this function will only work for a room that is in open room mode. If not, first use imm_set_room_layout() to get the room to an open room layout, and then this function will work properly.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID of the participant you are relocating. |
| [in] | position | The position you would like to move this participant to. |
| [in] | heading | The direction you would like this participant to face. |
| 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.
You can only move a participant to a seat defined in the current room's room layout. Note that seats are 1 indexed, meaning the first seat in the array is seat 1.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room the participant is in |
| [in] | participant_id | The ID of the participant that is moving seats |
| [in] | seat_id | The ID of the new seat |
| 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.
Use this function to adjust the various audio effects available through imm_audio_control
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID for the room the participant is in |
| [in] | participant_id | The ID of the participant you want to adjust the settings for |
| [in] | control_to_edit | The control you want to adjust. |
| [in] | value | The new value of the control_to_edit that was specified. |
| 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.
The integer value refers to the position of the layout in the room_list array in the room layout file. For example, if you have three layouts in your room layout file, a returned value of 1 would indicate this room's layout is set to the first room layout in the room_list array. When you switch layouts, the library will automatically move participants to the new seating positions consistent with the new layout.
| [in] | handle | Your imm_handle given to you after successfully intializing the library with imm_initialize_library |
| [in] | room_id | The ID of the room you would like to set the layout of |
| [in] | layout_id | The ID of the room layout you'd like to set the room to |
| 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 functions.
Convert a string to an actual enum control value to use in various functions. For example you may have "IMM_CONTROL_ANC_ENABLE" but you need an imm_audio_control enum value to send into a function
| [in] | control_string | The string representing the corresponding imm_audio_control value |
| IMMERSITECH_API int imm_string_to_participant_value | ( | const char * | value_string | ) |
Convert string to specific participant value.
To edit an immersitech audio control you will need to have the value as an integer. If you have obtained the value as a string such as IMM_DEVICE_HEADPHONES or a boolean such as True, this function will convert to an integer
| [in] | value_string | The string representing the value you'd like to use |