libtgvoip wrapper

VoIPController

class tgvoip.VoIPController(persistent_state_file: str = '', debug=False, logs_dir='logs')[source]

A wrapper around C++ wrapper for libtgvoip VoIPController

Parameters:
  • persistent_state_file (str, optional) – ?, empty to not use
  • debug (bool, optional) – Modifies logging behavior
  • logs_dir (str, optional) – Logs directory
Class attributes:
LIBTGVOIP_VERSION
Used libtgvoip version
CONNECTION_MAX_LAYER
Maximum layer supported by used libtgvoip version
persistent_state_file

Value set in the constructor

call_state_changed_handlers

list of call state change callbacks, callbacks receive a CallState object as argument

signal_bars_changed_handlers

list of signal bars count change callbacks, callbacks receive an int object as argument

call_duration

Current call duration in seconds as int if call was started, otherwise 0

start()[source]

Start the controller

connect()[source]

Start the call

set_proxy(address: str, port: int = 1080, username: str = '', password: str = '')[source]

Set SOCKS5 proxy config

Parameters:
  • address (str) – Proxy hostname or IP address
  • port (int, optional) – Proxy port
  • username (int, optional) – Proxy username
  • password (int, optional) – Proxy password
Raises:

ValueError if address is empty

set_encryption_key(key: bytes, is_outgoing: bool)[source]

Set call auth key

Parameters:
  • key (bytes) – Auth key, must be exactly 256 bytes
  • is_outgoing (bool) – Is call outgoing
Raises:

ValueError if provided auth key has wrong length

set_remote_endpoints(endpoints: List[<sphinx.ext.autodoc.importer._MockObject object at 0x7fef44b2f668>], allow_p2p: bool, tcp: bool, connection_max_layer: int)[source]

Set remote endpoints received in call object from Telegram.

Usually it’s [call.connection] + call.alternative_connections.

You must build Endpoint objects from MTProto phoneConnection objects and pass them in list.

Parameters:
  • endpoints (list of Endpoint) – List of endpoints
  • allow_p2p (bool) – Is p2p connection allowed, usually call.p2p_allowed value is used
  • tcp (bool) – Connect via TCP, not recommended
  • connection_max_layer (int) – Use a value provided by VoIPController.CONNECTION_MAX_LAYER
Raises:

ValueError if either no endpoints are provided or endpoints without IPv4 or with wrong peer_tag (must be either None or have length of 16 bytes) are detected

get_debug_string() → str[source]

Get debug string

Returns:
str containing debug info
set_network_type(_type: tgvoip.tgvoip.NetType)[source]

Set network type

Parameters:_type (NetType) – Network type to set
set_mic_mute(mute: bool)[source]

Set “microphone” state. If muted, audio is not being sent

Parameters:mute (bool) – Whether to mute “microphone”
set_config(recv_timeout: float, init_timeout: float, data_saving_mode: tgvoip.tgvoip.DataSaving, call_id: int, enable_aec: bool = True, enable_ns: bool = True, enable_agc: bool = True, log_file_path: str = None, status_dump_path: str = None, log_packet_stats: bool = None)[source]

Set call config

Parameters:
  • recv_timeout (float) – Packet receive timeout, usually value received from help.getConfig() is used
  • init_timeout (float) – Packet init timeout, usually value received from help.getConfig() is used
  • data_saving_mode (DataSaving) – Data saving mode
  • call_id (int) – Call ID
  • enable_aec (bool, optional) – Whether to enable automatic echo cancellation, defaults to True
  • enable_ns (bool, optional) – Whether to enable noise suppression, defaults to True
  • enable_agc (bool, optional) – Whether to enable automatic gain control, defaults to True
  • log_file_path (str, optional) – Call log file path, calculated automatically if not provided
  • status_dump_path (str, optional) – Status dump path, calculated automatically if not provided and debug is enabled
  • log_packet_stats (bool, optional) – Whether to log packet stats, defaults to debug value
debug_ctl(request: int, param: int)[source]

Debugging options

Parameters:
  • request (int) – Option (1 for max bitrate, 2 for packet loss (in percents), 3 for toggling p2p, 4 for toggling echo cancelling)
  • param (int) – Numeric value for options 1 and 2, 0 or 1 for options 3 and 4
get_preferred_relay_id() → int[source]

Get preferred relay ID (used in discardCall MTProto request)

Returns:int ID
get_last_error() → tgvoip.tgvoip.CallError[source]

Get last error type

Returns:CallError matching last occurred error type
get_stats() → <sphinx.ext.autodoc.importer._MockObject object at 0x7fef44b2f5f8>[source]

Get call stats

Returns:Stats object
get_debug_log() → str[source]

Get debug log

Returns:JSON str containing debug log
set_audio_output_gain_control_enabled(enabled: bool)[source]

Toggle output gain control

