Data Structures
struct	tox_instance_t

struct	tox_web_request_config_t

struct	tox_config_t

Macros
#define	TOX_VERSION "1.9.0"

Enumerations
enum	TOX_TRIAGE_SETTING { TOX_NONE = 0 , TOX_LIGHT , TOX_HEAVY }

enum	TOX_ERROR { TOX_NO_ERROR = 0 , TOX_UNKNOWN_ERROR , TOX_BAD_INSTANCE , TOX_BAD_CONFIG , TOX_BAD_ACCOUNT_UUID , TOX_BAD_API_KEY , TOX_BAD_PLAYER_NAME , TOX_BAD_SESSION_NAME , TOX_BAD_AUDIO , TOX_BAD_SAMPLE_RATE , TOX_SAMPLES_SKIPPED , TOX_NO_SESSION_SET , TOX_UPLOAD_METADATA_FAILED , TOX_BAD_TENANT_PREFIX , TOX_BAD_PLAYER_ALIAS , TOX_BAD_SESSION_ALIAS , TOX_BAD_SESSION_DATA , TOX_ALREADY_IN_SESSION , TOX_NOT_IN_SESSION , TOX_BAD_SESSION_DATA_TYPE , TOX_BAD_PLAYER_DATA_TYPE , TOX_BAD_PLAYER_DATA , TOX_BAD_PLAYER_LIST , TOX_PROXIMITY_CHAT_DISABLED , TOX_BAD_AUTH_MODE , TOX_INCONSISTENT_PROXIMITY_CHAT_UPDATE }

enum	TOX_PLAYER_DATA_TYPE { TOX_PLAYER_LANGUAGE_PREFERENCE , TOX_PLAYER_PLATFORM_INFO }

enum	TOX_SESSION_DATA_TYPE { TOX_SESSION_TYPE , TOX_SESSION_PASSTHROUGH_DATA }

Functions
TOX_DEF_PREFIX TOX_ERROR	tox_global_init (void)

TOX_DEF_PREFIX TOX_ERROR	tox_init_default_web_config (tox_web_request_config_t *config)

TOX_DEF_PREFIX TOX_ERROR	tox_global_init_with_web_config (const tox_web_request_config_t *config)

TOX_DEF_PREFIX TOX_ERROR	tox_global_cleanup (void)

TOX_DEF_PREFIX const char *	tox_error_name (TOX_ERROR error)

TOX_DEF_PREFIX TOX_ERROR	tox_create_instance (tox_instance_t tox_instance_ptr, const tox_config_t tox_config_ptr)

TOX_DEF_PREFIX TOX_ERROR	tox_destroy_instance (tox_instance_t *tox_instance_ptr)

TOX_DEF_PREFIX TOX_ERROR	tox_set_session_name (tox_instance_t tox_instance_ptr, const char session_name_unique)

TOX_DEF_PREFIX TOX_ERROR	tox_join_session (tox_instance_t tox_instance_ptr, const char session_name_unique)

TOX_DEF_PREFIX TOX_ERROR	tox_leave_session (tox_instance_t *tox_instance_ptr)

TOX_DEF_PREFIX TOX_ERROR	tox_get_internal_player_uuid (tox_instance_t tox_instance_ptr, const char *internal_player_uuid)

TOX_DEF_PREFIX TOX_ERROR	tox_set_player_alias (tox_instance_t tox_instance_ptr, const char player_alias)

TOX_DEF_PREFIX TOX_ERROR	tox_get_internal_session_uuid (tox_instance_t tox_instance_ptr, const char *internal_session_uuid)

TOX_DEF_PREFIX TOX_ERROR	tox_set_session_alias (tox_instance_t tox_instance_ptr, const char session_alias)

TOX_DEF_PREFIX TOX_ERROR	tox_add_structured_player_data (tox_instance_t tox_instance_ptr, TOX_PLAYER_DATA_TYPE data_type, const char data)

TOX_DEF_PREFIX TOX_ERROR	tox_add_structured_session_data (tox_instance_t tox_instance_ptr, TOX_SESSION_DATA_TYPE data_type, const char language)

TOX_DEF_PREFIX TOX_ERROR	tox_add_session_data (tox_instance_t tox_instance_ptr, const char session_data)

TOX_DEF_PREFIX TOX_ERROR	tox_set_proximity_chat_player_can_hear (tox_instance_t tox_instance_ptr, const char const *players, unsigned int num_players)

TOX_DEF_PREFIX TOX_ERROR	tox_set_proximity_chat_can_hear_player (tox_instance_t tox_instance_ptr, const char const *players, unsigned int num_players)

TOX_DEF_PREFIX TOX_ERROR	tox_set_global_muted (tox_instance_t *tox_instance_ptr, int muted)

TOX_DEF_PREFIX TOX_ERROR	tox_set_player_muted (tox_instance_t tox_instance_ptr, const char player, int muted)

TOX_DEF_PREFIX TOX_ERROR	tox_set_players_muted_at_join (tox_instance_t tox_instance_ptr, const char const *players, unsigned int num_players)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio_float (tox_instance_t tox_instance_ptr, const float audio, unsigned int num_samples, unsigned int sample_rate, unsigned int num_channels)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio_short (tox_instance_t tox_instance_ptr, const short audio, unsigned int num_samples, unsigned int sample_rate, unsigned int num_channels)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio (tox_instance_t tox_instance_ptr, const float audio, unsigned int num_samples, unsigned int sample_rate)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio_nonrealtime_float (tox_instance_t tox_instance_ptr, const float audio, unsigned int num_samples, unsigned int sample_rate, unsigned int num_channels)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio_nonrealtime_short (tox_instance_t tox_instance_ptr, const short audio, unsigned int num_samples, unsigned int sample_rate, unsigned int num_channels)

