@kaltura-sdk/rtc-core 1.25.0

package/src/lib/peer-connection/PeerConnection.d.ts

@@ -0,0 +1,153 @@
+import PeerConnectionBeacon from './PeerConnectionBeacon';
+import IceHandler from './IceHandler';
+import PeerConnectionWebrtcStats, { PcStatsObj } from './PeerConnectionWebrtcStats';
+import { StreamStatus, PeerConnectionConfig, ConnectionFailureInfo, IceConfiguration, IceCandidateDataObj, VideoSenderConfig } from './types';
+export interface webrtcStreamStatsObj {
+    videoBytes: number;
+    audioInBytes: number;
+    audioOutBytes: number;
+}
+type OnPcConnectionFail = (failureInfo: ConnectionFailureInfo) => void;
+type OnPcCreated = () => void;
+type OnPcConnected = () => void;
+type OnPcConnectedFinal = () => void;
+type OnHandlePcTrackEvent = (streams: ReadonlyArray<MediaStream>) => void;
+type OnStartPublishing = (localDescription: RTCSessionDescription | null) => void;
+type OnIceCandidate = (candidate: IceCandidateDataObj | null) => void;
+declare class PeerConnection {
+    peerConnection: RTCPeerConnection | null;
+    pcWebrtcStats: PeerConnectionWebrtcStats;
+    prevStatsInfo: webrtcStreamStatsObj | null;
+    pcBeacon: PeerConnectionBeacon;
+    iceHandler: IceHandler;
+    private logger;
+    private streamerId;
+    isPublisher: boolean;
+    isDesktop: boolean;
+    private isAudioMix;
+    private connectionStartTimer;
+    private connectDisconnectTimer;
+    SdpAnswerTimer: number | ReturnType<typeof setTimeout> | null;
+    private lastConnFailureTime;
+    private lastDisconnectionTime;
+    streamStatus: StreamStatus | undefined;
+    turnAddress: string;
+    private pcJanusPrivateIp;
+    private startedNegotiation;
+    pcCreationTime: number;
+    private onPcConnectionFail;
+    private onPcConnected;
+    private onPcConnectedFinal;
+    private onHandlePcTrackEvent;
+    private onPcCreated;
+    /**
+     * Primary callback - fires when local description (offer OR answer) is ready to send via signaling
+     */
+    private onLocalDescriptionReady?;
+    /**
+     * @deprecated Use onLocalDescriptionReady instead. Kept for backward compatibility.
+     */
+    private onStartPublishing;
+    /**
+     * Trickle ICE callback - fires when ICE candidate is discovered (if trickle ICE enabled)
+     */
+    private onIceCandidate?;
+    private config;
+    private pendingIceCandidates;
+    private OnIceConnectionFail;
+    constructor(streamerId: string, config: PeerConnectionConfig, isPublisher: boolean, isDesktop: boolean, isAudioMix: boolean, onPcCreated: OnPcCreated, onPcConnected: OnPcConnected, onPcConnectedFinal: OnPcConnectedFinal, onPcConnectionFail: OnPcConnectionFail, onHandlePcTrackEvent: OnHandlePcTrackEvent, onStartPublishing: OnStartPublishing, onLocalDescriptionReady?: OnStartPublishing, onIceCandidate?: OnIceCandidate);
+    updateWebrtcStreamInfo(streamStats: webrtcStreamStatsObj): void;
+    getPeerConnectionsStatus(connectionType?: string): number;
+    isPeerConnected(): boolean;
+    private updateDisconnectsList;
+    private clearConnectionStartTimer;
+    private clearConnectDisconnectTimer;
+    private clearConnectionStreamTimers;
+    clearSdpAnswerTimer(): void;
+    clearPcStreamTimers(): void;
+    handleConnectionFail(iceFailure: boolean, reason: number, subReason: number, reasonStr: string): void;
+    connectDisconnectTimeout(reason: number, subReason: number): Promise<void>;
+    setStreamStatus(newStatus?: StreamStatus): StreamStatus;
+    collectStreamStatsAfterInit(): void;
+    getPeerConnection(): RTCPeerConnection;
+    getPeerConnectionStats(forceGet: boolean): Promise<PcStatsObj>;
+    private getLocalCandidateNetworkStats;
+    private updateLocalCandidateNetStats;
+    handleConnectionStateChangeEvent(e: any): void;
+    handleICEConnectionStateChangeEvent(e: any, nextState: RTCIceConnectionState): void;
+    private handleICEGatheringStateChangeEvent;
+    private handleTrackEvent;
+    private handleSignalingstatechange;
+    connectionStartTimeout(): Promise<void>;
+    pcCollectBeaconIceInfo(callOnReset: boolean, resetReasonStr: string): void;
+    resetPC(updateDisconnectsList: boolean, resetReasonStr: string, calcStats: boolean): void;
+    updateJanusPrivateIp(privateIp: string): void;
+    createPC(isPublisher: boolean, streamerId: string, iceConfiguration: IceConfiguration): void;
+    private handlePCNegotiationNeededEvent;
+    sdpAnswerTimeout(): Promise<void>;
+    /**
+     * Create an offer for a viewer connection (recvonly)
+     * This is called when viewer wants to receive streams
+     */
+    /**
+     * Helper: Start negotiation timers (connection start and SDP answer)
+     */
+    private startNegotiationTimers;
+    /**
+     * Helper: Apply SDP manipulations (codec forcing, DTX)
+     * @param sdp - The SDP string to manipulate
+     * @returns Manipulated SDP string
+     */
+    private applySdpManipulations;
+    /**
+     * Helper: Notify callbacks when local description is ready
+     * Calls both onLocalDescriptionReady and onStartPublishing (deprecated)
+     * @param description - The local description to send
+     */
+    private notifyLocalDescriptionReady;
+    /**
+     * Generic method to create an offer
+     * Works for both publishers and viewers - does NOT depend on isPublisher flag
+     * @param options - Optional RTCOfferOptions
+     */
+    createOffer(options?: RTCOfferOptions): Promise<void>;
+    /**
+     * Generic method to create an answer to a remote offer
+     * Used for viewers who receive offers from the backend (KME pattern)
+     * Expects setRemoteDescription() to be called first with the offer
+     * @param options - Optional RTCAnswerOptions
+     */
+    createAnswer(options?: RTCAnswerOptions): Promise<void>;
+    /**
+     * Set remote description (offer or answer from signaling backend)
+     * @param description - The remote session description
+     */
+    setRemoteDescription(description: RTCSessionDescriptionInit, videoSenderConfig?: VideoSenderConfig | null): Promise<void>;
+    /**
+     * Add a remote ICE candidate to the peer connection
+     * Handles ICE candidate from remote peer received via signaling
+     * @param iceCandidate - The remote ICE candidate to add, or null to signal end of candidates
+     */
+    addRemoteIceCandidate(iceCandidate: IceCandidateDataObj | null): Promise<void>;
+    private flushPendingIceCandidates;
+    /**
+     * Applies video sender configuration to the peer connection.
+     *
+     * Step 1: calls setParameters() with all params except bitrate
+     *         (degradationPreference, maxFramerate, scaleResolutionDownBy, contentHint).
+     * Step 2: calls setParameters() with bitrate only. If that fails and offerSdp is
+     *         provided, falls back to SDP bandwidth munge via sdpLimitBw.
+     *
+     * @param config - Video sender parameters to apply
+     * @param offerSdp - Optional SDP string; bandwidth will be injected on bitrate setParameters failure
+     * @returns Modified SDP if bandwidth munge was applied, original offerSdp otherwise, undefined if no SDP passed
+     */
+    applyVideoSenderConfig(config: VideoSenderConfig, offerSdp?: string): Promise<string | undefined>;
+    /**
+     * Handle negotiation needed event
+     * Simplified to delegate to generic createOffer() method
+     * No longer checks isPublisher - applicative SDKs control the flow
+     */
+    handleNegotiationNeededEvent(_e: any): Promise<void>;
+}
+export default PeerConnection;

