@ksp-gonogo/kerbcast 1.10.0 → 1.10.2

package/src/__generated__/types.ts

@@ -111,6 +111,14 @@ export enum QualityPreset {
 	Quarter = "quarter",
 }
 
+/** The per-dimension MAX display size held for a camera across consumers. */
+export interface DisplaySizeReport {
+	width: number;
+	height: number;
+	/** Milliseconds since the most recent report that contributed to the max. */
+	ageMs: number;
+}
+
 /**
  * Per-camera snapshot pushed by the sidecar on every state change
  * (operator API call, adaptive shed, vessel change). Same shape served
@@ -250,6 +258,44 @@ export interface CameraState {
 	 * Absent/None = the request is fully honored.
 	 */
 	qualityLimitedBy?: string;
+	/**
+	 * Rate in fps Kerbcast is currently pacing this camera's capture to: the
+	 * plugin's primary rate (MaxCaptureFps) while displayed, the background
+	 * rate while subscribed but undisplayed, 0 when not capturing.
+	 */
+	targetCaptureFps?: number;
+	/**
+	 * Whether any consumer reports a non-zero display size for this camera,
+	 * or a consumer forces it (e.g. a full-resolution recording).
+	 */
+	displayed?: boolean;
+	/**
+	 * Frames the plugin produced into this camera's ring per second, over
+	 * roughly the last two seconds, as observed by the sidecar's encode loop.
+	 */
+	captureFps?: number;
+	/**
+	 * Encoded frames handed to this camera's tracks per second, over the same
+	 * window. Below `capture_fps` when the encoder skips frames (encode pacing,
+	 * degrade); a viewer receiving less than this is losing frames in transit.
+	 */
+	sentFps?: number;
+	/**
+	 * Keyframes the encoder emitted for this camera (periodic or requested)
+	 * since its ring was attached.
+	 */
+	keyframesSent?: number;
+	/**
+	 * PLI/FIR keyframe requests received from viewers for this camera, across
+	 * peers, since its ring was attached. Counted before the per-slot debounce,
+	 * so it can exceed the keyframes forced in response.
+	 */
+	keyframeRequestsReceived?: number;
+	/**
+	 * Largest display size currently held for this camera across consumers.
+	 * Absent when no consumer reports one (`GET /cameras` sends null instead).
+	 */
+	displaySize?: DisplaySizeReport;
 }
 
 export interface CameraSnapshotPayload {

package/src/client.test.ts

@@ -214,6 +214,23 @@ describe("KerbcastClient", () => {
     expect(captured.dc?.sent).toContain(JSON.stringify({ type: "hello" }));
   });
 
+  it("emits `control-open` once per control channel open, after hello is sent", async () => {
+    const { transport, captured } = makeFakeTransport();
+    const client = new KerbcastClient({ host: "h", port: 1 }, transport);
+    vi.spyOn(globalThis, "fetch").mockImplementation(async () => fakeAnswer());
+    const sentAtOpen: string[][] = [];
+    client.on("control-open", () => sentAtOpen.push([...(captured.dc?.sent ?? [])]));
+
+    await client.connect();
+    expect(sentAtOpen).toHaveLength(0);
+    captured.dc?._open();
+    expect(sentAtOpen).toEqual([[JSON.stringify({ type: "hello" })]]);
+
+    await client.connect();
+    captured.dc?._open();
+    expect(sentAtOpen).toHaveLength(2);
+  });
+
   it("populates the camera registry from a snapshot push", async () => {
     const { transport, captured } = makeFakeTransport();
     const client = new KerbcastClient({ host: "h", port: 1 }, transport);
@@ -510,6 +527,92 @@ describe("KerbcastClient", () => {
     expect(result[0].supportsZoom).toBe(true);
   });
 
+  it("discover() surfaces per-camera rates and the held display size", async () => {
+    const { transport } = makeFakeTransport();
+    const client = new KerbcastClient({ host: "h", port: 1 }, transport);
+    const base = {
+      partName: "navCam1",
+      partTitle: "NavCam",
+      cameraName: "NavCam",
+      vesselName: "Test Vessel",
+      maxWidth: 1280,
+      maxHeight: 720,
+      supportsZoom: true,
+      fov: 60,
+      fovMin: 30,
+      fovMax: 100,
+      supportsPan: false,
+    };
+    const mockCameras = [
+      {
+        ...base,
+        flightId: 1,
+        targetCaptureFps: 30,
+        displayed: true,
+        captureFps: 29.5,
+        sentFps: 23,
+        keyframesSent: 12,
+        keyframeRequestsReceived: 4,
+        displaySize: { width: 640, height: 360, ageMs: 250 },
+      },
+      { ...base, flightId: 2, targetCaptureFps: 2, displayed: false, displaySize: null },
+      { ...base, flightId: 3 },
+    ];
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ cameras: mockCameras }), { status: 200 }),
+    );
+
+    const [watched, background, old] = await client.discover();
+    expect(watched.targetCaptureFps).toBe(30);
+    expect(watched.displayed).toBe(true);
+    expect(watched.captureFps).toBe(29.5);
+    expect(watched.sentFps).toBe(23);
+    expect(watched.keyframesSent).toBe(12);
+    expect(watched.keyframeRequestsReceived).toBe(4);
+    expect(watched.displaySize).toEqual({ width: 640, height: 360, ageMs: 250 });
+    expect(background.targetCaptureFps).toBe(2);
+    expect(background.displaySize).toBeNull();
+    // An older sidecar sends none of the rate fields.
+    expect(old.targetCaptureFps).toBeUndefined();
+    expect(old.displaySize).toBeUndefined();
+  });
+
+  it("camera state from the snapshot carries the rate fields when the sidecar sends them", async () => {
+    const { transport, captured } = makeFakeTransport();
+    const client = new KerbcastClient({ host: "h", port: 1 }, transport);
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(fakeAnswer());
+
+    await client.connect();
+    captured.dc?._open();
+    captured.dc?._msg(
+      JSON.stringify({
+        type: "camera-snapshot",
+        content: {
+          cameras: [
+            fakeCameraState(1, {
+              targetCaptureFps: 2,
+              displayed: false,
+              captureFps: 2,
+              sentFps: 2,
+              keyframesSent: 3,
+              keyframeRequestsReceived: 0,
+            }),
+            fakeCameraState(2),
+          ],
+        },
+      }),
+    );
+
+    const [withRates, legacy] = client.cameras;
+    expect(withRates.targetCaptureFps).toBe(2);
+    expect(withRates.displayed).toBe(false);
+    expect(withRates.sentFps).toBe(2);
+    expect(withRates.keyframesSent).toBe(3);
+    expect(withRates.displaySize).toBeUndefined();
+    expect(legacy.targetCaptureFps).toBeUndefined();
+    expect(legacy.captureFps).toBeUndefined();
+  });
+
   it("sidecar error message emits error event with correct payload including source", async () => {
     const { transport, captured } = makeFakeTransport();
     const client = new KerbcastClient({ host: "h", port: 1 }, transport);

package/src/client.ts

@@ -2,6 +2,7 @@ import type {
   AdaptiveShedPayload,
   CameraState,
   ClientMessage,
+  DisplaySizeReport,
   ErrorPayload,
   Layer,
   QualityPreset,
@@ -247,6 +248,26 @@ export interface DiscoveredCamera {
   targetBitrateBps: number;
   /** Effective degrade level (max across active subscribers). 0.0 to 1.0. */
   degradeLevel: number;
+  /*
+   * Live rate fields, absent from sidecars that predate them. Poll
+   * discover() for current values; the data-channel CameraState carries the
+   * same fields as of its last push.
+   */
+  /** Rate Kerbcast paces this camera's capture to: the primary rate while
+   *  displayed, the background rate while undisplayed, 0 when not capturing. */
+  targetCaptureFps?: number;
+  /** Any consumer reports a non-zero display size, or the feed is forced. */
+  displayed?: boolean;
+  /** Frames the plugin produced per second over roughly the last 2 s. */
+  captureFps?: number;
+  /** Encoded frames handed to this camera's tracks per second, same window. */
+  sentFps?: number;
+  /** Keyframes the encoder emitted since the camera's stream started. */
+  keyframesSent?: number;
+  /** PLI/FIR keyframe requests received across peers since the stream started. */
+  keyframeRequestsReceived?: number;
+  /** Largest display size held across consumers; null when none is held. */
+  displaySize?: DisplaySizeReport | null;
 }
 
 /** Event payloads emitted by a {@link KerbcastClient}. */
@@ -274,6 +295,13 @@ export interface KerbcastClientEvents {
    * instead of per-camera SIGNAL LOST.
    */
   "scene-change": boolean | undefined;
+  /**
+   * Fired each time the control channel of a freshly (re)connected peer
+   * opens, i.e. the earliest moment it can carry messages. Consumers that
+   * hold per-peer state on the sidecar (display sizes, subscriptions) re-send
+   * it here, because the sidecar forgets a peer's state when it leaves.
+   */
+  "control-open": undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -1030,6 +1058,7 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     this.control = peer.createDataChannel("kerbcast-control");
     this.control.onOpen(() => {
       void this._send({ type: "hello" });
+      this.emit("control-open", undefined);
     });
     this.control.onMessage((raw) => {
       this.handleServerMessage(raw);

package/src/index.ts

@@ -36,7 +36,9 @@ export {
   utToRecordingTimeMs,
   DEFAULT_COVERAGE_TIMEOUT_MS,
   ARM_TIMEOUT_MS,
+  videoElementDecodedSizeProbe,
   type ActiveRecordingInfo,
+  type DecodedSizeProbe,
   type RecordingClient,
   type RecordingControllerOptions,
   type RecordingHandle,

package/src/noise.test.ts

@@ -338,3 +338,43 @@ describe("noise pipeline stall presentation", () => {
     }
   });
 });
+
+describe("noise pipeline sizing", () => {
+  it("resizes the output canvas when the source's decoded size changes mid-stream", () => {
+    const env = installStallEnv();
+    let vw = 784;
+    let vh = 448;
+    const proto = HTMLVideoElement.prototype;
+    const origW = Object.getOwnPropertyDescriptor(proto, "videoWidth");
+    const origH = Object.getOwnPropertyDescriptor(proto, "videoHeight");
+    Object.defineProperty(proto, "videoWidth", { configurable: true, get: () => vw });
+    Object.defineProperty(proto, "videoHeight", { configurable: true, get: () => vh });
+    let output: HTMLCanvasElement | null = null;
+    // @ts-expect-error -- jsdom augmentation
+    HTMLCanvasElement.prototype.captureStream = vi.fn(function (this: HTMLCanvasElement) {
+      output = this;
+      return {} as MediaStream;
+    });
+    try {
+      const pipeline = tryCreateNoisePipeline(fakeStream(), 0.05);
+      expect(pipeline).not.toBeNull();
+
+      env.setNow(1000);
+      env.fireFrame();
+      env.draw();
+      expect([output!.width, output!.height]).toEqual([784, 448]);
+
+      // The sidecar raises the render size; no second loadedmetadata fires.
+      vw = 1024;
+      vh = 576;
+      env.setNow(1033);
+      env.fireFrame();
+      env.draw();
+      expect([output!.width, output!.height]).toEqual([1024, 576]);
+    } finally {
+      if (origW) Object.defineProperty(proto, "videoWidth", origW);
+      if (origH) Object.defineProperty(proto, "videoHeight", origH);
+      env.restore();
+    }
+  });
+});

package/src/noise.ts

@@ -185,6 +185,19 @@ export function tryCreateNoisePipeline(
   const draw = () => {
     if (destroyed) return;
     const now = performance.now();
+    /*
+     * Follow mid-stream size changes. loadedmetadata fires once per source,
+     * so without this the canvas (and the processed stream every consumer
+     * displays and records) stays at the first decoded size forever, even
+     * after the sidecar raises the render size.
+     */
+    if (
+      video.srcObject &&
+      video.videoWidth > 0 &&
+      (video.videoWidth !== canvas.width || video.videoHeight !== canvas.height)
+    ) {
+      onMeta();
+    }
     const cw = canvas.width;
     const ch = canvas.height;
     const nw = noiseCanvas.width;