TOX_DEF_PREFIX TOX_ERROR	tox_add_audio_nonrealtime (tox_instance_t tox_instance_ptr, const float audio, unsigned int num_samples, unsigned int sample_rate)

TOX_DEF_PREFIX TOX_ERROR	tox_set_single_tenant_prefix (tox_instance_t tox_instance_ptr, const char prefix)

TOX_DEF_PREFIX TOX_ERROR	tox_set_log_info_callback (void(log_info_callback)(const char ))

TOX_DEF_PREFIX TOX_ERROR	tox_set_log_error_callback (void(log_error_callback)(const char ))

TOX_DEF_PREFIX const char *	tox_get_version (void)

TOX_DEF_PREFIX TOX_ERROR	tox_set_instance_token (tox_instance_t tox_instance_ptr, const char token)

Detailed Description

Copyright: This file is Confidential and Proprietary to Modulate, Inc. This file may not be shared or distributed without permission from Modulate. Email suppo.nosp@m.rt@m.nosp@m.odula.nosp@m.te.a.nosp@m.i with requests, bug reports, or questions! Last updated September 16, 2024.

Macro Definition Documentation

◆ TOX_VERSION

#define TOX_VERSION "1.9.0"

The version of the tox library - this updates anytime Modulate ships a new libtox with bugfixes, performance improvements, API changes, etc.

ToxMod follows semantic versioning, therefore:

Major (first number) versions are not compatible
Minor (second number) versions are backwards compatible - applications compiled against less recent versions can link with more recent versions, but not necessarily vice versa
Patch (third number) all versions compatible - internal differences only
Dev Build - "d" for dev build, nothing for external release

Enumeration Type Documentation

◆ TOX_TRIAGE_SETTING

enum TOX_TRIAGE_SETTING

Option to select what level of on-device triage the ToxMod library uses.

The choice between triage configuration options is purely technical and will not affect your ToxMod usage or pricing. We’ve found that most of our customers prefer to stay as close to zero compute/memory as possible, and therefore choose the TOX_NONE configuration.

Enumerator
TOX_NONE	No on-device triaging, all speech-contentful audio uploaded
TOX_LIGHT	Lightweight statistics-based ML triaging with light performance impact
TOX_HEAVY	Larger neural-network-based ML triaging with significant performance impact

◆ TOX_ERROR

enum TOX_ERROR

Error value responses from ToxMod functions; use tox_error_name() to get related message on error.

Enumerator
TOX_NO_ERROR	Default return value for successful function calls.
TOX_UNKNOWN_ERROR	Returned in case of internal library errors, and should not be encountered during normal use of the SDK.
TOX_BAD_INSTANCE	returned if the tox_server_instance_t parameter was not initialized by tox_server_create_instance(), or has otherwise become corrupted.
TOX_BAD_CONFIG	Returned if a null tox_server_config_t is used
TOX_BAD_ACCOUNT_UUID	Returned if an account UUID is null
TOX_BAD_API_KEY	Returned if an operation was performed using a null API key
TOX_BAD_PLAYER_NAME	Returned if a null session name is passed
TOX_BAD_SESSION_NAME	Returned if a null session name is passed
TOX_BAD_AUDIO	Returned if null audio is passed
TOX_BAD_SAMPLE_RATE	Returned if the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_SAMPLES_SKIPPED	if the internal circular buffer couldn't hold all of the audio samples passed into this function call. This can happen if too many samples are added much faster than realtime - e.g. 50,000 samples added in one function call - since the internal circular buffer is drained by a separate thread several times per second, and only holds approx. 1 second of audio at a time. This return value indicates that there be a skip in the processed/uploaded audio. Large or frequent skips may degrade toxicity detection model performance, and cause difficulty for human moderators.
TOX_NO_SESSION_SET	Returned if tox_set_session_name() has not yet been called to set a session name
TOX_UPLOAD_METADATA_FAILED	Returned if the player or session name failed to upload (only applicable if tox_config_t.obscure_names is 0).
TOX_BAD_TENANT_PREFIX	Returned if the prefix argument is an empty string
TOX_BAD_PLAYER_ALIAS	Returned if the player alias is null or empty
TOX_BAD_SESSION_ALIAS	Returned if the session alias is null or empty
TOX_BAD_SESSION_DATA	Returned if data is null or does not match the structure required for the given data type (e.g. this will be returned if "en-us" is passed as a language preference instead of "en")
TOX_ALREADY_IN_SESSION	Returned if player is already in a session
TOX_NOT_IN_SESSION	Returned if an operation is performed where a player needs to be in a session but the player is not part of a session
TOX_BAD_SESSION_DATA_TYPE	Returned if the data type passed is not an item from TOX_PLAYER_DATA_TYPE
TOX_BAD_PLAYER_DATA_TYPE	Returned if the data type passed is not an item from TOX_SESSION_DATA_TYPE
TOX_BAD_PLAYER_DATA	Returned if data is null or does not match the structure required for the given data type (e.g. this will be returned if "en-us" is passed as a language preference instead of "en")
TOX_BAD_PLAYER_LIST	Returned if passed player list is null but num_players is greater than 0
TOX_PROXIMITY_CHAT_DISABLED	Returned if a proximity chat function is called but tox_config_t.enable_proximity_chat is 0
TOX_BAD_AUTH_MODE	Returned if an attempt is made to use both API key and token authentication features at the same time for the same instance
TOX_INCONSISTENT_PROXIMITY_CHAT_UPDATE	Returned if tox_proximity_chat_set_player_can_hear is called after tox_proximity_chat_can_hear_player, or vice versa. Only one of those functions can be used within a given session.