Parameters:enabled (bool) – Whether to enable output gain control
set_echo_cancellation_strength(strength: int)[source]

Set echo cancellation strength, does nothing currently but was in Java bindings (?)

Parameters:strength (int) – Strength value
get_peer_capabilities() → int[source]

Get peer capabilities

Returns:int with bit mask, looks like it is used only for experimental features (group, video calls)
need_rate() → bool[source]

Get whether the call needs rating

Returns:bool value
native_io

Get native I/O status (file I/O implemented in C++)

Returns:bool status (enabled or not)
play(path: str) → bool[source]

Add a file to play queue for native I/O

Parameters:path (str) – File path
Returns:bool whether opening the file was successful. File is not added to queue on failure.
play_on_hold(paths: List[str]) → None[source]

Replace the hold queue for native I/O

Parameters:paths (list of str) – List of file paths
set_output_file(path: str) → bool[source]

Set output file for native I/O

Parameters:path (str) – File path
Returns:bool whether opening the file was successful. Output file is not replaced on failure.
clear_play_queue() → None[source]

Clear the play queue for native I/O

clear_hold_queue() → None[source]

Clear the hold queue for native I/O

unset_output_file() → None[source]

Unset the output file for native I/O

update_state(state: tgvoip.tgvoip.CallState)[source]

Manually update state (only triggers handlers)

Parameters:state (CallState) – State to set
set_send_audio_frame_callback(func: callable)[source]

Set callback providing audio data to send

Should accept one argument (int length of requested audio frame) and return bytes object with audio data encoded in 16-bit signed PCM

If returned object has insufficient length, it will be automatically padded with zero bytes

Parameters:func (callable) – Callback function
set_recv_audio_frame_callback(func: callable)[source]

Set callback receiving incoming audio data

Should accept one argument (bytes) with audio data encoded in 16-bit signed PCM

Parameters:func (callable) – Callback function

VoIPServerConfig

class tgvoip.VoIPServerConfig(*args, **kwargs)[source]

Global server config class. This class contains default config in its source

classmethod set_config(_json: Union[str, dict])[source]

Set global server config

Parameters:_json (str | dict) – either JSON-encoded object or dict containing config values. Might be received from MTProto phone.getCallConfig() call, if not set default values are used
Raises:Prints an error to stderr if JSON parsing (for str argument) or encoding (for dict argument) has occurred
classmethod set_bitrate_config(init_bitrate: int = 16000, max_bitrate: int = 20000, min_bitrate: int = 8000, decrease_step: int = 1000, increase_step: int = 1000)[source]

Helper method for setting bitrate options

Parameters:
  • init_bitrate (int) – Initial bitrate value
  • max_bitrate (int) – Maximum bitrate value
  • min_bitrate (int) – Minimum bitrate value
  • decrease_step (int) – Bitrate decrease step
  • increase_step (int) – Bitrate increase step
Raises:

Same as set_config()

Enums

class tgvoip.NetType[source]

An enumeration of network types

Members:
  • UNKNOWN = 0
  • GPRS = 1
  • EDGE = 2
  • NET_3G = 3
  • HSPA = 4
  • LTE = 5
  • WIFI = 6
  • ETHERNET = 7
  • OTHER_HIGH_SPEED = 8
  • OTHER_LOW_SPEED = 9
  • DIALUP = 10
  • OTHER_MOBILE = 11
class tgvoip.DataSaving[source]

An enumeration of data saving modes

Members:
  • NEVER = 0
  • MOBILE = 1
  • ALWAYS = 2
class tgvoip.CallState[source]

An enumeration of call states

Members:
  • WAIT_INIT = 1
  • WAIT_INIT_ACK = 2
  • ESTABLISHED = 3
  • FAILED = 4
  • RECONNECTING = 5
  • HANGING_UP = 10
  • ENDED = 11
  • EXCHANGING_KEYS = 12
  • WAITING = 13
  • REQUESTING = 14
  • WAITING_INCOMING = 15
  • RINGING = 16
  • BUSY = 17
class tgvoip.CallError[source]

An enumeration of call errors

Members:
  • UNKNOWN = 0
  • INCOMPATIBLE = 1
  • TIMEOUT = 2
  • AUDIO_IO = 3
  • PROXY = 4

Data structures

class tgvoip.Stats

Object storing call stats

bytes_sent_wifi

Amount of data sent over WiFi :type: int

bytes_sent_mobile

Amount of data sent over mobile network :type: int

bytes_recvd_wifi

Amount of data received over WiFi :type: int

bytes_recvd_mobile

Amount of data received over mobile network :type: int

class tgvoip.Endpoint

Object storing endpoint info

Parameters:
  • _id (int) – Endpoint ID
  • ip (str) – Endpoint IPv4 address
  • ipv6 (str) – Endpoint IPv6 address
  • port (int) – Endpoint port
  • peer_tag (bytes) – Endpoint peer tag