package/src/lib/peer-connection/PeerConnectionBeacon.d.ts

@@ -0,0 +1,208 @@
+type ConnectionGroupType = number | string;
+export type ConnectionInfoObj = {
+    connId: string;
+    updateTime: number;
+    connectionGroup: ConnectionGroupType;
+};
+export type BeaconObj = {
+    userId: number;
+    roomId: number;
+    companyId: number;
+    msid: number;
+    mediaServerPublicIP: string;
+    mediaServerRegion: number;
+    msSessionId: number;
+    msHandleId: number;
+    streamId: string;
+    startTime: number;
+    mediaPlayTime: number;
+    duration: number;
+    direction: number;
+    isAudioMix: number;
+    setupTime: number;
+    totalVideoMuteTime: number;
+    totalAudioMuteTime: number;
+    reason: number;
+    prevReason: number;
+    subReason: number;
+    prevSubReason: number;
+    sessionId: number;
+    avgRTT: string;
+    env: string;
+    disconnections: number;
+    initSuccessful: number;
+    attempt: number;
+    isLastAttempt: number;
+    totalSetupTime: number;
+    connectionState: number;
+    iceConnectionState: number;
+    videoQuality: number;
+    framesReceived: number;
+    totalSamplesReceived: number;
+    trayMode: number;
+    turnServer: string;
+    availableBitrate: number;
+    room_session_id: string;
+    user_session_id: string;
+    region: number;
+    device_type: string;
+    logical_cores: number;
+    memory: number;
+    network_type: string;
+    isRec: number;
+    appVersion: string;
+    reconnectionsCount: number;
+    longestReconnection: number;
+    cgrp: number;
+    cgrHistory: string;
+    cgrpPrev: number;
+    cgrInitial: number;
+    thp: string;
+    cgr0Cnt: number;
+    cgr1Cnt: number;
+    cgr2Cnt: number;
+    cgr3Cnt: number;
+    cgr4Cnt: number;
+    cgr5Cnt: number;
+    cgr6Cnt: number;
+    cgr7Cnt: number;
+    localCandidateType: string;
+    localRelayProtocol: string;
+    localProtocol: string;
+    remoteNetworkPort: string;
+    iceStats: string;
+    iceNumCandidates: number;
+    iceGatherTime: number;
+    iceFirstCandTime: number;
+    iceTestDisconnectTime: number;
+    audioPlay: number;
+    videoPlay: number;
+    incomingBandwidthKB: number;
+    outgoingBandwidthKB: number;
+    smoothnessScore: number;
+    qfps: number;
+    resW: number;
+    resH: number;
+    videoQScore: number;
+    rtc_v: string;
+    rsConType: number;
+    scGQlReason?: string;
+    scGQldNone?: number;
+    scGQldBw?: number;
+    scGQldCpu?: number;
+    scGQldOther?: number;
+    scGLayersDisable?: number;
+    scGLayersEnable?: number;
+    scGTrackW?: number;
+    scGTrackH?: number;
+    scHresW?: number;
+    scHresH?: number;
+    scHbw?: number;
+    scHpli?: number;
+    scHfps?: number;
+    scMresW?: number;
+    scMresH?: number;
+    scMbw?: number;
+    scMpli?: number;
+    scMfps?: number;
+    scLresW?: number;
+    scLresH?: number;
+    scLbw?: number;
+    scLpli?: number;
+    scLfps?: number;
+    scSubstream?: number;
+    scTemporal?: number;
+    scResW?: number;
+    scResH?: number;
+    scAvalBw?: number;
+    scPli?: number;
+    scUpscales?: number;
+    scDownscales?: number;
+    audioInQuality?: number;
+    audioInPackets?: number;
+    audioInBytes?: number;
+    audioInPacketsLost?: number;
+    audioInPercentPacketsLost?: number;
+    audioInJitter?: number;
+    audioInEnergy?: number;
+    audioOutQuality?: number;
+    audioOutPackets?: number;
+    audioOutBytes?: number;
+    audioOutPacketsLost?: number;
+    audioOutPercentPacketsLost?: number;
+    audioOutJitter?: number;
+    audioOutRemoteJitter?: number;
+    audioOutEnergy?: number;
+    totalVideoPackets?: number;
+    totalVideoPacketsDropped?: number;
+    totalVideoBytes?: number;
+    percentTotalVideoPacketsDropped?: string;
+    nacks?: number;
+    videoJitter?: number;
+    concealedSamples?: number;
+    silentConcealedSamples?: number;
+    framesDropped?: number;
+    sdpTime: number;
+    remoteVideoPlay: number;
+    remoteAudioPlay: number;
+};
+declare class PeerConnectionBeacon {
+    startTime: number;
+    reason: number;
+    prevReason: number;
+    subReason: number;
+    prevSubReason: number;
+    publisherSDPStartTime: number;
+    publisherSDPAcceptTime: number;
+    viewerSDPStartTime: number;
+    viewerSDPAcceptTime: number;
+    mediaPlayTime: number;
+    lastVideoMuteTime: number;
+    lastAudioMuteTime: number;
+    totalVideoMuteTime: number;
+    totalAudioMuteTime: number;
+    samplesCount: number;
+    rttSum: number;
+    totalRTT: number;
+    responsesReceived: number;
+    successful: number;
+    attempt: number;
+    isLastAttempt: number;
+    totalSetupTime: number;
+    videoQuality: number;
+    audioInQuality: number;
+    audioOutQuality: number;
+    totalSamplesReceived: number;
+    framesReceived: number;
+    videoJitterPrevTransit: number;
+    videoJitterSum: number;
+    firstReportTime: number;
+    lastReportTime: number;
+    availableBitrate: number;
+    localNetworkType: string;
+    setupTime: number;
+    firstTrackEventTime: number;
+    disconnectionsCount: number;
+    longestReconnection: number;
+    cgr: number;
+    cgrHistory: string;
+    cgrPrev: number;
+    cgrInitial: number;
+    cgr0Cnt: number;
+    cgr1Cnt: number;
+    cgr2Cnt: number;
+    cgr3Cnt: number;
+    cgr4Cnt: number;
+    cgr5Cnt: number;
+    cgr6Cnt: number;
+    cgr7Cnt: number;
+    localCandidateType: string;
+    localRelayProtocol: string;
+    localProtocol: string;
+    remoteNetworkPort: string;
+    resetAll(): void;
+    restart(): void;
+    constructor();
+    updatecgHistoryStr(): void;
+}
+export default PeerConnectionBeacon;