◆ TOX_PLAYER_DATA_TYPE

enum TOX_PLAYER_DATA_TYPE

Types of player data that can be uploaded via tox_add_structured_player_data()

Enumerator

TOX_PLAYER_LANGUAGE_PREFERENCE

2-letter ISO 639-1 code for player's language preference. Informs transcription as well as displayed for moderators

Format check includes:

2 characters long

TOX_PLAYER_PLATFORM_INFO

Information about player platform/version for display/logging. does not affect algorithm, but useful for debugging and analytics e.g. "Windows 10 build 1809" or "Oculus Quest 2 beta"

Format check includes:

No specific checks

◆ TOX_SESSION_DATA_TYPE

enum TOX_SESSION_DATA_TYPE

Types of session data that can be uploaded via tox_add_structured_session_data()

Enumerator

TOX_SESSION_TYPE

The type of the current session

Format check includes:

No specific checks

TOX_SESSION_PASSTHROUGH_DATA

Type for arbitrary data to be passed back to the moderation action integration endpoint

Format check includes:

No specific checks

Function Documentation

◆ tox_global_init()

TOX_DEF_PREFIX TOX_ERROR tox_global_init ( void )

Global state initialization - run once on application startup, before any other tox functions

Returns

TOX_NO_ERROR Function executed successfully

Examples: main.c.

◆ tox_init_default_web_config()

TOX_DEF_PREFIX TOX_ERROR tox_init_default_web_config ( tox_web_request_config_t * config )

Initialize a tox_web_request_config_t to default values

Note: Always initialize web config objects using this function to ensure that fields you have not customized have reasonable default values

Parameters

[out] config - config object to be initialized to default values

Returns

TOX_NO_ERROR Function executed successfully

Example:

tox_web_request_config_t web_cfg;
tox_init_default_web_config(&cfg);
cfg.SSLOPT_REVOKE_BEST_EFFORT = 1;
tox_global_init_with_web_config(&cfg);

◆ tox_global_init_with_web_config()

TOX_DEF_PREFIX TOX_ERROR tox_global_init_with_web_config ( const tox_web_request_config_t * config )

Equivalent to tox_global_init() but accepts web framework configuration options

Note: Always initialize config using tox_init_default_web_config() before customizing and passing here

Parameters

[in] config - Web configuration options

Returns

TOX_NO_ERROR Function executed successfully

◆ tox_global_cleanup()

TOX_DEF_PREFIX TOX_ERROR tox_global_cleanup ( void )

Global state cleanup - run once before application shutdown, after any other tox functions

Returns

TOX_NO_ERROR Function executed successfully

Examples: main.c.

◆ tox_error_name()

TOX_DEF_PREFIX const char * tox_error_name ( TOX_ERROR error )

Return the associated string for a ToxMod error - useful in log messages

Parameters

[in] error - the tox error for which to retrieve an error string

Returns: Error message as a string

Examples: main.c.

◆ tox_create_instance()

TOX_DEF_PREFIX TOX_ERROR tox_create_instance	(	tox_instance_t *	tox_instance_ptr,
		const tox_config_t *	tox_config_ptr )

Create a tox_instance to store internal state. Create once before adding audio. The tox_config_t object and its member data are all copied to internal storage, and do not need to be preserved after this function returns.

Parameters

[in]	tox_instance_ptr	Pointer to a fresh tox_instance_t
[in]	tox_config_ptr	Pointer to a tox_config_t

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_INSTANCE If tox_instance_ptr is null
TOX_BAD_CONFIG If tox_config_ptr is null
TOX_BAD_ACCOUNT_UUID If the account uuid in tox_config_ptr is null or empty
TOX_BAD_API_KEY If the api key in tox_config_ptr is null or empty
TOX_BAD_PLAYER_NAME If the player name in tox_config_ptr is null or empty
TOX_BAD_TENANT_PREFIX If the prefix argument is an empty string
TOX_BAD_AUTH_MODE If a non-null & non-empty API key is passed but token authentication is enabled in the tox_config_ptr

Example:

tox_instance_t tox_instance;
tox_config_t tox_config = {
  .account_uuid = "00000000-0000-0000-0000-000000000000",
  .api_key = "00000000-0000-0000-0000-000000000000",
  .player_name_unique = "player1",
  .verbose = 0,
  .obscure_names = 0;
  .enable_proximity_chat = 0;
};
TOX_ERROR tox_error = tox_create_instance(&tox_instance, &tox_config);

Examples: main.c.

◆ tox_destroy_instance()

TOX_DEF_PREFIX TOX_ERROR tox_destroy_instance ( tox_instance_t * tox_instance_ptr )

Destroy a tox_instance to cleanup internal state. Call once before application shutdown

Parameters

[in] tox_instance_ptr Pointer to the tox_jnstance_t to be destroyed

Returns

TOX_NO_ERROR Function executed successfully

Examples: main.c.

◆ tox_set_session_name()

