VoIP and WebRTC calls
Overview
This doc owns Telegram Android's call runtime and call-specific WebRTC bindings:
TMessagesProj/src/main/java/org/telegram/messenger/voip/**: call service, native-instance wrapper, audio/camera bridges, notification actions, Telecom integration, and call sound provider.- TMessagesProj/…/VoIP*.java: private call UI, permission bridge, and feedback entry point.
- TMessagesProj/…/GroupCall*.java and TMessagesProj/…/GroupCall*.java: group-call bottom sheet, fullscreen/grid/PiP helpers, and record/join affordances.
- TMessagesProj/…/JoinCall*.java: join-as and invite-link sheets for group calls.
TMessagesProj/src/main/java/org/webrtc/**: vendored Java WebRTC wrappers used by native tgcalls for rendering, capture, audio, peer connections, and EGL/native object ownership.TMessagesProj/jni/voip/**: native tgvoip/tgcalls bridge, WebRTC sources, and JNI glue.TMessagesProj/src/main/res/raw/voip_*andTMessagesProj/src/main/res/raw/voicechat_*: call and voice-chat sounds/animations loaded by the service and UIs.
VoIPService (TMessagesProj/…/VoIPService.java) is the owner of call lifetime. It is a foreground Service with a single static sharedInstance; it is started with intent extras that route the session to either a private user call (user_id) or a group call (chat_id, peer*, hash, createGroupCall, scheduleDate). onStartCommand loads sounds, initializes video sinks, resolves the user/chat, creates camera capture when needed, starts or acknowledges call signaling, and publishes NotificationCenter.voipServiceCreated. Private-call UI is shown through LaunchActivity action voip, while group-call UI is routed through action voip_chat.
For private calls, VoIPService.startOutgoingCall, acceptIncomingCall, processAcceptedCall, onCallUpdated, and initiateActualEncryptedCall implement the Telegram DH handshake and native-instance startup. The service requests or receives TLRPC.PhoneCall, validates g_a/g_b, derives a 256-byte auth key and key fingerprint, confirms/accepts the call through TL_phone_* requests, and then creates a NativeInstance via Instance.makeInstance. The native instance receives an Instance.Config, persistent-state path, TURN/reflector endpoints, proxy config, network type, encryption key, remote video sink, optional video capturer, and audio-level callback. State from native returns through NativeInstance listeners and is converted into service states such as STATE_ESTABLISHED, STATE_RECONNECTING, STATE_FAILED, and STATE_ENDED.
For group calls, VoIPService.startGroupCall, createGroupInstance, startScreenCapture, and updateConnectionState coordinate TL_phone_createGroupCall, TL_phone_joinGroupCall, TL_phone_joinGroupCallPresentation, and the native NativeInstance.makeGroup path. The native group instance first emits a JSON join payload with an audio SSRC; Java sends that payload to Telegram and later feeds the server join response back to native with setJoinResponsePayload. Broadcast/RTMP streams switch the native mode through prepareForStream; stream parts are fetched as TL_upload_getFile with TL_inputGroupCallStream and delivered back to native with onStreamPartAvailable. Group calls keep mySource[] for camera/audio and screen presentation sources, periodically validate them with TL_phone_checkGroupCall, and recreate the native group instance when the server reports missing or duplicate sources.
VoIPService owns service-side audio and notification routing. onCreate acquires a CPU wakelock, registers connectivity/headset/Bluetooth/telephony/screen receivers when not using Android Telecom, registers media-button handling, and sets the native audio buffer size. configureDeviceForCall switches AudioManager to communication mode for calls or normal/media mode for RTMP streams, requests audio focus, starts/stops Bluetooth SCO, applies speaker/earpiece state through VoipAudioManager, and registers the proximity wake lock. setAudioOutput, toggleSpeakerphoneOrShowRouteSheet, updateOutputGainControlState, and headset/Bluetooth callbacks keep the native echo-cancellation and output-gain settings aligned with the selected route. VoipAudioManager caches speakerphone state and posts AudioManager.setSpeakerphoneOn to the global queue because some Samsung devices block on the call.
Foreground notifications are created by VoIPService.showNotification for ongoing calls and showIncomingNotification for incoming calls. Notification actions are broadcast to VoIPActionsReceiver, which calls VoIPService.handleNotificationAction to answer, decline, or hang up. Incoming-call notification sound uses CallNotificationSoundProvider: Android opens a silent WAV URI only when notification policy permits sound, and openFile then starts ringtone/vibration inside VoIPService. Android Telecom integration lives in TelegramConnectionService; private calls pass call_type == 1 and delegate incoming/outgoing connection creation or failure back to VoIPService.getConnectionAndStartCall / callFailedFromConnectionService.
Private call UI is VoIPFragment. It attaches a VoIPWindowView, observes VoIPService.StateListener, initializes WebRTC renderers using VideoCapturerDevice.getEglBase, and wires buttons to service actions for accept/decline, speaker route sheet, mute, camera, PiP, and screen sharing. It uses service video sinks (setSinks, setLocalSink, setRemoteSink) to bind local/remote VideoSinks to TextureViewRenderer/VoIPTextureView, shows the encrypted-call emoji key from EncryptionKeyEmojifier, and reacts to onMediaStateUpdated, onCameraSwitch, signal bars, and service end notifications.
Group-call UI is centered on GroupCallActivity, a BottomSheet that observes VoIPService.StateListener and account/global NotificationCenter events. It starts scheduled or immediate group-call services, renders participants and video grids through GroupCallFullscreenAdapter, GroupCallTabletGridAdapter, and Components/voip render containers, edits participant mute/video/volume through VoIPService.editCallMember, and controls camera/screen sharing, RTMP PiP, recording prompts, join-as identity, and speaking/raised-hand state. JoinCallAlert fetches TL_phone_getGroupCallJoinAs, caches join-as peers briefly, and returns the chosen InputPeer to the caller; JoinCallByUrlAlert is the lightweight invite-link confirmation sheet. GroupCallPip and related GroupCallPip* components create an overlay button for ongoing group calls when the sheet is hidden, support hold-to-unmute through VoIPService.setMicMute, display speaking avatars, and remove themselves on didEndCall.
The Java/native boundary is split between the generic wrapper in NativeInstance and JNI implementation in TMessagesProj/…/org_telegram_messenger_voip_Instance.cpp. NativeInstance.make creates encrypted private-call instances and exposes state, signal bars, signaling data, remote media states, traffic stats, persistent state, mute, network type, audio output gain, and video setup. NativeInstance.makeGroup creates group-call instances and exposes callbacks for join payloads, participant media descriptions, group audio levels, broadcast-part requests, RTMP current time, incoming video outputs, and video quality changes. The JNI bridge maps Java Instance.Config, Endpoint, Proxy, and EncryptionKey into tgcalls descriptors, maps native state back to Java methods, and owns deletion in stopNative / stopGroupNative.
Video capture is bridged by VideoCapturerDevice and native Android tgcalls context files. NativeInstance.createVideoCapturer and setupOutgoingVideo* create native VideoCaptureInterfaces; native AndroidContext creates a Java VideoCapturerDevice, and VideoCameraCapturer.cpp calls its private init, onStateChanged, and nativeGetJavaVideoCapturerObserver methods. The Java capturer uses Camera2Enumerator or Camera1Enumerator for front/back cameras and ScreenCapturerAndroid for screen capture, feeds frames to the native observer, maintains a shared EGL context for renderers, reports first frames to VoIPService, and starts/stops Android playback-capture audio for screen sharing through org.webrtc.voiceengine.WebRtcAudioRecord when available.
Audio has two paths. Legacy tgvoip uses AudioRecordJNI and AudioTrackJNI, which allocate direct/native buffers, prefer 48 kHz with 44.1 kHz resampling via Resampler, and expose native callbacks from TMessagesProj/…/tg_voip_jni.cpp. WebRTC/tgcalls uses vendored org/webrtc/audio and org/webrtc/voiceengine classes; PeerConnectionFactory defaults to JavaAudioDeviceModule, WebRtcAudioTrack allows the service to switch usage/stream type for voice vs RTMP, and WebRtcAudioRecord supports microphone capture plus optional API 29+ playback capture for screen sharing. Most org/webrtc/** classes are thin Java holders for native pointers and rendering/capture helpers; they should be treated as API surface for the native WebRTC build rather than ordinary app logic.
Path-routing notes: changes under org/telegram/messenger/voip usually affect service lifetime, native setup, notifications, or audio/video routing; changes under org/…/VoIP*.java affect private call UX; changes under org/…/GroupCall*.java or Components/GroupCall*.java affect voice-chat/live-stream UX; changes under org/webrtc/** must be checked against matching JNI/native WebRTC expectations; changes under jni/voip/** can silently alter Java callback contracts; raw voip_* and voicechat_* resources are referenced by exact R.raw.* names in VoIPService.loadResources and group-call UI animations.
Coupling
- If a private-call state, error, media-state, endpoint, or config field changes in NativeInstance.java, update both TMessagesProj/…/org_telegram_messenger_voip_Instance.cpp and the service code that consumes it in VoIPService.java; the JNI bridge looks up Java field and method names/signatures directly and will fail at runtime rather than compile time.
- If group-call join payloads or SSRC/source semantics change, verify
VoIPService.createGroupInstance,startGroupCall,startScreenCapture,broadcastUnknownParticipants, and org_telegram_messenger_voip_Instance.cpp; Java stores camera and screen sources separately inmySource[]and native requests participant descriptions by SSRC. - If audio routing changes in VoIPService.java, verify VoipAudioManager.java, WebRtcAudioTrack.java, and
NativeInstance.setAudioOutputGainControlEnabled/setEchoCancellationStrength; route changes alter both AndroidAudioManagerstate and native echo/gain behavior. - If RTMP or broadcast stream handling changes, verify
VoIPService.configureDeviceForCall,NativeInstance.prepareForStream,VoIPService.createGroupInstancestream-part callbacks, andGroupCallActivity/GroupCallPipRTMP UI paths; RTMP intentionally uses media audio attributes and download-styleConnectionsManager.ConnectionTypeDownloadrequests. - If camera or screen capture setup changes, verify
VoIPService.createCaptureDevice, VideoCapturerDevice.java, TMessagesProj/…/AndroidContext.cpp, and VideoCameraCapturer.cpp; native owns Java capturer instances through global refs and calls private Java methods by name. - If incoming-call notification channels or sounds change, verify
VoIPService.showIncomingNotificationand CallNotificationSoundProvider.java; ringtone start is tied to Android opening the silent provider URI, not only to notification construction. - If Android permission flow changes, verify VoIPPermissionActivity.java,
VoIPFragmentaccept handling, andVoIPService.acceptIncomingCallFromNotification; incoming call answer can arrive from UI, notification, media button, or Telecom, and permission denial may decline the call. - If
org/webrtc/**classes are updated from upstream, verify native WebRTC/tgcalls build compatibility underTMessagesProj/jni/voip/**; many classes (VideoSink, renderers, capturer observers, audio modules) are referenced from native code by generated/manual JNI rather than ordinary Java imports.
Risks
- VoIPService.java combines private-call, group-call, notification, audio route, and native lifecycle state in one singleton. Starting a new call while
sharedInstanceis non-null returnsSTART_NOT_STICKY; missed cleanup inonDestroycan leave audio mode, Bluetooth SCO, video capturers, or foreground notifications stuck for the next call. - TMessagesProj/…/org_telegram_messenger_voip_Instance.cpp, NativeInstance.java, and VideoCapturerDevice.java rely on exact JNI method names/signatures such as
onEmitJoinPayload,onParticipantDescriptionsRequired,init, andonStateChanged. Refactoring Java method names or parameter types without synchronized JNI edits breaks call startup or media capture only at runtime. - VideoCapturerDevice.java keeps static
eglBase, static capture instances, and a static screen-capture permissionIntent. If screen sharing is started without validmediaProjectionPermissionResultData, or if destroy paths do not run through nativeAndroidContextcleanup, camera/screen capture and playback-capture audio can leak or fail on subsequent starts. - CallNotificationSoundProvider.java intentionally abuses a notification sound URI as a DND gate. Changing the URI, notification channel sound, or provider behavior in
VoIPService.showIncomingNotificationcan make incoming calls ring when DND should suppress them or fail to ring when allowed.