@ksp-gonogo/kerbcast 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.8.0 - 2026-07-28
+
+Client-side camera recording. The capture itself is pure SDK: the recorder taps
+a track the browser has already received, and the sidecar never learns a
+recording happened. Full-resolution recording is the exception, and it does
+reach the wire: it added the `SetForceFullResolution` control message to the
+protocol, plus the matching force-pin handling in the sidecar's camera
+registry.
+
+### Added
+
+- `KerbcastClient.recording`: a `RecordingController` that records a camera's
+  already-received WebRTC track with the browser's `MediaRecorder`, entirely
+  client-local (the sidecar never learns a recording happened)
+- Per-feed API: `startRecording(flightId, opts?)` returns a client-minted
+  `recordingId`; `stopRecording(recordingId)` resolves a `RecordingHandle`;
+  `fetchRecording` / `discardRecording` / `isRecording`
+- `RecordingHandle = { recordingId, blob, mimeType, utStart?, utEnd?,
+  utSamples, byteSize, durationMs }`, where `utSamples` is a ~1Hz
+  (recording-time, UT) series so a consumer can interpolate any frame's
+  mission-time near-frame-tight; out of flight it falls back to wall-clock
+  timing (`ut` absent) and upgrades automatically once UT appears
+- Mime negotiation prefers `video/mp4;codecs=avc1` where
+  `MediaRecorder.isTypeSupported`, else `video/webm;codecs=vp9`, else
+  `video/webm`; the chosen type is on the handle. `opts.maxDurationMs` auto-stops
+- Grouped API: `startGroupedRecording(flightIds, opts?)` (all recorders open in
+  one tick) and `stopGroupedRecording(groupId, { targetUt? })`. `targetUt`
+  enforces a coverage guarantee: finalization waits until every feed's latest
+  UT sample passes it, so no feed falls short of the common window
+- `GroupedRecordingHandle = { groupId, recordings, commonUtWindow? }`, where
+  `commonUtWindow` is the intersection of the feeds' `[utStart, utEnd]`
+- Grouped clips are physically remux-trimmed to `commonUtWindow` by default
+  (keyframe-boundary cut, no re-encode) via a lazily `import()`-ed Mediabunny,
+  loaded only on grouped-record start (single recordings stay dependency-free);
+  a clip that can't be cut cleanly (webm, or a remux error) degrades to
+  metadata-only and never fails the recording. `utSamples` + `commonUtWindow`
+  still ride along after trimming so a consumer can align to telemetry
+- Helpers `negotiateMimeType`, `commonUtWindow`, `utToRecordingTimeMs`
+- `StubMediaRecorder`: a jsdom `MediaRecorder` shim installed by
+  `installDomStubs`, so the full record -> UT-sample -> stop -> handle path is
+  headless-testable (its `isTypeSupported` is controllable for mime tests)
+- `mediabunny` as a dependency, dynamically imported for grouped-clip trimming
+  only (never pulled by single recordings or non-recording consumers)
+
 ## 1.7.0 - 2026-07-24
 
 Crew face cameras, auto-resolution, and camera targeting.

package/dist/__generated__/types.d.ts

@@ -260,6 +260,17 @@ export interface SetDegradePayload {
      */
     level: number;
 }
+/**
+ * Forces a camera to render at the operator ceiling regardless of
+ * display-size demand. Per-viewer, OR-aggregated by the sidecar: a feed
+ * stays forced while any connected viewer forces it, and releases when
+ * the last one clears it (or disconnects). Still yields to the adaptive
+ * framerate shed; overrides only the demand term.
+ */
+export interface SetForceFullResolutionPayload {
+    flightId: number;
+    force: boolean;
+}
 export interface SetFovPayload {
     flightId: number;
     fov: number;
@@ -435,6 +446,18 @@ export type ClientMessage =
     type: "report-display-size";
     content: ReportDisplaySizePayload;
 }
