libtgvoip wrapper

VoIPController

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

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()

Start the controller

connect()

Start the call

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

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)

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 0x7f98eedf7cf8>], allow_p2p: bool, tcp: bool, connection_max_layer: int)

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

Get debug string

Returns:

str containing debug info

set_network_type(_type: tgvoip.tgvoip.NetType)

Set network type

Parameters:_type (NetType) – Network type to set

set_mic_mute(mute: bool)

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)

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)

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

Get preferred relay ID (used in discardCall MTProto request)

Returns:int ID

get_last_error() → tgvoip.tgvoip.CallError

Get last error type

Returns:CallError matching last occurred error type

get_stats() → <sphinx.ext.autodoc.importer._MockObject object at 0x7f98eedf7c88>

Get call stats

Returns:Stats object

get_debug_log() → str

Get debug log

Returns:JSON str containing debug log

set_audio_output_gain_control_enabled(enabled: bool)

Toggle output gain control

Parameters:enabled (bool) – Whether to enable output gain control

set_echo_cancellation_strength(strength: int)

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

Parameters:strength (int) – Strength value

get_peer_capabilities() → int

Get peer capabilities

Returns:int with bit mask, looks like it is used only for experimental features (group, video calls)

need_rate() → bool

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

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

Replace the hold queue for native I/O

Parameters:paths (list of str) – List of file paths

set_output_file(path: str) → bool

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

Clear the play queue for native I/O

clear_hold_queue() → None

Clear the hold queue for native I/O

unset_output_file() → None

Unset the output file for native I/O

update_state(state: tgvoip.tgvoip.CallState)

Manually update state (only triggers handlers)

Parameters:state (CallState) – State to set

set_send_audio_frame_callback(func: callable)

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)

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)

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

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

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)

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

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

An enumeration of data saving modes

Members:

• NEVER = 0
• MOBILE = 1
• ALWAYS = 2

class tgvoip.CallState

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

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