@ksp-gonogo/kerbcast 1.8.1 → 1.9.0

package/dist/__generated__/types.d.ts

@@ -22,6 +22,35 @@ export declare enum CameraKind {
     Part = "part",
     Kerbal = "kerbal"
 }
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ *
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export declare enum CaptureState {
+    /** Capturing at the primary rate: an ordinary live feed. */
+    Full = "full",
+    /**
+     * Promoted and on the way to the primary rate, but not there yet — either
+     * awaiting the forced keyframe or still rate-limited by the capture budget.
+     */
+    Ramping = "ramping",
+    /**
+     * Background capture: recent but sparse. A consumer should present this as
+     * a reduced-rate channel, not as a live feed.
+     */
+    Background = "background",
+    /**
+     * Not being captured at all — unsubscribed, or the background layer has
+     * been shed under load. A consumer must NOT keep presenting the last frame
+     * as though it were a live low-rate channel.
+     */
+    Off = "off"
+}
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when
@@ -95,6 +124,11 @@ export interface CameraState {
      * Defaults to `Part` so existing payloads are unaffected.
      */
     kind?: CameraKind;
+    /**
+     * How hard this camera is currently being captured. Defaults to `Full` so
+     * existing payloads and plugins predating background capture are unaffected.
+     */
+    captureState?: CaptureState;
     /**
      * The kerbal's real `ProtoCrewMember.persistentID`: the stable key a
      * consumer correlates against. `None` for part cameras. Distinct from
@@ -248,6 +282,18 @@ export interface ReportDisplaySizePayload {
 export interface SceneStateChangedPayload {
     inFlight: boolean;
 }
+/**
+ * Consumer's background-capture request. Global rather than
+ * per-camera: it is a statement about how much background cost this consumer
+ * wants spent, not about one camera. Zero stops asking.
+ */
+export interface SetBackgroundCaptureFpsPayload {
+    /**
+     * Requested rate in fps for cameras this consumer is not displaying.
+     * Clamped to the operator ceiling; 0 means no background capture.
+     */
+    fps: number;
+}
 export interface SetDegradePayload {
     flightId: number;
     /**
@@ -458,6 +504,31 @@ export type ClientMessage =
     type: "set-force-full-resolution";
     content: SetForceFullResolutionPayload;
 }
+/**
+ * Ask for background capture: subscribed cameras that this
+ * consumer is NOT displaying keep capturing at a low rate instead of
+ * stopping, so switching to one promotes an already-flowing stream rather
+ * than cold-starting from black.
+ *
+ * Per-consumer and MAX-aggregated, like `ReportDisplaySize`: it runs
+ * at the highest rate any connected consumer asked for, and relaxes when
+ * they lower it or disconnect. A consumer that never sends this pays
+ * nothing, which is why a stock install needs no configuration to serve
+ * both a plain viewer and a consumer that wants background capture.
+ *
+ * The rate is a REQUEST, not a guarantee. It is clamped to the operator's
+ * `BackgroundCaptureFps` ceiling and is the first thing dropped when the
+ * game approaches its framerate floor — watch `CameraState.capture_state`
+ * for what is actually happening. Send 0 to stop asking.
+ *
+ * Receiving the frames is not the same as keeping them: a consumer that
+ * wants history for a camera it isn't showing has to buffer the background
+ * feed itself.
+ */
+ | {
+    type: "set-background-capture-fps";
+    content: SetBackgroundCaptureFpsPayload;
+}
 /**
  * Set the camera's field-of-view (degrees). Silently ignored for
  * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/dist/__generated__/types.js

@@ -22,6 +22,36 @@ export var CameraKind;
     CameraKind["Part"] = "part";
     CameraKind["Kerbal"] = "kerbal";
 })(CameraKind || (CameraKind = {}));
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ *
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export var CaptureState;
+(function (CaptureState) {
+    /** Capturing at the primary rate: an ordinary live feed. */
+    CaptureState["Full"] = "full";
+    /**
+     * Promoted and on the way to the primary rate, but not there yet — either
+     * awaiting the forced keyframe or still rate-limited by the capture budget.
+     */
+    CaptureState["Ramping"] = "ramping";
+    /**
+     * Background capture: recent but sparse. A consumer should present this as
+     * a reduced-rate channel, not as a live feed.
+     */
+    CaptureState["Background"] = "background";
+    /**
+     * Not being captured at all — unsubscribed, or the background layer has
+     * been shed under load. A consumer must NOT keep presenting the last frame
+     * as though it were a live low-rate channel.
+     */
+    CaptureState["Off"] = "off";
+})(CaptureState || (CaptureState = {}));
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when

