@ksp-gonogo/kerbcast 1.6.2 → 1.6.3

package/dist/__generated__/types.d.ts

@@ -131,8 +131,8 @@ export interface CameraState {
      */
     targetBitrateBps: number;
     /**
-     * Effective degrade level (max across subscribers' SetDegrade
-     * requests). 0.0 = perfect, 1.0 = max degradation. Applied
+     * Effective degrade level (last-writer-wins across subscribers'
+     * SetDegrade requests). 0.0 = perfect, 1.0 = max degradation. Applied
      * alongside operator render-size + adaptive shed; the encoder
      * multiplies its effective bitrate by `(1 - 0.7 * level)` and
      * skips fan-out for a fraction of frames at high levels.
@@ -187,10 +187,12 @@ export interface SceneStateChangedPayload {
 export interface SetDegradePayload {
     flightId: number;
     /**
-     * 0.0 = perfect quality, 1.0 = maximum degradation. Caps and
-     * is per-subscriber: the sidecar applies max across active
-     * subscribers so the noisiest consumer's request wins (same
-     * pattern as REMB picking the min bandwidth).
+     * 0.0 = perfect quality, 1.0 = maximum degradation. Clamped.
+     * Last-writer-wins: degrade is a property of the camera's game
+     * state (comms strength), shared by all viewers of the single
+     * encoded stream, so the sidecar stores the latest value rather
+     * than reducing across subscribers. A well-behaved driver
+     * re-asserts every tick.
      */
     level: number;
 }
@@ -379,11 +381,12 @@ export type ClientMessage =
 }
 /**
  * Request artificial signal degradation. 0.0 = perfect quality,
- * 1.0 = maximum degradation. Per-subscriber: the sidecar
- * applies max across active subscribers (slowest consumer
- * wins, same pattern as REMB bandwidth). Lets consumers signal
- * to the sidecar "I want to look like the in-game CommNet
- * antenna is struggling"; sidecar takes the opportunity to
+ * 1.0 = maximum degradation. Last-writer-wins: the sidecar stores
+ * the latest value on the camera (degrade is shared across all
+ * viewers of the one encoded stream), so a departed peer can't
+ * pin it. Lets consumers signal to the sidecar "I want to look
+ * like the in-game CommNet antenna is struggling"; sidecar takes
+ * the opportunity to
  * reduce bitrate + skip frames, which both creates the
  * signal-loss aesthetic AND saves encoder CPU.
  */

package/dist/client.js

@@ -4,6 +4,13 @@ import { tryCreateNoisePipeline } from "./noise";
 const SOURCELESS_INTENSITY = 1.0;
 /** Floor applied to the degrade-driven intensity of a live feed. */
 const LIVE_INTENSITY_FLOOR = 0.05;
