@kaltura-sdk/rtc-core 1.25.0

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

@@ -0,0 +1,167 @@
+export declare enum StreamStatus {
+    Na = "Na",
+    new = "new",
+    connecting = "connecting",
+    getRemoteSDPOffer = "getRemoteSDPOffer",
+    setRemoteSDPOffer = "setRemoteSDPOffer",
+    getLocalSDPAnswer = "getLocalSDPAnswer",
+    setLocalSDPAnswer = "setLocalSDPAnswer",
+    createdPeerConnection = "createdPeerConnection",
+    gotTrackEvent = "gotTrackEvent",
+    connected = "connected",
+    createdLocalSDPOffer = "createdLocalSDPOffer",
+    setLocalSDPOffer = "setLocalSDPOffer",
+    iceGatheringDone = "iceGatheringDone",
+    disconnected = "disconnected",
+    gotRemoteSDPAnswer = "gotRemoteSDPAnswer",
+    setRemoteSDPAnswer = "setRemoteSDPAnswer"
+}
+export type LocalIceCandidateInfoObj = {
+    localCandidateType: string;
+    localRelayProtocol: string;
+    localProtocol: string;
+    localNetworkType: string;
+    remoteNetworkPort: string;
+};
+/**
+ * Simplified ICE candidate data for trickle ICE
+ * Matches the format from test_webrtc.html
+ */
+export type IceCandidateDataObj = {
+    candidate: string | null | undefined;
+    sdpMLineIndex: number;
+};
+export interface PeerConnectionConfig {
+    isPublisher: boolean;
+    isDesktop?: boolean;
+    isAudioMix?: boolean;
+    retryStrategy?: RetryStrategy;
+    statsInterval?: number;
+    timeouts?: {
+        connectionStart?: number;
+        disconnectCheck?: number;
+        sdpAnswer?: number;
+        iceGathering?: number;
+    };
+    codecType?: string;
+    turnServerUrl?: string;
+    enableTrickleIce?: boolean;
+}
+export interface IceConfiguration {
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+}
+export interface ConnectionFailureInfo {
+    iceFailure: boolean;
+    reason: ConnectionFailureReason | number;
+    subReason: number;
+    reasonStr: string;
+    wasConnected: boolean;
+    disconnections: Array<{
+        disconnectionTime: number;
+        disconnectReason: number;
+        duration: number;
+        totalBytes: number;
+        wasConnected: boolean;
+    }>;
+    lastConnFailureTime: number;
+    pcCreationTime: number;
+    localCandidateType?: string;
+}
+export interface RetryStrategy {
+    shouldRetry(attempt: number, reason: ConnectionFailureReason): boolean;
+    getRetryDelay(attempt: number): number;
+    onRetryAttempt?(attempt: number): void;
+    onRetrySuccess?(): void;
+    onRetryExhausted?(): void;
+}
+export interface VideoSenderConfig {
+    /** @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/contentHint */
+    contentHint?: string;
+    degradationPreference?: RTCDegradationPreference;
+    maxFps?: number;
+    maxBitrateKbps?: number;
+    scaleResolutionDownBy?: number;
+}
+export declare enum ConnectionFailureReason {
+    ICE_FAILED = "ice_failed",
+    CONNECTION_TIMEOUT = "connection_timeout",
+    DISCONNECTED = "disconnected",
+    SIGNALING_ERROR = "signaling_error",
+    MEDIA_ERROR = "media_error",
+    UNKNOWN = "unknown"
+}
+export interface PeerConnectionEventPayloads {
+    pcCreated: {
+        connectionId: string;
+        timestamp: number;
+    };
+    pcConnected: {
+        connectionId: string;
+    };
+    pcConnectedFinal: {
+        connectionId: string;
+    };
+    pcConnectionFailed: {
+        connectionId: string;
+        reason: ConnectionFailureReason;
+        willRetry: boolean;
+        iceFailure: boolean;
+        subReason: number;
+        reasonStr: string;
+    };
+    pcTrackReceived: {
+        connectionId: string;
+        track: MediaStreamTrack;
+        streams: ReadonlyArray<MediaStream>;
+    };
+    pcStartPublishing: {
+        connectionId: string;
+        localDescription: RTCSessionDescription;
+    };
+    pcClosed: {
+        connectionId: string;
+    };
+    pcStatsUpdate: {
+        connectionId: string;
+        stats: any;
+    };
+    pcConnectionGroupNeeded: {
+        connectionId: string;
+        currentGroup: any;
+        reason: number;
+    };
+    pcNegotiationNeeded: {
+        connectionId: string;
+        isPublisher: boolean;
+    };
+    pcLocalDescriptionCreated: {
+        connectionId: string;
+        description: RTCSessionDescriptionInit;
+    };
+    pcIceCandidate: {
+        connectionId: string;
+        candidate: RTCIceCandidate | null;
+    };
+    pcConnectionStateChange: {
+        connectionId: string;
+        state: RTCPeerConnectionState;
+        previousState: RTCPeerConnectionState;
+    };
+    pcIceConnectionStateChange: {
+        connectionId: string;
+        state: RTCIceConnectionState;
+    };
+    pcConnectionStartTimeout: {
+        connectionId: string;
+    };
+    pcDisconnectCheckTimeout: {
+        connectionId: string;
+    };
+    pcSdpAnswerTimeout: {
+        connectionId: string;
+    };
+    pcIceGatheringTimeout: {
+        connectionId: string;
+    };
+}