package/dist/client.d.ts

@@ -474,6 +474,31 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * feed primitives self-measure and call this; consumers do not report by hand.
      */
     reportDisplaySize(flightId: number, width: number, height: number): Promise<void>;
+    /**
+     * Ask for background capture: subscribed cameras this consumer is NOT
+     * displaying keep capturing at a low rate instead of stopping, so switching
+     * to one promotes an already-flowing stream rather than cold-starting from
+     * black.
+     *
+     * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+     * never calls this pays nothing, which is why the same kerbcast install
+     * serves both a plain viewer and a consumer that wants background capture
+     * with no configuration either side. Pass 0 to stop asking; the request is
+     * dropped automatically on disconnect.
+     *
+     * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+     * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+     * approaches its framerate floor. Read `CameraState.captureState` for what is
+     * actually happening rather than assuming this took effect — it reports
+     * `Background` only while the reduced rate is genuinely running, and `Off`
+     * once the layer has been shed.
+     *
+     * Receiving background frames is not the same as keeping them. A consumer
+     * that wants *history* for a camera it isn't showing — to render instantly on
+     * switch under a simulated signal delay, say — has to buffer those feeds
+     * itself; background capture only makes the frames available to buffer.
+     */
+    setBackgroundCaptureFps(fps: number): Promise<void>;
     /**
      * 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

package/dist/client.js

@@ -712,6 +712,33 @@ export class KerbcastClient extends TypedEmitter {
     async reportDisplaySize(flightId, width, height) {
         await this._send({ type: "report-display-size", content: { flightId, width, height } });
     }
+    /**
+     * Ask for background capture: subscribed cameras this consumer is NOT
+     * displaying keep capturing at a low rate instead of stopping, so switching
+     * to one promotes an already-flowing stream rather than cold-starting from
+     * black.
+     *
+     * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+     * never calls this pays nothing, which is why the same kerbcast install
+     * serves both a plain viewer and a consumer that wants background capture
+     * with no configuration either side. Pass 0 to stop asking; the request is
+     * dropped automatically on disconnect.
+     *
+     * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+     * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+     * approaches its framerate floor. Read `CameraState.captureState` for what is
+     * actually happening rather than assuming this took effect — it reports
+     * `Background` only while the reduced rate is genuinely running, and `Off`
+     * once the layer has been shed.
+     *
+     * Receiving background frames is not the same as keeping them. A consumer
+     * that wants *history* for a camera it isn't showing — to render instantly on
+     * switch under a simulated signal delay, say — has to buffer those feeds
+     * itself; background capture only makes the frames available to buffer.
+     */
+    async setBackgroundCaptureFps(fps) {
+        await this._send({ type: "set-background-capture-fps", content: { fps } });
+    }
     /**
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "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

@@ -29,6 +29,36 @@ export enum CameraKind {
 	Kerbal = "kerbal",
 }
 
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ * 
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export enum CaptureState {
+	/** Capturing at the primary rate: an ordinary live feed. */
+	Full = "full",
+	/**
+	 * Promoted and on the way to the primary rate, but not there yet — either
+	 * awaiting the forced keyframe or still rate-limited by the capture budget.
+	 */
+	Ramping = "ramping",
+	/**
+	 * Background capture: recent but sparse. A consumer should present this as
+	 * a reduced-rate channel, not as a live feed.
+	 */
+	Background = "background",
+	/**
+	 * Not being captured at all — unsubscribed, or the background layer has
+	 * been shed under load. A consumer must NOT keep presenting the last frame
+	 * as though it were a live low-rate channel.
+	 */
+	Off = "off",
+}
+
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when
@@ -106,6 +136,11 @@ export interface CameraState {
 	 * Defaults to `Part` so existing payloads are unaffected.
 	 */
 	kind?: CameraKind;
+	/**
+	 * How hard this camera is currently being captured. Defaults to `Full` so
+	 * existing payloads and plugins predating background capture are unaffected.
+	 */
+	captureState?: CaptureState;
 	/**
 	 * The kerbal's real `ProtoCrewMember.persistentID`: the stable key a
 	 * consumer correlates against. `None` for part cameras. Distinct from
@@ -268,6 +303,19 @@ export interface SceneStateChangedPayload {
 	inFlight: boolean;
 }
 
+/**
+ * Consumer's background-capture request. Global rather than
+ * per-camera: it is a statement about how much background cost this consumer
+ * wants spent, not about one camera. Zero stops asking.
+ */
+export interface SetBackgroundCaptureFpsPayload {
+	/**
+	 * Requested rate in fps for cameras this consumer is not displaying.
+	 * Clamped to the operator ceiling; 0 means no background capture.
+	 */
+	fps: number;
+}
+
 export interface SetDegradePayload {
 	flightId: number;
 	/**
@@ -473,6 +521,28 @@ export type ClientMessage =
 	 * term, never the perf-protection ceiling.
 	 */
 	| { type: "set-force-full-resolution", content: SetForceFullResolutionPayload }
+	/**
+	 * Ask for background capture: subscribed cameras that this
+	 * consumer is NOT displaying keep capturing at a low rate instead of
+	 * stopping, so switching to one promotes an already-flowing stream rather
+	 * than cold-starting from black.
+	 * 
+	 * Per-consumer and MAX-aggregated, like `ReportDisplaySize`: it runs
+	 * at the highest rate any connected consumer asked for, and relaxes when
+	 * they lower it or disconnect. A consumer that never sends this pays
+	 * nothing, which is why a stock install needs no configuration to serve
+	 * both a plain viewer and a consumer that wants background capture.
+	 * 
+	 * The rate is a REQUEST, not a guarantee. It is clamped to the operator's
+	 * `BackgroundCaptureFps` ceiling and is the first thing dropped when the
+	 * game approaches its framerate floor — watch `CameraState.capture_state`
+	 * for what is actually happening. Send 0 to stop asking.
+	 * 
+	 * Receiving the frames is not the same as keeping them: a consumer that
+	 * wants history for a camera it isn't showing has to buffer the background
+	 * feed itself.
+	 */
+	| { type: "set-background-capture-fps", content: SetBackgroundCaptureFpsPayload }
 	/**
 	 * Set the camera's field-of-view (degrees). Silently ignored for
 	 * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/src/client.ts

@@ -1127,6 +1127,34 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     await this._send({ type: "report-display-size", content: { flightId, width, height } });
   }
 
+  /**
+   * Ask for background capture: subscribed cameras this consumer is NOT
+   * displaying keep capturing at a low rate instead of stopping, so switching
+   * to one promotes an already-flowing stream rather than cold-starting from
+   * black.
+   *
+   * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+   * never calls this pays nothing, which is why the same kerbcast install
+   * serves both a plain viewer and a consumer that wants background capture
+   * with no configuration either side. Pass 0 to stop asking; the request is
+   * dropped automatically on disconnect.
+   *
+   * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+   * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+   * approaches its framerate floor. Read `CameraState.captureState` for what is
+   * actually happening rather than assuming this took effect — it reports
+   * `Background` only while the reduced rate is genuinely running, and `Off`
+   * once the layer has been shed.
+   *
+   * Receiving background frames is not the same as keeping them. A consumer
+   * that wants *history* for a camera it isn't showing — to render instantly on
+   * switch under a simulated signal delay, say — has to buffer those feeds
+   * itself; background capture only makes the frames available to buffer.
+   */
+  async setBackgroundCaptureFps(fps: number): Promise<void> {
+    await this._send({ type: "set-background-capture-fps", content: { fps } });
+  }
+
   /**
    * 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