vx_sdk_config

Learn about client SDK basics.

Read time 11 minutes

Last updated a day 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.