@ksp-gonogo/kerbcast 1.6.3 → 1.8.0

package/src/client.test.ts

@@ -4,6 +4,7 @@ import {
   ErrorSource,
   Layer,
   QualityPreset,
+  TrackMode,
 } from "./__generated__/types";
 import {
   BrowserKerbcastTransport,
@@ -381,6 +382,68 @@ describe("KerbcastClient", () => {
     ]);
   });
 
+  it("set-force-full-resolution routes onto the control channel via the handle", 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!.sent.length = 0; // drop the hello
+
+    await client.camera(42).setForceFullResolution(true);
+    await client.camera(42).setForceFullResolution(false);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "set-force-full-resolution",
+        content: { flightId: 42, force: true },
+      }),
+      JSON.stringify({
+        type: "set-force-full-resolution",
+        content: { flightId: 42, force: false },
+      }),
+    ]);
+  });
+
+  it("reportDisplaySize sends a report-display-size command", 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!.sent.length = 0;
+
+    await client.reportDisplaySize(3, 40, 40);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "report-display-size",
+        content: { flightId: 3, width: 40, height: 40 },
+      }),
+    ]);
+  });
+
+  it("setTrackTarget sends a set-track-target command", 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!.sent.length = 0;
+
+    await client.setTrackTarget(5, TrackMode.ActiveVessel);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "set-track-target",
+        content: { flightId: 5, mode: TrackMode.ActiveVessel },
+      }),
+    ]);
+  });
+
   it("disconnect tears down peer + emits null MediaStream events", async () => {
     const { transport, captured } = makeFakeTransport();
     const client = new KerbcastClient({ host: "h", port: 1 }, transport);

package/src/client.ts

@@ -7,9 +7,11 @@ import type {
   QualityPreset,
   ServerMessage,
   SettingsStatePayload,
+  TrackMode,
 } from "./__generated__/types";
 import { CameraLifecycle, ErrorSource } from "./__generated__/types";
 import { type NoisePipeline, tryCreateNoisePipeline } from "./noise";
+import { RecordingController, type RecordingControllerOptions } from "./recording";
 
 /** Intensity the static runs at when a camera has no live source (signal lost). */
 const SOURCELESS_INTENSITY = 1.0;
@@ -46,6 +48,16 @@ export interface KerbcastCameraHandle {
   readonly stalled: boolean;
   /** Current {@link setShowStatic} setting. */
   readonly showStatic: boolean;
+  /**
+   * The feed's physical/ceiling maximum render size (`DiscoveredCamera.maxWidth`
+   * / `maxHeight`), or `null` until known. Populated from a prior
+   * `client.discover()` call (there is no live-pushed field for it), so a
+   * consumer that never calls `discover()` sees `null` here indefinitely.
+   * Used by `RecordingController` to recognise a force-full-resolution feed
+   * that has actually reached its ceiling, as opposed to one merely
+   * unchanged since before the force was sent.
+   */
+  readonly maxRenderSize: { width: number; height: number } | null;
 
   setLayers(layers: Layer[]): Promise<void>;
   setRenderSize(width: number, height: number): Promise<void>;
@@ -77,6 +89,15 @@ export interface KerbcastCameraHandle {
    * machinery keeps overriding it downward while throttled.
    */
   setQuality(preset: QualityPreset | null): Promise<void>;
+  /**
+   * Force this feed to render at the operator's configured maximum
+   * regardless of display size, until released by calling this with
+   * `false`. Per-viewer, OR-aggregated server-side across viewers: a feed
+   * stays forced while any viewer forces it, and releases when the last one
+   * clears it (or disconnects). Still yields to the adaptive framerate
+   * shed; it only overrides the display-size demand term.
+   */
+  setForceFullResolution(force: boolean): Promise<void>;
   requestKeyframe(): Promise<void>;
 
   /**
@@ -149,6 +170,15 @@ export interface KerbcastClientConfig {
     cameras: number[];
     slots?: number;
   }) => Promise<{ sdp: string; cameras: number[] }>;
+  /**
+   * Options for the lazily-built {@link RecordingController} (`client.recording`).
+   * The load-bearing use is `loadTrimmer`: a consumer that can't rely on the
+   * default bare `import("mediabunny")` resolving (the sidecar's embedded web
+   * page serves its own copy of the package locally, offline/LAN, no CDN)
+   * supplies its own loader here. Bundler consumers (e.g. gonogo) can omit
+   * this and get the default.
+   */
+  recording?: RecordingControllerOptions;
 }
 
 /** WebRTC connection state surface. */
@@ -508,6 +538,10 @@ class CameraHandle
     return this._showStatic;
   }
 
+  get maxRenderSize(): { width: number; height: number } | null {
+    return this.client._maxRenderSize(this.flightId);
+  }
+
   configure(options: { noise?: Partial<NoiseConfig> }): void {
     this._noiseOverride = options.noise ?? null;
     // Re-evaluate with the new noise setting: rebuild from whatever source
@@ -738,6 +772,13 @@ class CameraHandle
     });
   }
 