+/**
+ * While a feed is stalled, how often to re-request a keyframe. A stall is
+ * usually a wedged decoder that only a fresh IDR clears; the first request or
+ * its keyframe can be lost during the same outage, so we keep asking until
+ * frames resume.
+ */
+const STALL_KEYFRAME_RETRY_MS = 2000;
 export class BrowserKerbcastTransport {
     constructor(opts = {}) {
         this.opts = { iceGatheringTimeoutMs: opts.iceGatheringTimeoutMs ?? 2000 };
@@ -159,6 +166,8 @@ class CameraHandle extends TypedEmitter {
         this._sourceless = false;
         /** Stall state mirrored from the pipeline's onStallChange callback. */
         this._stalled = false;
+        /** Interval that re-requests keyframes while stalled; null when not stalled. */
+        this._keyframeRetry = null;
         /** Whether animated static is drawn; survives pipeline rebuilds. */
         this._showStatic = true;
         this.flightId = flightId;
@@ -291,6 +300,26 @@ class CameraHandle extends TypedEmitter {
             return;
         this._stalled = stalled;
         this.emit("stall", stalled);
+        if (stalled) {
+            // A stall usually means the browser decoder is wedged (broken H.264
+            // reference chain after packet loss or heavy degrade), which only a
+            // fresh keyframe clears. Force one now and keep asking while stalled,
+            // rather than waiting on the browser's rate-limited PLI.
+            this._requestKeyframeForRecovery();
+            if (this._keyframeRetry === null) {
+                this._keyframeRetry = setInterval(() => this._requestKeyframeForRecovery(), STALL_KEYFRAME_RETRY_MS);
+            }
+        }
+        else if (this._keyframeRetry !== null) {
+            clearInterval(this._keyframeRetry);
+            this._keyframeRetry = null;
+        }
+    }
+    _requestKeyframeForRecovery() {
+        this.requestKeyframe().catch(() => {
+            // Best effort; a failed send (disconnected) is retried on the next tick,
+            // or cleared when the stall ends.
+        });
     }
     _liveIntensity() {
         return Math.max(LIVE_INTENSITY_FLOOR, this._state?.degradeLevel ?? 0);
@@ -300,6 +329,10 @@ class CameraHandle extends TypedEmitter {
      * the persistent pipeline, stops its rAF loop, and nulls the stream.
      */
     _teardown() {
+        if (this._keyframeRetry !== null) {
+            clearInterval(this._keyframeRetry);
+            this._keyframeRetry = null;
+        }
         this._noisePipeline?.destroy();
         this._noisePipeline = null;
         this._rawStream = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "TypeScript client for the kerbcast KSP camera-streaming sidecar. KerbcastClient wraps the WebRTC peer + control channel; wire-format types are typeshare-generated from the sidecar's Rust protocol module.",
   "license": "MIT",
   "author": "Jon Pepler",

package/src/__generated__/types.ts

@@ -139,8 +139,8 @@ export interface CameraState {
 	 */
 	targetBitrateBps: number;
 	/**
-	 * Effective degrade level (max across subscribers' SetDegrade
-	 * requests). 0.0 = perfect, 1.0 = max degradation. Applied
+	 * Effective degrade level (last-writer-wins across subscribers'
+	 * SetDegrade requests). 0.0 = perfect, 1.0 = max degradation. Applied
 	 * alongside operator render-size + adaptive shed; the encoder
 	 * multiplies its effective bitrate by `(1 - 0.7 * level)` and
 	 * skips fan-out for a fraction of frames at high levels.
@@ -203,10 +203,12 @@ export interface SceneStateChangedPayload {
 export interface SetDegradePayload {
 	flightId: number;
 	/**
-	 * 0.0 = perfect quality, 1.0 = maximum degradation. Caps and
-	 * is per-subscriber: the sidecar applies max across active
-	 * subscribers so the noisiest consumer's request wins (same
-	 * pattern as REMB picking the min bandwidth).
+	 * 0.0 = perfect quality, 1.0 = maximum degradation. Clamped.
+	 * Last-writer-wins: degrade is a property of the camera's game
+	 * state (comms strength), shared by all viewers of the single
+	 * encoded stream, so the sidecar stores the latest value rather
+	 * than reducing across subscribers. A well-behaved driver
+	 * re-asserts every tick.
 	 */
 	level: number;
 }
@@ -385,11 +387,12 @@ export type ClientMessage =
 	| { type: "set-zoom-rate", content: SetZoomRatePayload }
 	/**
 	 * Request artificial signal degradation. 0.0 = perfect quality,
-	 * 1.0 = maximum degradation. Per-subscriber: the sidecar
-	 * applies max across active subscribers (slowest consumer
-	 * wins, same pattern as REMB bandwidth). Lets consumers signal
-	 * to the sidecar "I want to look like the in-game CommNet
-	 * antenna is struggling"; sidecar takes the opportunity to
+	 * 1.0 = maximum degradation. Last-writer-wins: the sidecar stores
+	 * the latest value on the camera (degrade is shared across all
+	 * viewers of the one encoded stream), so a departed peer can't
+	 * pin it. Lets consumers signal to the sidecar "I want to look
+	 * like the in-game CommNet antenna is struggling"; sidecar takes
+	 * the opportunity to
 	 * reduce bitrate + skip frames, which both creates the
 	 * signal-loss aesthetic AND saves encoder CPU.
 	 */

package/src/client.ts

@@ -15,6 +15,13 @@ import { type NoisePipeline, tryCreateNoisePipeline } from "./noise";
 const SOURCELESS_INTENSITY = 1.0;
 /** Floor applied to the degrade-driven intensity of a live feed. */
 const LIVE_INTENSITY_FLOOR = 0.05;
+/**
+ * While a feed is stalled, how often to re-request a keyframe. A stall is
+ * usually a wedged decoder that only a fresh IDR clears; the first request or
+ * its keyframe can be lost during the same outage, so we keep asking until
+ * frames resume.
+ */
+const STALL_KEYFRAME_RETRY_MS = 2000;
 
 /** Controls the digital-static noise overlay baked into `cam.mediaStream`. */
 export interface NoiseConfig {
@@ -473,6 +480,8 @@ class CameraHandle
   private _sourceless = false;
   /** Stall state mirrored from the pipeline's onStallChange callback. */
   private _stalled = false;
+  /** Interval that re-requests keyframes while stalled; null when not stalled. */
+  private _keyframeRetry: ReturnType<typeof setInterval> | null = null;
   /** Whether animated static is drawn; survives pipeline rebuilds. */
   private _showStatic = true;
   private readonly client: KerbcastClient;
@@ -625,6 +634,29 @@ class CameraHandle
     if (this._stalled === stalled) return;
     this._stalled = stalled;
     this.emit("stall", stalled);
+    if (stalled) {
+      // A stall usually means the browser decoder is wedged (broken H.264
+      // reference chain after packet loss or heavy degrade), which only a
+      // fresh keyframe clears. Force one now and keep asking while stalled,
+      // rather than waiting on the browser's rate-limited PLI.
+      this._requestKeyframeForRecovery();
+      if (this._keyframeRetry === null) {
+        this._keyframeRetry = setInterval(
+          () => this._requestKeyframeForRecovery(),
+          STALL_KEYFRAME_RETRY_MS,
+        );
+      }
+    } else if (this._keyframeRetry !== null) {
+      clearInterval(this._keyframeRetry);
+      this._keyframeRetry = null;
+    }
+  }
+
+  private _requestKeyframeForRecovery(): void {
+    this.requestKeyframe().catch(() => {
+      // Best effort; a failed send (disconnected) is retried on the next tick,
+      // or cleared when the stall ends.
+    });
   }
 
   private _liveIntensity(): number {
@@ -636,6 +668,10 @@ class CameraHandle
    * the persistent pipeline, stops its rAF loop, and nulls the stream.
    */
   _teardown(): void {
+    if (this._keyframeRetry !== null) {
+      clearInterval(this._keyframeRetry);
+      this._keyframeRetry = null;
+    }
     this._noisePipeline?.destroy();
     this._noisePipeline = null;
     this._rawStream = null;