TOX_DEF_PREFIX TOX_ERROR tox_set_session_name	(	tox_instance_t *	tox_instance_ptr,
		const char *	session_name_unique )

Update the chat room session name - use a unique name (per account_uuid) for a chat room where one or more players are chatting with each other. This would typically be derived from the unique specifier for a chat lobby or room that the player joins in the voice chat system. Used to show the context of a player's voice chat in relation to what other players are saying to/with them. Call this before running tox_add_audio(), and then any time the chat room changes (e.g. if the user joins a new game lobby which uses a new chatroom) The session name is copied to internal storage, and does not need to be preserved after this function returns.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t of the player in question
[in]	session_name_unique	Unique name for the new session

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SESSION_NAME If the session name is null or empty

Example:

tox_error = tox_set_session_name(&tox_instance, "chatroom123");

tox_set_session_name

TOX_DEF_PREFIX TOX_ERROR tox_set_session_name(tox_instance_t *tox_instance_ptr, const char *session_name_unique)

◆ tox_join_session()

TOX_DEF_PREFIX TOX_ERROR tox_join_session	(	tox_instance_t *	tox_instance_ptr,
		const char *	session_name_unique )

Join a session with the specified name - use a unique name (per account_uuid) for a chat room where one or more players are chatting with each other. This would typically be derived from the unique specifier for a chat lobby or room that the player joins in the voice chat system. Used to show the context of a player's voice chat in relation to what other players are saying to/with them. Call this before running tox_add_audio(), then call tox_leave_session to when the player leaves a session. If a player is switching sessions, first leave and then join again. (e.g. if the user joins a new game lobby which uses a new chatroom). ToxMod only supports a player being in one session at a time, so this function will return an error if the player is already in a session. The session name is copied to internal storage, and does not need to be preserved after this function returns.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t of the player in question
[in]	session_name_unique	Unique name for the new session

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SESSION_NAME If the session name is null or empty
TOX_ALREADY_IN_SESSION If player is already in a session
TOX_UPLOAD_METADATA_FAILED Returned on any error uploading data to server

Examples: main.c.

◆ tox_leave_session()

TOX_DEF_PREFIX TOX_ERROR tox_leave_session ( tox_instance_t * tox_instance_ptr )

Leave the current session. If a player is switching sessions, first call this to leave and then call tox_join_session to join the new session. This function will not error if the player is not in a session, so it is always safe to call this before joining a session.

Parameters

[in] tox_instance_ptr Pointer to the tox_instance_t of the player in question

Returns

TOX_NO_ERROR Function executed successfully
TOX_UPLOAD_METADATA_FAILED Returned on any error uploading data to server

Examples: main.c.

◆ tox_get_internal_player_uuid()

TOX_DEF_PREFIX TOX_ERROR tox_get_internal_player_uuid	(	tox_instance_t *	tox_instance_ptr,
		const char **	internal_player_uuid )

Get the ToxMod-internal anonymous UUID associated with the provided player. Retrieving this and storing it in your own database allows you to consume messages from ToxMod (e.g. "a moderator banned <player_uuid>") and relate them back to your internal player database or players' usernames, without ToxMod storing any player usernames. If you don't require ToxMod to not store player usernames, you can avoid storing this relationship yourself by providing ToxMod a player alias which you can consume later - such as the player username or internal database ID - using tox_set_player_alias(), in which case the above messages will alos include the alias (e.g. "a moderator banned <player_uuid>, alias: <player_alias>"). The const char* set by tox_get_internal_player_uuid() points to a valid string allocated in in the internal tox_instance_t object, and remains valid until the tox_instance_t is destroyed in tox_destroy_instance(). If this call returns an error, the const char* returned in *internal_player_uuid is null, NOT a valid string.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t of the player in question
[out]	internal_player_uuid	The toxmod internal UUID used to identify the player in question. This will remain valid until the corresponding tox_instance_t is destroyed.

Returns

TOX_NO_ERROR Function executed successfully

Example:
     const char* player_uuid;
     tox_error = tox_get_internal_player_uuid(&tox_instance, &player_uuid);
     if(!tox_error)
       <save player_uuid to some database, associated with the player's username>

◆ tox_set_player_alias()

TOX_DEF_PREFIX TOX_ERROR tox_set_player_alias	(	tox_instance_t *	tox_instance_ptr,
		const char *	player_alias )

Save an alias for the associated player within ToxMod's database, to be passed back to you upon moderation actions. This avoids you having to store the ToxMod anonymous id and do the association yourself, as moderation actions will produce messages that you consume with the information "a moderator banned <player_uuid>, alias: <player_alias> The player alias is copied to internal storage, and does not need to be preserved after this function returns. @param [in] tox_instance_ptr Pointer to the tox_instance_t of the player in question @param [in] player_alias alias for the player in question @return + ::TOX_NO_ERROR Function executed successfully + ::TOX_BAD_PLAYER_ALIAS If player_alias is null or empty + ::TOX_UPLOAD_METADATA_FAILED Returned on any error in uploading the player alias to the server, potentially due to issues connecting to the server, initializing cURL for the network request, or invalid credentials used to create the tox_instance_ptr Example: @icode tox_error = tox_set_player_alias(&tox_instance, "player1");

◆ tox_get_internal_session_uuid()

TOX_DEF_PREFIX TOX_ERROR tox_get_internal_session_uuid	(	tox_instance_t *	tox_instance_ptr,
		const char **	internal_session_uuid )

