@agatx/serenada-core 0.6.10

package/dist/media/AudioLevelMonitor.d.ts

@@ -0,0 +1,51 @@
+import type { SerenadaLogger } from '../types.js';
+export interface AudioLevelMonitorOptions {
+    /** AnalyserNode smoothingTimeConstant (0..1). Defaults to 0.5. */
+    smoothing?: number;
+    /** AnalyserNode FFT size — power of two. Defaults to 1024. */
+    fftSize?: number;
+    /** Subscriber notification interval in ms. Defaults to 100. */
+    updateIntervalMs?: number;
+    /** Reuse an existing AudioContext (the monitor will not close it on dispose). */
+    audioContext?: AudioContext;
+    /** Optional logger for diagnostics. */
+    logger?: SerenadaLogger;
+}
+type LevelCallback = (level: number) => void;
+/**
+ * Computes a normalized speech audio level (0..1) from a MediaStream's audio
+ * track using the Web Audio API. Use it to drive UI activity indicators.
+ *
+ * The monitor is lazy: it only runs the analysis loop while at least one
+ * subscriber is attached. Call {@link dispose} when the stream is gone or
+ * the consumer goes away.
+ */
+export declare class AudioLevelMonitor {
+    private context;
+    private analyser;
+    private source;
+    private buffer;
+    private timer;
+    private subscribers;
+    private currentLevel;
+    private disposed;
+    private readonly ownsContext;
+    private readonly updateIntervalMs;
+    private readonly logger?;
+    constructor(stream: MediaStream, options?: AudioLevelMonitorOptions);
+    /** Returns the most recent level computed by the monitor (0..1). */
+    get level(): number;
+    /**
+     * Subscribe for level updates. The callback fires immediately with the
+     * current level, then at {@link AudioLevelMonitorOptions.updateIntervalMs}.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: LevelCallback): () => void;
+    dispose(): void;
+    private startLoop;
+    private stopLoop;
+    private tick;
+    private cleanup;
+}
+export {};
+//# sourceMappingURL=AudioLevelMonitor.d.ts.map

package/dist/media/AudioLevelMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioLevelMonitor.d.ts","sourceRoot":"","sources":["../../src/media/AudioLevelMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD,MAAM,WAAW,wBAAwB;IACrC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,uCAAuC;IACvC,MAAM,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7C;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;gBAE7B,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,wBAA6B;IA0CvE,oEAAoE;IACpE,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;IAkB9C,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,IAAI;IA0BZ,OAAO,CAAC,OAAO;CAiBlB"}

package/dist/media/AudioLevelMonitor.js

@@ -0,0 +1,179 @@
+/** Update frequency for audio level subscribers. 10 Hz pairs well with 100 ms CSS transitions. */
+const DEFAULT_UPDATE_INTERVAL_MS = 100;
+/** Default FFT size — small for low CPU; we only need a coarse RMS. */
+const DEFAULT_FFT_SIZE = 1024;
+/** Default smoothing applied by the analyser node (0..1). */
+const DEFAULT_SMOOTHING = 0.5;
+/** dBFS at which the indicator reads zero. Quieter than this is treated as silence. */
+const NOISE_FLOOR_DB = -60;
+/** dBFS at which the indicator reads full. Normal speech peaks around -20 to -15 dBFS. */
+const SPEECH_PEAK_DB = -15;
+/** Attack/release smoothing across ticks (0..1). Higher = stickier; 0 = no smoothing. */
+const ATTACK_SMOOTHING = 0.4;
+const RELEASE_SMOOTHING = 0.7;
+/**
+ * Computes a normalized speech audio level (0..1) from a MediaStream's audio
+ * track using the Web Audio API. Use it to drive UI activity indicators.
+ *
+ * The monitor is lazy: it only runs the analysis loop while at least one
+ * subscriber is attached. Call {@link dispose} when the stream is gone or
+ * the consumer goes away.
+ */
+export class AudioLevelMonitor {
+    context = null;
+    analyser = null;
+    source = null;
+    buffer = null;
+    timer = null;
+    subscribers = new Set();
+    currentLevel = 0;
+    disposed = false;
+    ownsContext;
+    updateIntervalMs;
+    logger;
+    constructor(stream, options = {}) {
+        this.updateIntervalMs = options.updateIntervalMs ?? DEFAULT_UPDATE_INTERVAL_MS;
+        this.logger = options.logger;
+        this.ownsContext = !options.audioContext;
+        const Ctx = typeof globalThis !== 'undefined'
+            ? (globalThis
+                .AudioContext
+                ?? globalThis.webkitAudioContext)
+            : undefined;
+        if (!Ctx && !options.audioContext) {
+            this.logger?.log('debug', 'AudioLevelMonitor', 'AudioContext unavailable; monitor will report zero level');
+            return;
+        }
+        if (stream.getAudioTracks().length === 0) {
+            this.logger?.log('debug', 'AudioLevelMonitor', 'Stream has no audio tracks');
+            return;
+        }
+        try {
+            this.context = options.audioContext ?? new Ctx();
+            this.analyser = this.context.createAnalyser();
+            this.analyser.fftSize = options.fftSize ?? DEFAULT_FFT_SIZE;
+            this.analyser.smoothingTimeConstant = options.smoothing ?? DEFAULT_SMOOTHING;
+            this.source = this.context.createMediaStreamSource(stream);
+            this.source.connect(this.analyser);
+            this.buffer = new Uint8Array(new ArrayBuffer(this.analyser.fftSize));
+            // Browsers may create the context in a suspended state until a user gesture;
+            // resume it so analysis starts producing samples immediately.
+            if (this.context.state === 'suspended') {
+                void this.context.resume().catch((err) => {
+                    this.logger?.log('debug', 'AudioLevelMonitor', `resume() failed: ${err}`);
+                });
+            }
+        }
+        catch (err) {
+            this.logger?.log('warning', 'AudioLevelMonitor', `Failed to attach to stream: ${err}`);
+            this.cleanup();
+        }
+    }
+    /** Returns the most recent level computed by the monitor (0..1). */
+    get level() {
+        return this.currentLevel;
+    }
+    /**
+     * Subscribe for level updates. The callback fires immediately with the
+     * current level, then at {@link AudioLevelMonitorOptions.updateIntervalMs}.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback) {
+        if (this.disposed) {
+            callback(0);
+            return () => { };
+        }
+        this.subscribers.add(callback);
+        callback(this.currentLevel);
+        if (this.analyser && this.subscribers.size === 1) {
+            this.startLoop();
+        }
+        return () => {
+            this.subscribers.delete(callback);
+            if (this.subscribers.size === 0) {
+                this.stopLoop();
+            }
+        };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.cleanup();
+    }
+    startLoop() {
+        if (this.timer !== null)
+            return;
+        const setIntervalFn = typeof globalThis !== 'undefined' && typeof globalThis.setInterval === 'function'
+            ? globalThis.setInterval.bind(globalThis)
+            : null;
+        if (!setIntervalFn)
+            return;
+        this.timer = setIntervalFn(() => this.tick(), this.updateIntervalMs);
+    }
+    stopLoop() {
+        if (this.timer === null)
+            return;
+        const clearIntervalFn = typeof globalThis !== 'undefined' && typeof globalThis.clearInterval === 'function'
+            ? globalThis.clearInterval.bind(globalThis)
+            : null;
+        clearIntervalFn?.(this.timer);
+        this.timer = null;
+    }
+    tick() {
+        if (this.disposed || !this.analyser || !this.buffer)
+            return;
+        if (this.context?.state === 'suspended') {
+            void this.context.resume().catch(() => { });
+        }
+        this.analyser.getByteTimeDomainData(this.buffer);
+        let sumSquares = 0;
+        for (let i = 0; i < this.buffer.length; i++) {
+            const sample = (this.buffer[i] - 128) / 128;
+            sumSquares += sample * sample;
+        }
+        const rms = Math.sqrt(sumSquares / this.buffer.length);
+        // Map RMS to dBFS, then to a perceptual 0..1 between the noise floor and speech peak.
+        const dbfs = rms > 0 ? 20 * Math.log10(rms) : NOISE_FLOOR_DB;
+        const target = Math.max(0, Math.min(1, (dbfs - NOISE_FLOOR_DB) / (SPEECH_PEAK_DB - NOISE_FLOOR_DB)));
+        // Asymmetric smoothing: snap up quickly (attack), decay slowly (release).
+        const smoothing = target > this.currentLevel ? ATTACK_SMOOTHING : RELEASE_SMOOTHING;
+        const level = this.currentLevel * smoothing + target * (1 - smoothing);
+        this.currentLevel = level;
+        this.subscribers.forEach((cb) => {
+            try {
+                cb(level);
+            }
+            catch (err) {
+                this.logger?.log('warning', 'AudioLevelMonitor', `Subscriber threw: ${err}`);
+            }
+        });
+    }
+    cleanup() {
+        this.stopLoop();
+        if (this.source) {
+            try {
+                this.source.disconnect();
+            }
+            catch { /* ignore */ }
+            this.source = null;
+        }
+        if (this.analyser) {
+            try {
+                this.analyser.disconnect();
+            }
+            catch { /* ignore */ }
+            this.analyser = null;
+        }
+        if (this.context && this.ownsContext) {
+            try {
+                void this.context.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.context = null;
+        this.buffer = null;
+        this.subscribers.clear();
+    }
+}
+//# sourceMappingURL=AudioLevelMonitor.js.map