+/**
+ * Force a camera to render at the operator ceiling regardless of
+ * display-size demand. Per-viewer, OR-aggregated by the sidecar: a
+ * feed stays forced while any connected viewer forces it, and
+ * releases when the last one clears it (or disconnects). Still
+ * yields to the adaptive framerate shed; overrides only the demand
+ * term, never the perf-protection ceiling.
+ */
+ | {
+    type: "set-force-full-resolution";
+    content: SetForceFullResolutionPayload;
+}
 /**
  * Set the camera's field-of-view (degrees). Silently ignored for
  * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, Layer, QualityPreset, SettingsStatePayload, TrackMode } from "./__generated__/types";
 import { CameraLifecycle } from "./__generated__/types";
+import { RecordingController, type RecordingControllerOptions } from "./recording";
 /** Controls the digital-static noise overlay baked into `cam.mediaStream`. */
 export interface NoiseConfig {
     /** When false, the pipeline is bypassed and `mediaStream` is the raw WebRTC track. */
@@ -22,6 +23,19 @@ 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>;
     setFov(fov: number): Promise<void>;
@@ -52,6 +66,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>;
     /**
      * Override noise settings for this camera only. Takes precedence over the
@@ -121,6 +144,15 @@ export interface KerbcastClientConfig {
         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. */
 export type KerbcastConnectionState = "disconnected" | "connecting" | "connected" | "failed";
@@ -328,6 +360,15 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     private _warpRate;
     /** Whether KSP is in a flight scene. `undefined` until the first signal. */
     private _inFlight;
+    /** Client-side recording controller, lazily built on first `recording` access. */
+    private _recording;
+    /**
+     * 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;
     constructor(cfg: KerbcastClientConfig, transport?: KerbcastTransport);
     get state(): KerbcastConnectionState;
     get cameras(): ReadonlyArray<CameraState>;
@@ -352,6 +393,13 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
         epoch: number;
         warpRate: number;
     };
+    /**
+     * 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;
     /**
      * Whether KSP is currently in a flight scene, from the sidecar's
      * `scene-state-changed`. `undefined` until the first signal (so a
@@ -371,6 +419,14 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * to subscribe to before opening a peer connection.
      */
     discover(): Promise<DiscoveredCamera[]>;
+    /**
+     * 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;
     /**
      * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
      * `connect` while already connected disconnects first.

package/dist/client.js

@@ -1,5 +1,6 @@
 import { CameraLifecycle, ErrorSource } from "./__generated__/types";
 import { tryCreateNoisePipeline } from "./noise";
+import { RecordingController } from "./recording";
 /** Intensity the static runs at when a camera has no live source (signal lost). */
 const SOURCELESS_INTENSITY = 1.0;
 /** Floor applied to the degrade-driven intensity of a live feed. */
@@ -185,6 +186,9 @@ class CameraHandle extends TypedEmitter {
     get showStatic() {
         return this._showStatic;
     }
+    get maxRenderSize() {
+        return this.client._maxRenderSize(this.flightId);
+    }
     configure(options) {
         this._noiseOverride = options.noise ?? null;
         // Re-evaluate with the new noise setting: rebuild from whatever source
@@ -390,6 +394,12 @@ class CameraHandle extends TypedEmitter {
             content: { flightId: this.flightId, preset: preset ?? undefined },
         });
     }
+    async setForceFullResolution(force) {
+        await this.client._send({
+            type: "set-force-full-resolution",
+            content: { flightId: this.flightId, force },
+        });
+    }
     async requestKeyframe() {
         await this.client._send({
             type: "request-keyframe",
@@ -465,6 +475,15 @@ export class KerbcastClient extends TypedEmitter {
         this._warpRate = 1;
         /** Whether KSP is in a flight scene. `undefined` until the first signal. */
         this._inFlight = undefined;
+        /** Client-side recording controller, lazily built on first `recording` access. */
+        this._recording = 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`).
+         */
+        this.maxRenderSizeByFlight = new Map();
         this.cfg = cfg;
         this.transport =
             transport ??
@@ -507,6 +526,17 @@ export class KerbcastClient extends TypedEmitter {
             warpRate: this._warpRate,
         };
     }
+    /**
+     * 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() {
+        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
@@ -537,8 +567,21 @@ export class KerbcastClient extends TypedEmitter {
         if (!res.ok)
             throw new Error(`/cameras returned ${res.status}`);
         const body = (await res.json());
+        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) {
+        return this.maxRenderSizeByFlight.get(flightId) ?? null;
+    }
     /**
      * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
      * `connect` while already connected disconnects first.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./__generated__/types";
 export { KerbcastClient, BrowserKerbcastTransport, type BrowserKerbcastTransportOptions, type InboundVideoStats, type KerbcastCameraHandle, type KerbcastClientConfig, type KerbcastConnectionState, type KerbcastClientEvents, type KerbcastCameraEvents, type KerbcastTransport, type KerbcastPeer, type KerbcastDataChannel, type DiscoveredCamera, type NoiseConfig, } from "./client";
 export { PanZoomController, type PanZoomCommandSink, 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";

package/dist/index.js

@@ -5,3 +5,4 @@
 export * from "./__generated__/types";
 export { KerbcastClient, BrowserKerbcastTransport, } from "./client";
 export { PanZoomController, } from "./panZoom";
+export { RecordingController, createMediabunnyTrimmerLoader, negotiateMimeType, commonUtWindow, utToRecordingTimeMs, DEFAULT_COVERAGE_TIMEOUT_MS, ARM_TIMEOUT_MS, } from "./recording";