Get the ToxMod-internal anonymous UUID associated with the provided session. This works much like tox_get_internal_player_uuid(), except that it is associated with a session instead of a player. Retrieving and storing the session UUID in your own database allows you to associate the UUID included in moderation messages with your internal session database or sessions' names, without ToxMod storing any session names. Alternatively, you can avoid storing this relationship yourself by providing ToxMod a session alias (i.e. the session name itsef) which will be passed back to you in moderation messages.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t of the player in question
[out]	internal_session_uuid	The toxmod internal UUID used to identify the player in question. This will remain valid until the corresponding tox_instance_t is destroyed or tox_leave_session() is called. If this function returns an error, internal_player_uuid will be null and should not be used

Returns

TOX_NO_ERROR Function executed successfully
TOX_NO_SESSION_SET If tox_set_session_name has not yet been called to set a session name

Example:

const char* session_uuid;
tox_error = tox_get_internal_session_uuid(&tox_instance, &session_uuid);
if(!tox_error)
  <save session_uuid to some database, associated with the session's name>

◆ tox_set_session_alias()

TOX_DEF_PREFIX TOX_ERROR tox_set_session_alias	(	tox_instance_t *	tox_instance_ptr,
		const char *	session_alias )

Save an alias for the associated session within ToxMod's database, to be passed back to you upon moderation actions. This allows you to associate a session name with the conversations shown in the web console rather than the internal UUID ToxMod uses to identify sessions. This function should be called after tox_set_session_name, in order to associate the session alias with the appropriate internal session uuid. The session alias is copied to internal storage, and does not need to be preserved after this function returns.

Parameters

[in]	tox_instance_ptr	reference to the tox_instance_t for the player in question
[in]	session_alias	alias for the session in question

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SESSION_ALIAS Returned if session_alias is null or empty
TOX_NO_SESSION_SET If tox_set_session_name has not yet been called to set a session name
TOX_UPLOAD_METADATA_FAILED Returned on any error in uploading the player alias to the server, potentially due to issues connecting to the server, initializing cURL for the network request, or invalid credentials used to create the tox_instance_ptr

Example:

tox_error = tox_set_session_alias(&tox_instance, "session1");

tox_set_session_alias

TOX_DEF_PREFIX TOX_ERROR tox_set_session_alias(tox_instance_t *tox_instance_ptr, const char *session_alias)

◆ tox_add_structured_player_data()

TOX_DEF_PREFIX TOX_ERROR tox_add_structured_player_data	(	tox_instance_t *	tox_instance_ptr,
		TOX_PLAYER_DATA_TYPE	data_type,
		const char *	data )

Send additional data about the current player to ToxMod. For a full list of possible data types, see the TOX_PLAYER_DATA_TYPE enum documentation. If the same type of data is sent multiple times, ToxMod will prefer the most recently received value.

Parameters

[in]	tox_instance_ptr	Reference to the tox_instance_t for the player in question
[in]	data_type	Option from TOX_PLAYER_DATA_TYPE
[in]	data	String of data - format will depend on data_type

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_PLAYER_DATA_TYPE If the value of data_type is not a recognized item from TOX_PLAYER_DATA_TYPE
TOX_BAD_PLAYER_DATA If data is null or does not match the structure required for the given data type (e.g. this will be returned if "en-us" is passed as a language preference instead of "en")
TOX_UPLOAD_METADATA_FAILED If there is a problem uploading information to the server

Example:

tox_error = tox_add_structured_player_data(&tox_instance, TOX_PLAYER_LANGUAGE_PREFERENCE, "en");

tox_add_structured_player_data

TOX_DEF_PREFIX TOX_ERROR tox_add_structured_player_data(tox_instance_t *tox_instance_ptr, TOX_PLAYER_DATA_TYPE data_type, const char *data)

TOX_PLAYER_LANGUAGE_PREFERENCE

@ TOX_PLAYER_LANGUAGE_PREFERENCE

Definition tox.h:277

◆ tox_add_structured_session_data()

TOX_DEF_PREFIX TOX_ERROR tox_add_structured_session_data	(	tox_instance_t *	tox_instance_ptr,
		TOX_SESSION_DATA_TYPE	data_type,
		const char *	language )

Send additional data about the current session to ToxMod. For a full list of possible data types, see the TOX_SESSION_DATA_TYPE enum documentation. If the same type of data is sent multiple times or by multiple players in the same session, ToxMod will prefer the most recently received value.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the player/session in question
[in]	data_type	Type of data being sent
[in]	language	Data being sent

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SESSION_DATA_TYPE If the value of data_type is not a recognized item from TOX_PLAYER_DATA_TYPE
TOX_BAD_SESSION_DATA If data is null or does not match the structure required for the given data type (e.g. this will be returned if "en-us" is passed as a language preference instead of "en")
TOX_UPLOAD_METADATA_FAILED If there is a problem uploading information to the server

Example:
tox_error = tox_add_structured_session_data(&tox_instance, TOX_SESSION_TYPE, "main-room");

TOX_SESSION_TYPE
@ TOX_SESSION_TYPE
Definition tox.h:299

tox_add_structured_session_data
TOX_DEF_PREFIX TOX_ERROR tox_add_structured_session_data(tox_instance_t *tox_instance_ptr, TOX_SESSION_DATA_TYPE data_type, const char *language)

◆ tox_add_session_data()

TOX_DEF_PREFIX TOX_ERROR tox_add_session_data	(	tox_instance_t *	tox_instance_ptr,
		const char *	session_data )