package/src/lib/session/CoreRTCSession.d.ts

@@ -0,0 +1,215 @@
+import { GetUserMediaManager } from '../media/GetUserMediaManager';
+import { MediaSources, TrackKind } from '../media/MediaSources';
+import { GetUserMediaEveObj } from '../media/types';
+import DevicesManager, { UserDevicesType, DeviceType } from '../devices/DevicesManager';
+import { PeerConnectionManager } from '../peer-connection/PeerConnectionManager';
+import PeerConnection from '../peer-connection/PeerConnection';
+import { PeerConnectionConfig, ConnectionFailureInfo, IceCandidateDataObj } from '../peer-connection/types';
+import { AudioNrMode } from '../media/media-processing/types';
+/**
+ * Media track/device type: audio or video
+ */
+export type MediaDeviceKind = 'audio' | 'video';
+export declare class CoreRTCSession {
+    peerConnectionManager: PeerConnectionManager;
+    userStreams: Map<string, MediaStream>;
+    mediaSources: MediaSources;
+    devicesManager: DevicesManager;
+    getUserMediaManager: GetUserMediaManager;
+    private logger;
+    private audioAnalyzer;
+    private speakingThreshold;
+    private dbgAudioLoopbackActive;
+    constructor(devicesManager: DevicesManager);
+    /**
+     * Handle AudioContext errors - attempt recovery by re-acquiring audio
+     * Called by AudioProcessing when audioContext.onerror is triggered
+     * MATCHES ORIGINAL: mediaSetup.getUserMedia recovery logic from audioProcessing.ts
+     */
+    private onAudioContextError;
+    /**
+     * Update peer connection senders with new track
+     * MATCHES ORIGINAL: mdReplaceStopSenderTrack with simulcast support
+     *
+     * This callback is passed to GetUserMediaManager and called when tracks need
+     * to be replaced in all active peer connections (e.g., device change, unmute)
+     *
+     * @param trackKind - 'audio' or 'video'
+     * @param newTrack - New track to replace with
+     *
+     * @param initial - Whether this is initial setup (for simulcast)
+     * @returns Promise<boolean> - True if track was replaced successfully
+     */
+    private updatePeerConnectionSenders;
+    /**
+     * Release media device - complete device release with stream cleanup
+     * MATCHES ORIGINAL: releaseMediaDevice function from production code
+     *
+     * This callback handles the full device release flow:
+     * 2. Stop and remove stream tracks
+     * 3. Stop audio/video processing
+     * 4. Clear mediaSources references
+     *
+     * @param deviceType - 'audio' or 'video'
+     * @param replaceWithEmptyTracks - If true, replace with silent/dummy track in PC
+     * @returns Promise<void>
+     */
+    private releaseMediaDevice;
+    init(): Promise<void>;
+    /**
+     * 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;
+    /**
+     * Get all peer connections
+     * @returns Array of PeerConnection instances
+     */
+    getAllConnections(): PeerConnection[];
+    /**
+     * Get the number of active connections
+     * @returns Number of connections
+     */
+    getConnectionCount(): number;
+    /**
+     * Create a new peer connection and add it to the manager
+     *
+     * @param connectionId - Unique identifier for this connection
+     * @param config - Peer connection configuration
+     * @param callbacks - Callbacks for peer connection events
+     * @returns The created PeerConnection instance
+     */
+    createPeerConnection(connectionId: string, config: PeerConnectionConfig, callbacks: {
+        onPcCreated?: () => void;
+        onPcConnected?: () => void;
+        onPcConnectedFinal?: () => void;
+        onPcConnectionFail?: (failureInfo: ConnectionFailureInfo) => void;
+        onHandlePcTrackEvent?: (streams: ReadonlyArray<MediaStream>) => void;
+        onIceCandidate?: (candidate: IceCandidateDataObj | null) => void;
+        /**
+         * Primary callback - fires when local description (offer OR answer) is ready to send via signaling
+         * Use this for new code
+         */
+        onLocalDescriptionReady?: (localDescription: RTCSessionDescription | null) => void;
+        /**
+         * @deprecated Use onLocalDescriptionReady instead. Kept for backward compatibility.
+         */
+        onStartPublishing?: (localDescription: RTCSessionDescription | null) => void;
+    }): PeerConnection;
+    getUserMedia(desiredConstraints: MediaStreamConstraints, isDeviceChange?: boolean): Promise<{
+        gumResult: GetUserMediaEveObj;
+        stream: MediaStream | null;
+    }>;
+    /**
+     * Start audio analysis for speaking indicator
+     * Called automatically after getUserMedia succeeds with audio
+     * @private
+     */
+    private startAudioAnalysis;
+    /**
+     * Stop audio analysis and clean up analysis track
+     * Call this when stopping media capture or closing connections
+     */
+    stopAudioAnalysis(): void;
+    /**
+     * Set speaking threshold
+     * @param threshold - Volume threshold for speaking detection (default: 300)
+     */
+    setSpeakingThreshold(threshold: number): void;
+    /**
+     * Update AudioAnalyzer about listener status (performance optimization)
+     * Called when listeners are added/removed from EselfSession
+     * Only emits events when listeners are registered to avoid overhead
+     */
+    updateAudioAnalyzerListeners(): void;
+    getUserDevices(): Promise<UserDevicesType>;
+    /**
+     * Replaces tracks in ALL active peer connections
+     * Critical for mute/unmute to work across multiple connections
+     * @param trackKind - 'audio' or 'video'
+     * @param newTrack - New track to replace with (or null to stop sending)
+     */
+    replaceTrackInAllConnections(trackKind: MediaDeviceKind, newTrack: MediaStreamTrack | null, publisher: boolean): Promise<void>;
+    /**
+     * Generic method to mute a track
+     * @param trackKind - TrackKind.AUDIO or TrackKind.VIDEO
+     * @param useDummyTrack - Whether to replace with dummy track
+     */
+    muteTrack(trackKind: TrackKind, useDummyTrack?: boolean): Promise<boolean>;
+    /**
+     * Generic method to unmute a track
+     * This will be called by EselfSession which handles getUserMedia with proper constraints
+     * Note: getUserMedia with isDeviceChange=true already updates all media sources and streams
+     * @param trackKind - TrackKind.AUDIO or TrackKind.VIDEO
+     */
+    unmuteTrack(trackKind: TrackKind): Promise<boolean>;
+    isAudioMuted(): boolean;
+    isVideoMuted(): boolean;
+    /**
+     * Clean up all media streams and tracks
+     * Stops all tracks from getUserMedia calls and nullifies stream references
+     * Call this when leaving a session or destroying the RTC connection
+     */
+    cleanupAllStreamsAndTracks(): Promise<void>;
+    releaseDeviceByType(deviceType: DeviceType.AudioInput | DeviceType.VideoInput | DeviceType.AudioOutput): Promise<void>;
+    /**
+     * Change input or output device (microphone, camera, or speaker)
+     * Handles complete device switching flow:
+     * - Validates device exists
+     * - Calls getUserMedia with new device for input devices
+     * - Replaces tracks on all peer connections
+     * - Stops old tracks
+     * - Updates localStorage
+     * - Emits deviceChanged event
+     *
+     * @param deviceType - DeviceType.AudioInput, DeviceType.VideoInput, or DeviceType.AudioOutput
+     * @param deviceId - Device ID from enumerateDevices
+     * @returns Promise with success status, stream, and previous device info
+     */
+    changeDevice(deviceType: DeviceType.AudioInput | DeviceType.VideoInput | DeviceType.AudioOutput, deviceId: string): Promise<{
+        success: boolean;
+        replaced: boolean;
+        stream: MediaStream | null;
+        error?: string;
+        previousDevice?: {
+            id: string;
+            label: string;
+        };
+    }>;
+    /**
+     * Set noise reduction state
+     * Enables or disables audio noise reduction with specified mode
+     * @param enable - True to enable NR, false to disable
+     * @param mode - Noise reduction mode (required when enabling, default: Mode13)
+     * @returns Promise<boolean> - True if successful, false otherwise
+     */
+    setNoiseReduction(enable: boolean, mode?: AudioNrMode): Promise<boolean>;
+    /**
+     * Get current noise reduction state
+     * @returns Object with enabled status and current mode
+     */
+    getNoiseReductionState(): {
+        enabled: boolean;
+        mode: AudioNrMode;
+    };
+    /**
+     */
+    getNoiseReductionEnableState(): boolean;
+    /**
+     * DEBUG: Start audio loopback to monitor the audio being sent to ASR
+     * Creates an audio element that plays back the published audio track
+     * WARNING: Use headphones to avoid feedback! For debugging only.
+     * @returns HTMLAudioElement or null if no audio track available
+     */
+    dbgStartAudioLoopback(): boolean;
+    /**
+     * DEBUG: Stop audio loopback monitoring
+     */
+    dbgStopAudioLoopback(): void;
+    /**
+     * DEBUG: Update audio loopback with new track if loopback is active
+     * Called automatically when audio track changes (device change, NR toggle, etc.)
+     */
+    dbgUpdateAudioLoopback(): void;
+}