package/src/lib/peer-connection/PeerConnectionManager.d.ts

@@ -0,0 +1,57 @@
+import PeerConnection from './PeerConnection';
+import { UnisphereLoggerType } from '@unisphere/core';
+export declare class PeerConnectionManager {
+    private connections;
+    private logger;
+    constructor(logger: UnisphereLoggerType);
+    /**
+     * Add a peer connection to the registry
+     * @param connectionId - Unique identifier for this connection
+     * @param connection - PeerConnection instance
+     */
+    addConnection(connectionId: string, connection: PeerConnection): void;
+    /**
+     * Remove a peer connection from the registry
+     * @param connectionId - Unique identifier for the connection to remove
+     * @returns true if connection was removed, false if not found
+     */
+    removeConnection(connectionId: string): boolean;
+    /**
+     * Get a peer connection by ID
+     * @param connectionId - Unique identifier for the connection
+     * @returns PeerConnection instance or undefined if not found
+     */
+    getConnection(connectionId: string): PeerConnection | undefined;
+    /**
+     * Check if a connection exists
+     * @param connectionId - Unique identifier for the connection
+     * @returns true if connection exists
+     */
+    hasConnection(connectionId: string): boolean;
+    /**
+     * Get all connection IDs
+     * @returns Array of connection IDs
+     */
+    getConnectionIds(): string[];
+    /**
+     * Get all peer connections
+     * @returns Array of PeerConnection instances
+     */
+    getAllConnections(): PeerConnection[];
+    /**
+     * Get the number of active connections
+     * @returns Number of connections in the registry
+     */
+    getConnectionCount(): number;
+    /**
+     * Clear all connections from the registry
+     * Note: Does NOT close the connections - caller must handle cleanup
+     */
+    clear(): void;
+    /**
+     * Execute a callback for each connection
+     * @param callback - Function to execute for each connection
+     */
+    forEach(callback: (connection: PeerConnection, connectionId: string) => void): void;
+}
+export default PeerConnectionManager;