Send additional session context/data/events to ToxMod for use in assisting moderation. Since each game has different structure and different relevant events that may contribute to player toxicity, the format for this session data is determined on a per-customer basis. Please reach out to your Modulate account representative for more information. The session data is copied to internal storage, and does not need to be preserved after this function returns.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the player/session in question
[in]	session_data	Session data as a string.

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SESSION_DATA Returned if session_data is null or empty
TOX_NO_SESSION_SET If tox_set_session_name() has not yet been run on tox_instance_ptr, i.e. there is no currently set session to add data to.
TOX_UPLOAD_METADATA_FAILED Returned on any error in uploading the player alias to the server, potentially due to issues connecting to the server, initializing cURL for the network request, or invalid credentials used to create the tox_instance_ptr

Example:

const char* event = "{\"Event\": \"killed_by\", \"Other Participants\": [\"player2\"]}";

tox_error = tox_add_session_data(&tox_instance, event);

tox_add_session_data

TOX_DEF_PREFIX TOX_ERROR tox_add_session_data(tox_instance_t *tox_instance_ptr, const char *session_data)

◆ tox_set_proximity_chat_player_can_hear()

TOX_DEF_PREFIX TOX_ERROR tox_set_proximity_chat_player_can_hear	(	tox_instance_t *	tox_instance_ptr,
		const char const	players,
		unsigned int	num_players )

Set a list of players that this player can hear. This should be the full list of players that this player can hear at the time of the function call, and should be called each time that that list changes. For example, if another player leaves proximity chat range and this player can no longer hear them, call this function with the remaining list of players that this player can hear. Use either this function or tox_set_proximity_chat_can_hear_player() to specify proximity chat information, not both.

Note: The players array of strings specifies the player names, not the ToxMod-internal UUIDs associated with those players.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the current player
[in]	players	An array of the player names of the players who are muted-at-join
[in]	num_players	Length of the players list

Returns

TOX_NO_ERROR Function executed successfully
TOX_PROXIMITY_CHAT_DISABLED Returned if proximity_chat_session is 0 in the instance's config.
TOX_BAD_PLAYER_LIST Returned If the player list is null but num_players isn't 0.
TOX_BAD_PLAYER_NAME Returned If the player name list contains null/empty strings.
TOX_NOT_IN_SESSION Returned If the player isn't currently in a session

Example:

const char* players[] = {"player1", "player2"};

tox_error = tox_set_proximity_chat_player_can_hear(&tox_instance, players, 2);

tox_set_proximity_chat_player_can_hear

TOX_DEF_PREFIX TOX_ERROR tox_set_proximity_chat_player_can_hear(tox_instance_t *tox_instance_ptr, const char *const *players, unsigned int num_players)

◆ tox_set_proximity_chat_can_hear_player()

TOX_DEF_PREFIX TOX_ERROR tox_set_proximity_chat_can_hear_player	(	tox_instance_t *	tox_instance_ptr,
		const char const	players,
		unsigned int	num_players )

Set a list of players that can hear this player. This should be the full list of players that can hear this player at the time of the function call, and should be called each time that that list changes. For example, if another player leaves proximity chat range and they can no longer hear this player, call this function with the remaining list of players that can hear this player. Use either this function or tox_set_proximity_chat_player_can_hear() to specify proximity chat information, not both.

Note: The players array of strings specifies the player names, not the ToxMod-internal UUIDs associated with those players.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the current player
[in]	players	An array of the player names of the players who are muted-at-join
[in]	num_players	Length of the players list

Returns

TOX_PROXIMITY_CHAT_DISABLED Returned if proximity_chat_session is 0 in the instance's config.
TOX_BAD_PLAYER_LIST Returned if the player list is null but num_players isn't 0.
TOX_BAD_PLAYER_NAME Returned if the player name list contains null/empty strings.
TOX_NOT_IN_SESSION Returned if the player isn't currently in a session

Example:

const char* players[] = {"player1", "player2"};

tox_error = tox_set_proximity_chat_can_hear_player(&tox_instance, players, 2);

tox_set_proximity_chat_can_hear_player

TOX_DEF_PREFIX TOX_ERROR tox_set_proximity_chat_can_hear_player(tox_instance_t *tox_instance_ptr, const char *const *players, unsigned int num_players)

◆ tox_set_global_muted()

TOX_DEF_PREFIX TOX_ERROR tox_set_global_muted	(	tox_instance_t *	tox_instance_ptr,
		int	muted )

Signal to ToxMod that the player associated with an instance has muted or unmuted voice chat entirely.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the current player
[in]	muted	0 signals that voice chat was unmuted, 1 signals that voice chat was muted.

Returns

TOX_NOT_IN_SESSION If the player is not in a session

◆ tox_set_player_muted()

TOX_DEF_PREFIX TOX_ERROR tox_set_player_muted	(	tox_instance_t *	tox_instance_ptr,
		const char *	player,
		int	muted )

Signal to ToxMod that the player associated with an instance has muted or unmuted another player.

Note: The player argument specifies the player name associated with the muted/unmuted player, not the ToxMod-internal UUIDs associated with that player.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the current player
[in]	player	The name of the player being muted/unmuted
[in]	muted	0 signals that the player was unmuted, 1 signals that the player was muted.

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_PLAYER_NAME If player name is a null pointer or empty string
TOX_NOT_IN_SESSION If the player associated with the instance is not in a session

