@openmoq/playback 0.0.0-stage → 0.6.1

package/dist/adaptive-tolerance.js

@@ -0,0 +1,339 @@
+/**
+ * Adaptive jitter tolerance controller.
+ *
+ * Auto-calibrates gap timeout and drift threshold from observed network
+ * jitter. Implements graduated recovery (monitoring → extended wait → skip)
+ * with stall-count escalation and exponential decay.
+ *
+ * Sans-I/O: time is an explicit parameter, no browser APIs.
+ * All state is flat and mutable in place — zero allocations in the hot path.
+ *
+ * @see draft-ietf-moq-loc-01 §2.3.1.1 (CaptureTimestamp)
+ * @module
+ */
+// ─── Recovery phases ────────────────────────────────────────────────
+export const RecoveryPhase = {
+    /** Baseline — no active jitter issues. */
+    Normal: 'normal',
+    /** Gap detected, observing whether transient or persistent. */
+    Monitoring: 'monitoring',
+    /** Persistent gap — waiting with extended timeout before skipping. */
+    ExtendedWait: 'extended_wait',
+};
+export const DEFAULT_TOLERANCE_CONFIG = {
+    emaAlpha: 0.125, // 1/8 — RFC 6298 gain
+    varianceAlpha: 0.25, // 1/4 — RFC 6298 gain
+    slidingWindowSize: 128, // ~4s at 30fps
+    jitterMultiplier: 4.0, // μ + 4σ ≈ 99.99% of Gaussian
+    minGapTimeoutMs: 50, // floor: ~1.5 video frames
+    maxGapTimeoutMs: 2000, // ceiling
+    minDriftThresholdMs: 80,
+    driftThresholdMultiplier: 3.0,
+    stallIncrementMs: 33, // 1 video frame interval
+    maxStallIncrements: 3, // max 3 × 33ms = ~100ms added
+    monitorWindowMs: 500, // observe before escalating
+    monitorCleanFrames: 60, // 1s at 60fps tick rate
+    monitorCleanDurationMs: 1000,
+    maxExtendedWaitMs: 2000,
+    skipFrequencyThreshold: 3, // 3 skips in window → quality reduce
+    skipFrequencyWindowMs: 30000,
+    decayMinCleanFrames: 120, // 2s at 60fps
+    decayMinCleanDurationMs: 2000,
+    decayFactor: 0.9, // 10% reduction per decay step
+};
+const TICK_NO_SKIP = { shouldSkip: false };
+const TICK_SKIP = { shouldSkip: true };
+// ─── Sliding window max ─────────────────────────────────────────────
+/**
+ * O(1) amortized sliding window maximum using a monotonic deque.
+ * Pre-allocated, zero-alloc after construction.
+ */
+class SlidingMax {
+    buf;
+    deq;
+    capacity;
+    writePos = 0;
+    count = 0;
+    dHead = 0;
+    dTail = 0;
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.buf = new Float64Array(capacity);
+        this.deq = new Uint32Array(capacity);
+    }
+    push(value) {
+        const cap = this.capacity;
+        const wIdx = this.writePos % cap;
+        // Evict expired front
+        if (this.count === cap && this.dHead !== this.dTail
+            && this.deq[this.dHead % cap] === wIdx) {
+            this.dHead++;
+        }
+        // Maintain monotonicity from back
+        while (this.dHead !== this.dTail
+            && this.buf[this.deq[(this.dTail - 1) % cap] % cap] <= value) {
+            this.dTail--;
+        }
+        this.deq[this.dTail % cap] = wIdx;
+        this.dTail++;
+        this.buf[wIdx] = value;
+        this.writePos++;
+        if (this.count < cap)
+            this.count++;
+    }
+    get max() {
+        if (this.dHead === this.dTail)
+            return 0;
+        return this.buf[this.deq[this.dHead % this.capacity] % this.capacity];
+    }
+    reset() {
+        this.writePos = 0;
+        this.count = 0;
+        this.dHead = 0;
+        this.dTail = 0;
+    }
+}
+// ─── Controller ─────────────────────────────────────────────────────
+/**
+ * Adaptive jitter tolerance controller.
+ *
+ * Consumes frame arrival and gap events, produces auto-calibrated
+ * thresholds for gap timeout and drift detection.
+ */
+export class AdaptiveToleranceController {
+    cfg;
+    // ── Jitter estimation ──
+    _jitterEma = 0;
+    _jitterVar = 0;
+    _lastTransitMs = 0;
+    _hasLastTransit = false;
+    _slidingMax;
+    // ── Phase state ──
+    _phase = RecoveryPhase.Normal;
+    _phaseEnteredMs = 0;
+    _monitorGapCount = 0;
+    _stallCount = 0;
+    _stallEscalationMs = 0;
+    // ── Skip frequency tracking ──
+    _skipTimestamps = [];
+    // ── Clean streak tracking (for monitoring exit + decay) ──
+    _cleanFrameCount = 0;
+    _cleanStreakStartMs = 0;
+    // ── Quality reduction ──
+    _shouldReduceQuality = false;
+    // ── Protocol signals ──
+    _deliveryTimeoutMs = 0;
+    // ── Capture timestamp jitter (for drift threshold) ──
+    _lastCaptureUs = 0;
+    _hasCaptureRef = false;
+    _captureJitterEma = 0;
+    constructor(config) {
+        this.cfg = config;
+        this._slidingMax = new SlidingMax(config.slidingWindowSize);
+    }
+    // ─── Read-only state ──────────────────────────────────────────
+    get phase() { return this._phase; }
+    get jitterEmaMs() { return this._jitterEma; }
+    get jitterVarMs() { return this._jitterVar; }
+    get slidingMaxMs() { return this._slidingMax.max; }
+    get stallCount() { return this._stallCount; }
+    get shouldReduceQuality() { return this._shouldReduceQuality; }
+    /**
+     * Auto-calibrated gap timeout in milliseconds.
+     *
+     * baseline = max(minGap, EMA + K × variance, slidingMax)
+     * effective = min(baseline + stallEscalation, maxGap, deliveryTimeout)
+     */
+    get effectiveGapTimeoutMs() {
+        const adaptive = Math.max(this.cfg.minGapTimeoutMs, this._jitterEma + this.cfg.jitterMultiplier * this._jitterVar, this._slidingMax.max);
+        const withStall = adaptive + this._stallEscalationMs;
+        let capped = Math.min(withStall, this.cfg.maxGapTimeoutMs);
+        if (this._deliveryTimeoutMs > 0) {
+            capped = Math.min(capped, this._deliveryTimeoutMs);
+        }
+        return capped;
+    }
+    /**
+     * Auto-calibrated drift threshold in milliseconds.
+     *
+     * Based on observed CaptureTimestamp interarrival jitter.
+     */
+    get effectiveDriftThresholdMs() {
+        if (!this._hasCaptureRef || this._captureJitterEma === 0) {
+            return this.cfg.minDriftThresholdMs;
+        }
+        return Math.max(this.cfg.minDriftThresholdMs, this._captureJitterEma * this.cfg.driftThresholdMultiplier);
+    }
+    // ─── Events IN ────────────────────────────────────────────────
+    /**
+     * Notify that a frame arrived.
+     *
+     * @param nowMs Current time in milliseconds
+     * @param captureUs CaptureTimestamp in microseconds
+     * @param arrivalMs Arrival time in milliseconds
+     */
+    onFrameArrived(nowMs, captureUs, arrivalMs) {
+        // Update interarrival jitter EMA (EWMA over transit deltas)
+        const transitMs = arrivalMs - captureUs * 0.001;
+        if (this._hasLastTransit) {
+            const d = transitMs - this._lastTransitMs;
+            const absD = d < 0 ? -d : d;
+            // EWMA update: α = 1/8, β = 1/4 (RFC 6298)
+            const emaErr = absD - this._jitterEma;
+            this._jitterEma += this.cfg.emaAlpha * emaErr;
+            this._jitterVar += this.cfg.varianceAlpha * (absD - this._jitterVar);
+            // Sliding window max
+            this._slidingMax.push(absD);
+        }
+        this._lastTransitMs = transitMs;
+        this._hasLastTransit = true;
+        // Capture timestamp jitter (for drift threshold)
+        if (this._hasCaptureRef) {
+            const captureIntervalUs = captureUs - this._lastCaptureUs;
+            // Expected ~33333 for 30fps, ~20000 for audio — we don't know, just track variance
+            const captureJitterMs = Math.abs(captureIntervalUs) * 0.001;
+            // Track the variance of capture intervals, not absolute value
+            if (this._captureJitterEma === 0) {
+                this._captureJitterEma = captureJitterMs;
+            }
+            else {
+                this._captureJitterEma += this.cfg.emaAlpha * (captureJitterMs - this._captureJitterEma);
+            }
+        }
+        this._lastCaptureUs = captureUs;
+        this._hasCaptureRef = true;
+        // Clean streak tracking
+        this._cleanFrameCount++;
+        if (this._cleanFrameCount === 1) {
+            this._cleanStreakStartMs = nowMs;
+        }
+    }
+    /**
+     * Notify that a gap was detected.
+     *
+     * @param nowMs Current time in milliseconds
+     * @param groupId The group ID where the gap was detected
+     */
+    onGapDetected(nowMs, _groupId) {
+        this._cleanFrameCount = 0;
+        switch (this._phase) {
+            case RecoveryPhase.Normal:
+                this._phase = RecoveryPhase.Monitoring;
+                this._phaseEnteredMs = nowMs;
+                this._monitorGapCount = 1;
+                break;
+            case RecoveryPhase.Monitoring:
+                this._monitorGapCount++;
+                if (this._monitorGapCount >= 2
+                    && nowMs - this._phaseEnteredMs <= this.cfg.monitorWindowMs) {
+                    // Persistent gap — escalate
+                    this._phase = RecoveryPhase.ExtendedWait;
+                    this._phaseEnteredMs = nowMs;
+                }
+                break;
+            case RecoveryPhase.ExtendedWait:
+                // Already waiting — no further escalation
+                break;
+        }
+    }
+    /**
+     * Periodic tick — evaluate phase transitions and decay.
+     *
+     * @param nowMs Current time in milliseconds
+     * @returns TickResult indicating whether caller should skip forward
+     */
+    tick(nowMs) {
+        switch (this._phase) {
+            case RecoveryPhase.Monitoring: {
+                // Check if monitoring window expired without 2nd gap → clean exit
+                if (nowMs - this._phaseEnteredMs > this.cfg.monitorWindowMs) {
+                    // Check clean period
+                    if (this._cleanFrameCount >= this.cfg.monitorCleanFrames
+                        && nowMs - this._cleanStreakStartMs >= this.cfg.monitorCleanDurationMs) {
+                        this._phase = RecoveryPhase.Normal;
+                        return TICK_NO_SKIP;
+                    }
+                }
+                break;
+            }
+            case RecoveryPhase.ExtendedWait: {
+                if (nowMs - this._phaseEnteredMs >= this.cfg.maxExtendedWaitMs) {
+                    // Timeout — skip forward
+                    this._stallCount++;
+                    this._stallEscalationMs = Math.min(this._stallCount * this.cfg.stallIncrementMs, this.cfg.maxStallIncrements * this.cfg.stallIncrementMs);
+                    // Track skip frequency for quality reduction
+                    this._skipTimestamps.push(nowMs);
+                    this._pruneSkipTimestamps(nowMs);
+                    if (this._skipTimestamps.length >= this.cfg.skipFrequencyThreshold) {
+                        this._shouldReduceQuality = true;
+                    }
+                    this._phase = RecoveryPhase.Normal;
+                    this._cleanFrameCount = 0;
+                    return TICK_SKIP;
+                }
+                break;
+            }
+            case RecoveryPhase.Normal: {
+                // Decay stall escalation during clean periods
+                if (this._stallEscalationMs > 0
+                    && this._cleanFrameCount >= this.cfg.decayMinCleanFrames
+                    && this._cleanStreakStartMs > 0
+                    && nowMs - this._cleanStreakStartMs >= this.cfg.decayMinCleanDurationMs) {
+                    this._stallEscalationMs *= this.cfg.decayFactor;
+                    if (this._stallEscalationMs < 1) {
+                        this._stallEscalationMs = 0;
+                        this._stallCount = 0;
+                    }
+                    // Reset clean counters for next decay step
+                    this._cleanFrameCount = 0;
+                    this._cleanStreakStartMs = nowMs;
+                }
+                // Decay quality reduction flag
+                if (this._shouldReduceQuality) {
+                    this._pruneSkipTimestamps(nowMs);
+                    if (this._skipTimestamps.length < this.cfg.skipFrequencyThreshold) {
+                        this._shouldReduceQuality = false;
+                    }
+                }
+                break;
+            }
+        }
+        return TICK_NO_SKIP;
+    }
+    /**
+     * Set DELIVERY_TIMEOUT from protocol negotiation.
+     * Caps the effective gap timeout.
+     *
+     * @see draft-ietf-moq-transport-16 §9.2.2.2
+     */
+    setDeliveryTimeout(timeoutMs) {
+        this._deliveryTimeoutMs = timeoutMs;
+    }
+    /** Reset all state (seek, pause→resume). */
+    reset() {
+        this._jitterEma = 0;
+        this._jitterVar = 0;
+        this._lastTransitMs = 0;
+        this._hasLastTransit = false;
+        this._slidingMax.reset();
+        this._phase = RecoveryPhase.Normal;
+        this._phaseEnteredMs = 0;
+        this._monitorGapCount = 0;
+        this._stallCount = 0;
+        this._stallEscalationMs = 0;
+        this._skipTimestamps = [];
+        this._cleanFrameCount = 0;
+        this._cleanStreakStartMs = 0;
+        this._shouldReduceQuality = false;
+        this._deliveryTimeoutMs = 0;
+        this._lastCaptureUs = 0;
+        this._hasCaptureRef = false;
+        this._captureJitterEma = 0;
+    }
+    // ─── Internal ─────────────────────────────────────────────────
+    _pruneSkipTimestamps(nowMs) {
+        const windowStart = nowMs - this.cfg.skipFrequencyWindowMs;
+        this._skipTimestamps = this._skipTimestamps.filter(t => t >= windowStart);
+    }
+}
+//# sourceMappingURL=adaptive-tolerance.js.map

