@ksp-gonogo/kerbcast 1.10.1 → 1.10.3

package/dist/__generated__/types.d.ts

@@ -99,6 +99,13 @@ export declare enum QualityPreset {
     Half = "half",
     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
@@ -238,6 +245,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 {
     cameras: CameraState[];

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, Layer, QualityPreset, SettingsStatePayload, TrackMode } from "./__generated__/types";
+import type { AdaptiveShedPayload, CameraState, ClientMessage, DisplaySizeReport, 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`. */
@@ -214,6 +214,21 @@ export interface DiscoveredCamera {
     targetBitrateBps: number;
     /** Effective degrade level (max across active subscribers). 0.0 to 1.0. */
     degradeLevel: number;
+    /** 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}. */
 export interface KerbcastClientEvents {
@@ -240,6 +255,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;
 }
 /**
  * Pluggable WebRTC transport. Production code uses the default

package/dist/client.js

@@ -626,6 +626,7 @@ export class KerbcastClient extends TypedEmitter {
         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/dist/index.d.ts

@@ -1,4 +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";
+export { RecordingController, createMediabunnyTrimmerLoader, negotiateMimeType, commonUtWindow, utToRecordingTimeMs, DEFAULT_COVERAGE_TIMEOUT_MS, ARM_TIMEOUT_MS, videoElementDecodedSizeProbe, type ActiveRecordingInfo, type DecodedSizeProbe, 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,4 +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";
+export { RecordingController, createMediabunnyTrimmerLoader, negotiateMimeType, commonUtWindow, utToRecordingTimeMs, DEFAULT_COVERAGE_TIMEOUT_MS, ARM_TIMEOUT_MS, videoElementDecodedSizeProbe, } from "./recording";

package/dist/noise.js

@@ -145,6 +145,17 @@ export function tryCreateNoisePipeline(rawStream, initialIntensity, options) {
         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;

package/dist/recording.d.ts

@@ -45,20 +45,22 @@ export interface StartRecordingOptions {
     /**
      * Force this feed to the operator's full render size for the duration of
      * the recording (overrides the display-size demand only; still yields to
-     * the adaptive framerate shed). Off by default. A single recording arms
-     * and waits (bounded) for the bump before the clip starts, so it opens on
-     * full-res frames; a grouped recording starts immediately and the lead-in
-     * is cut via the existing UT-window trim instead. Released automatically
-     * on stop, discard, or auto-stop.
+     * the adaptive framerate shed). Off by default. The recording arms and
+     * waits (bounded) until the browser is decoding full-size frames before
+     * the clip starts: MediaRecorder fixes the clip's frame size when it
+     * starts, so a later bump would never reach the file. A grouped recording
+     * arms every member and starts all their recorders together once every
+     * feed is ready (or the shared bound passes). Released automatically on
+     * stop, discard, or auto-stop.
      */
     forceFullResolution?: boolean;
 }
 /**
- * Bound on the single-recording arm-and-wait: how long
- * {@link RecordingController.startRecording} waits for a forced feed to
- * reach full resolution before starting the recorder anyway. Never hangs a
- * start indefinitely (feed out of flight, wedged, or the sidecar/plugin
- * round trip taking longer than expected).
+ * Bound on the arm-and-wait: how long a forced recording waits for its feed
+ * (or, for a group, every member's feed) to reach full resolution before
+ * starting the recorder anyway. Never hangs a start indefinitely (feed out
+ * of flight, wedged, or the sidecar/plugin round trip taking longer than
+ * expected).
  */
 export declare const ARM_TIMEOUT_MS = 3000;
 /** Options for {@link RecordingController.stopGroupedRecording}. */
@@ -122,11 +124,11 @@ export interface ActiveRecordingInfo {
     startedAt: number;
     groupId?: string;
     /**
-     * True while a single forced recording is armed (force sent, waiting for
-     * the feed to reach full resolution) but the recorder has not started
-     * yet. Always false for a non-forced recording and for grouped members
-     * (which record immediately). A UI shows a distinct "arming" state while
-     * this is true.
+     * True while a forced recording is armed (force sent, waiting for the
+     * feed to reach full resolution) but the recorder has not started yet.
+     * Forced grouped members stay arming until every member is ready, then
+     * flip together. Always false for a non-forced recording. A UI shows a
+     * distinct "arming" state while this is true.
      */
     arming: boolean;
 }
@@ -208,6 +210,25 @@ export interface GroupTrimmer {
 }
 /** Loads a {@link GroupTrimmer}, or resolves null when trimming is unavailable. */
 export type TrimmerLoader = () => Promise<GroupTrimmer | null>;
+/**
+ * Watches the decoded frame size of a feed's live stream, calling `onSize`
+ * whenever it is known or changes (repeats are fine). Returns a stop function
+ * that releases everything the probe holds. The arm-and-wait gates a forced
+ * recording on this, not on the reported camera state: the state flips to
+ * the full size before the decoder delivers full-size frames, and
+ * MediaRecorder locks the clip to whatever size it sees first.
+ */
+export type DecodedSizeProbe = (flightId: number, stream: MediaStream, onSize: (width: number, height: number) => void) => () => void;
+/**
+ * Default {@link DecodedSizeProbe}: plays the stream into an off-DOM muted
+ * `<video>` and reads the decoded size from each frame
+ * (requestVideoFrameCallback where available) and from `resize` /
+ * `loadedmetadata`. `track.getSettings()` is not used because Chromium often
+ * reports stale or missing dimensions for remote WebRTC tracks. Outside a
+ * browser it never reports, so a forced recording falls back to the arm
+ * timeout.
+ */
+export declare const videoElementDecodedSizeProbe: DecodedSizeProbe;
 /** Options for {@link RecordingController}. */
 export interface RecordingControllerOptions {
     /**
@@ -216,6 +237,12 @@ export interface RecordingControllerOptions {
      * `import("mediabunny")` keyframe remux.
      */
     loadTrimmer?: TrimmerLoader;
+    /**
+     * Override how a forced recording observes its feed's decoded frame size
+     * (tests inject a fake; a harness without real decoding can follow the
+     * camera state instead). Defaults to {@link videoElementDecodedSizeProbe}.
+     */
+    probeDecodedSize?: DecodedSizeProbe;
 }
 /**
  * Builds a {@link TrimmerLoader} around a caller-supplied module import.
@@ -249,6 +276,7 @@ export declare class RecordingController {
     /** Per-group trimmer load kicked off at group-start, awaited at stop. */
     private readonly groupTrimmers;
     private readonly loadTrimmer;
+    private readonly probeDecodedSize;
     /** recordingIds in a grouped set, so they stay out of the standalone `recordings` list. */
     private readonly groupMemberIds;
     /** recordingId -> groupId, so discarding one member can pull it out of its group's array. */
@@ -268,6 +296,8 @@ export declare class RecordingController {
      * one; see {@link acquireForce}.
      */
     private readonly forceSendState;
+    /** groupId -> arm state, present only while a forced group is still arming. */
+    private readonly groupArms;
     private readonly listeners;
     private snapshot;
     /** While true, {@link rebuild} is a no-op; used to batch startGroupedRecording's
@@ -307,31 +337,20 @@ export declare class RecordingController {
      */
     private releaseForce;
     /**
-     * Whether `state` shows a feed actually rendering at its full target size,
-     * as opposed to merely having caught up to whatever small size it already
-     * had. Two ways to know the target:
-     *
-     * - `target` known (from `maxRenderSize`): ready once the operator size
-     *   has reached it and the rendered size has caught up to the operator
-     *   size. Resolves promptly even when the feed was already at its ceiling
-     *   before the force was sent (nothing ever "increases").
-     * - `target` unknown: falls back to requiring the operator size to have
-     *   increased past `baseline` (the first REAL state observed at or after
-     *   watch-start; see {@link watchResolutionReady}) and the rendered size
-     *   to have caught up. `baseline` is `null` until that first real state
-     *   arrives, and a `null` baseline is never ready: a placeholder `{0,0}`
-     *   would let any positive operator size look like an increase, so no
-     *   verdict is possible until a genuine baseline exists. This is a
-     *   strictly weaker guarantee than the known-target path: a feed already
-     *   at its true ceiling when forced will not be recognised as ready until
-     *   something else changes its operator size, or the wait simply times
-     *   out, but it still refuses to treat the pre-force snapshot itself as
-     *   ready.
-     *
-     * Either way, a state whose rendered size has not yet caught up to its own
-     * operator size (adaptive shed still catching up) is never ready.
+     * Fallback readiness for a feed whose ceiling is unknown to the client (no
+     * `maxRenderSize`), judged from the reported camera state alone. Ready once
+     * the operator size has increased past `baseline` (the first REAL state
+     * observed at or after watch-start; see {@link watchResolutionReady}) and
+     * the rendered size has caught up to it. `baseline` is `null` until that
+     * first real state arrives, and a `null` baseline is never ready: a
+     * placeholder `{0,0}` would let any positive operator size look like an
+     * increase. A feed already at its true ceiling when forced is not
+     * recognised until something else changes its operator size, so the wait
+     * usually times out instead, but the pre-force snapshot itself is never
+     * treated as ready. A state whose rendered size has not yet caught up to
+     * its own operator size (adaptive shed still catching up) is never ready.
      */
-    private isAtFullResolution;
+    private stateIncreasedPastBaseline;
     /**
      * Seeds a fallback baseline from an observed state, or returns `null` if
      * the state isn't a REAL observation (operator size still zero, i.e. no
@@ -341,14 +360,24 @@ export declare class RecordingController {
      */
     private seedResolutionBaseline;
     /**
-     * Waits for a forced feed to actually render at full resolution.
+     * Waits for a forced feed to actually deliver full-resolution frames.
+     *
+     * With the ceiling known (`maxRenderSize`), the gate is the decoded frame
+     * size from {@link probeDecodedSize} reaching it (within
+     * {@link DECODED_SIZE_TOLERANCE_PX}). The camera state is deliberately not
+     * trusted here: it reports the new size before the decoder delivers
+     * full-size frames, and a recorder started in that gap locks the clip to
+     * the old size. A feed already at its ceiling resolves on the probe's
+     * first report. With the ceiling unknown, falls back to the state-only
+     * check ({@link stateIncreasedPastBaseline}).
+     *
      * `timeoutMs` omitted means no bound: the wait only ends when the feed
      * becomes ready or the caller cancels it (the grouped path, bounded by the
-     * recording's own lifetime instead; see {@link startRecording}).
-     * Resolves `true` once ready, `false` on timeout. Returns a `cancel` next
-     * to the promise so a caller can abandon the wait (stop/discard) without
-     * leaking the underlying "change" subscription or timer; cancelling never
-     * settles the promise.
+     * group's one shared timer instead; see {@link armGroup}). Resolves `true`
+     * once ready, `false` on timeout. `cancel` abandons the wait (stop/discard)
+     * without settling the promise; every exit path releases the "change"
+     * subscription, the probe, and the timer. `lastDecoded` reports the most
+     * recent decoded size seen, for logging.
      */
     private watchResolutionReady;
     /**
@@ -356,16 +385,38 @@ export declare class RecordingController {
      * synchronously. Throws if the feed has no live track or is already
      * recording.
      *
-     * `inGroup` is internal (set by {@link startGroupedRecording}) and governs
-     * how `opts.forceFullResolution` behaves: a single recording (`inGroup`
-     * false) arms and waits, bounded by {@link ARM_TIMEOUT_MS}, for the feed to
-     * reach full resolution before the recorder actually starts, so the clip
-     * opens on full-res frames. A grouped member starts immediately and
-     * instead records the moment it reaches full resolution
-     * (`resolutionReadyAt`/`resolutionReadyUt`) so {@link stopGroupedRecording}
-     * can fold it into the common trim window.
+     * With `opts.forceFullResolution`, the recording arms and waits, bounded by
+     * {@link ARM_TIMEOUT_MS}, for the feed to reach full resolution before the
+     * recorder actually starts, so the clip opens on full-res frames.
+     * `inGroup` is internal (set by {@link startGroupedRecording}): a forced
+     * grouped member arms the same way but leaves the wait to the group, which
+     * starts every member's recorder together (see {@link armGroup}).
      */
     startRecording(flightId: number, opts?: StartRecordingOptions, inGroup?: boolean): string;
+    /**
+     * Arms a forced group: watches every member's feed and starts all their
+     * recorders together once each has reached full resolution, or once the
+     * one shared {@link ARM_TIMEOUT_MS} bound passes, whichever comes first.
+     * Members stopped or discarded mid-arm drop out of the wait, so a slow
+     * feed that gets cancelled no longer holds the rest back.
+     */
+    private armGroup;
+    /** Members of a group still armed and waiting to start (not stopped or discarded). */
+    private armingMembers;
+    /** Starts an arming group once every member still waiting is ready. */
+    private checkGroupArm;
+    /**
+     * Ends a group's arm and starts every still-armed member's recorder in the
+     * same tick, on one shared clock base (`startedAt`, `utStart`), so the
+     * clips open together. Cancels any outstanding per-member watches (the
+     * timeout path).
+     */
+    private startArmedGroup;
+    /**
+     * Abandons a group's arm without starting anything: the caller is tearing
+     * the whole group down (stop or discard), so no member should start mid-way.
+     */
+    private cancelGroupArm;
     /**
      * Stop a recording and resolve its finished handle. Idempotent per id: a
      * second call (or a race with maxDurationMs auto-stop) returns the same
@@ -386,12 +437,15 @@ export declare class RecordingController {
     discardRecording(recordingId: string): void;
     /**
      * Start recording several feeds as one synchronised moment. All recorders
-     * open in a single tick to minimise skew. Returns the groupId plus the real
-     * per-feed recordingIds (so a caller can cancel one member individually via
-     * `stopRecording`/`discardRecording`, the same ids that end up on each
-     * clip's `RecordingHandle`). If any feed can't start (no track / already
-     * recording), the ones already started are discarded and the error
-     * rethrows.
+     * open in a single tick to minimise skew. With `opts.forceFullResolution`,
+     * every member arms first and that single tick comes later, once all feeds
+     * have reached full resolution or {@link ARM_TIMEOUT_MS} passes (see
+     * {@link armGroup}); the members report `arming` until then. Returns the
+     * groupId plus the real per-feed recordingIds (so a caller can cancel one
+     * member individually via `stopRecording`/`discardRecording`, the same ids
+     * that end up on each clip's `RecordingHandle`). If any feed can't start
+     * (no track / already recording), the ones already started are discarded
+     * and the error rethrows.
      */
     startGroupedRecording(flightIds: number[], opts?: StartRecordingOptions): GroupedRecordingStart;
     /**