ToxAV

Description:

Public audio/video API for Tox clients.

This API can handle multiple calls. Each call has its state, in very rare occasions the library can change the state of the call without apps knowledge.

Events and callbacks

As in Core API, events are handled by callbacks. One callback can be registered per event. All events have a callback function type named `toxav_{event}_cb` and a function to register it named `toxav_callback_{event}`. Passing a NULL callback will result in no callback being registered for that event. Only one callback per event can be registered, so if a client needs multiple event listeners, it needs to implement the dispatch functionality itself. Unlike Core API, lack of some event handlers will cause the the library to drop calls before they are started. Hanging up call from a callback causes undefined behaviour.

Threading implications

Unlike the Core API, this API is fully thread-safe. The library will ensure the proper synchronization of parallel calls.

A common way to run ToxAV (multiple or single instance) is to have a thread, separate from tox instance thread, running a simple toxav_iterate loop, sleeping for toxav_iteration_interval * milliseconds on each iteration.

An important thing to note is that events are triggered from both tox and toxav thread (see above). Audio and video receive frame events are triggered from toxav thread while all the other events are triggered from tox thread.

Tox thread has priority with mutex mechanisms. Any api function can fail if mutexes are held by tox thread in which case they will set SYNC error code.

Content:

Classes:

ToxAV - The ToxAV instance type. Each ToxAV instance can be bound to only one Tox instance, and Tox instance can have only one ToxAV instance. One must make sure to close ToxAV instance prior closing Tox instance otherwise undefined behaviour occurs. Upon closing of ToxAV instance, all active calls will be forcibly terminated without notifying peers.

Enums:

Delegates:

public delegate void AudioBitRateCallback (ToxAV av, uint32 friend_number, uint32 audio_bit_rate)
The function type for the audio_bit_rate callback. The event is triggered when the network becomes too saturated for current bit rates at which point core suggests new bit rates.
public delegate void AudioReceiveFrameCallback (ToxAV av, uint32 friend_number, int16[] pcm, size_t sample_count, uint8 channels, uint32 sampling_rate)
The function type for the audio_receive_frame callback. The callback can be called multiple times per single iteration depending on the amount of queued frames in the buffer. The received format is the same as in send function.
public delegate void CallCallback (ToxAV av, uint32 friend_number, bool audio_enabled, bool video_enabled)
The function type for the call callback.
public delegate void CallStateCallback (ToxAV av, uint32 friend_number, FriendCallState state)
The function type for the call_state callback.
public delegate void GroupchatAudioReceiveFrameCallback (Tox self, uint32 group_number, uint32 peer_number, int16[] pcm, uint samples, uint8 channels, uint32 sampling_rate)
public delegate void VideoBitRateCallback (ToxAV av, uint32 friend_number, uint32 video_bit_rate)
The function type for the video_bit_rate callback. The event is triggered when the network becomes too saturated for current bit rates at which point core suggests new bit rates.
public delegate void VideoReceiveFrameCallback (ToxAV av, uint32 friend_number, uint16 width, uint16 height, uint8[] y, uint8[] u, uint8[] v, int32 ystride, int32 ustride, int32 vstride)
The function type for the video_receive_frame callback.