package/src/lib/peer-connection/PeerConnectionWebrtcStats.d.ts

@@ -0,0 +1,32 @@
+export type PcStatsObj = {
+    id: string;
+    stats?: RTCStatsReport | null;
+    reason?: string;
+    err?: any;
+};
+declare class PeerConnectionWebrtcStats {
+    private logger;
+    private streamerId;
+    private peerConnection;
+    private lastCaptureTime;
+    private statsReport;
+    private viewerQualityTimer;
+    private publisherQualityTimer;
+    private isPublisher;
+    private hasVideo;
+    private prevViewerStats;
+    private prevPublisherStats;
+    constructor(streamerId: string);
+    updatePeerConnection(peerConnection: RTCPeerConnection | null): void;
+    private getPcStats;
+    getPeerConnectionStats(forceGet: boolean): Promise<PcStatsObj>;
+    startStatsTimer(isPublisher: boolean): void;
+    stopStatsTimer(): void;
+    private viewerCheckQuality;
+    private publisherCheckQuality;
+    private prepareViewerSimulcastStats;
+    private logViewerSimStats;
+    private preparePublisherStreamSimulcastStats;
+    private logPublisherSimStats;
+}
+export default PeerConnectionWebrtcStats;

package/src/lib/peer-connection/constants.d.ts

