vx_sdk_config
Learn about client SDK basics.
Read time 11 minutesLast updated 7 months ago
Module: Initialization
Configuration options that are passed to [vx_initialize3()].
#include <VxcTypes.h>Public Attributes
Name | |
|---|---|
| int | num_codec_threads |
| int | num_voice_threads |
| int | num_web_threads |
| int | render_source_queue_depth_max The render source maximum queue depth. |
| int | render_source_initial_buffer_count The render source initial buffer count. |
| int | upstream_jitter_frame_count The upstream jitter frame count. |
| int | allow_shared_capture_devices Indicate whether to allow shared capture devices (shared in the Vivox context only). |
| int | max_logins_per_user The maximum number of logins per user. |
| char[3] | app_id A three-letter app ID. |
| char[256] | cert_data_dir The certificate data directory where the certificate bundle is located. |
| void ()(size_t bytes) | pf_malloc_func A pointer to a function that is used to allocate memory. |
| void(*)(void *memory) | pf_free_func A pointer to a function that is used to free memory. |
| void ()(void *memory, size_t bytes) | pf_realloc_func A pointer to a function that is used to reallocate memory. |
| void ()(size_t num, size_t bytes) | pf_calloc_func A pointer to a function that is used to allocate zeroed-out memory. |
| void ()(size_t alignment, size_t size) | pf_malloc_aligned_func A pointer to a function that is used to allocate aligned memory. |
| void(*)(void *memory) | pf_free_aligned_func A pointer to a function that is used to free aligned memory. |
| int | reserved Reserved for future use. |
| void * | job_queue_handle A handle for use in SPURS job queue functions. |
| int(*)(void *job_queue_handle, void *job, size_t size) | pf_queue_job_sync A function to synchronously queue a job to SPURS. |
| int(*)(void *job_queue_handle, void *job, size_t size) | pf_queue_job_async A function to asynchronously queue a job to SPURS. |
| long long | processor_affinity_mask A processor affinity mask for SDK threads. |
| void * | callback_handle A callback handle for message and logging notifications. |
| void(*)(void *callback_handle, vx_log_level level, const char *source, const char *message) | pf_logging_callback Ensure that you are prepared to receive a logging callback immediately after calling [vx_initialize3()]. |
| void(*)(void *callback_handle) | pf_sdk_message_callback When the SDK message callback is called, call [vx_get_message()] until there are no more messages. |
| vx_log_level | initial_log_level The initial log level. |
| int | disable_device_polling Disable audio device polling by using a timer. |
| int | force_capture_silence For diagnostic purposes only. |
| int | enable_advanced_auto_levels |
| pf_on_audio_unit_started_t | pf_on_audio_unit_started Called when an audio processing unit is started in the audio processing thread. |
| pf_on_audio_unit_stopped_t | pf_on_audio_unit_stopped Called when an audio processing unit is stopped in the audio processing thread. |
| pf_on_audio_unit_after_capture_audio_read_t | pf_on_audio_unit_after_capture_audio_read Called after audio is read from the capture device. |
| pf_on_audio_unit_before_capture_audio_sent_t | pf_on_audio_unit_before_capture_audio_sent Called when an audio processing unit is about to send captured audio to the network from the audio processing thread. |
| pf_on_audio_unit_before_recv_audio_mixed_t | pf_on_audio_unit_before_recv_audio_mixed Called before an audio processing unit mixes the per-participant audio data to a single stream in the audio processing thread. |
| pf_on_audio_unit_before_recv_audio_rendered_t | pf_on_audio_unit_before_recv_audio_rendered Called when an audio processing unit is about to write received audio to the render device in the audio processing thread. |
| int | capture_device_buffer_size_intervals The number of 20 millisecond buffers for the capture device. |
| int | render_device_buffer_size_intervals The number of 20 millisecond buffers for the render device. |
| int | disable_audio_ducking |
| int | use_access_tokens Vivox Access Tokens (VAT) are a more scalable, usable, and extensible replacement to the use of Access Control Lists for controlling access to Vivox resources. |
| int | enable_multiparty_text If use_access_tokens is 1 and multiparty text is being used, set this to 1. |
| int | enable_dtx |
| unsigned int | default_codecs_mask The default codec mask that is used to initialize a connector's configured_codecs. |
| pf_on_before_udp_frame_transmitted_t | pf_on_before_udp_frame_transmitted Called before any UDP frame is transmitted. |
| pf_on_after_udp_frame_transmitted_t | pf_on_after_udp_frame_transmitted Called after any UDP frame is transmitted. |
| int | enable_fast_network_change_detection Enable fast network change detection. |
| int | use_os_proxy_settings Use the operating system-configured proxy settings. |
| int | enable_persistent_http |
| int | preferred_sip_port |
| int | default_render_to_receiver |
| float | mic_makeup_gain |
| pf_on_thread_created_t | pf_on_thread_created Called after a thread is created. |
| pf_on_thread_exit_t | pf_on_thread_exit Called before a thread is destructed. |
| int(*)(void) | pf_request_permission_for_network |
| int | dynamic_voice_processing_switching Enable dynamic voice processing switching. |
| int | ios_voice_processing_io_mode Configure how the VoiceProcessingIO unit should be used on iOS By default, the value is 1, meaning the voiceProcessingIO unit will only be used when the speakerphone is used for render and capture. |
| pf_on_audio_unit_capture_device_status_changed_t | pf_on_audio_unit_capture_device_status_changed |
| int | never_rtp_timeout_ms The number of millseconds to wait before disconnecting audio due to RTP timeout at the initial call time. |
| int | lost_rtp_timeout_ms The number of millseconds to wait before disconnecting audio due to RTP timeout after the call has been established. |
| vx_bluetooth_profile | bluetooth_profile |
| int | mobile_recording_conflicts_avoidance |
| pf_on_assert_t | pf_on_assert Called when an unexpected situation is encountered in the SDK. |
| pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis_t | pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis Called before an audio processing unit informs its acoustic echo canceller about what audio is being output by the device. |
Public Attributes Documentation
variable num_codec_threads
int num_codec_threads;
Deprecated:
Do not use this parameter, because it has no effect. The number of threads used for encoding and decoding audio.
Note: For client SDKs, this number must be 1.
variable num_voice_threads
int num_voice_threads;
Deprecated:
Do not use this parameter, because it has no effect. The number of threads used for voice processing.
Note: For client SDKs, this number must be 1.
variable num_web_threads
int num_web_threads;
Deprecated:
Do not use this parameter, because it has no effect. The number of threads used for web requests.
Note: For client SDKs, this number must be 1.
variable render_source_queue_depth_max
int render_source_queue_depth_max;
The render source maximum queue depth.
variable render_source_initial_buffer_count
int render_source_initial_buffer_count;
The render source initial buffer count.
variable upstream_jitter_frame_count
int upstream_jitter_frame_count;
The upstream jitter frame count.
variable allow_shared_capture_devices
int allow_shared_capture_devices;
Indicate whether to allow shared capture devices (shared in the Vivox context only).
variable max_logins_per_user
int max_logins_per_user;
The maximum number of logins per user.
variable app_id
char[3] app_id;
A three-letter app ID.
Attention: Do not set this value. For more information, contact your Vivox representative.
variable cert_data_dir
char[256] cert_data_dir;
The certificate data directory where the certificate bundle is located.
variable pf_malloc_func
void *(*)(size_t bytes) pf_malloc_func;
A pointer to a function that is used to allocate memory.
variable pf_free_func
void(*)(void *memory) pf_free_func;
A pointer to a function that is used to free memory.
variable pf_realloc_func
void *(*)(void *memory, size_t bytes) pf_realloc_func;
A pointer to a function that is used to reallocate memory.
variable pf_calloc_func
void *(*)(size_t num, size_t bytes) pf_calloc_func;
A pointer to a function that is used to allocate zeroed-out memory.
variable pf_malloc_aligned_func
void *(*)(size_t alignment, size_t size) pf_malloc_aligned_func;
A pointer to a function that is used to allocate aligned memory.
variable pf_free_aligned_func
void(*)(void *memory) pf_free_aligned_func;
A pointer to a function that is used to free aligned memory.
variable reserved
int reserved;
Reserved for future use.
variable job_queue_handle
void * job_queue_handle;
A handle for use in SPURS job queue functions.
variable pf_queue_job_sync
int(*)(void *job_queue_handle, void *job, size_t size) pf_queue_job_sync;
A function to synchronously queue a job to SPURS.
The job argument is a pointer CellSpursJobHeader structure.
variable pf_queue_job_async
int(*)(void *job_queue_handle, void *job, size_t size) pf_queue_job_async;
A function to asynchronously queue a job to SPURS.
The job argument is a pointer CellSpursJobHeader structure.
variable processor_affinity_mask
long long processor_affinity_mask;
A processor affinity mask for SDK threads.
Note: For more information, consult your documentation or contact your Vivox representative.
variable callback_handle
void * callback_handle;
A callback handle for message and logging notifications.
variable pf_logging_callback
void(*)(void *callback_handle, vx_log_level level, const char *source, const char *message) pf_logging_callback;
Ensure that you are prepared to receive a logging callback immediately after calling [vx_initialize3()].
variable pf_sdk_message_callback
void(*)(void *callback_handle) pf_sdk_message_callback;
When the SDK message callback is called, call [vx_get_message()] until there are no more messages.
variable initial_log_level
vx_log_level initial_log_level;
The initial log level.
variable disable_device_polling
int disable_device_polling;
Disable audio device polling by using a timer.
variable force_capture_silence
int force_capture_silence;
For diagnostic purposes only.
variable enable_advanced_auto_levels
int enable_advanced_auto_levels;
Deprecated:
Do not use this parameter, because it has no effect. Enable advanced automatic setting of audio levels.
variable pf_on_audio_unit_started
pf_on_audio_unit_started_t pf_on_audio_unit_started;
Called when an audio processing unit is started in the audio processing thread.
No blocking operations should occur on this callback.
variable pf_on_audio_unit_stopped
pf_on_audio_unit_stopped_t pf_on_audio_unit_stopped;
Called when an audio processing unit is stopped in the audio processing thread.
No blocking operations should occur on this callback.
variable pf_on_audio_unit_after_capture_audio_read
pf_on_audio_unit_after_capture_audio_read_t pf_on_audio_unit_after_capture_audio_read;
Called after audio is read from the capture device.
No blocking operations should occur on this callback.
variable pf_on_audio_unit_before_capture_audio_sent
pf_on_audio_unit_before_capture_audio_sent_t pf_on_audio_unit_before_capture_audio_sent;
Called when an audio processing unit is about to send captured audio to the network from the audio processing thread.
No blocking operations should occur on this callback.
variable pf_on_audio_unit_before_recv_audio_mixed
pf_on_audio_unit_before_recv_audio_mixed_t pf_on_audio_unit_before_recv_audio_mixed;
Called before an audio processing unit mixes the per-participant audio data to a single stream in the audio processing thread.
No blocking operations should occur on this callback.
variable pf_on_audio_unit_before_recv_audio_rendered
pf_on_audio_unit_before_recv_audio_rendered_t pf_on_audio_unit_before_recv_audio_rendered;
Called when an audio processing unit is about to write received audio to the render device in the audio processing thread.
No blocking operations should occur on this callback.
variable capture_device_buffer_size_intervals
int capture_device_buffer_size_intervals;
The number of 20 millisecond buffers for the capture device.
variable render_device_buffer_size_intervals
int render_device_buffer_size_intervals;
The number of 20 millisecond buffers for the render device.
variable disable_audio_ducking
int disable_audio_ducking;
Note: Only applicable to the iOS platform.
variable use_access_tokens
int use_access_tokens;
Vivox Access Tokens (VAT) are a more scalable, usable, and extensible replacement to the use of Access Control Lists for controlling access to Vivox resources.
This security token is generated by the game server and then validated by the Vivox system to authorize certain Vivox operations at the time which those operations are to be performed.
variable enable_multiparty_text
int enable_multiparty_text;
If use_access_tokens is 1 and multiparty text is being used, set this to 1.
This can also be controlled by setting the VIVOX_ENABLE_MULTIPARTY_TEXT environment variable.
variable enable_dtx
int enable_dtx;
Attention: Changes to this value must be coordinated with Vivox. For most platforms, this uses a default of 1.
variable default_codecs_mask
unsigned int default_codecs_mask;
The default codec mask that is used to initialize a connector's configured_codecs.
variable pf_on_before_udp_frame_transmitted
pf_on_before_udp_frame_transmitted_t pf_on_before_udp_frame_transmitted;
Called before any UDP frame is transmitted.
This callback must be a non-blocking callback. It is recommended that this callback complete in less than 1 millisecond.
variable pf_on_after_udp_frame_transmitted
pf_on_after_udp_frame_transmitted_t pf_on_after_udp_frame_transmitted;
Called after any UDP frame is transmitted.
The application can use this callback to deallocate the header and trailer, if necessary.
variable enable_fast_network_change_detection
int enable_fast_network_change_detection;
Enable fast network change detection.
The default value is 0.
variable use_os_proxy_settings
int use_os_proxy_settings;
Use the operating system-configured proxy settings.
- The default value is 0.
- The value is 1 if the environment variable "VIVOX_USE_OS_PROXY_SETTINGS" is set. Only applicable to the Windows platform.
variable enable_persistent_http
int enable_persistent_http;
Note: Only applicable to the Windows platform.
Attention: Before changing this value, contact your developer support representative. Enable persistent connections.
- The default value is 0.
- If the environment variable "VIVOX_ENABLE_PERSISTENT_HTTP" is set, the value is 1. The use of proxies can interfere with any behavior that is controlled by this setting.
variable preferred_sip_port
int preferred_sip_port;
Note: Setting this parameter to an incorrect value could result in delays in logging in or joining channels.
variable default_render_to_receiver
int default_render_to_receiver;
Deprecated:
Do not use this parameter, because it has no effect. By default, audio output goes to the mobile device's speakers, unless the value is set to 1. On the iOS platform, when the audio session is set to the category "PlayAndRecord", the receiver, which is the mobile device speaker that is put to your ear for voice calls, is used.
variable mic_makeup_gain
float mic_makeup_gain;
Deprecated:
Do not use this parameter, because it has no effect. For platforms with soft mics, apply linear gain in dB before processing.
variable pf_on_thread_created
pf_on_thread_created_t pf_on_thread_created;
Called after a thread is created.
The application can use this callback to monitor and profile thread creation.
variable pf_on_thread_exit
pf_on_thread_exit_t pf_on_thread_exit;
Called before a thread is destructed.
The application can use this callback to monitor and profile thread destruction.
variable pf_request_permission_for_network
int(*)(void) pf_request_permission_for_network;
Deprecated:
This function pointer is unused and is never called.
variable dynamic_voice_processing_switching
int dynamic_voice_processing_switching;
Enable dynamic voice processing switching.
If enabled, the SDK automatically switches between hardware and software AECs.
- The default value is 1.
- To disable this capability, set the value to 0.
variable ios_voice_processing_io_mode
int ios_voice_processing_io_mode;
Configure how the VoiceProcessingIO unit should be used on iOS By default, the value is 1, meaning the voiceProcessingIO unit will only be used when the speakerphone is used for render and capture.
Other configurations are possible:
- Set the value to 2 to to always use the voiceProcessingIO unit.
- Set the value to 0 to never use the voiceProcessingIO unit.
variable pf_on_audio_unit_capture_device_status_changed
pf_on_audio_unit_capture_device_status_changed_t pf_on_audio_unit_capture_device_status_changed;
Attention: This function is only called on specific platforms. For more information, contact Vivox. If set, this function is called when the active capture device status is updated.
variable never_rtp_timeout_ms
int never_rtp_timeout_ms;
The number of millseconds to wait before disconnecting audio due to RTP timeout at the initial call time.
A zero or negative value turns off the guard, which is not recommended.
variable lost_rtp_timeout_ms
int lost_rtp_timeout_ms;
The number of millseconds to wait before disconnecting audio due to RTP timeout after the call has been established.
A zero or negative value turns off the guard, which is not recommended.
variable bluetooth_profile
vx_bluetooth_profile bluetooth_profile;
Attention:
-
This value is only used on iOS and Android.
-
This value will only have an effect if dynamic_voice_processing_switching is enabled. The Bluetooth profile that is in use when Vivox is accessing the microphone.
-
The default value is vx_bluetooth_profile_hfp.
variable mobile_recording_conflicts_avoidance
int mobile_recording_conflicts_avoidance;
Attention: This value is only used on Android. Enable mobile recording conflicts avoidance. If Vivox detects that there is more than one recorder, Vivox disables its recorder to allow for others to record. Real call dialer app, Voip apps, Voice recognition apps are all prioritized to use the recorder over Vivox if this field is set to 1.
- The default value is 0.
- To enable this capability, set the value to 1.
variable pf_on_assert
pf_on_assert_t pf_on_assert;
Called when an unexpected situation is encountered in the SDK.
variable pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis
pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis_t pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis;
Called before an audio processing unit informs its acoustic echo canceller about what audio is being output by the device.
Mix application audio into pcm_frames so acoustic echo cancellation can attempt to remove it from the microphone capture signal. If the application is rendering Vivox voices instead of the Vivox SDK and the application is modifying the voice signals, ... then write the application audio mixed with the modified voice signals into pcm_frames, overwriting its previous contents. No blocking operations should occur on this callback.