@kaltura-sdk/rtc-avatar 1.32.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@kaltura-sdk/rtc-avatar",
+  "version": "1.32.0",
+  "author": "kaltura",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaltura/rtc"
+  },
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@kaltura-sdk/rtc-core": "^1.25.0",
+    "@unisphere/core": "^1.91.1",
+    "lodash.isequal": "^4.5.0"
+  },
+  "module": "./index.esm.js",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/eself-demo';
+export * from './lib/session';
+export * from './lib/dom';
+export * from './lib/signaling';
+export * from './lib/connection';
+export * from './lib/utils/logsCollector';

package/src/lib/connection/EselfRTCConnection.d.ts

@@ -0,0 +1,186 @@
+import { PeerConnection, PeerConnectionConfig, IceConfiguration, CoreRTCSession, TrackKind, GetUserMediaEveObj, VideoSenderConfig } from '@kaltura-sdk/rtc-core';
+import { EselfSignaling } from '../signaling';
+import { ConnectionType, ConnectionEvent, ConnectionEventPayloads, ConnectionState, MediaTrackState } from './types';
+import { IceCandidateData } from '../session';
+/**
+ * Options for configuring the RTC connection behavior.
+ */
+export interface EselfRTCConnectionOptions {
+    /** Force video codec (e.g. 'H264', 'VP8') */
+    videoCodec?: string;
+    /** Force audio codec (e.g. 'opus') */
+    audioCodec?: string;
+    /** Enable trickle ICE for this connection */
+    enableTrickleIce?: boolean;
+    /** Degradation preference for the video sender */
+    videoDegradationPreference?: RTCDegradationPreference;
+    /** Content hint for the video track */
+    videoContentHint?: string;
+    /** Maximum frame rate for the video sender */
+    videoMaxFps?: number;
+    /** Maximum bitrate in Kilobits for the video sender */
+    videoMaxBitrateKbps?: number;
+    /** Scale resolution down factor for the video sender (1.0 = no scaling) */
+    videoScaleResolutionDownBy?: number;
+}
+/**
+ * Event listener type for connection events
+ */
+type EventListener<T extends ConnectionEvent> = (payload: ConnectionEventPayloads[T]) => void;
+/**
+ * EselfRTCConnection: Per-connection coordinator that wraps ONE core SDK PeerConnection
+ *
+ * Purpose:
+ * - Wraps a single PeerConnection from the core SDK
+ * - Handles signaling for this connection
+ * - Emits simplified events to EselfSession
+ * - Manages connection lifecycle (NO retry logic in Phase 2a)
+ *
+ * Two modes:
+ * - Publisher: Sends local stream (e.g., ASR audio publishing)
+ * - Viewer: Receives remote stream only (e.g., STV avatar viewing)
+ *
+ * Events emitted:
+ * - pcConnected: Connection established
+ * - pcConnectionFailed: Connection failed
+ * - pcTrackReceived: Remote track received
+ * - pcIceCandidate: Local ICE candidate generated
+ */
+export declare class EselfRTCConnection {
+    private connectionId;
+    private connectionType;
+    private peerConnection;
+    private signalingClient;
+    private logger;
+    private state;
+    private localStream;
+    private videoElementId;
+    private options;
+    useRelay: boolean;
+    private audioState;
+    private videoState;
+    private isReconnecting;
+    private requestsDebouncer;
+    private hwMuteDebounceTimer;
+    private readonly HW_MUTE_DEBOUNCE_MS;
+    private coreRTCSession;
+    private getUserMediaCallback;
+    private eventListeners;
+    constructor(connectionId: string, connectionType: ConnectionType, signalingClient: EselfSignaling, createPeerConnection: (connectionId: string, config: PeerConnectionConfig, callbacks: any) => PeerConnection, coreRTCSession: CoreRTCSession, getUserMediaCallback: (audio: boolean, video: boolean, elementId?: string, isDeviceChange?: boolean) => Promise<{
+        gumResult: GetUserMediaEveObj;
+        stream: MediaStream | null;
+    }>, options?: EselfRTCConnectionOptions);
+    /**
+     * Sets the video element ID for DOM reattachment during unmute
+     * @param elementId - The container element ID where video should be attached
+     */
+    setVideoElementId(elementId: string | null): void;
+    /**
+     * Sets the reconnection flag
+     * @param value - True if this is a reconnection attempt
+     */
+    setReconnecting(value: boolean): void;
+    /**
+     * Test method to manually trigger connection failed event
+     * Used for testing reconnection logic in development/testing
+     */
+    testTriggerConnectionFailed(): void;
+    /**
+     * Create and configure the peer connection
+     *
+     * @param iceConfig - ICE server configuration
+     * @param localStream - Optional local stream for publisher connections
+     * @param videoElementId - Optional element ID for video attachment
+     * @throws Error if connection creation fails
+     */
+    createConnection(iceConfig: IceConfiguration, localStream?: MediaStream, videoElementId?: string): Promise<void>;
+    /**
+     * Handle a remote offer (for viewer mode)
+     * Creates answer and sends it via signaling
+     *
+     * @param sdp - Remote SDP offer
+     */
+    handleRemoteOffer(sdp: RTCSessionDescriptionInit): Promise<void>;
+    /**
+     * Handle a remote answer (after sending offer)
+     *
+     * @param sdp - Remote SDP answer
+     */
+    handleRemoteAnswer(sdp: RTCSessionDescriptionInit, videoSenderConfig?: VideoSenderConfig | null): Promise<void>;
+    /**
+     * Handle a remote ICE candidate
+     *
+     * @param candidate - Remote ICE candidate
+     */
+    handleRemoteICECandidate(candidate: IceCandidateData): Promise<void>;
+    /**
+     * Register an event listener
+     *
+     * @param event - Event type
+     * @param listener - Listener function
+     */
+    on<T extends ConnectionEvent>(event: T, listener: EventListener<T>): void;
+    /**
+     * Remove an event listener
+     *
+     * @param event - Event type
+     * @param listener - Listener function
+     */
+    off<T extends ConnectionEvent>(event: T, listener: EventListener<T>): void;
+    /**
+     * Close the connection and clean up resources
+     */
+    close(): void;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Get the underlying core SDK PeerConnection (for advanced use)
+     */
+    getPeerConnection(): PeerConnection | null;
+    private handlePcCreated;
+    private handlePcConnected;
+    private handlePcConnectedFinal;
+    private handlePcConnectionFail;
+    private handlePcTrackEvent;
+    private handleStartPublishing;
+    private handleIceCandidate;
+    /**
+     * Generic method to mute a track using RequestsDebouncer with state comparison
+     * Protects against rapid duplicate calls from the app
+     * @param trackKind - TrackKind.AUDIO or TrackKind.VIDEO
+     */
+    muteTrack(trackKind: TrackKind): Promise<void>;
+    /**
+     * Generic method to unmute a track using RequestsDebouncer with state comparison
+     * Calls getUserMedia through callback to preserve constraints
+     * @param trackKind - TrackKind.AUDIO or TrackKind.VIDEO
+     */
+    unmuteTrack(trackKind: TrackKind): Promise<boolean>;
+    muteAudio(): Promise<void>;
+    unmuteAudio(): Promise<boolean>;
+    muteVideo(): Promise<void>;
+    unmuteVideo(): Promise<boolean>;
+    /**
+     * Sets up hardware mute detection on tracks
+     * Should be called after tracks are added to connection
+     */
+    setupHardwareMuteDetection(): void;
+    /**
+     * Handles track mute event (hardware mute detected)
+     * Uses 5-second debounce to avoid false positives
+     */
+    private handleTrackMute;
+    /**
+     * Handles track unmute event (hardware unmute detected)
+     */
+    private handleTrackUnmute;
+    getAudioState(): MediaTrackState;
+    getVideoState(): MediaTrackState;
+    /**
+     * Emit an event to all registered listeners
+     */
+    private emit;
+}
+export default EselfRTCConnection;

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