@@ -0,0 +1,89 @@
+export declare enum IceCandidateType {
+    NA = "na",
+    RELAY = "relay",
+    SRFLX = "srflx",
+    PRFLX = "prflx",
+    HOST = "host"
+}
+export declare enum IceRelayType {
+    NA = "na",
+    UDP = "udp",
+    TCP = "tcp",
+    TLS = "tls",
+    DTLS = "dtls"
+}
+export declare enum PcCloseReason {
+    CONNECTION_DISCONNECTED = 101,
+    CONNECTION_FAILED = 102,
+    CONNECTION_START_TIMEOUT = 103,
+    NEGOTIATION_FAILED = 104,
+    NO_PEER_CONNECTION = 105,
+    NO_SDP_ANSWER_TIMEOUT = 106
+}
+export declare enum DisconnectSubReason {
+    NONE = 0
+}
+export declare enum PeerConnectionState {
+    NEW = "new",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    DISCONNECTED = "disconnected",
+    FAILED = "failed",
+    CLOSED = "closed"
+}
+export declare enum SettingValue {
+    ON = "on",
+    OFF = "off"
+}
+export declare const IceTimerConfig: {
+    readonly IceStatsTimerMsec: 1000;
+    readonly iceStatsDurationMsec: 30000;
+    readonly durationForNoCandsCheckMsec: 3000;
+    readonly DisconnectsSecDuration: 60;
+    readonly connectionStartTimerMsec: 20000;
+    readonly disconnectCheckTimerMsec: 10000;
+    readonly sdpAnswerTimerMsec: 30000;
+    readonly connectCheckTimerMsec: 5000;
+};
+export declare const Constants: {
+    iceCandidateType: {
+        na: IceCandidateType;
+        relay: IceCandidateType;
+        srflx: IceCandidateType;
+        host: IceCandidateType;
+    };
+    pcCloseReason: {
+        CONNECTION_DISCONNECTED: PcCloseReason;
+        CONNECTION_FAILED: PcCloseReason;
+        CONNECTION_START_TIMEOUT: PcCloseReason;
+        NEGOTIATION_FAILED: PcCloseReason;
+        NO_PEER_CONNECTION: PcCloseReason;
+        NO_SDP_ANSWER_TIMEOUT: PcCloseReason;
+    };
+    disconnectSubReasons: {
+        none: DisconnectSubReason;
+    };
+    iceConf: {
+        readonly IceStatsTimerMsec: 1000;
+        readonly iceStatsDurationMsec: 30000;
+        readonly durationForNoCandsCheckMsec: 3000;
+        readonly DisconnectsSecDuration: 60;
+        readonly connectionStartTimerMsec: 20000;
+        readonly disconnectCheckTimerMsec: 10000;
+        readonly sdpAnswerTimerMsec: 30000;
+        readonly connectCheckTimerMsec: 5000;
+    };
+    peerConnectionConnectionStates: {
+        new: PeerConnectionState;
+        connecting: PeerConnectionState;
+        connected: PeerConnectionState;
+        disconnected: PeerConnectionState;
+        failed: PeerConnectionState;
+        closed: PeerConnectionState;
+    };
+    settingValues: {
+        ON: SettingValue;
+        OFF: SettingValue;
+    };
+};
+export default Constants;

package/src/lib/peer-connection/index.d.ts

@@ -0,0 +1,10 @@
+export { default as PeerConnection } from './PeerConnection';
+export { default as PeerConnectionBeacon } from './PeerConnectionBeacon';
+export { default as PeerConnectionWebrtcStats } from './PeerConnectionWebrtcStats';
+export { default as PeerConnectionManager } from './PeerConnectionManager';
+export { default as IceHandler } from './IceHandler';
+export * from './types';
+export * from './constants';
+export type { PcStatsObj } from './PeerConnectionWebrtcStats';
+export type { BeaconObj, ConnectionInfoObj } from './PeerConnectionBeacon';
+export type { IceDisconnectionObj } from './IceHandler';