package/dist/adaptive-tolerance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-tolerance.js","sourceRoot":"","sources":["../src/adaptive-tolerance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,0CAA0C;IAC1C,MAAM,EAAE,QAAQ;IAChB,+DAA+D;IAC/D,UAAU,EAAE,YAAY;IACxB,sEAAsE;IACtE,YAAY,EAAE,eAAe;CACrB,CAAC;AAyCX,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,QAAQ,EAAE,KAAK,EAAa,sBAAsB;IAClD,aAAa,EAAE,IAAI,EAAS,sBAAsB;IAClD,iBAAiB,EAAE,GAAG,EAAM,eAAe;IAC3C,gBAAgB,EAAE,GAAG,EAAO,8BAA8B;IAE1D,eAAe,EAAE,EAAE,EAAS,2BAA2B;IACvD,eAAe,EAAE,IAAI,EAAO,UAAU;IAEtC,mBAAmB,EAAE,EAAE;IACvB,wBAAwB,EAAE,GAAG;IAE7B,gBAAgB,EAAE,EAAE,EAAQ,yBAAyB;IACrD,kBAAkB,EAAE,CAAC,EAAO,8BAA8B;IAE1D,eAAe,EAAE,GAAG,EAAQ,4BAA4B;IACxD,kBAAkB,EAAE,EAAE,EAAM,wBAAwB;IACpD,sBAAsB,EAAE,IAAI;IAC5B,iBAAiB,EAAE,IAAI;IAEvB,sBAAsB,EAAE,CAAC,EAAG,qCAAqC;IACjE,qBAAqB,EAAE,KAAK;IAE5B,mBAAmB,EAAE,GAAG,EAAI,cAAc;IAC1C,uBAAuB,EAAE,IAAI;IAC7B,WAAW,EAAE,GAAG,EAAY,+BAA+B;CAC5D,CAAC;AASF,MAAM,YAAY,GAAe,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AACvD,MAAM,SAAS,GAAe,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAEnD,uEAAuE;AAEvE;;;GAGG;AACH,MAAM,UAAU;IACG,GAAG,CAAe;IAClB,GAAG,CAAc;IACjB,QAAQ,CAAS;IAC1B,QAAQ,GAAG,CAAC,CAAC;IACb,KAAK,GAAG,CAAC,CAAC;IACV,KAAK,GAAG,CAAC,CAAC;IACV,KAAK,GAAG,CAAC,CAAC;IAElB,YAAY,QAAgB;QAC1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,GAAG,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,KAAa;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QAEjC,sBAAsB;QACtB,IAAI,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;eAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QAED,kCAAkC;QAClC,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;eACtB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAE,GAAG,GAAG,CAAE,IAAI,KAAK,EAAE,CAAC;YACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,IAAI,CAAC,KAAK,GAAG,GAAG;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,GAAG;QACL,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAE,GAAG,IAAI,CAAC,QAAQ,CAAE,CAAC;IAC1E,CAAC;IAED,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACjB,CAAC;CACF;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,OAAO,2BAA2B;IACrB,GAAG,CAAkB;IAEtC,0BAA0B;IAClB,UAAU,GAAG,CAAC,CAAC;IACf,UAAU,GAAG,CAAC,CAAC;IACf,cAAc,GAAG,CAAC,CAAC;IACnB,eAAe,GAAG,KAAK,CAAC;IACf,WAAW,CAAa;IAEzC,oBAAoB;IACZ,MAAM,GAAuB,aAAa,CAAC,MAAM,CAAC;IAClD,eAAe,GAAG,CAAC,CAAC;IACpB,gBAAgB,GAAG,CAAC,CAAC;IACrB,WAAW,GAAG,CAAC,CAAC;IAChB,kBAAkB,GAAG,CAAC,CAAC;IAE/B,gCAAgC;IACxB,eAAe,GAAa,EAAE,CAAC;IAEvC,4DAA4D;IACpD,gBAAgB,GAAG,CAAC,CAAC;IACrB,mBAAmB,GAAG,CAAC,CAAC;IAEhC,0BAA0B;IAClB,oBAAoB,GAAG,KAAK,CAAC;IAErC,yBAAyB;IACjB,kBAAkB,GAAG,CAAC,CAAC;IAE/B,uDAAuD;IAC/C,cAAc,GAAG,CAAC,CAAC;IACnB,cAAc,GAAG,KAAK,CAAC;IACvB,iBAAiB,GAAG,CAAC,CAAC;IAE9B,YAAY,MAAuB;QACjC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC;QAClB,IAAI,CAAC,WAAW,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC9D,CAAC;IAED,iEAAiE;IAEjE,IAAI,KAAK,KAAyB,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,IAAI,WAAW,KAAa,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACrD,IAAI,WAAW,KAAa,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACrD,IAAI,YAAY,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,IAAI,UAAU,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACrD,IAAI,mBAAmB,KAAc,OAAO,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAExE;;;;;OAKG;IACH,IAAI,qBAAqB;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,IAAI,CAAC,GAAG,CAAC,eAAe,EACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAC7D,IAAI,CAAC,WAAW,CAAC,GAAG,CACrB,CAAC;QACF,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC;QACrD,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAE3D,IAAI,IAAI,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACrD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,IAAI,yBAAyB;QAC3B,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,iBAAiB,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CACb,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAC5B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,wBAAwB,CAC3D,CAAC;IACJ,CAAC;IAED,iEAAiE;IAEjE;;;;;;OAMG;IACH,cAAc,CAAC,KAAa,EAAE,SAAiB,EAAE,SAAiB;QAChE,4DAA4D;QAC5D,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC;QAEhD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC;YAC1C,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAE5B,2CAA2C;YAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC;YACtC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC;YAC9C,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;YAErE,qBAAqB;YACrB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAE5B,iDAAiD;QACjD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC;YAC1D,mFAAmF;YACnF,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC;YAC5D,8DAA8D;YAC9D,IAAI,IAAI,CAAC,iBAAiB,KAAK,CAAC,EAAE,CAAC;gBACjC,IAAI,CAAC,iBAAiB,GAAG,eAAe,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,eAAe,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAE3B,wBAAwB;QACxB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,gBAAgB,KAAK,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,KAAa,EAAE,QAAgB;QAC3C,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAE1B,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,aAAa,CAAC,MAAM;gBACvB,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC;gBACvC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;gBAC7B,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;gBAC1B,MAAM;YAER,KAAK,aAAa,CAAC,UAAU;gBAC3B,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBACxB,IAAI,IAAI,CAAC,gBAAgB,IAAI,CAAC;uBACvB,KAAK,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;oBAChE,4BAA4B;oBAC5B,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC;oBACzC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;gBAC/B,CAAC;gBACD,MAAM;YAER,KAAK,aAAa,CAAC,YAAY;gBAC7B,0CAA0C;gBAC1C,MAAM;QACV,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAa;QAChB,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;gBAC9B,kEAAkE;gBAClE,IAAI,KAAK,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;oBAC5D,qBAAqB;oBACrB,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,GAAG,CAAC,kBAAkB;2BACjD,KAAK,GAAG,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC;wBAC3E,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;wBACnC,OAAO,YAAY,CAAC;oBACtB,CAAC;gBACH,CAAC;gBACD,MAAM;YACR,CAAC;YAED,KAAK,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;gBAChC,IAAI,KAAK,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC;oBAC/D,yBAAyB;oBACzB,IAAI,CAAC,WAAW,EAAE,CAAC;oBACnB,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAChC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAC5C,IAAI,CAAC,GAAG,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,CACxD,CAAC;oBAEF,6CAA6C;oBAC7C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACjC,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;oBACjC,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC;wBACnE,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;oBACnC,CAAC;oBAED,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;oBACnC,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;oBAC1B,OAAO,SAAS,CAAC;gBACnB,CAAC;gBACD,MAAM;YACR,CAAC;YAED,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC1B,8CAA8C;gBAC9C,IAAI,IAAI,CAAC,kBAAkB,GAAG,CAAC;uBACxB,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,GAAG,CAAC,mBAAmB;uBACrD,IAAI,CAAC,mBAAmB,GAAG,CAAC;uBAC5B,KAAK,GAAG,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,CAAC;oBAC5E,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;oBAChD,IAAI,IAAI,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;wBAChC,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;wBAC5B,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;oBACvB,CAAC;oBACD,2CAA2C;oBAC3C,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;oBAC1B,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC;gBACnC,CAAC;gBAED,+BAA+B;gBAC/B,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;oBAC9B,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;oBACjC,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC;wBAClE,IAAI,CAAC,oBAAoB,GAAG,KAAK,CAAC;oBACpC,CAAC;gBACH,CAAC;gBACD,MAAM;YACR,CAAC;QACH,CAAC;QAED,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,SAAiB;QAClC,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACtC,CAAC;IAED,4CAA4C;IAC5C,KAAK;QACH,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;QAC7B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QAEzB,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAE5B,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,oBAAoB,GAAG,KAAK,CAAC;QAClC,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAE5B,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,iEAAiE;IAEzD,oBAAoB,CAAC,KAAa;QACxC,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,qBAAqB,CAAC;QAC3D,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/dist/bandwidth-estimator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * BandwidthEstimator — EWMA-smoothed bandwidth estimation from
+ * group arrival rate.
+ *
+ * MoQ/QUIC has no HTTP request/response cycle to time, so traditional
+ * ABR segment-download bandwidth estimation doesn't apply. Instead we
+ * measure the effective throughput from object arrival timing:
+ *
+ *   instantaneous_bps = group_size_bytes * 8 / inter_arrival_seconds
+ *
+ * Smoothed with EWMA (Exponentially Weighted Moving Average) to filter
+ * single-sample spikes and bursty delivery patterns (conference WiFi).
+ *
+ * The estimate drives proactive quality decisions — downshift BEFORE
+ * stalls occur, based on arrival rate vs current track bitrate.
+ *
+ * @module
+ */
+export declare class BandwidthEstimator {
+    private readonly alpha;
+    private readonly minSamples;
+    private estimateBps;
+    private lastTimestampUs;
+    private lastGroupBytes;
+    private sampleCount;
+    /**
+     * @param alpha EWMA smoothing factor (0-1). Higher = more responsive
+     *              to recent samples, lower = smoother. Default 0.3.
+     * @param minSamples Minimum group arrivals before reporting a non-zero
+     *                   estimate. Early samples include connection latency
+     *                   and aren't representative. Default 5 (~10s at 2s GOPs).
+     */
+    constructor(alpha?: number, minSamples?: number);
+    /**
+     * Record a group arrival. Call once per complete group (GOP).
+     *
+     * @param bytes Total bytes in the group.
+     * @param timestampUs Arrival timestamp in microseconds.
+     */
+    recordGroup(bytes: number, timestampUs: number): void;
+    /**
+     * Current smoothed bandwidth estimate in kbps.
+     * Returns 0 if fewer than 2 groups have been recorded.
+     */
+    getEstimateKbps(): number;
+    /** Reset all state. */
+    reset(): void;
+}
+//# sourceMappingURL=bandwidth-estimator.d.ts.map