@@ -0,0 +1,3 @@
+export { EselfRTCConnection, default as EselfRTCConnectionDefault, } from './EselfRTCConnection';
+export type { EselfRTCConnectionOptions } from './EselfRTCConnection';
+export * from './types';

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

@@ -0,0 +1,94 @@
+import { IceCandidateData } from '../session';
+/**
+ * Connection type for EselfRTCConnection
+ */
+export type ConnectionType = 'publisher' | 'viewer';
+/**
+ * Media track mute state
+ */
+export declare enum MediaTrackState {
+    UNMUTED = "UNMUTED",// Track active, not muted
+    MUTED = "MUTED",// Software muted by user
+    HW_MUTED = "HW_MUTED"
+}
+/**
+ * ICE configuration for peer connections
+ */
+export type IceConfiguration = {
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    bundlePolicy?: RTCBundlePolicy;
+    rtcpMuxPolicy?: RTCRtcpMuxPolicy;
+};
+/**
+ * Events emitted by EselfRTCConnection
+ */
+export declare enum ConnectionEvent {
+    PC_CONNECTED = "pcConnected",
+    PC_CONNECTION_FAILED = "pcConnectionFailed",
+    PC_TRACK_RECEIVED = "pcTrackReceived",
+    PC_ICE_CANDIDATE = "pcIceCandidate",
+    AUDIO_MUTED = "audio-muted",
+    AUDIO_UNMUTED = "audio-unmuted",
+    VIDEO_MUTED = "video-muted",
+    VIDEO_UNMUTED = "video-unmuted",
+    HW_AUDIO_MUTED = "hw-audio-muted",
+    HW_AUDIO_UNMUTED = "hw-audio-unmuted"
+}
+/**
+ * Connection event payloads
+ */
+export type ConnectionEventPayloads = {
+    [ConnectionEvent.PC_CONNECTED]: {
+        connectionId: string;
+    };
+    [ConnectionEvent.PC_CONNECTION_FAILED]: {
+        connectionId: string;
+        error: Error;
+    };
+    [ConnectionEvent.PC_TRACK_RECEIVED]: {
+        connectionId: string;
+        stream: MediaStream;
+        track: MediaStreamTrack;
+    };
+    [ConnectionEvent.PC_ICE_CANDIDATE]: {
+        connectionId: string;
+        iceCandidate: IceCandidateData | null;
+    };
+    [ConnectionEvent.AUDIO_MUTED]: {
+        connectionId: string;
+        state: MediaTrackState;
+    };
+    [ConnectionEvent.AUDIO_UNMUTED]: {
+        connectionId: string;
+        state: MediaTrackState;
+    };
+    [ConnectionEvent.VIDEO_MUTED]: {
+        connectionId: string;
+        state: MediaTrackState;
+    };
+    [ConnectionEvent.VIDEO_UNMUTED]: {
+        connectionId: string;
+        state: MediaTrackState;
+    };
+    [ConnectionEvent.HW_AUDIO_MUTED]: {
+        connectionId: string;
+        previousState: MediaTrackState;
+        currentState: MediaTrackState;
+    };
+    [ConnectionEvent.HW_AUDIO_UNMUTED]: {
+        connectionId: string;
+        currentState: MediaTrackState;
+        message: string;
+    };
+};
+/**
+ * Connection state
+ */
+export declare enum ConnectionState {
+    IDLE = "idle",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    FAILED = "failed",
+    CLOSED = "closed"
+}