◆ tox_set_players_muted_at_join()

TOX_DEF_PREFIX TOX_ERROR tox_set_players_muted_at_join	(	tox_instance_t *	tox_instance_ptr,
		const char const	players,
		unsigned int	num_players )

Notify ToxMod that the player associated with an instance has a preexisting persistent mute set on one or more players in this session. ToxMod will treat this differently than a call to tox_set_player_muted(), which should be used for real-time muting actions.

This is intended to be called when the associated player joins a session, and again if a player who the associated player has muted joins the session later.

Note: The players array of strings specifies the player names, not the internal ToxMod UUIDs.

Parameters

[in]	tox_instance_ptr	Pointer to the tox_instance_t corresponding to the current player
[in]	players	An array of the player names of the players who are muted-at-join
[in]	num_players	Length of the players list

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_PLAYER_LIST If players list is a null pointer
TOX_BAD_PLAYER_NAME If any item in players list is null pointer or empty string
TOX_NOT_IN_SESSION If the player associated with the instance is not in a session

◆ tox_add_audio_float()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio_float	(	tox_instance_t *	tox_instance_ptr,
		const float *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate,
		unsigned int	num_channels )

Realtime-friendly hook to consume voice chat audio - call this with access to the voice chat stream.

Note: This should be used in a realtime audio stream context, and not used on a large amount of batched audio. Good sizes for audio chunks range from a few milliseconds to a few hundred milliseconds; larger than that should be broken into chunks and passed through. The input audio buffer is immediately copied into an internal circular buffer, so the audio parameter does not need to remain valid after this function returns. This function accepts a float point linear PCM audio buffer with an arbitrary number of interleaved channels. The num_samples parameter is irrespective of the number of channels, so for example a mono-channel 10ms audio buffer at 48kHz would have num_samples=480, num_channels=1, sample_rate=1 with the audio parameter pointing to a buffer holding 480 floating point numbers; while a stereo 10ms buffer at 48kHz would have num_samples=480, num_channels=2, sample_rate=1 with the audio parameter pointing to a buffer holding 960 floating point numbers in the order [left channel sample 0, right channel sample 0, left channel sample 1, right channel sample 1,...].

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz
[in]	num_channels	The number of interleaved channels in the input audio buffer

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE If the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO If the audio parameter is null
TOX_SAMPLES_SKIPPED If the internal circular buffer couldn't hold all of the audio samples passed into this function call. This can happen if too many samples are added much faster than realtime - e.g. 50,000 samples added in one function call - since the internal circular buffer is drained by a separate thread several times per second, and only holds approx. 1 second of audio at a time. This return value indicates that there be a skip in the processed/uploaded audio. Large or frequent skips may degrade toxicity detection model performance, and cause difficulty for human moderators.

Examples: main.c.

◆ tox_add_audio_short()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio_short	(	tox_instance_t *	tox_instance_ptr,
		const short *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate,
		unsigned int	num_channels )

An equivalent function to tox_add_audio_float(), but consuming audio data in 16-bit signed integer linear PCM format (i.e. shorts in the range [-2^15, 2^15-1]). This converts the short values to floats in [-1, 1] internally, and uses the same functionality as tox_add_audio_float().

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz
[in]	num_channels	The number of interleaved channels in the input audio buffer

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE If the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO If the audio parameter is null
TOX_SAMPLES_SKIPPED If the internal circular buffer couldn't hold all of the audio samples passed into this function call. This can happen if too many samples are added much faster than realtime - e.g. 50,000 samples added in one function call - since the internal circular buffer is drained by a separate thread several times per second, and only holds approx. 1 second of audio at a time. This return value indicates that there be a skip in the processed/uploaded audio. Large or frequent skips may degrade toxicity detection model performance, and cause difficulty for human moderators.

◆ tox_add_audio()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio	(	tox_instance_t *	tox_instance_ptr,
		const float *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate )

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE If the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO If the audio parameter is null
TOX_SAMPLES_SKIPPED If the internal circular buffer couldn't hold all of the audio samples passed into this function call. This can happen if too many samples are added much faster than realtime - e.g. 50,000 samples added in one function call - since the internal circular buffer is drained by a separate thread several times per second, and only holds approx. 1 second of audio at a time. This return value indicates that there be a skip in the processed/uploaded audio. Large or frequent skips may degrade toxicity detection model performance, and cause difficulty for human moderators.

◆ tox_add_audio_nonrealtime_float()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio_nonrealtime_float	(	tox_instance_t *	tox_instance_ptr,
		const float *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate,
		unsigned int	num_channels )

Non-realtime-friendly hook to consume voice chat audio - call this with access to the voice chat stream.

Warning: Do not use this in a realtime audio stream context, it accesses mutexes, allocates memory, and is not optimized for realtime use. Intended for audio batches that are too large to use in tox_add_audio() - e.g. over a few hundred milliseconds (although smaller batches will work too). Good audio batch sizes range from a few milliseconds to a few seconds - anything longer than about 10s should be broken into chunks and passed through. The input audio buffer is immediately copied into internal storage, so the audio parameter does not need to remain valid after this function returns. This function accepts a float point linear PCM audio buffer with an arbitrary number of interleaved channels. The num_samples parameter is irrespective of the number of channels, so for example a mono-channel 10ms audio buffer at 48kHz would have num_samples=480, num_channels=1, sample_rate=1 with the audio parameter pointing to a buffer holding 480 floating point numbers; while a stereo 10ms buffer at 48kHz would have num_samples=480, num_channels=2, sample_rate=1 with the audio parameter pointing to a buffer holding 960 floating point numbers in the order [left channel sample 0, right channel sample 0, left channel sample 1, right channel sample 1,...].

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz
[in]	num_channels	The number of interleaved channels in the input audio buffer

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE If the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO If the audio parameter is null