package/dist/bandwidth-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.d.ts","sourceRoot":"","sources":["../src/bandwidth-estimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAK;IAExB;;;;;;OAMG;gBACS,KAAK,SAAM,EAAE,UAAU,SAAI;IAKvC;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAiBrD;;;OAGG;IACH,eAAe,IAAI,MAAM;IAKzB,uBAAuB;IACvB,KAAK,IAAI,IAAI;CAMhB"}

package/dist/bandwidth-estimator.js

@@ -0,0 +1,77 @@
+/**
+ * BandwidthEstimator — EWMA-smoothed bandwidth estimation from
+ * group arrival rate.
+ *
+ * MoQ/QUIC has no HTTP request/response cycle to time, so traditional
+ * ABR segment-download bandwidth estimation doesn't apply. Instead we
+ * measure the effective throughput from object arrival timing:
+ *
+ *   instantaneous_bps = group_size_bytes * 8 / inter_arrival_seconds
+ *
+ * Smoothed with EWMA (Exponentially Weighted Moving Average) to filter
+ * single-sample spikes and bursty delivery patterns (conference WiFi).
+ *
+ * The estimate drives proactive quality decisions — downshift BEFORE
+ * stalls occur, based on arrival rate vs current track bitrate.
+ *
+ * @module
+ */
+export class BandwidthEstimator {
+    alpha;
+    minSamples;
+    estimateBps = null;
+    lastTimestampUs = null;
+    lastGroupBytes = null;
+    sampleCount = 0;
+    /**
+     * @param alpha EWMA smoothing factor (0-1). Higher = more responsive
+     *              to recent samples, lower = smoother. Default 0.3.
+     * @param minSamples Minimum group arrivals before reporting a non-zero
+     *                   estimate. Early samples include connection latency
+     *                   and aren't representative. Default 5 (~10s at 2s GOPs).
+     */
+    constructor(alpha = 0.3, minSamples = 5) {
+        this.alpha = alpha;
+        this.minSamples = minSamples;
+    }
+    /**
+     * Record a group arrival. Call once per complete group (GOP).
+     *
+     * @param bytes Total bytes in the group.
+     * @param timestampUs Arrival timestamp in microseconds.
+     */
+    recordGroup(bytes, timestampUs) {
+        if (this.lastTimestampUs !== null && this.lastGroupBytes !== null) {
+            const deltaUs = timestampUs - this.lastTimestampUs;
+            if (deltaUs > 0) {
+                this.sampleCount++;
+                const instantBps = (bytes * 8) / (deltaUs / 1_000_000);
+                if (this.estimateBps === null) {
+                    this.estimateBps = instantBps;
+                }
+                else {
+                    this.estimateBps = this.alpha * instantBps + (1 - this.alpha) * this.estimateBps;
+                }
+            }
+        }
+        this.lastTimestampUs = timestampUs;
+        this.lastGroupBytes = bytes;
+    }
+    /**
+     * Current smoothed bandwidth estimate in kbps.
+     * Returns 0 if fewer than 2 groups have been recorded.
+     */
+    getEstimateKbps() {
+        if (this.estimateBps === null || this.sampleCount < this.minSamples)
+            return 0;
+        return this.estimateBps / 1000;
+    }
+    /** Reset all state. */
+    reset() {
+        this.estimateBps = null;
+        this.lastTimestampUs = null;
+        this.lastGroupBytes = null;
+        this.sampleCount = 0;
+    }
+}
+//# sourceMappingURL=bandwidth-estimator.js.map

package/dist/bandwidth-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.js","sourceRoot":"","sources":["../src/bandwidth-estimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,OAAO,kBAAkB;IACV,KAAK,CAAS;IACd,UAAU,CAAS;IAC5B,WAAW,GAAkB,IAAI,CAAC;IAClC,eAAe,GAAkB,IAAI,CAAC;IACtC,cAAc,GAAkB,IAAI,CAAC;IACrC,WAAW,GAAG,CAAC,CAAC;IAExB;;;;;;OAMG;IACH,YAAY,KAAK,GAAG,GAAG,EAAE,UAAU,GAAG,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,KAAa,EAAE,WAAmB;QAC1C,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YAChE,MAAM,OAAO,GAAG,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC;YACnD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBACd,IAAI,CAAC,WAAW,EAAE,CAAC;gBACnB,MAAM,UAAU,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;gBACvD,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;oBAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;gBAClC,CAAC;qBAAM,CAAC;oBACJ,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,GAAG,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;gBACrF,CAAC;YACL,CAAC;QACL,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,WAAW,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,eAAe;QACX,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IACnC,CAAC;IAED,uBAAuB;IACvB,KAAK;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACzB,CAAC;CACJ"}