@softtynet/zca-js 2.3.4 → 2.3.6

package/dist/call-engine/ZaloRtcSession.d.ts

@@ -0,0 +1,609 @@
+import EventEmitter from "node:events";
+import { Buffer } from "node:buffer";
+import type { API } from "../apis.js";
+import { CallType, type RequestCallServerInfo } from "../apis/call/sendVoiceCall.js";
+import { type CallEvent } from "../models/CallEvent.js";
+import { type ParsedZRTPPacket, type ZRTPControlPacket } from "./ZRTPPacketCodec.js";
+import { ZaloSrtpSession, type ParsedRtpPacket, type SrtpCryptoSuite } from "./ZaloSrtpSession.js";
+export type ZaloRtcSessionState = "idle" | "allocating" | "handshaking_udp" | "ringing" | "active" | "ended" | "error";
+export type ZaloMobileDirectHandoffBundle = {
+    callId: number;
+    sessId: string;
+    isCaller: boolean;
+    partnerId: string;
+    fromUid32: number;
+    toUid32: number;
+    callType: CallType;
+    rtpHost: string;
+    rtpPort: number;
+    rtcpHost: string;
+    rtcpPort: number;
+    packetMode: 1 | 2;
+    routingToken: number;
+    codec: string;
+    srtpMasterKeyBase64?: string;
+    zrtpKey?: string;
+    /**
+     * Gói UDP `InitCall` (`0x01 0x7e`, `cmd=11` cho Caller hoặc `cmd=12` cho Callee) mã hoá sẵn dạng hex.
+     * Mobile gửi gói này đầu tiên tới `rtpHost:rtpPort` để đăng ký NAT trực tiếp với Relay Server
+     * và nhận phản hồi `0x02 0x7e` (chứa `routingToken` Int32LE tại byte `17..20`).
+     */
+    initCallPacketHex: string;
+    /**
+     * Gói UDP `RelayPing` (`0x01 0x7e`, `cmd=2`) kèm `sessId` mã hoá sẵn dạng hex (Mobile gửi mỗi 1000ms tới `rtpHost:rtpPort`).
+     */
+    relayPingPacketHex: string;
+    /**
+     * Gói UDP `Ping` (`0x01 0x7e`, `cmd=5`) giữ NAT mã hoá sẵn dạng hex (Mobile gửi mỗi 1000ms tới `rtpHost:rtpPort`).
+     */
+    pingPacketHex: string;
+    /**
+     * Gói UDP `RequestForward ManualControl` (`0x01 0x7e`, `cmd=32, subCmd=10`, 20-byte payload) báo FPS/PacketRate định kỳ mỗi 1000ms.
+     */
+    manualControlPacketHex: string;
+    /**
+     * Gói UDP `RequestForward OnCamera` (`0x01 0x7e`, `cmd=32, subCmd=7`) báo bật Camera.
+     */
+    cameraOnPacketHex: string;
+    /**
+     * Gói UDP `RequestForward OffCamera` (`0x01 0x7e`, `cmd=32, subCmd=8`) báo tắt Camera.
+     */
+    cameraOffPacketHex: string;
+    /**
+     * Gói UDP `RequestEndCall` (`0x01 0x7e`, `cmd=3`, 25 bytes) gửi 3 lần khi kết thúc cuộc gọi.
+     */
+    endCallPacketHex: string;
+    /**
+     * Tiền tố 5-byte (Relay mode `1`: `[type(1B)][routingToken(4B LE)]`) hoặc 9-byte (P2P mode `2`)
+     * để Mobile ghép trực tiếp vào trước mỗi gói RTP/RTCP khi gửi/nhận qua UDP.
+     */
+    audioRtpPrefixHex: string;
+    audioRtcpPrefixHex: string;
+    videoRtpPrefixHex: string;
+    videoRtcpPrefixHex: string;
+};
+export type ParsedIncomingCallInfo = {
+    callId: number;
+    callerId: string;
+    callerName: string;
+    callerAvatar: string;
+    fromUid32: number;
+    toUid32: number;
+    sessId: string;
+    callType: CallType;
+    isVideo: boolean;
+    isGroupCall: boolean;
+    groupId: string;
+    groupName: string;
+    groupAvatar: string;
+    hostCall: string;
+    partners: string[];
+    rtpAddress: string;
+    rtpHost: string;
+    rtpPort: number;
+    rtcpAddress: string;
+    rtcpHost: string;
+    rtcpPort: number;
+    codec: string;
+    srtpKey?: string;
+    srtpMode?: number;
+    zrtpKey?: string;
+    extendData: Record<string, unknown>;
+    rawEvent: CallEvent | Record<string, unknown>;
+};
+export type ZaloCallConnectionParams = {
+    callId: number;
+    sessId: string;
+    isCaller: boolean;
+    partnerId: string;
+    fromId: number;
+    toId: number;
+    callType: CallType;
+    rtpAddress: string;
+    rtpHost: string;
+    rtpPort: number;
+    rtcpAddress: string;
+    rtcpHost: string;
+    rtcpPort: number;
+    routingToken: number;
+    udpHandshakeVerified: boolean;
+    localUdpPort: number;
+    packetMode: 1 | 2;
+    codec: string;
+    extendData: Record<string, unknown>;
+    zrtpKey?: string;
+    srtpMasterKeyBase64?: string;
+    audioZrtcHeaderHex: string;
+    videoZrtcHeaderHex: string;
+    serverInfo?: RequestCallServerInfo;
+    mobileDirectHandoff: ZaloMobileDirectHandoffBundle;
+};
+export type ZaloRtcSessionOptions = {
+    /**
+     * Chế độ đóng gói gói tin Media UDP:
+     * - `1` (Mặc định cho Relay Server): 5-byte Relay header (`0x03` Audio RTP, `0x05` Audio RTCP, `0x0d` Video RTP, `0x0f` Video RTCP)
+     * - `2` (Dành riêng cho kết nối P2P trực tiếp): ZRTC Multiplexed 9-byte header (`0x7f 0x00 ...`)
+     */
+    packetMode?: 1 | 2;
+    /**
+     * Tự động gửi gói âm thanh Opus im lặng 20ms (khi không có audio ngoài) và báo cáo RTCP SR/RR định kỳ
+     * để duy trì luồng RTP/RTCP ổn định (tránh cảnh báo "Kết nối không ổn định" sau 3-4 giây). Mặc định `true`.
+     */
+    autoKeepaliveMedia?: boolean;
+    /**
+     * Chế độ chỉ xử lý Signaling trên Worker (`true` = KHÔNG mở socket UDP và KHÔNG gửi Ping/Media từ Worker,
+     * để ứng dụng Mobile tự kết nối UDP trực tiếp tới `rtpHost:rtpPort` bằng `mobileDirectHandoff`). Mặc định `false`.
+     */
+    signalingOnly?: boolean;
+    /**
+     * Bật mã hoá SRTP (RFC 3711 `AES_CM_128_HMAC_SHA1_80`) cho luồng RTP/RTCP.
+     */
+    enableSrtp?: boolean;
+    srtpSuite?: SrtpCryptoSuite;
+    srtpMasterKeyBase64?: string;
+    /**
+     * Thời gian chờ phản hồi UDP `0x02 0x7e` tối đa (mặc định `1500` ms).
+     * Nếu server UDP chưa phản hồi kịp hoặc chạy trong môi trường test giả lập HTTP,
+     * phiên sẽ tự động tiếp tục với `routingToken` dự phòng từ `callId`.
+     */
+    udpHandshakeTimeoutMs?: number;
+    /**
+     * Chu kỳ gửi gói tin UDP `Ping` (`cmd=2`, `cmd=5`, `cmd=32`) giữ kết nối NAT/Relay (mặc định `1000` ms).
+     */
+    pingIntervalMs?: number;
+    /**
+     * Tự động lắng nghe sự kiện `call_event` từ `api.listener` để cập nhật trạng thái cuộc gọi.
+     */
+    autoAttachListener?: boolean;
+    /**
+     * Cổng UDP nội bộ muốn bind (mặc định `0` để OS tự cấp phát).
+     */
+    localUdpPort?: number;
+    /**
+     * Thời gian chờ đổ chuông tối đa cho cuộc gọi đi trước khi tự động huỷ (`cancelVoiceCall`)
+     * để giải phóng tài nguyên UDP socket (mặc định `60000` ms = 60 giây, đặt `0` để tắt).
+     */
+    ringingTimeoutMs?: number;
+};
+export type StartOutgoingCallOptions = {
+    callType?: CallType;
+    callId?: number;
+    codec?: string;
+    skipUdpHandshake?: boolean;
+    /**
+     * Chỉ thực hiện Signaling HTTP/WebSocket trên Worker mà không mở UDP socket tại Worker,
+     * trả về `mobileDirectHandoff` để Mobile App tự kết nối UDP trực tiếp tới Relay Server.
+     */
+    signalingOnly?: boolean;
+    /**
+     * Bắt đầu cuộc gọi với Camera tắt (`offCameraAtStart`), nhưng vẫn khởi tạo sẵn kênh Video RTP/RTCP
+     * để có thể bật Camera / chuyển lên Video tức thì giữa cuộc gọi.
+     */
+    offCameraAtStart?: boolean;
+    /**
+     * Khởi tạo sẵn đường truyền Video RTP/RTCP (`extendData.callType = 1` + `OffCamera` ban đầu)
+     * ngay cả khi gọi Thoại (`CallType.Audio = 1`) để cho phép nâng cấp Thoại ➔ Video mượt mà giữa cuộc gọi
+     * trên ứng dụng Zalo Mobile (`zrtc::Peer::initialize` @ `0x100199de0`). Mặc định `true`.
+     */
+    allowVideoUpgrade?: boolean;
+};
+export type AcceptIncomingCallOptions = {
+    codec?: string;
+    skipUdpHandshake?: boolean;
+    signalingOnly?: boolean;
+    allowVideoUpgrade?: boolean;
+    offCameraAtStart?: boolean;
+    /**
+     * Nếu `true`, bỏ qua bước gọi lại `ringRingVoiceCall` (khi trước đó đã gọi `ringIncomingCall`).
+     */
+    skipRingRing?: boolean;
+    /**
+     * Nếu `true`, bỏ qua bước gửi tín hiệu HTTP `answerVoiceCall` / `answerGroupCall` (dùng khi đã gửi riêng hoặc khi giả lập local).
+     */
+    skipAnswerSignal?: boolean;
+};
+export type RejectIncomingCallOptions = {
+    status?: number;
+};
+export type StartGroupCallOptions = {
+    partners: string[];
+    callType?: CallType;
+    callId?: number;
+    codec?: string;
+    skipUdpHandshake?: boolean;
+    signalingOnly?: boolean;
+    offCameraAtStart?: boolean;
+};
+export type JoinGroupCallSessionOptions = {
+    hostCall: string;
+    groupId?: string;
+    partners?: string[];
+    callType?: CallType;
+    rtpAddress?: string;
+    rtcpAddress?: string;
+    session?: string;
+    skipUdpHandshake?: boolean;
+    signalingOnly?: boolean;
+};
+export type ZaloCallMediaStateEvent = {
+    isLocal: boolean;
+    isCameraOn?: boolean;
+    isMicMuted?: boolean;
+    isHold?: boolean;
+    isScreenSharing?: boolean;
+    callType?: CallType;
+    rawAct?: string;
+    reason?: number;
+};
+export type IncomingRtpEvent = {
+    isVideo: boolean;
+    isFec: boolean;
+    rtpPacket: Buffer;
+    parsedRtp: ParsedRtpPacket;
+    zrtpPacket: ParsedZRTPPacket;
+};
+export type IncomingAudioFrameEvent = {
+    payload: Buffer;
+    sequenceNumber: number;
+    timestamp: number;
+    ssrc: number;
+    payloadType: number;
+    marker: boolean;
+};
+export type IncomingVideoFrameEvent = {
+    payload: Buffer;
+    sequenceNumber: number;
+    timestamp: number;
+    ssrc: number;
+    payloadType: number;
+    marker: boolean;
+};
+export type IncomingVideoAnnexBFrameEvent = {
+    annexB: Buffer;
+    isKeyframe: boolean;
+    timestamp: number;
+    ssrc: number;
+    sps?: Buffer;
+    pps?: Buffer;
+    nalTypes?: number[];
+};
+export type IncomingRtcpEvent = {
+    isVideo: boolean;
+    rtcpPacket: Buffer;
+    zrtpPacket: ParsedZRTPPacket;
+};
+export interface ZaloRtcSessionEvents {
+    state: [state: ZaloRtcSessionState];
+    connection_params: [params: ZaloCallConnectionParams];
+    active: [params: ZaloCallConnectionParams];
+    incoming_call: [info: ParsedIncomingCallInfo];
+    media_state_change: [state: ZaloCallMediaStateEvent];
+    zrtp_control: [packet: ZRTPControlPacket];
+    zrtp_packet: [packet: ParsedZRTPPacket];
+    rtp_packet: [event: IncomingRtpEvent];
+    audio_frame: [frame: IncomingAudioFrameEvent];
+    video_frame: [frame: IncomingVideoFrameEvent];
+    video_annexb_frame: [frame: IncomingVideoAnnexBFrameEvent];
+    rtcp_packet: [event: IncomingRtcpEvent];
+    call_event: [event: CallEvent];
+    ended: [reason: string];
+    error: [error: unknown];
+}
+/**
+ * Giải mã chuẩn xác sự kiện cuộc gọi đến (`act: "request"` 1-1 hoặc `act: "group_request"` Nhóm)
+ * khớp 100% với `zrtc_call::ZMessageDeserializer::_parseActRequest` (`0x10001c824`),
+ * `_parseActRequestDetail` (`0x10001dfa0`), `_parseActRequestGroup` (`0x10001ffc4`) và
+ * `ZCallInfo::_prepareCallConfig` (`0x1000cd588`).
+ */
+export declare function parseIncomingCallEvent(callEvent: CallEvent | Record<string, unknown>, localUid?: string | number): ParsedIncomingCallInfo;
+/**
+ * Bộ máy xử lý phiên gọi Thoại & Video thuần TypeScript / Node.js (`node:dgram` UDP + `ZRTPPacket` + `SRTP`).
+ *
+ * Hoạt động độc lập 100% trên Worker, Linux Server, Docker, hoặc Desktop mà **không cần cài đặt Zalo PC**:
+ * - Thực hiện trọn vẹn luồng Signaling 401 -> Bắt tay UDP `0x01 0x7e` (`cmd=11/12`) -> Nhận `routingToken` -> Signaling 416 / 402 -> Duy trì UDP Ping (`cmd=2/5/32`) & RTCP SR/RR.
+ * - Hỗ trợ chế độ **Direct Mobile Media Handoff** (`signalingOnly: true` / `handoffUdpToExternal()`): Worker chỉ tạo/nhận cuộc gọi qua HTTPS/WebSocket rồi trả gói `mobileDirectHandoff` cho Mobile App tự kết nối UDP trực tiếp tới máy chủ Relay của Zalo mà không cần đi qua trung gian.
+ * - Hỗ trợ đầy đủ cả **Chiều gọi đi (Outgoing)** lẫn **Chiều gọi đến (Incoming 1-1 & Nhóm)**: giải mã chuẩn `act: "request"` / `"group_request"`, báo đổ chuông (`ringIncomingCall`), bắt máy (`acceptIncomingCall` / `acceptIncomingGroupCall`), và từ chối (`rejectIncomingCall`).
+ */
+export declare class ZaloRtcSession extends EventEmitter<ZaloRtcSessionEvents> {
+    private readonly api;
+    private state;
+    private udpSocket;
+    private pingTimer;
+    private groupPingTimer;
+    private audioKeepaliveTimer;
+    private videoKeepaliveTimer;
+    private rtcpTimer;
+    private ringingTimeoutTimer;
+    private startedAtMs;
+    private activeStartedAtMs;
+    private callId;
+    private sessId;
+    private isCaller;
+    private partnerId;
+    private groupId;
+    private groupPartners;
+    private fromUid32;
+    private toUid32;
+    private callType;
+    private isCameraOn;
+    private isMicMuted;
+    private isHold;
+    private isScreenSharing;
+    private rtpEndpoint;
+    private rtcpEndpoint;
+    private routingToken;
+    private udpHandshakeVerified;
+    private hasReceivedPartnerMedia;
+    private hasSentAnswerAck;
+    private localUdpPort;
+    private zrtpKey?;
+    private codec;
+    private extendData;
+    private serverInfo?;
+    private controlSeq;
+    private forwardPingSeq;
+    private manualControlSeq;
+    private audioSeq;
+    private audioTimestamp;
+    private readonly audioSsrc;
+    private audioPacketCount;
+    private audioOctetCount;
+    private lastExternalAudioSentAtMs;
+    private videoSeq;
+    private videoTimestamp;
+    private readonly videoSsrc;
+    private videoPacketCount;
+    private videoOctetCount;
+    private lastExternalVideoSentAtMs;
+    private remoteAudioSsrc;
+    private remoteAudioMaxSeq;
+    private remoteAudioSeqCycles;
+    private lastRemoteAudioSrMiddleNtp;
+    private lastRemoteAudioSrReceivedAtMs;
+    private remoteVideoSsrc;
+    private remoteVideoMaxSeq;
+    private remoteVideoSeqCycles;
+    private lastRemoteVideoSrMiddleNtp;
+    private lastRemoteVideoSrReceivedAtMs;
+    private localSpsNal;
+    private localPpsNal;
+    private remoteSpsNal;
+    private remotePpsNal;
+    private fuaFragments;
+    private currentAccessUnitNals;
+    private currentAccessUnitTs;
+    private currentAccessUnitHasIdr;
+    private srtpSession;
+    private readonly options;
+    private boundCallEventListener?;
+    constructor(api: API, options?: ZaloRtcSessionOptions);
+    getState(): ZaloRtcSessionState;
+    getSrtpSession(): ZaloSrtpSession | null;
+    getCallDurationSeconds(): number;
+    getMediaState(): {
+        callId: number;
+        callType: CallType;
+        isCameraOn: boolean;
+        isMicMuted: boolean;
+        isHold: boolean;
+        isScreenSharing: boolean;
+        durationSeconds: number;
+        groupId: string;
+        groupPartners: string[];
+    };
+    private getLocalAudioSsrc;
+    private getLocalVideoSsrc;
+    /**
+     * Tạo bộ thông số + các gói tin nhị phân `ZRTPPacket` đã đóng gói sẵn dạng hex
+     * để ứng dụng Mobile có thể mở socket UDP kết nối **trực tiếp** tới máy chủ Relay của Zalo (`rtpHost:rtpPort`)
+     * mà không cần đẩy luồng dữ liệu âm thanh/hình ảnh qua Worker trung gian.
+     */
+    getMobileDirectHandoffBundle(routingTokenOverride?: number): ZaloMobileDirectHandoffBundle;
+    /**
+     * Đặt lại toàn bộ trạng thái định tuyến UDP, bộ đếm RTP/RTCP, bộ đệm giải mã H.264 FU-A/SPS/PPS
+     * và khóa SRTP trước khi bắt đầu hoặc chấp nhận một cuộc gọi mới trên cùng một instance `ZaloRtcSession`.
+     */
+    private resetSessionStateForNewCall;
+    private clearIncomingVideoAssemblyBuffers;
+    /**
+     * Tái kích hoạt (Re-activate / Re-bind) kết nối UDP và luồng Media/RTCP cho phiên gọi hiện tại:
+     * - Dùng khi chuyển vùng mạng (Wi-Fi <-> 4G/5G), khi socket UDP bị gián đoạn, hoặc khi muốn thu hồi lại
+     *   quyền xử lý UDP từ Mobile về lại Worker/Desktop sau khi đã gọi `signalingOnly` / `handoffUdpToExternal()`.
+     * - Tự động mở cổng UDP mới, gửi lại gói bắt tay `0x01 0x7e` (`cmd=11` Caller hoặc `cmd=12` Callee),
+     *   khởi động lại vòng lặp UDP Ping + Media Keepalive + RTCP SR/RR, đồng bộ lại trạng thái Mic/Camera
+     *   và bắn `RTCP PLI` để khôi phục hình ảnh H.264 ngay lập tức.
+     */
+    reconnectUdp(options?: {
+        skipUdpHandshake?: boolean;
+    }): Promise<ZaloCallConnectionParams>;
+    /**
+     * Ngắt toàn bộ socket UDP và các vòng lặp Ping/Media cục bộ trên Worker
+     * (nhưng vẫn giữ nguyên kết nối Signaling WebSocket để lắng nghe `answer`, `end`, `cancel`, `audio_to_video`),
+     * nhằm bàn giao hoàn toàn kênh UDP cho ứng dụng Mobile kết nối trực tiếp tới máy chủ Relay Zalo
+     * mà không bị xung đột NAT (NAT flip-flopping).
+     */
+    handoffUdpToExternal(routingTokenOverride?: number): ZaloMobileDirectHandoffBundle;
+    /**
+     * Xuất toàn bộ thông số kết nối cuộc gọi & UDP `ZRTPPacket` sau khi thương lượng xong
+     * để truyền về Mobile App hoặc Media Bridge.
+     */
+    getConnectionParams(): ZaloCallConnectionParams;
+    /**
+     * Khởi tạo cuộc gọi đi (Caller) 1-1 hoàn chỉnh:
+     * 1. Gọi `/api/voicecall/requestcall` (401) lấy `sessId`, `rtpaddr`, `rtcpaddr`, `zrtpKey`
+     * 2. Mở socket UDP và gửi gói bắt tay `0x01 0x7e` (`cmd=11`) tới `rtpaddr` để nhận `routingToken` (bỏ qua nếu `signalingOnly: true`)
+     * 3. Gọi `/api/voicecall/request` (416) kèm codec Opus chuẩn và `extendData` để máy đối phương đổ chuông
+     * 4. Duy trì nhịp tim UDP Ping (`0x01 0x7e`, `cmd=2/5/32`) và sẵn sàng truyền/nhận RTP/SRTP (nếu không bật `signalingOnly`)
+     */
+    startOutgoingCall(calleeId: string, options?: StartOutgoingCallOptions): Promise<ZaloCallConnectionParams>;
+    /**
+     * Giải mã sự kiện cuộc gọi đến (`act: "request"` hoặc `"group_request"`) và gửi ngay tín hiệu
+     * báo máy đang đổ chuông (`ringRingVoiceCall` `11302` / `ringRingGroupCall` `12439`) tới phía người gọi,
+     * đồng thời chuyển phiên sang trạng thái `"ringing"` trong khi chờ người dùng bấm Nghe máy hoặc Từ chối.
+     * Khớp với `zrtc_call::ZCallInfo::receiveIncomingCall` (`0x1000ccbbc`).
+     */
+    ringIncomingCall(callEvent: CallEvent | Record<string, unknown>): Promise<ParsedIncomingCallInfo>;
+    /**
+     * Chấp nhận cuộc gọi đến (Callee) từ sự kiện `call_event` (`act: "request"` hoặc `"group_request"`):
+     * - Tự động giải mã chuẩn xác `params.id` (`callId`), `uidN` (`callerId`), `uidFrom` (`toUid32`), `uidTo` (`fromUid32`), `rtpIP`/`rtcpIP`/`servers`
+     * - Nếu là cuộc gọi Nhóm (`isGroupCall`), tự động uỷ quyền sang `acceptIncomingGroupCall`
+     * - Với cuộc gọi 1-1:
+     *   1. Gửi `/api/voicecall/ringring` (407) (nếu chưa gửi)
+     *   2. Nếu sự kiện thiếu địa chỉ Relay UDP, tự động gọi dự phòng `requestVoiceCall` (401) như `_trySendAcceptSignal` (`0x1000c2c9c`)
+     *   3. Mở socket UDP và gửi gói bắt tay `0x01 0x7e` (`cmd=12`) tới `rtpaddr` (bỏ qua nếu `signalingOnly: true`)
+     *   4. Gửi `/api/voicecall/answer` (402) để kết nối âm thanh/hình ảnh 2 chiều
+     */
+    acceptIncomingCall(callEvent: CallEvent | Record<string, unknown>, options?: AcceptIncomingCallOptions): Promise<ZaloCallConnectionParams>;
+    /**
+     * Từ chối cuộc gọi đến (1-1 hoặc Nhóm) từ sự kiện `call_event` (`act: "request"` / `"group_request"`):
+     * - Với 1-1: gọi `/api/voicecall/cancel` (`11305`) và `/api/voicecall/endcall` (`11306`)
+     * - Với Nhóm: gọi `/api/voicecall/group/cancel` (`12437`) và `/api/voicecall/group/endcall` (`12438`)
+     */
+    rejectIncomingCall(callEvent: CallEvent | Record<string, unknown>, options?: RejectIncomingCallOptions): Promise<void>;
+    /**
+     * Chấp nhận lời mời gọi Nhóm đến từ sự kiện `call_event` (`act: "group_request"`):
+     * 1. Gửi `/api/voicecall/group/ringring` (`12439`, signal `506`)
+     * 2. Mở socket UDP và bắt tay `InitCallCallee` (`0x01 0x7e`, `cmd=12`) (bỏ qua nếu `signalingOnly: true`)
+     * 3. Gửi `/api/voicecall/group/answer` (`12436`, signal `503`)
+     */
+    acceptIncomingGroupCall(callEvent: CallEvent | Record<string, unknown>, options?: AcceptIncomingCallOptions): Promise<ZaloCallConnectionParams>;
+    /**
+     * Khởi tạo cuộc gọi nhóm (Group Audio `CallType.GroupAudio = 5` hoặc Group Video `CallType.GroupVideo = 6`):
+     * 1. Gọi `/api/voicecall/group/requestcall` (501) xin cấp phát máy chủ Relay UDP
+     * 2. Mở socket UDP và bắt tay `0x01 0x7e` (`cmd=11`) (bỏ qua nếu `signalingOnly: true`)
+     * 3. Gọi `/api/voicecall/group/request` (513) mời danh sách `partners` tham gia
+     * 4. Duy trì nhịp tim UDP + `/api/voicecall/group/ping` (509) và luồng RTP/RTCP
+     */
+    startGroupCall(groupId: string, options: StartGroupCallOptions): Promise<ZaloCallConnectionParams>;
+    /**
+     * Tham gia cuộc gọi nhóm đang diễn ra (`/api/voicecall/group/join`, command `12043`).
+     */
+    joinActiveGroupCall(callId: number, options: JoinGroupCallSessionOptions): Promise<ZaloCallConnectionParams>;
+    /**
+     * Mời thêm thành viên vào cuộc gọi nhóm đang diễn ra (`/api/voicecall/group/adduser`, command `12435`).
+     */
+    addMembersToGroupCall(partners: string[]): Promise<Record<string, unknown>>;
+    /**
+     * Bật / tắt Camera trong cuộc gọi Video (đồng bộ cả gói UDP `cmd=32, subCmd=7/8` và HTTP `/api/voicecall/conf` hoặc `/api/voicecall/group/broadcast`).
+     */
+    setCameraEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Bật / tắt Microphone trong cuộc gọi (đồng bộ cả gói UDP `cmd=32, subCmd=5/6` và HTTP `/api/voicecall/conf` hoặc `/api/voicecall/group/broadcast`).
+     */
+    setMicMuted(muted: boolean): Promise<void>;
+    /**
+     * Tạm giữ (`hold`) hoặc tiếp tục (`unhold`) cuộc gọi 1-1 (`/api/voicecall/holdreq` & `/api/voicecall/unholdreq`).
+     */
+    setHoldState(isHold: boolean, isResponse?: boolean): Promise<void>;
+    /**
+     * Bật / tắt chia sẻ màn hình trong cuộc gọi 1-1 (`/api/voicecall/requestsharescreen`, command `12064`)
+     * hoặc cuộc gọi Nhóm (`/api/voicecall/group/sharescreen`, command `12044`).
+     */
+    setScreenShareEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Chuyển đổi cuộc gọi Thoại (Audio) đang diễn ra lên cuộc gọi Video (`/api/voicecall/requestaudio2video`, command `12056`):
+     * - `status = 1`: Gửi yêu cầu bật Video
+     * - `status = 2`: Đồng ý yêu cầu bật Video từ đối phương
+     * Tự động kích hoạt luồng Video RTP/RTCP, tín hiệu UDP `OnCamera` (`cmd=32, subCmd=7`) & HTTP `/api/voicecall/conf` (`isOnCam=1, isOnMic=-1`) ngay lập tức.
+     */
+    upgradeAudioToVideoCall(status?: 1 | 2): Promise<void>;
+    /**
+     * Gửi trực tiếp một khung âm thanh Opus (mặc định 20ms @ 16kHz = 320 samples)
+     * qua đường truyền UDP của cuộc gọi.
+     * Tự động đóng gói RTP 12-byte header -> (Tuỳ chọn) Mã hoá SRTP -> Bọc `ZRTPPacket` header.
+     */
+    sendAudioFrame(opusPayload: Buffer, options?: {
+        payloadType?: number;
+        samples?: number;
+        marker?: boolean;
+        sequenceNumber?: number;
+        timestamp?: number;
+        ssrc?: number;
+        isKeepalive?: boolean;
+    }): Promise<void>;
+    /**
+     * Gửi một gói tin chuẩn WebRTC RTP (Audio) qua đường truyền UDP Zalo.
+     */
+    sendAudioRtp(rtpPacket: Buffer): Promise<void>;
+    /**
+     * Gửi trực tiếp một khung hình ảnh H.264 NAL / RTP payload (mặc định 90kHz clock, payloadType=97)
+     * qua đường truyền UDP của cuộc gọi Video.
+     */
+    sendVideoFrame(h264Payload: Buffer, options?: {
+        payloadType?: number;
+        timestampStep?: number;
+        marker?: boolean;
+        sequenceNumber?: number;
+        timestamp?: number;
+        ssrc?: number;
+        isKeepalive?: boolean;
+    }): Promise<void>;
+    /**
+     * Đóng gói một khung hình H.264 dạng Annex-B (`00 00 00 01 <NAL>`) theo chuẩn RFC 6184:
+     * - Tự động tách các NAL unit, lưu cache SPS (`type=7`) / PPS (`type=8`) và đóng gói STAP-A (`0x78`) trước IDR (`type=5`)
+     * - Không cho phép khung keepalive 16x16 ghi đè `localSpsNal` / `localPpsNal` của camera thực
+     * - Tự động phân mảnh các NAL lớn (> 1150 bytes) thành các gói RTP **FU-A (`type=28`)** cùng `timestamp` 90kHz
+     * - Đặt cờ `marker = true` ở gói RTP cuối cùng của khung hình để bộ giải mã đối phương hiển thị ngay.
+     */
+    sendH264AnnexBFrame(annexB: Buffer, options?: {
+        payloadType?: number;
+        timestampStep?: number;
+        timestamp?: number;
+        ssrc?: number;
+        isKeepalive?: boolean;
+    }): Promise<void>;
+    /**
+     * Gửi tín hiệu bật/tắt Camera (`cmd = 32, subCmd = 7` `OnCamera` / `subCmd = 8` `OffCamera`)
+     * khớp với `CallController::vidSendSignalOffCamera` (`0x10016fbe4`).
+     * Phát lặp 3 lần (0ms, 60ms, 150ms) để chống mất gói UDP.
+     */
+    sendCameraState(isCameraOn: boolean, reason?: number): Promise<void>;
+    /**
+     * Gửi tín hiệu bật/tắt Microphone (`cmd = 32, subCmd = 5` `OnMic` / `subCmd = 6` `OffMic`)
+     * qua máy chủ Relay UDP.
+     */
+    sendMicState(isMicOn: boolean): Promise<void>;
+    /**
+     * Gửi gói RTCP PLI (Picture Loss Indication — `PT=206, FMT=1`) yêu cầu máy đối phương
+     * gửi ngay khung hình khoá H.264 IDR kèm SPS/PPS.
+     */
+    sendRtcpPli(): Promise<void>;
+    /**
+     * Gửi một gói tin chuẩn WebRTC RTP (Video H.264) qua đường truyền UDP Zalo.
+     */
+    sendVideoRtp(rtpPacket: Buffer): Promise<void>;
+    /**
+     * Gửi gói tin điều khiển chất lượng RTCP (Audio hoặc Video) qua đường truyền UDP Zalo.
+     */
+    sendRtcp(rtcpPacket: Buffer, isVideo?: boolean): Promise<void>;
+    /**
+     * Kết thúc cuộc gọi hiện tại:
+     * 1. Gửi gói UDP `RequestEndCall` (`0x01 0x7e`, `cmd=3`, 25 bytes) 3 lần tới máy chủ Relay (`_sendRequestZRTPEndCall` @ `0x10016a880`)
+     * 2. Giải phóng toàn bộ tài nguyên UDP socket & bộ định thời
+     * 3. Gửi tín hiệu HTTP `/api/voicecall/cancel` (`11305`) và `/api/voicecall/endcall` (`11306`) hoặc `/api/voicecall/group/end` (`12046`)
+     *    cho mọi thao tác ngắt máy từ phía local (`local_end`, `user_hangup`, `new_call`, ...).
+     */
+    endCall(reason?: string): Promise<void>;
+    /**
+     * Xử lý sự kiện `call_event` từ WebSocket (hoặc truyền thủ công).
+     */
+    handleCallEvent(event: CallEvent): Promise<void>;
+    private setState;
+    private applyServerInfo;
+    private ensureUdpSocket;
+    private performUdpInitHandshake;
+    private startUdpPingLoop;
+    private startGroupPingLoop;
+    private startMediaKeepaliveLoop;
+    private stopMediaKeepaliveLoop;
+    private buildCompoundRtcpReport;
+    private markCallActiveFromPartnerTraffic;
+    private handleIncomingUdpPacket;
+    private handleIncomingVideoRtpPayload;
+    private recordIncomingNal;
+    private flushIncomingAccessUnit;
+    private attachCallEventListener;
+    private detachCallEventListener;
+    private cleanupResources;
+    private sendRawUdp;
+}