ToxMod Server-Side SDK

The ToxMod Server-Side SDK is designed to integrate into a voice chat server, handling multiple streams of player audio in potentially multiple voice chat rooms simultaneously. It is designed to copy mono-channel Opus packets from individual player audio streams in a realtime-safe way to an internal circular buffer, then build and upload Ogg Opus files to the ToxMod server for further analysis. The results of that analysis appear, triaged and prioritized for toxic content, in the ToxMod web console.

Included in this release is the core tox_server shared library, along with a header file tox_server.h to enable integration into a voice chat server application. Additionally, the full source code behind tox_server is included to allow for performance tweaking and profiling, as well as compilation for new platforms. Finally, two test programs program are included which simulate voice chat by running a test file (also included) through tox_server as if one or multiple players were speaking. Checking the ToxMod web console should show clips from the test file on the Livestreams page to verify that the library is functioning properly.

Please contact suppo.nosp@m.rt@m.nosp@m.odula.nosp@m.te.a.nosp@m.i with any questions, comments, or feedback.

Platforms

Supported platforms for pre-compiled libraries are x86_64 Windows 10, macOSX 10.15 and later, and Linux. The pre-compiled libraries are in the lib/ subdirectory, with the following structure:

• lib/linux/libtox_server.so - the tox_server library for Linux
• lib/osx/libtox_server.dylib - the tox_server library for macOSX 10.15 and up
• lib/windows/Release/tox_server.dll - the tox_server DLL for Windows 10, a tox_server.lib import library is included in the same directory
• lib/windows/Debug/tox_server.dll - a Debug version of the tox_server DLL for Windows 10, a tox_server.lib import library and tox_server.pdb debugging symbols file are included in the same directory

Dependencies

tox_server depends on the cURL and Ogg libraries, for upload functions and packing Opus packets into Ogg formatted data buffers. Additionally, building the example programs require including the Ogg header files, so installing a developer version of the Ogg library may be necessary.

Integration

The Server-Side SDK integration consists of a few moving pieces to safely move data from the realtime audio threads through to upload to the ToxMod severs:

1. Call tox_server_global_init() with the account id, key, and optionally single-tenant prefix to set account-wide parameters
   
2. Call tox_server_create_instance() as players join sessions, associating the tox_server_instance_t with a specific player and voice chat session. The player name and session fields are converted to UUIDv3 strings and used as identifiers to track the session and player as they communicate with others. The player name and session name do not need to be usernames, lobby names, etc. - but do need to be unique strings that can be correlated back to internal ids for the player and/or session in order to take moderation action against the appropriate player. Additionally, the config parameters for maximum number of packets and maximum packet size determine the amount of memory pre-allocated for every player and voice chat stream. The maximum packet size must be large enough to hold any single Opus packet that tox_server may receive. The number of packets determines how often the internal circular buffer must be drained in a separate loop to avoid dropping packets - choosing a number such that the circular buffer can hold up to 1s total of audio is a reasonable initial default.
   
3. Call tox_server_add_packet() each time an Opus packet is received. Each packet should be added to the tox_server_instance_t corresponding to the player who spoke the audio in that packet.
4. Call tox_server_run_buffer_copy() in a loop over all current tox_server_instance_t objects, to drain the circular buffers and avoid dropping packets. This should happen at a pace such that no more than the maximum number of packets specified in (2) will build up for any given tox_server_instance_t before this function is called. If enough packets are allocated in (2) to hold a second of audio, running this 3-4 times per second is a reasonable default to provide plenty of margin and avoid dropping packets.
   
5. Call tox_server_begin_upload() in a loop over all current tox_server_instance_t objects, to move finished Ogg data buffers from an internal upload queue to cURL for uploading. This should be done once every few seconds, to ensure relatively low latency between events happening in voice chat and having them appear on the ToxMod web console, and to avoid hitting the maximum number of Ogg data buffers in the internal upload queue.
   
6. Call tox_server_run_all_uploads_with_timeout() in a loop to progress any currently ongoing Ogg data buffer uploads. This does not require pointers to tox_server_instance_t objects, as the uploading data is at this point owned by cURL and tracked separately. This function does not require the caller to wait in a timed loop, as it includes a built-in wait if no work is available for running uploads.
   
7. When a player leaves a voice chat session, destroy the corresponding tox_server_instance_t object via tox_server_destroy_instance().
   
8. When the ToxMod functionality is no longer needed, such as during application shutdown, call tox_server_global_cleanup() to cleanup internal state, at the point where no further tox_server functions will be called.
   

Building the SDK

The ToxMod Server-Side SDK comes pre-compiled for specific platforms as part of the downloaded release, however it may also be compiled from source. There is no pre-configuration required to do so beyond installing the cURL and Ogg libraries as dependencies, defining LIBTOX_SERVER_EXPORTS on Windows or TOX_SERVER_EXPORT_SHARED on other platforms for public symbol visibility, and compiling the sources in src/ along with the public header in include/.

A CMakeLists.txt file is included for convenience in building the SDK across various systems. To build using CMake, use the following commands. If building for Windows, you may need to use cmake.exe instead of cmake depending on your shell settings.

cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build

To install dependencies with VCPKG, use:

vcpkg install libogg curl

To build the SDK using VCPKG dependencies, just add the path to the VCPKG CMAKE_TOOLCHAIN_FILE:

cmake -B build -DCMAKE_TOOLCHAIN_FILE="<path containing vcpkg>"/scripts/buildsystems/vcpkg.cmake" -DCMAKE_BUILD_TYPE=Release && cmake --build build

Exception Support

The pre-compiled ToxMod Server-Side libraries included in this release are built with exceptions supported internally (though no exceptions pass through the C interface exposed in tox_server.h). If needed, the SDK may be compiled without exception support by defining the flag TOX_SERVER_NO_EXCEPTIONS at compile time. This compilation mode is officially supported on Linux and macOSX.

Note

If exceptions are disabled, the memory allocator that we pass to the STL containers will return nullptr on an allocation error, instead of throwing an exception. If your implementation of the containers does not handle that case, a crash could occur. A future release of this SDK will replace STL containers with alternatives that handle memory allocation errors without relying on exceptions.

Structure of the SDK

The ToxMod Server-Side SDK exposes the following public header file in the include/ subdirectory:

• tox_server.h: The header file exposing the core SDK functionality

The source code to build the library consists of the above header plus source code in the src/ subdirectory:

• tox_server.cpp: Wrapper functions implementing most of the functions in the header file and interfacing with the rest of the SDK internals
• circular_packet_buffer.hpp/.cpp: An implementation of a circular buffer specialized to holding discrete packets of data, allowing for single reader / single writer wait-free multithreading
• tox_clip.hpp/.cpp: A class managing an Ogg data buffer, handling converting Opus packets into an Ogg stream state and writing from that stream state to the data buffer. Also manages the criteria for when an Ogg data buffer should be uploaded as a discrete audio clip to the ToxMod server.
• tox_packet_collector.hpp/.cpp: The main stateful class for the Server-Side SDK, which manages all data specific to a player in a voice chat stream. Owns a circular packet buffer, an in-progress ToxClip, and a queue of finished ToxClips to upload.
• ogg_opus_utils.hpp/.cpp: Helper functions for reading Opus packet metadata, packing Opus packets into Ogg packets, and building Opus header and tags packets
• uuidv3.hpp/.cpp: A small helper for creating UUID version 3 strings from input strings. Leverages a slightly modified implementation of MD5 from RSA Data Security (see Md5.c for details)
• web_functions.hpp/.cpp: Functions and internal state for managing cURL uploads to the ToxMod server
• utils.hpp: A small set of helper print and timing functions, can be overridden for other logging options, improved performance of time functions, etc.

Example Programs

Source code for building a basic example program (example/basic_example.c) which verifies tox_server functionality, as well as a more realistic multistream example program (example/multistream_example.cpp) are included. Before compiling the example programs, please add the Modulate-provided account id, api key, and (if applicable) single tenant prefix to the top of the files. The example programs may be compiled by linking to the Ogg library and tox_server library, assuming the Ogg headers are installed on the system.

The basic example program runs an Opus file through the ToxServer library by reading Opus packets from the file and adding them to the library under the guise of a single player. The contents of the example file should show up on the ToxMod web console Livestreams page in several short clips. The clips should be intelligible and transcribed understandably, though they may show up out of temporal order since the basic example program reads through the entire file as fast as possible (instead of in realtime).

The basic example program takes no arguments, and expects to read a file called test_clip.opus from the same directory as the executable. The relevant test_clip.opus included in the example/ may be copied to the correct location if building with the provided CMakeLists.txt file, but on some platforms may need to be copied to the correct location manually. If experimenting with a clip other than the provided test_clip.opus, the max_packet_size and frame_size parameters in basic_example.c may need to be updated to reflect the properties of the new Opus clip. You may also manually set the properties of a new file by adjusting its frame duration, bitrate, and VBR setting, such as with

ffmpeg -i high_quality_test_clip.opus -b:a 32000 -vbr off -frame_duration 20 test_clip.opus

The basic example program will print outputs from cURL uploads, to indicate successful clip upload to ToxMod (error code 0), or some clip upload error.

Additionally, source code for a more realistic example program (example/multistream_example.cpp) is included, which behaves similarly to the basic example but has the following differences: multiple players are simulated as if they are all "speaking" the input file, grouped into multiple voice chat sessions; the buffer copy, begin upload, and run upload functions are all run in timed loops as in a real production voice chat server; the simulated voice chat happens in approximately realtime (by adding packet, then sleeping for the duration of that packet) instead of as fast as possible.

The multistream example program is intended as a reference for production usage of tox_server. However, the multistream example program is not an exact simulation of production usage: for example, it simulates all speakers speaking simultaneously all of the time, and all speaking exactly the same thing - therefore buffer copies, clip uploads, etc. all happen at exactly the same time for all players; as opposed to production usage where a smaller set of players will be speaking at any given time, and buffer copies and clip uploads will be more evenly distributed over time.

The multistream example program will print out dots once per second to show that it is running, as well as outputs from cURL approximately once ever 15 seconds, to indicate successful clip upload to ToxMod (error code 0), or some clip upload error.

Bindings

Wrappers of the Server-Side C API to provide bindings for other languages are provided in the bindings/ subdirectory. In each case the wrapper file is name tox_server.<typical language extension>, and is shipped alongside a simple API test program to verify that the bindings are functional and a makefile to build/run the API tests.