◆ tox_add_audio_nonrealtime_short()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio_nonrealtime_short	(	tox_instance_t *	tox_instance_ptr,
		const short *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate,
		unsigned int	num_channels )

An equivalent function to tox_add_audio_nonrealtime_float(), but consuming audio data in 16-bit signed integer linear PCM format (i.e. shorts in the range [-2^15, 2^15-1]). This converts the short values to floats in [-1, 1] internally, and uses the same functionality as tox_add_audio_nonrealtime_float.

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz
[in]	num_channels	The number of interleaved channels in the input audio buffer

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE - if the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO - if the audio parameter is null

◆ tox_add_audio_nonrealtime()

TOX_DEF_PREFIX TOX_ERROR tox_add_audio_nonrealtime	(	tox_instance_t *	tox_instance_ptr,
		const float *	audio,
		unsigned int	num_samples,
		unsigned int	sample_rate )

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	audio	Pointer to num_samples 32-bit floating point linear PCM audio samples. Should be within the range [-1, 1]
[in]	num_samples	The number of audio samples pointed to by audio. This is irrespective of the number of channels in the audio, and is "the sample rate times the number of seconds of audio input".
[in]	sample_rate	The sample rate of the audio stream, in Hertz

Returns

TOX_NO_ERROR Function executed successfully
TOX_BAD_SAMPLE_RATE - if the sample rate is outside of most typical ranges for audio, potentially indicating an error in setting parameter. Here, the check is for valid sample rates between (inclusive) 1,000 Hz and 96,000 Hz.
TOX_BAD_AUDIO - if the audio parameter is null

◆ tox_set_single_tenant_prefix()

TOX_DEF_PREFIX TOX_ERROR tox_set_single_tenant_prefix	(	tox_instance_t *	tox_instance_ptr,
		const char *	prefix )

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	prefix	Single tenant prefix string

Returns

TOX_NO_ERROR Function executed successfully

◆ tox_set_log_info_callback()

TOX_DEF_PREFIX TOX_ERROR tox_set_log_info_callback ( void(* log_info_callback )(const char *) )

Set a user-defined callback to print/log info messages from tox If this is not called, ToxMod will print info messages to stdout

Returns

TOX_NO_ERROR Function executed successfully

Examples: main.c.

◆ tox_set_log_error_callback()

TOX_DEF_PREFIX TOX_ERROR tox_set_log_error_callback ( void(* log_error_callback )(const char *) )

Set a user-defined callback to print/log error messages from tox If this is not called, ToxMod will print error messages to stderr

Returns

TOX_NO_ERROR Function executed successfully

Examples: main.c.

◆ tox_get_version()

TOX_DEF_PREFIX const char * tox_get_version ( void )

Return the version string for the library that this is built with
Should match TOX_VERSION

Returns: Version number of the ToxMod SDK

◆ tox_set_instance_token()

TOX_DEF_PREFIX TOX_ERROR tox_set_instance_token	(	tox_instance_t *	tox_instance_ptr,
		const char *	token )

Set or refresh the token a given instance uses to authenticate. The token provided should conform to the ToxMod JWT authentication spec provided in the web console.

Note: This does not check the validity of the token - invalid tokens or a null pointer will not raise an error

Parameters

[in]	tox_instance_ptr	Pointer to the instance created in tox_create_instance()
[in]	token	JWT meeting the spec on the web console. If an empty string or null pointer is passed, this will clear the existing token from memory and future web requests will fail until a valid token is passed.

Returns

TOX_BAD_AUTH_MODE Instance is set up to use API key authentication instead of tokens

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TOX_VERSION

Enumeration Type Documentation

◆ TOX_TRIAGE_SETTING

◆ TOX_ERROR

◆ TOX_PLAYER_DATA_TYPE

◆ TOX_SESSION_DATA_TYPE

Function Documentation

◆ tox_global_init()

◆ tox_init_default_web_config()

◆ tox_global_init_with_web_config()

◆ tox_global_cleanup()

◆ tox_error_name()

◆ tox_create_instance()

◆ tox_destroy_instance()

◆ tox_set_session_name()

◆ tox_join_session()

◆ tox_leave_session()

◆ tox_get_internal_player_uuid()

◆ tox_set_player_alias()

◆ tox_get_internal_session_uuid()

◆ tox_set_session_alias()

◆ tox_add_structured_player_data()

◆ tox_add_structured_session_data()

◆ tox_add_session_data()

◆ tox_set_proximity_chat_player_can_hear()

◆ tox_set_proximity_chat_can_hear_player()

◆ tox_set_global_muted()

◆ tox_set_player_muted()

◆ tox_set_players_muted_at_join()

◆ tox_add_audio_float()

◆ tox_add_audio_short()

◆ tox_add_audio()

◆ tox_add_audio_nonrealtime_float()

◆ tox_add_audio_nonrealtime_short()

◆ tox_add_audio_nonrealtime()

◆ tox_set_single_tenant_prefix()

◆ tox_set_log_info_callback()

◆ tox_set_log_error_callback()

◆ tox_get_version()

◆ tox_set_instance_token()