package/src/lib/dom/EselfDOMManager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * EselfDOMManager: Handles DOM manipulation and tracks multiple attachments per stream
+ *
+ * Key Features:
+ * - One stream can be attached to multiple video containers
+ * - Audio streams are attached to the body (one audio element per stream)
+ * - Tracks all attachments for proper cleanup
+ * - Gracefully handles missing containers (logs warning, doesn't throw)
+ */
+export declare class EselfDOMManager {
+    private logger;
+    private streamAttachments;
+    private audioElements;
+    constructor();
+    /**
+     * Attach a video stream to a container element
+     * Creates a video element inside the container and plays the stream
+     * Same stream can be attached to multiple containers
+     *
+     * @param stream - MediaStream to attach
+     * @param containerElementId - ID of the container element
+     */
+    attachVideoStream(stream: MediaStream, containerElementId: string): void;
+    /**
+     * Attach an audio stream to the document body
+     * Creates an audio element in the body (not in a container)
+     * One audio element per stream (not multiple like video)
+     *
+     * @param stream - MediaStream to attach
+     */
+    attachAudioStream(stream: MediaStream): void;
+    /**
+     * Detach a stream from a specific container element
+     * Removes the video element from that container only
+     * Stream may still be attached to other containers
+     *
+     * @param streamId - ID of the stream
+     * @param containerElementId - ID of the container to detach from
+     */
+    detachStreamFromElement(streamId: string, containerElementId: string): void;
+    /**
+     * Detach a stream from ALL elements (all video containers + audio)
+     * Removes all video elements and audio element for this stream
+     *
+     * @param streamId - ID of the stream to fully detach
+     */
+    detachStream(streamId: string): void;
+    /**
+     * Clean up all tracked streams and elements
+     * Detaches all video and audio elements
+     * Call this on session destroy
+     */
+    cleanup(): void;
+    /**
+     * Check if a stream is attached to any elements
+     * @param streamId - ID of the stream to check
+     * @returns true if stream has any attachments (video or audio)
+     */
+    isStreamAttached(streamId: string): boolean;
+    /**
+     * Get all container IDs that a stream is attached to
+     * @param streamId - ID of the stream
+     * @returns Array of container element IDs
+     */
+    getStreamAttachments(streamId: string): string[];
+    /**
+     * Update tracks in DOM elements for local media preview
+     * Used when device changes to replace old tracks with new tracks
+     * This is for local media only (getUserMedia streams), not remote streams
+     *
+     * @param newTrack - New track to replace in DOM elements
+     * @param streamElementMappings - Map of element tracking from EselfSession
+     */
+    updateLocalMediaTracks(newTrack: MediaStreamTrack, streamElementMappings: Map<string, {
+        audioElement: HTMLAudioElement | null;
+        videoElement: HTMLVideoElement | null;
+        videoContainerId: string | null;
+    }>): void;
+}
+export default EselfDOMManager;

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

@@ -0,0 +1 @@
+export { EselfDOMManager, default as EselfDOMManagerDefault, } from './EselfDOMManager';

package/src/lib/eself-demo.d.ts

@@ -0,0 +1 @@
+export declare const HiFromEsSelf: () => void;