+  async setForceFullResolution(force: boolean): Promise<void> {
+    await this.client._send({
+      type: "set-force-full-resolution",
+      content: { flightId: this.flightId, force },
+    });
+  }
+
   async requestKeyframe(): Promise<void> {
     await this.client._send({
       type: "request-keyframe",
@@ -815,6 +856,15 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
   private _warpRate = 1;
   /** Whether KSP is in a flight scene. `undefined` until the first signal. */
   private _inFlight: boolean | undefined = undefined;
+  /** Client-side recording controller, lazily built on first `recording` access. */
+  private _recording: RecordingController | null = null;
+  /**
+   * Physical/ceiling max render size per camera, cached from the last
+   * `discover()` call. Empty until `discover()` has been called at least
+   * once; a camera absent from the last discovery response is simply
+   * missing here (its handle's `maxRenderSize` reads `null`).
+   */
+  private readonly maxRenderSizeByFlight = new Map<number, { width: number; height: number }>();
 
   constructor(cfg: KerbcastClientConfig, transport?: KerbcastTransport) {
     super();
@@ -867,6 +917,17 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     };
   }
 
+  /**
+   * Client-side recording controller. Records a camera's already-received
+   * track with the browser's `MediaRecorder`, annotated with the mission-time
+   * (UT) clock; purely local, no sidecar involvement. Lazily created on first
+   * access and stable thereafter. See {@link RecordingController}.
+   */
+  get recording(): RecordingController {
+    if (!this._recording) this._recording = new RecordingController(this, this.cfg.recording);
+    return this._recording;
+  }
+
   /**
    * Whether KSP is currently in a flight scene, from the sidecar's
    * `scene-state-changed`. `undefined` until the first signal (so a
@@ -898,9 +959,23 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     const res = await fetch(`http://${this.cfg.host}:${this.cfg.port}/cameras`);
     if (!res.ok) throw new Error(`/cameras returned ${res.status}`);
     const body = (await res.json()) as { cameras: DiscoveredCamera[] };
+    for (const cam of body.cameras) {
+      this.maxRenderSizeByFlight.set(cam.flightId, {
+        width: cam.maxWidth,
+        height: cam.maxHeight,
+      });
+    }
     return body.cameras;
   }
 
+  /**
+   * Internal: backs {@link KerbcastCameraHandle.maxRenderSize}. `null` when
+   * `discover()` has never been called or never reported this camera.
+   */
+  _maxRenderSize(flightId: number): { width: number; height: number } | null {
+    return this.maxRenderSizeByFlight.get(flightId) ?? null;
+  }
+
   /**
    * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
    * `connect` while already connected disconnects first.
@@ -1040,6 +1115,29 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     await this._send({ type: "unsubscribe", content: { flightId } });
   }
 
+  /**
+   * Report this consumer's own displayed pixel size for a camera, driving the
+   * sidecar's auto-resolution. Unlike `setRenderSize` (an operator command that
+   * sets the shared render size directly, last-writer-wins), this is a
+   * per-consumer input the sidecar aggregates MAX-across-consumers, so a big
+   * spotlight bumps the stream up while tiny avatars leave it small. The SDK's
+   * feed primitives self-measure and call this; consumers do not report by hand.
+   */
+  async reportDisplaySize(flightId: number, width: number, height: number): Promise<void> {
+    await this._send({ type: "report-display-size", content: { flightId, width, height } });
+  }
+
+  /**
+   * Ask a pan+zoom camera to auto-track a moving vessel (or stop). Sends the
+   * intent; the sidecar holds the chosen mode per camera and publishes it in
+   * `CameraState.trackMode`, so the UI must reflect that server-confirmed value
+   * rather than this call (two browsers stay in agreement). While tracking, the
+   * camera also auto-zooms; `TrackMode.None` hands aiming/zoom back.
+   */
+  async setTrackTarget(flightId: number, mode: TrackMode): Promise<void> {
+    await this._send({ type: "set-track-target", content: { flightId, mode } });
+  }
+
   /**
    * Internal — resolves the effective noise enabled state for a camera,
    * merging the per-camera override (if any) with the client-level default.

package/src/index.ts

@@ -27,3 +27,25 @@ export {
   type PanZoomBounds,
   type PanZoomControllerOptions,
 } from "./panZoom";
+
+export {
+  RecordingController,
+  createMediabunnyTrimmerLoader,
+  negotiateMimeType,
+  commonUtWindow,
+  utToRecordingTimeMs,
+  DEFAULT_COVERAGE_TIMEOUT_MS,
+  ARM_TIMEOUT_MS,
+  type ActiveRecordingInfo,
+  type RecordingClient,
+  type RecordingControllerOptions,
+  type RecordingHandle,
+  type RecordingsSnapshot,
+  type GroupedRecordingHandle,
+  type GroupedRecordingStart,
+  type GroupTrimmer,
+  type TrimmerLoader,
+  type UtSample,
+  type StartRecordingOptions,
+  type StopGroupedRecordingOptions,
+} from "./recording";