package/src/lib/session/index.d.ts

@@ -0,0 +1,2 @@
+import { CoreRTCSession } from './CoreRTCSession';
+export { CoreRTCSession };

package/src/lib/simulcast/simulcastCommonPublisher.d.ts

@@ -0,0 +1,4 @@
+export declare enum publisherQualityCheckStageType {
+    periodic = "periodic",
+    connected = "connected"
+}

package/src/lib/unisphere-sample.d.ts

@@ -0,0 +1,50 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+export interface RTCCoreOptions {
+    logger: UnisphereLoggerType;
+    onEvent: (event: any) => void;
+}
+export declare class RTCCore {
+    private _options;
+    private _microphoneStatus;
+    get onMicrophoneStatusChange(): (callback: (data: {
+        available: boolean;
+        muted: boolean;
+        devices: string[];
+    }) => void, options?: {
+        once?: boolean | undefined;
+        replayLastValue?: boolean | undefined;
+    } | undefined) => () => void;
+    get microphoneStatus(): {
+        available: boolean;
+        muted: boolean;
+        devices: string[];
+    };
+    private _userStream;
+    get onUserStreamChange(): (callback: (data: {
+        identifier: string;
+        elementId: string;
+        status: "attached" | "detached";
+        htmlElementId: string;
+    }) => void, options?: {
+        once?: boolean | undefined;
+        replayLastValue?: boolean | undefined;
+    } | undefined) => () => void;
+    get userStream(): {
+        identifier: string;
+        elementId: string;
+        status: "attached" | "detached";
+        htmlElementId: string;
+    };
+    private _onSomethingSpecificHappened;
+    get onSomethingSpecificHappened(): (callback: (data: {
+        interesting: boolean;
+    }) => void, options?: {
+        once?: boolean | undefined;
+        replayLastValue?: boolean | undefined;
+    } | undefined) => () => void;
+    constructor(_options: RTCCoreOptions);
+    attachUserStream(elementId: string): void;
+    muteMicrophone(): void;
+    unmuteMicrophone(): void;
+    detachUserStream(): void;
+}