@camstack/addon-webrtc-adaptive 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-webrtc-adaptive",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Adaptive WebRTC streaming engine for CamStack — quality adaptation, RTCP monitoring, multi-camera",
   "keywords": [
     "camstack",

package/dist/addon--i9xjbhN.d.cts

@@ -1,561 +0,0 @@
-import { ICamstackAddon, IConfigurable, AddonManifest, AddonContext, CapabilityProviderMap, ConfigUISchema } from '@camstack/types';
-import { EventEmitter } from 'node:events';
-
-/**
- * Core types for media stream servers.
- * Protocol-agnostic frame types used across all server implementations.
- */
-type VideoCodec = "H264" | "H265";
-type AudioCodec = "Aac" | "Adpcm" | "Opus" | "Pcmu" | "Pcma";
-/**
- * A single video frame in Annex-B format (with start codes).
- */
-interface VideoFrame {
-    /** Raw video data in Annex-B format (NAL units with 0x00000001 start codes) */
-    data: Buffer;
-    /** Video codec type */
-    codec: VideoCodec;
-    /** True if this is a keyframe (IDR for H.264, IRAP for H.265) */
-    isKeyframe: boolean;
-    /** Presentation timestamp in microseconds (monotonic) */
-    timestampMicros: number;
-    /** Optional: frame width in pixels */
-    width?: number;
-    /** Optional: frame height in pixels */
-    height?: number;
-}
-/**
- * A single audio frame.
- * For AAC: data should include ADTS headers.
- * For other codecs: raw audio samples.
- */
-interface AudioFrame {
-    /** Raw audio data */
-    data: Buffer;
-    /** Audio codec */
-    codec: AudioCodec;
-    /** Sample rate in Hz */
-    sampleRate: number;
-    /** Number of channels */
-    channels: number;
-    /** Presentation timestamp in microseconds */
-    timestampMicros: number;
-}
-/**
- * Tagged union for video/audio frames.
- */
-type MediaFrame = {
-    type: "video";
-    frame: VideoFrame;
-} | {
-    type: "audio";
-    frame: AudioFrame;
-};
-/**
- * Primary frame source interface.
- * Yields MediaFrame objects. Returning from the generator signals end of stream.
- * Throwing signals an error that should trigger reconnection.
- */
-type FrameSource = AsyncGenerator<MediaFrame, void, unknown>;
-/**
- * Factory that creates a new FrameSource.
- * Called each time the server needs to start/restart the stream.
- * The server is responsible for calling return() to stop the source.
- */
-type FrameSourceFactory = () => FrameSource;
-/**
- * Minimal logger interface compatible with console.
- */
-interface Logger {
-    log(message?: unknown, ...args: unknown[]): void;
-    info(message?: unknown, ...args: unknown[]): void;
-    warn(message?: unknown, ...args: unknown[]): void;
-    error(message?: unknown, ...args: unknown[]): void;
-    debug(message?: unknown, ...args: unknown[]): void;
-}
-/**
- * Accept Console or partial Logger implementations.
- */
-type LoggerLike = Partial<Logger> | Console;
-/**
- * Wrap a LoggerLike into a full Logger (no-op for missing methods).
- */
-declare function asLogger(logger?: LoggerLike): Logger;
-/**
- * Create a logger that discards all output.
- */
-declare function createNullLogger(): Logger;
-
-/**
- * Adaptive FFmpeg source — RTSP→FrameSource pipeline with hot-swappable encoding params.
- *
- * Spawns ffmpeg to transcode an RTSP source to raw H.264 Annex-B on stdout.
- * Supports dynamic bitrate/resolution changes by restarting ffmpeg with new params,
- * gating the transition on the next keyframe to avoid visual artifacts.
- */
-
-interface EncodingParams {
-    /** Max video bitrate in kbps (e.g. 8000 for 8 Mbps). */
-    maxBitrateKbps: number;
-    /** Output width (0 = keep source). */
-    width: number;
-    /** Output height (0 = keep source). */
-    height: number;
-    /** H.264 preset (default: "ultrafast"). */
-    preset?: string;
-}
-/** Audio mode: "copy" = passthrough G.711, "opus" = transcode to Opus, "off" = no audio */
-type AudioMode = "copy" | "opus" | "off";
-interface AdaptiveFfmpegSourceOptions {
-    /** RTSP source URL. */
-    rtspUrl: string;
-    /** Initial encoding parameters. */
-    initialParams: EncodingParams;
-    /** Audio mode (default: "copy"). */
-    audioMode?: AudioMode;
-    /** FFmpeg binary path (default: "ffmpeg"). */
-    ffmpegPath?: string;
-    /** Logger instance. */
-    logger?: Logger;
-    /** Label for logging. */
-    label?: string;
-}
-declare class AdaptiveFfmpegSource {
-    private readonly rtspUrl;
-    private readonly ffmpegPath;
-    private readonly logger;
-    private readonly label;
-    private readonly audioMode;
-    private currentParams;
-    private proc;
-    private audioProc;
-    private closed;
-    /** Push callback for the frame source. */
-    private pushFrame;
-    private closeSource;
-    /** The FrameSource async generator. Created once, survives ffmpeg restarts. */
-    readonly source: FrameSource;
-    constructor(options: AdaptiveFfmpegSourceOptions);
-    /** Start the ffmpeg process with current encoding params. */
-    start(): Promise<void>;
-    /** Get the current encoding parameters. */
-    getParams(): Readonly<EncodingParams>;
-    /**
-     * Hot-swap encoding parameters.
-     * Stops the current ffmpeg and starts a new one with updated params.
-     * The FrameSource continues seamlessly — the new ffmpeg's first keyframe
-     * is gated internally so consumers see a clean transition.
-     */
-    updateParams(params: Partial<EncodingParams>): Promise<void>;
-    /** Stop the source and kill ffmpeg. */
-    stop(): Promise<void>;
-    private spawnFfmpeg;
-    private killFfmpeg;
-}
-
-/**
- * Adaptive quality controller — state machine for bitrate/resolution/source adaptation.
- *
- * Monitors packet loss, jitter, and RTT from RTCP reports and client-reported stats.
- * Makes quality decisions using a three-tier degradation/recovery model:
- *
- * Level 1 — Reduce bitrate cap (ffmpeg -maxrate)
- * Level 2 — Downscale resolution (ffmpeg -vf scale=)
- * Level 3 — Switch source stream (main → sub via replaceTrack)
- *
- * Hysteresis prevents oscillation: degradation requires 2 consecutive bad intervals,
- * recovery requires 3 consecutive good intervals.
- */
-
-type QualityTier = "high" | "medium" | "low";
-interface QualityProfile {
-    tier: QualityTier;
-    /** Encoding params to apply. */
-    encoding: EncodingParams;
-    /** Source stream profile ("main" | "sub"). */
-    sourceProfile: "main" | "sub";
-}
-interface StreamStats {
-    /** Packet loss ratio (0.0 – 1.0). */
-    packetLoss: number;
-    /** Jitter in milliseconds. */
-    jitterMs: number;
-    /** Round-trip time in milliseconds. */
-    rttMs: number;
-    /** Timestamp of this measurement. */
-    timestamp: number;
-}
-interface AdaptiveControllerOptions {
-    /** Available quality profiles, ordered from highest to lowest. */
-    profiles: QualityProfile[];
-    /** Packet loss threshold to degrade (default: 0.02 = 2%). */
-    degradeThreshold?: number;
-    /** Packet loss threshold to recover (default: 0.005 = 0.5%). */
-    recoverThreshold?: number;
-    /** Consecutive bad intervals before degradation (default: 2). */
-    degradeCount?: number;
-    /** Consecutive good intervals before recovery (default: 3). */
-    recoverCount?: number;
-    /** Callback when quality should change. */
-    onQualityChange: (from: QualityProfile, to: QualityProfile) => void | Promise<void>;
-    /** Logger. */
-    logger?: Logger;
-}
-declare class AdaptiveController {
-    private readonly profiles;
-    private readonly degradeThreshold;
-    private readonly recoverThreshold;
-    private readonly degradeCount;
-    private readonly recoverCount;
-    private readonly onQualityChange;
-    private readonly logger;
-    private currentIndex;
-    private consecutiveBad;
-    private consecutiveGood;
-    private switching;
-    /** Smoothed stats per session (aggregated for decisions). */
-    private readonly sessionStats;
-    /** Manual override tier (null = auto). */
-    private forcedTier;
-    constructor(options: AdaptiveControllerOptions);
-    /** Get the current quality profile. */
-    get currentProfile(): QualityProfile;
-    /** Get the current quality tier. */
-    get currentTier(): QualityTier;
-    /** Get aggregated stats summary. */
-    getAggregatedStats(): {
-        packetLoss: number;
-        jitterMs: number;
-        rttMs: number;
-    };
-    /**
-     * Report stats from a session (RTCP or client-reported).
-     * Call this periodically (e.g. every 3–5 seconds).
-     */
-    reportStats(sessionId: string, stats: StreamStats): void;
-    /** Remove a session's stats (call on session close). */
-    removeSession(sessionId: string): void;
-    /** Force a specific quality tier (null = auto). */
-    forceQuality(tier: QualityTier | null): void;
-    /** Check if auto-adaptation is active (not forced). */
-    get isAuto(): boolean;
-    private evaluate;
-    private degrade;
-    private recover;
-    private switchTo;
-}
-
-/**
- * Adaptive WebRTC session — extends the base session pattern with:
- * - RTCP Receiver Report monitoring (packet loss, jitter, RTT)
- * - Source replacement (replaceTrack for seamless quality switching)
- * - Stats emission for the AdaptiveController
- *
- * Uses werift (optional peer dependency) for server-side WebRTC.
- */
-
-interface AdaptiveSessionOptions {
-    sessionId: string;
-    source: FrameSource;
-    intercom?: {
-        onAudioReceived: (data: Buffer, format: AudioCodec) => void | Promise<void>;
-    };
-    iceConfig?: {
-        stunServers?: string[];
-        turnServers?: Array<{
-            urls: string;
-            username?: string;
-            credential?: string;
-        }>;
-        portRange?: [number, number];
-        additionalHostAddresses?: string[];
-    };
-    /** Callback for RTCP stats (called every ~3s). */
-    onStats?: (stats: SessionStats) => void;
-    /** Enable verbose frame/RTP logging. */
-    debug?: boolean;
-    logger: Logger;
-}
-interface SessionStats {
-    sessionId: string;
-    /** Fraction of packets lost (0.0–1.0). */
-    packetLoss: number;
-    /** Interarrival jitter in ms. */
-    jitterMs: number;
-    /** Round-trip time in ms (from RTCP SR/RR). */
-    rttMs: number;
-    /** Total packets received. */
-    packetsReceived: number;
-    /** Total packets lost. */
-    packetsLost: number;
-    /** Timestamp. */
-    timestamp: number;
-}
-interface SessionInfo {
-    sessionId: string;
-    state: "new" | "connecting" | "connected" | "disconnected" | "closed";
-    createdAt: number;
-}
-declare class AdaptiveSession {
-    private readonly sessionId;
-    private source;
-    private readonly logger;
-    private readonly intercom;
-    private readonly iceConfig;
-    private readonly onStats;
-    readonly debug: boolean;
-    private readonly createdAt;
-    private state;
-    private pc;
-    private videoTrack;
-    private audioTrack;
-    /** Transceiver senders for direct sendRtp (more reliable than track.writeRtp) */
-    private videoSender;
-    private audioSender;
-    private feedAbort;
-    private closed;
-    private statsTimer;
-    /** RTP sequence number counter (must increment per packet). */
-    private videoSeqNum;
-    private audioSeqNum;
-    /** Previous RTCP stats for delta calculation. */
-    private prevPacketsReceived;
-    private prevPacketsLost;
-    constructor(options: AdaptiveSessionOptions);
-    /** Build PeerConnection options including H.264 codec config. */
-    private buildPcOptions;
-    /** Create offer SDP (server → client). */
-    createOffer(): Promise<{
-        sdp: string;
-        type: "offer";
-    }>;
-    /** Handle WHEP answer: client sends SDP answer, we set remote description and start feeding. */
-    handleAnswer(answer: {
-        sdp: string;
-        type: "answer";
-    }): Promise<void>;
-    /**
-     * Handle WHEP offer: client sends SDP offer, we create answer.
-     *
-     * Uses the server-creates-offer pattern internally: we create our own offer
-     * with sendonly tracks, then use the client's offer codecs to build a
-     * compatible answer. This avoids werift transceiver direction issues.
-     */
-    handleOffer(clientOffer: {
-        sdp: string;
-        type: "offer";
-    }): Promise<{
-        sdp: string;
-        type: "answer";
-    }>;
-    /** Add ICE candidate. */
-    addIceCandidate(candidate: any): Promise<void>;
-    /**
-     * Detach the frame source (for connection pooling).
-     * The session stays alive (ICE/DTLS connected) but stops feeding frames.
-     * Call replaceSource() later to reattach a camera.
-     */
-    detachSource(): void;
-    /** Whether the session has an active feed (vs idle/pooled). */
-    get isFeeding(): boolean;
-    /**
-     * Replace the frame source (for seamless source switching).
-     * The new source will take effect at the next keyframe.
-     */
-    replaceSource(newSource: FrameSource): void;
-    getInfo(): SessionInfo;
-    close(): Promise<void>;
-    private startFeedingFrames;
-    /** Build a serialized RTP packet for sender.sendRtp(). */
-    private buildRtpBuffer;
-    /** Max RTP payload size (MTU 1200 to stay under typical network MTU). */
-    private static readonly MAX_RTP_PAYLOAD;
-    private rtpPacketsSent;
-    private writeVideoNals;
-    private writeAudio;
-    private startStatsCollection;
-    private collectStats;
-}
-
-/**
- * Adaptive WebRTC streaming server — multi-camera manager with quality adaptation.
- *
- * For each camera:
- * - Spawns AdaptiveFfmpegSource to transcode RTSP → H.264 with configurable params
- * - Uses StreamFanout to distribute frames to multiple viewer sessions
- * - AdaptiveController monitors stats and adjusts quality per-camera
- *
- * Usage:
- *   const server = new AdaptiveStreamServer({ ... });
- *   server.addCamera("front_door", { rtspUrl: "rtsp://...", profiles: [...] });
- *   const { sessionId, answer } = await server.handleWhepOffer("front_door", sdpOffer);
- */
-
-interface AdaptiveStreamServerOptions {
-    /** FFmpeg binary path (default: "ffmpeg"). */
-    ffmpegPath?: string;
-    /** STUN servers for ICE. */
-    stunServers?: string[];
-    /** TURN servers for ICE. */
-    turnServers?: Array<{
-        urls: string;
-        username?: string;
-        credential?: string;
-    }>;
-    /** ICE port range. */
-    icePortRange?: [number, number];
-    /** Additional host IPs to announce. */
-    iceAdditionalHostAddresses?: string[];
-    /** Logger. */
-    logger?: Logger;
-}
-interface CameraConfig {
-    /** Primary RTSP source URL (typically main stream). */
-    rtspUrl: string;
-    /** Secondary RTSP source URL (typically sub stream, for Level 3 switching). */
-    subRtspUrl?: string;
-    /** Quality profiles ordered from highest to lowest quality. */
-    profiles: QualityProfile[];
-    /** Audio mode: "copy" (G.711 passthrough), "opus" (transcode), "off" (no audio). Default: "copy". */
-    audioMode?: "copy" | "opus" | "off";
-}
-/** Default quality profiles for adaptive streaming. */
-declare function createDefaultProfiles(): QualityProfile[];
-declare class AdaptiveStreamServer extends EventEmitter {
-    private readonly ffmpegPath;
-    private readonly stunServers;
-    private readonly turnServers;
-    private readonly icePortRange;
-    private readonly iceAdditionalHostAddresses;
-    private readonly logger;
-    private readonly cameras;
-    private readonly sessionCamera;
-    private stopped;
-    constructor(options?: AdaptiveStreamServerOptions);
-    /** Register a camera with adaptive streaming. */
-    addCamera(name: string, config: CameraConfig): void;
-    /** Remove a camera and close all its sessions. */
-    removeCamera(name: string): Promise<void>;
-    getCameraNames(): string[];
-    /**
-     * Create an adaptive session for a camera.
-     * Returns a server-generated SDP offer that the client must answer.
-     *
-     * Flow: createSession() → server offer → client sets remote, creates answer → handleAnswer()
-     */
-    createSession(cameraName: string): Promise<{
-        sessionId: string;
-        sdpOffer: string;
-    }>;
-    /**
-     * Handle the client's SDP answer for an adaptive session.
-     * Call after createSession() with the client's answer.
-     */
-    handleAnswer(sessionId: string, sdpAnswer: string): Promise<void>;
-    /**
-     * Convenience: handleWhepOffer is NOT supported — werift requires server-initiated offers.
-     * Use createSession() + handleAnswer() instead.
-     */
-    handleWhepOffer(_cameraName: string, _sdpOffer: string): Promise<{
-        sessionId: string;
-        sdpAnswer: string;
-    }>;
-    /** Pooled sessions: sessionId → true (idle, no camera attached). */
-    private readonly pooledSessions;
-    /**
-     * Create a pooled session (no camera attached yet).
-     * The SDP exchange happens, ICE connects, but no ffmpeg is started.
-     * Call attachCamera() later to start feeding frames.
-     */
-    createPooledSession(): Promise<{
-        sessionId: string;
-        sdpOffer: string;
-    }>;
-    /**
-     * Attach a camera to a pooled session.
-     * Starts the ffmpeg transcoder and begins feeding frames.
-     */
-    attachCamera(sessionId: string, cameraName: string): Promise<void>;
-    /**
-     * Detach a camera from a session (session returns to pool).
-     */
-    detachCamera(sessionId: string): Promise<void>;
-    /** Check if a session is in the idle pool. */
-    isPooledSession(sessionId: string): boolean;
-    /** Set debug flag on all sessions for a camera. */
-    setDebug(cameraName: string, debug: boolean): number;
-    /** Get count of idle pooled sessions. */
-    getPoolSize(): number;
-    /** Close a specific session. */
-    closeSession(sessionId: string): Promise<void>;
-    /**
-     * Report client-side stats for a session (supplements RTCP monitoring).
-     * Call from tRPC route when the client pushes stats.
-     */
-    reportClientStats(sessionId: string, stats: StreamStats): {
-        currentTier: QualityTier;
-        currentBitrateKbps: number;
-        currentResolution: {
-            width: number;
-            height: number;
-        };
-        sourceProfile: "main" | "sub";
-    } | null;
-    /** Force quality for a camera (null = auto). */
-    forceQuality(cameraName: string, tier: QualityTier | null): boolean;
-    /** Get current quality info for a camera. */
-    getCameraQuality(cameraName: string): {
-        tier: QualityTier;
-        encoding: EncodingParams;
-        isAuto: boolean;
-        stats: {
-            packetLoss: number;
-            jitterMs: number;
-            rttMs: number;
-        };
-        sessionCount: number;
-        sourceProfile: "main" | "sub";
-    } | null;
-    /** Get all sessions. */
-    getSessions(cameraName?: string): SessionInfo[];
-    getSessionCount(cameraName?: string): number;
-    /** Stop all cameras and sessions. */
-    stop(): Promise<void>;
-    /** Get the currently active fanout for a camera. */
-    private getActiveFanout;
-    private ensureCameraRunning;
-    private scheduleCameraAutoStop;
-    /**
-     * Handle a quality change from the AdaptiveController.
-     * When the sourceProfile changes (main ↔ sub), performs a seamless source
-     * switch for all active sessions. When only encoding params change (same
-     * sourceProfile), updates ffmpeg params in-place.
-     */
-    private handleQualityChange;
-    /**
-     * Switch all active sessions from one source to another (main ↔ sub).
-     *
-     * Steps:
-     * 1. Create/start the target ffmpeg source + fanout
-     * 2. For each session: subscribe to new fanout, call replaceSource()
-     * 3. Unsubscribe all from old fanout
-     * 4. Stop old ffmpeg + fanout (save resources)
-     * 5. Update activeSourceProfile
-     */
-    private switchSource;
-}
-
-declare class WebrtcAdaptiveAddon implements ICamstackAddon, IConfigurable {
-    readonly manifest: AddonManifest;
-    private server;
-    private currentConfig;
-    initialize(context: AddonContext): Promise<void>;
-    shutdown(): Promise<void>;
-    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
-    getConfigSchema(): ConfigUISchema;
-    getConfig(): Record<string, unknown>;
-    onConfigChange(config: Record<string, unknown>): Promise<void>;
-    getServer(): AdaptiveStreamServer | null;
-}
-
-export { type AudioFrame as A, type CameraConfig as C, type EncodingParams as E, type FrameSource as F, type Logger as L, type MediaFrame as M, type QualityProfile as Q, type SessionInfo as S, type VideoCodec as V, WebrtcAdaptiveAddon as W, type VideoFrame as a, AdaptiveController as b, type AdaptiveControllerOptions as c, AdaptiveFfmpegSource as d, type AdaptiveFfmpegSourceOptions as e, AdaptiveSession as f, type AdaptiveSessionOptions as g, AdaptiveStreamServer as h, type AdaptiveStreamServerOptions as i, type AudioCodec as j, type AudioMode as k, type FrameSourceFactory as l, type LoggerLike as m, type QualityTier as n, type SessionStats as o, type StreamStats as p, asLogger as q, createDefaultProfiles as r, createNullLogger as s };