mirror of
https://github.com/TelegramMessenger/tgcalls.git
synced 2026-11-18 21:35:28 +00:00
Two defects shared by every InstanceV2ReferenceImpl build, found in the
2026-10-11 Android log sample (getlogstgcalls/analysis/FINDINGS-android.md).
- Every call took two offer/answer rounds: both sides pre-create their audio
transceiver with AddTransceiver, which FindAvailableTransceiverToReceive never
associates with the caller's m=0, so the callee answered recvonly and
re-offered its audio as a new m-section. network_reference_use_addtrack is
now default on and covers the camera (addSendTransceiver): 2
SetLocalDescription per call instead of 4, the callee's answer sendrecv, no
glare window on every call. SetCodecPreferences is skipped on a transceiver
AddTrack reused (it already has a mid; the peer negotiated its codec list).
- A rejected answer ("order of m-lines", the offer was replaced in flight) left
the caller without a DTLS role, and it then answered the callee's colliding
offer as a second DTLS client: handshake failure on a connected ICE path,
every later SDP "Failed to set SSL role", no recovery (43 of 200 Android
calls). sendLocalDescription() remembers that the peer answered setup:active
and, when answering an offer in that state, sets passive on the created
answer's transport descriptions and applies it from the CreateAnswer
callback on the signaling thread, so nothing can land in between.
tools/cli: --video-late-caller-ms / --video-late-callee-ms attach one side's
camera N ms after start; network_reference_immediate_capture_renegotiation
(read only under TGCALLS_ALLOW_TEST_KNOBS, a CLI-only define) restores the
pre-2026-09-17 immediate offer so run-negotiation-tests.sh reproduces the
Android chain in-process. All four scenarios failed before and pass after;
mixed old/new pairings, mid-call cameras, mtproto and 30% signaling loss
checked.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
11 KiB
11 KiB
tgcalls CLI Test Tool
In-process test harness for tgcalls. See the root CLAUDE.md for build instructions, top-level CLI usage, and the CLI options reference.
Supported Versions
| Version | Implementation | Notes |
|---|---|---|
14.0.0 |
InstanceV2CompatImpl |
WebRTC PeerConnection speaking V2Impl's channel protocol; interoperates with 7.0.0–13.0.0 and itself (rewritten 2026-10-11, see submodules/TgVoipWebrtc/CLAUDE.md) |
13.0.0 (default) |
InstanceV2Impl |
Also: 7.0.0, 8.0.0, 9.0.0, 12.0.0 |
11.0.0 |
InstanceV2ReferenceImpl |
Also: 10.0.0. Uses WebRTC PeerConnection |
5.0.0 |
InstanceImpl (v1) |
Also: 2.7.7. Legacy |
Architecture (P2P/Reflector)
- Two
tgcalls::Instanceobjects (caller + callee) created viaMeta::Create(version, ...) - Signaling bridged via
SignalingBridgewith configurable drop rate and delay - Group participant logs (
/tmp/tgcalls_group_p<id>_<pid>.log) are written at stop and unlinked after validation; setTGCALLS_CLI_KEEP_LOGS=1to keep them (added 2026-09-17). --videoin p2p/reflector mode attaches atgcalls::VideoCaptureInterface::Create(threads, ...)to BOTH descriptors (descriptor.videoCapture, the iOS join-time path: camera already on when the call is created). Added 2026-09-17 to reproduce the 18/19 start-glare renegotiation loop; a healthy video call shows 2Calling SetLocalDescriptionin the--log-filefor 11.0.0 (one per side since the 2026-10-12 one-round negotiation; 4 for 18/19), noSetLocalDescription failed, oneCreating data channel. Combine with--delay 100-300for field-like signaling latency.--video-late-caller-ms N/--video-late-callee-ms Nattach that side's capture N ms after the instances are created (the other side gets none unless it has its own value): the Android app's shape, where the camera reaches the engine while the first offer is in flight.run-negotiation-tests.sh(2026-10-12) uses them withnetwork_reference_immediate_capture_renegotiationto reproduce the late-camera DTLS failure and pins the one-round negotiation (see the tgcallsCLAUDE.md).--video-lateattaches the same captures mid-call viasetVideoCapture(callee at 3 s, caller at 5 s). With either flag both instances get aFakeVideoSink(setIncomingVideoOutput) and the summary prints the decoded frames each side received;remoteMediaStateUpdatedis counted per side. Both are informational, not pass criteria.FakeAudioDeviceModulewithSineRecorder(440Hz tone) andNoOpRenderer(audio discarded; validation via BWE)FakeInterfaceplatform implementation (pure C++, no iOS/ObjC deps)- Stats log validation: both caller and callee write
config.statsLogPathwith bitrate records; non-empty log with at least one non-zero BWE value is a success condition - On failure, full tgcalls internal logs (caller + callee) are dumped to stdout via
config.logPath
Architecture (Group)
- N participants using
GroupInstanceCustomImpland/orGroupInstanceReferenceImplconnect to an in-process Go SFU - SFU uses Pion's low-level APIs (pion/ice, pion/dtls, pion/srtp, pion/sctp) — NOT PeerConnection
- ICE: lite mode, loopback-only, UDP host candidates on 127.0.0.1. SFU uses
Dial(controlling) for CustomImpl clients andAccept(controlled) for PeerConnection clients - DTLS: SFU acts as DTLS client (setup=active); GroupNetworkManager hardcodes SSL_SERVER for the tgcalls client
- SRTP: AES-256-GCM (negotiated via DTLS-SRTP; GroupNetworkManager requires GCM suites)
- SCTP: over DTLS, accepts data channel from client, reads Colibri messages, sends
ActiveVideoSsrcsnotifications - RTP forwarding: audio RTP forwarded to all others unconditionally; video RTP forwarded only to receivers that have requested video from that sender (via
ReceiverVideoConstraints) - SSRC tracking: SFU maintains
ssrcRegistry map[uint32]ssrcInfowith kind (audio/video/video-rtx) and simulcast layer index, exposed viaGoSfu_QuerySsrcandGoSfu_QueryVideoSsrcsCGo exports - SSRC discovery: video SSRCs are broadcast via
ActiveVideoSsrcs(the test app'sdataChannelMessageReceivedcallback consumes them and callssetRequestedVideoChannels). Audio SSRCs are discovered byGroupInstanceReferenceImplfrom the RTP packets WebRTC's demuxer drops (OnUnDemuxableRtpPacketseam; mid=0 is sendonly and payload-type demuxing is off, so an SSRC without its own m-line is always dropped) — same shape CustomImpl uses (receiveUnknownSsrcPacket→_requestMediaChannelDescriptions). The legacyActiveAudioSsrcsdata-channel message has been removed. - Video SSRC groups: parsed from join payload
"ssrc-groups"field (SIM + FID semantics), stored per participant - Colibri video constraints: SFU parses
ReceiverVideoConstraintsfrom receivers, sendsSenderVideoConstraintsback to senders withidealHeight, and sends proactive PLI to trigger keyframes when a receiver first requests video - RTCP feedback: SFU demuxes SRTCP from the shared ICE transport (RFC 5761: byte[1] >= 200 && < 224), decrypts with per-participant SRTCP contexts, parses PLI/FIR, and forwards as new PLI to the sender. NACK is terminated (not forwarded).
- Audio validation:
audioLevelsUpdatedcallback tracks remote audio levels; success requires every participant to receive audio from at least one other participant (remote SSRC != 0, level > 0.05). The 440Hz sine tone arrives at ~0.126 level after SFU forwarding. - Video validation:
FakeVideoSink(implementsrtc::VideoSinkInterface<VideoFrame>) counts decoded frames per remote endpoint; success requires every participant to receive ≥1 frame from every other - Video signaling flow: SFU broadcasts
ActiveVideoSsrcsover data channel →dataChannelMessageReceivedcallback fires in the app → app callssetRequestedVideoChannels→ CustomImpl createsIncomingVideoChannel/ ReferenceImpl adds recvonly video transceiver → both sendReceiverVideoConstraints→ SFU sendsSenderVideoConstraints+ proactive PLI → sender produces keyframe → receiver decodes.requestVideoFromEndpoints()(group_participant.cpp) is the single request path: it accumulates the FULL requested set inParticipantState::requestedVideoChannelsand resends all of it on every call, because both engines treat the list as the complete set and drop endpoints missing from it. With--early-video-requestthe same helper runs right afteremitJoinPayloadfor every already-joined participant (SSRCs viaGoSfu_QueryVideoSsrcs), reproducing the real app's order — request before join response, before the data channel — which theActiveVideoSsrcs-driven path never exercises (the broadcast fires 500 ms after the data channel is up) dataChannelMessageReceivedcallback: added toGroupInstanceDescriptor, forwards all incoming Colibri data channel messages to the application. Used by the CLI test tool to react toActiveVideoSsrcsand dynamically set up video channels — mirrors the real Telegram app's reactive flowFakeAudioDeviceModulewithSineRecorder(440Hz tone) andNoOpRenderer— same as P2P modeFakeInterface(tgcalls/platform/fake/FakeInterface.cpp) wraps the builtin video encoder/decoder factories soGetSupportedFormats()comes back in the iOS platform order — two H264 entries (packetization-mode 1, the constrained-baseline one kept), VP8, VP9 profile 0. PeerConnection assigns dynamic payload types by walking that list (96, 98, 100, ... with RTX at +1), so the ORDER decides which codec sits on which number; the raw builtin host order lists five H264 profiles and lands one on PT 104 by coincidence, which is exactly the number the group-call convention uses for H264 and hid a ReferenceImpl bug for the device (where PT 104 was H265).--builtin-codec-orderrestores the raw order for comparisonchurnVideoSinks()(group_participant.cpp,--video-sink-churn) replaces every participant's incoming sinks viaaddIncomingVideoOutputand releases the old ones, mirroring the app recreating tile views on quality changes; the engine must only ever hold weak references (a raw sink pointer left on the track crashes on the next frame)dropAllVideoRequests()/rerequestAllVideo()(group_participant.cpp,--video-rerequest): after frames flow, every participant's SFU egress gets a 150 ms delay (GoSfu_SetNetworkParams), then five rounds ofsetRequestedVideoChannels({})followed a second later by the full accumulated set again, sinks kept throughout. Validation requires every sink's frame count to grow past the value recorded at the last drop ("Video after re-request: N/M stalled", must be 0). The delay is load-bearing: on the in-process SFU the streams stop before the renegotiation lands, whereas on a real network the packets forwarded before the SFU read the emptyReceiverVideoConstraintsare still arriving while the receive streams are torn down; that in-flight packet is what used to create a default receive stream on the abandoned transceiver's channel and freeze the tile on re-request. The window is sub-millisecond at the harness's packet rates, so the reproduction needs--reference-participants 6(both unfixed runs failed 1/30; three participants passed by luck).FakeVideoTrackSourcegenerates 1280x720 I420 frames at 30fps with per-participant color tint and frame counter (720p needed for 3 simulcast layers; 640x360 only allows 2 per WebRTC'skSimulcastFormats)- Two ways a participant feeds outgoing video (
VideoFeedin group_participant.h):Source—descriptor.getVideoSourcereturning theFakeVideoTrackSourceabove (the CLI's original shortcut, no app uses it);CaptureAtJoin/CaptureLate(--video-via-capture/--video-via-capture-late) — a realtgcalls::VideoCaptureInterface::Create(threads, "<id>"), handed over asdescriptor.videoCaptureor viasetVideoCapture()after the join response, exactly as the iOS wrapper does. For that to produce frames on the host, the fake platform implementsmakeVideoSource(aFakePlatformVideoSource: plain adapted source, pushed into) andmakeVideoCapturer(FakeVideoCapturer: 1280x720 @ 30 fps, tint fromdeviceId, a sweeping bar for motion, also feeds the uncropped preview sink) intgcalls/platform/fake/FakeVideoCapturer.{h,cpp}. Both used to return nullptr, which is whysetVideoCapturecould be a no-op in the reference engine without any test noticing. --request-own-video:requestVideoFromEndpoints()appends the participant's own endpoint to every request (the SFU'sActiveVideoSsrcsnever names the receiver, but the app's roster includes the local participant and is handed to the engine unfiltered) and registers a sink for it. Validation readsGoSfu_QueryRequestedLayer(receiver, receiver)before the SFU is destroyed (ParticipantState::sfuSelfRequestedLayer) — any value ≥ 0 means the engine let a self-request through — and, for Capture* feeds, requires the own-endpoint sink to have received preview frames (videoViaCaptureoutlives the releasedvideoCapture). The own-endpoint sink is never counted as a received pair.- Group mode source:
submodules/TgVoipWebrtc/tgcalls/tools/cli/group_mode.cpp