package/dist/media/AudioLevelMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioLevelMonitor.js","sourceRoot":"","sources":["../../src/media/AudioLevelMonitor.ts"],"names":[],"mappings":"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"}

package/dist/media/MediaEngine.d.ts

@@ -0,0 +1,137 @@
+import type { RoomState, SignalingMessage } from '../signaling/types.js';
+import type { ConnectionStatus, SerenadaLogger } from '../types.js';
+export interface MediaEngineConfig {
+    turnsOnly?: boolean;
+    logger?: SerenadaLogger;
+    /** Initial camera facing mode. Defaults to `'user'` (selfie). */
+    initialFacingMode?: 'user' | 'environment';
+    /** When `false`, media starts audio-only and camera is requested on first video enable. */
+    initialVideoEnabled?: boolean;
+    /** When `false`, the camera is never requested and video is always off. */
+    videoCaptureSupported?: boolean;
+}
+export declare class MediaEngine {
+    localStream: MediaStream | null;
+    remoteStreams: Map<string, MediaStream>;
+    isScreenSharing: boolean;
+    canScreenShare: boolean;
+    facingMode: 'user' | 'environment';
+    hasMultipleCameras: boolean;
+    readonly videoCaptureSupported: boolean;
+    iceConnectionState: RTCIceConnectionState;
+    connectionState: RTCPeerConnectionState;
+    signalingState: RTCSignalingState;
+    connectionStatus: ConnectionStatus;
+    private peers;
+    private readonly initialVideoEnabled;
+    private lastInboundBytesByCid;
+    private rtcConfig;
+    private screenShareTrack;
+    private requestingMedia;
+    private destroyed;
+    private cameraRecoveryInFlight;
+    private mediaRequestId;
+    private retryingTimer;
+    private localVideoHeartbeatAt;
+    private localVideoHiddenAt;
+    private visibilityHandler;
+    private pageShowHandler;
+    private heartbeatInterval;
+    private onlineHandler;
+    private networkChangeHandler;
+    private deviceChangeHandler;
+    private turnsOnly;
+    private logger?;
+    private sendSignalingMessage;
+    private roomState;
+    private clientId;
+    private isSignalingConnected;
+    private onChange;
+    constructor(config: MediaEngineConfig, sendMessage: (type: string, payload?: Record<string, unknown>, to?: string) => void);
+    setOnChange(cb: () => void): void;
+    updateRoomState(state: RoomState | null, clientId: string | null): void;
+    updateSignalingConnected(connected: boolean): void;
+    setIceServers(iceServers: RTCIceServer[]): void;
+    handleSignalingReconnect(): void;
+    /**
+     * Schedule glare-safe ICE restart for a specific peer because the server
+     * told us the pair is dirty after the peer reattached (#1).
+     */
+    scheduleDirtyPairRestart(remoteCid: string): void;
+    processSignalingMessage(msg: SignalingMessage): void;
+    startLocalMedia(): Promise<MediaStream | null>;
+    stopLocalMedia(): void;
+    releaseVideoTrack(): Promise<void>;
+    reacquireVideoTrack(): Promise<void>;
+    startScreenShare(): Promise<void>;
+    stopScreenShare(): Promise<void>;
+    flipCamera(): Promise<void>;
+    getPeerConnections(): RTCPeerConnection[];
+    getPeerConnectionsMap(): Map<string, RTCPeerConnection>;
+    cleanupAllPeers(): void;
+    /**
+     * Sample inbound RTP `bytesReceived` per remote peer and return the CIDs
+     * whose totals advanced since the previous sample. Drives #3's
+     * `media_liveness{cids}` emission so the server can defer hard-eviction
+     * of suspended peers whose media is still being received locally.
+     *
+     * Conservative on first call (no baseline → empty result). Cleans up
+     * tracking for peers that have left.
+     */
+    getInboundFlowingCids(): Promise<string[]>;
+    destroy(): void;
+    /**
+     * Inspects each peer connection's currently-selected ICE candidate pair
+     * and returns true only when at least one peer exists and every peer's
+     * local candidate is direct (host / srflx / prflx). Returns false when
+     * any peer is relaying through TURN, when any stats query fails, or when
+     * there are no peers (TURN may be needed for a future join).
+     *
+     * We identify the active pair via `RTCTransportStats.selectedCandidatePairId`,
+     * with a fallback to the nominated+succeeded pair. We do NOT accept any
+     * arbitrary succeeded pair: after an ICE failover the old pair stays
+     * present as "succeeded" for a while, so reading it would lie about the
+     * current active path and wrongly suppress TURN refresh while media is
+     * actually relaying.
+     *
+     * Used by the TURN refresh gate: if all active media flows are direct,
+     * refreshing TURN credentials over signaling is unnecessary upkeep. This
+     * lets a P2P call survive indefinite signaling outages.
+     */
+    arePeerPathsAllDirect(): Promise<boolean>;
+    private isPeerOnDirectPath;
+    private syncPeers;
+    private getOrCreatePeer;
+    private cleanupPeer;
+    private clearPeerTimers;
+    private shouldIOffer;
+    private createOfferTo;
+    private scheduleIceRestart;
+    private triggerIceRestart;
+    private scheduleNonHostFallback;
+    private handleOfferFrom;
+    private handleAnswerFrom;
+    private handleIceFrom;
+    private updateAggregateState;
+    private updateConnectionStatusValue;
+    private resetConnectionStatusMachine;
+    private setConnectionRecovering;
+    private scheduleRetryingTransition;
+    private normalizeIceServers;
+    private applySpeechTrackHints;
+    private applyAudioSenderParameters;
+    private acquireCameraTrack;
+    private replaceVideoTrackOnAllPeers;
+    private swapLocalVideoTrack;
+    private ensureMediaTransceivers;
+    private findTransceiver;
+    private attachLocalTracksToPeer;
+    private attachLocalTrackToPeer;
+    private scheduleLocalTrackNegotiation;
+    private refreshLocalVideoTrack;
+    private detectCameras;
+    private setupEventListeners;
+    private removeEventListeners;
+    private notifyChange;
+}
+//# sourceMappingURL=MediaEngine.d.ts.map

package/dist/media/MediaEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MediaEngine.d.ts","sourceRoot":"","sources":["../../src/media/MediaEngine.ts"],"names":[],"mappings":"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"}