Documentation

Support

Vivox Core SDK

Vivox Core SDK

vx_sdk_config

Learn about client SDK basics.
Read time 11 minutesLast updated 20 hours ago

Module: Initialization Configuration options that are passed to [vx_initialize3()].
#include <VxcTypes.h>

Public Attributes

Name

intnum_codec_threads
intnum_voice_threads
intnum_web_threads
intrender_source_queue_depth_max
The render source maximum queue depth.
intrender_source_initial_buffer_count
The render source initial buffer count.
intupstream_jitter_frame_count
The upstream jitter frame count.
intallow_shared_capture_devices
Indicate whether to allow shared capture devices (shared in the Vivox context only).
intmax_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.
intreserved
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 longprocessor_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_levelinitial_log_level
The initial log level.
intdisable_device_polling
Disable audio device polling by using a timer.
intforce_capture_silence
For diagnostic purposes only.
intenable_advanced_auto_levels
pf_on_audio_unit_started_tpf_on_audio_unit_started
Called when an audio processing unit is started in the audio processing thread.
pf_on_audio_unit_stopped_tpf_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_tpf_on_audio_unit_after_capture_audio_read
Called after audio is read from the capture device.
pf_on_audio_unit_before_capture_audio_sent_tpf_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_tpf_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_tpf_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.
intcapture_device_buffer_size_intervals
The number of 20 millisecond buffers for the capture device.
intrender_device_buffer_size_intervals
The number of 20 millisecond buffers for the render device.
intdisable_audio_ducking
intuse_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.
intenable_multiparty_text
If use_access_tokens is 1 and multiparty text is being used, set this to 1.
intenable_dtx
unsigned intdefault_codecs_mask
The default codec mask that is used to initialize a connector's configured_codecs.
pf_on_before_udp_frame_transmitted_tpf_on_before_udp_frame_transmitted
Called before any UDP frame is transmitted.
pf_on_after_udp_frame_transmitted_tpf_on_after_udp_frame_transmitted
Called after any UDP frame is transmitted.
intenable_fast_network_change_detection
Enable fast network change detection.
intuse_os_proxy_settings
Use the operating system-configured proxy settings.
intenable_persistent_http
intpreferred_sip_port
intdefault_render_to_receiver
floatmic_makeup_gain
pf_on_thread_created_tpf_on_thread_created
Called after a thread is created.
pf_on_thread_exit_tpf_on_thread_exit
Called before a thread is destructed.
int(*)(void)pf_request_permission_for_network
intdynamic_voice_processing_switching
Enable dynamic voice processing switching.
intios_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_tpf_on_audio_unit_capture_device_status_changed
intnever_rtp_timeout_ms
The number of millseconds to wait before disconnecting audio due to RTP timeout at the initial call time.
intlost_rtp_timeout_ms
The number of millseconds to wait before disconnecting audio due to RTP timeout after the call has been established.
vx_bluetooth_profilebluetooth_profile
intmobile_recording_conflicts_avoidance
pf_on_assert_tpf_on_assert
Called when an unexpected situation is encountered in the SDK.
pf_on_audio_unit_requesting_final_mix_for_echo_canceller_analysis_tpf_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.