@ksp-gonogo/kerbcast 1.4.0

package/dist/client.d.ts

@@ -0,0 +1,433 @@
+import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, Layer, QualityPreset, SettingsStatePayload } from "./__generated__/types";
+import { CameraLifecycle } from "./__generated__/types";
+/** 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. */
+    enabled: boolean;
+}
+/**
+ * Per-camera handle returned from {@link KerbcastClient.camera}.
+ * Stable identity per flight ID for the lifetime of the client.
+ */
+export interface KerbcastCameraHandle {
+    readonly flightId: number;
+    readonly state: CameraState | null;
+    readonly mediaStream: MediaStream | null;
+    /**
+     * True while the camera has a live source whose frames have stopped
+     * arriving (the noise pipeline's stall detector). Always false when the
+     * noise pipeline is unavailable (no `captureStream`) or bypassed.
+     * Transitions are emitted as `stall` events.
+     */
+    readonly stalled: boolean;
+    /** Current {@link setShowStatic} setting. */
+    readonly showStatic: boolean;
+    setLayers(layers: Layer[]): Promise<void>;
+    setRenderSize(width: number, height: number): Promise<void>;
+    setFov(fov: number): Promise<void>;
+    setPan(yaw: number, pitch: number): Promise<void>;
+    /**
+     * Set a persistent pan/tilt velocity (normalised, -1..1 per axis;
+     * +yaw = right, +pitch = up). Holds until superseded — send
+     * `setPanRate(0, 0)` to stop. Smoothing happens in the plugin's frame
+     * loop, so call this only when the input changes (e.g. arrow down /
+     * release), not on a timer.
+     */
+    setPanRate(yawRate: number, pitchRate: number): Promise<void>;
+    /**
+     * Set a persistent zoom velocity (normalised, -1..1; +1 = zoom in,
+     * FoV decreasing). Holds until superseded — send `setZoomRate(0)` to
+     * stop. Like {@link setPanRate}, call on input change (press-and-hold),
+     * not on a timer.
+     */
+    setZoomRate(rate: number): Promise<void>;
+    setDegrade(level: number): Promise<void>;
+    /**
+     * Request a resolution preset for this camera, or `null` for auto
+     * (clear the viewer clamp). Server-wide and last-write-wins across
+     * peers; the authoritative result arrives as a `change` event
+     * (`state.viewerQuality` + `state.qualityLimitedBy`). The effective
+     * resolution is min(operator ceiling, adaptive level, preset): a
+     * preset can only lower quality, and the sidecar's adaptive perf
+     * machinery keeps overriding it downward while throttled.
+     */
+    setQuality(preset: QualityPreset | null): Promise<void>;
+    requestKeyframe(): Promise<void>;
+    /**
+     * Override noise settings for this camera only. Takes precedence over the
+     * client-level default in {@link KerbcastClientConfig.noise}.
+     */
+    configure(options: {
+        noise?: Partial<NoiseConfig>;
+    }): void;
+    /**
+     * Choose whether animated static is drawn (default true). When false:
+     * a stalled source holds its last decoded frame with no noise (the
+     * consumer's chrome carries the staleness indicator via the `stall`
+     * event / {@link stalled}), and a sourceless path clears to black
+     * without noise so only the text overlay renders.
+     */
+    setShowStatic(enabled: boolean): void;
+    on<K extends keyof KerbcastCameraEvents>(event: K, handler: (data: KerbcastCameraEvents[K]) => void): () => void;
+}
+/** Event payloads emitted by a {@link KerbcastCameraHandle}. */
+export interface KerbcastCameraEvents {
+    /** Latest `CameraState` from the sidecar's `camera-state-changed`. */
+    change: CameraState;
+    /** Track arrival or teardown for this camera. `null` on disconnect. */
+    stream: MediaStream | null;
+    /** Frames stopped arriving on a live source (`true`) / resumed (`false`). */
+    stall: boolean;
+}
+/** Configuration for {@link KerbcastClient} construction. */
+export interface KerbcastClientConfig {
+    /** Sidecar host (matches the sidecar's `--http-bind`). */
+    host: string;
+    /** Sidecar port. */
+    port: number;
+    /**
+     * ICE servers to use. Defaults to Google's public STUN server,
+     * which is enough for LAN streaming.
+     */
+    iceServers?: RTCIceServer[];
+    /**
+     * Default noise settings for all cameras. Individual cameras can override
+     * this via `cam.configure({ noise: ... })`. Noise is enabled by default.
+     */
+    noise?: Partial<NoiseConfig>;
+    /**
+     * ICE gathering timeout in milliseconds. Passed to the default
+     * {@link BrowserKerbcastTransport}; ignored when a custom transport is
+     * provided (the transport owns gathering). Defaults to 2000 ms.
+     *
+     * On LAN topologies where the STUN server is unreachable (e.g. Steam Deck
+     * IPv6 LAN with no internet path), gathering can stall for the full STUN
+     * timeout. Host candidates alone are sufficient for LAN streaming, so this
+     * timeout lets the connect flow proceed once host candidates are gathered.
+     */
+    iceGatheringTimeoutMs?: number;
+    /**
+     * Override how the SDP offer/answer is exchanged. Defaults to a POST to the
+     * sidecar's HTTP `/offer`. A station screen injects a version that relays
+     * the offer through the main screen (which can reach the sidecar), so the
+     * station needs no direct sidecar address. The media itself still flows
+     * peer-to-sidecar (direct or via TURN) -- only the handshake is brokered.
+     */
+    negotiate?: (offer: {
+        sdp: string;
+        cameras: number[];
+        slots?: number;
+    }) => Promise<{
+        sdp: string;
+        cameras: number[];
+    }>;
+}
+/** WebRTC connection state surface. */
+export type KerbcastConnectionState = "disconnected" | "connecting" | "connected" | "failed";
+/**
+ * Inbound RTP video statistics for one camera track, derived from the
+ * WebRTC stats report. Fields are `undefined` when the browser has not yet
+ * emitted that stat (e.g. `framesPerSecond` before the first full second).
+ * `packetsReceived` and `bytesReceived` default to 0 in the same case.
+ *
+ * Retrieve per-camera stats via {@link KerbcastClient.inboundVideoStats}.
+ */
+export interface InboundVideoStats {
+    packetsReceived: number;
+    bytesReceived: number;
+    framesReceived: number | undefined;
+    framesDecoded: number | undefined;
+    jitter: number | undefined;
+    framesPerSecond: number | undefined;
+}
+/**
+ * Camera summary returned by {@link KerbcastClient.discover} (`GET /cameras`).
+ *
+ * This is the shape the sidecar serialises from its internal `CameraInfo`
+ * struct. It is a discovery snapshot, not a live operating state: it carries
+ * capability and identity fields but not per-connection operator state
+ * (`layers`, `renderWidth`, `panYaw`, etc.) -- those arrive over the data
+ * channel after `connect()`.
+ *
+ * Deliberately separate from `CameraState` even though the two share several
+ * field names, because the shapes differ: `DiscoveredCamera` has `maxWidth`
+ * / `maxHeight` (physical sensor limits) which `CameraState` omits, while
+ * `CameraState` adds runtime fields (`layers`, `renderWidth`, `panYaw`, ...).
+ */
+export interface DiscoveredCamera {
+    flightId: number;
+    /** Part-destruction lifecycle. `"active"` for live cameras. */
+    lifecycle?: CameraLifecycle;
+    partName: string;
+    partTitle: string;
+    cameraName: string;
+    vesselName: string;
+    /** Physical sensor width ceiling (pixels). Distinct from `renderWidth` on
+     *  `CameraState`, which is the currently-negotiated resolution. */
+    maxWidth: number;
+    /** Physical sensor height ceiling (pixels). */
+    maxHeight: number;
+    supportsZoom: boolean;
+    fov: number;
+    fovMin: number;
+    fovMax: number;
+    supportsPan: boolean;
+    panYawMin: number;
+    panYawMax: number;
+    panPitchMin: number;
+    panPitchMax: number;
+    /** Current encoder bitrate in bits per second. 0 when no encoder is running. */
+    encoderBitrateBps: number;
+    /** REMB-derived bandwidth target. 0 until the first feedback arrives. */
+    targetBitrateBps: number;
+    /** Effective degrade level (max across active subscribers). 0.0 to 1.0. */
+    degradeLevel: number;
+}
+/** Event payloads emitted by a {@link KerbcastClient}. */
+export interface KerbcastClientEvents {
+    "state-change": KerbcastConnectionState;
+    "cameras-change": CameraState[];
+    "adaptive-shed": AdaptiveShedPayload;
+    error: ErrorPayload;
+    /**
+     * Fired whenever a `ping` keepalive arrives from the sidecar.
+     * Consumers can use this to reset their own staleness watchdogs
+     * without intercepting at the transport layer.
+     */
+    ping: undefined;
+    /**
+     * Fired when a `settings-state` message arrives (after `Hello` and
+     * whenever the plugin-reported throttle state changes). Payload
+     * reflects what the plugin has applied, not just what was requested.
+     */
+    "settings-change": SettingsStatePayload;
+}
+/**
+ * Pluggable WebRTC transport. Production code uses the default
+ * (browser `RTCPeerConnection`). Tests substitute an in-memory
+ * implementation to exercise the state machine without a real peer.
+ */
+export interface KerbcastTransport {
+    createPeer(iceServers: RTCIceServer[]): KerbcastPeer;
+}
+export interface KerbcastPeer {
+    addRecvOnlyTransceiver(): void;
+    createDataChannel(label: string): KerbcastDataChannel;
+    onTrack(handler: (track: MediaStreamTrack, idx: number, mid: string) => void): void;
+    onStateChange(handler: (state: KerbcastConnectionState) => void): void;
+    createOffer(): Promise<string>;
+    setLocalDescription(sdp: string): Promise<void>;
+    setRemoteAnswer(sdp: string): Promise<void>;
+    waitForIceComplete(): Promise<void>;
+    localSdp(): string;
+    close(): void;
+    /**
+     * Retrieve the raw WebRTC stats report. Optional so existing third-party
+     * transports and mocks that predate this method keep compiling without
+     * changes. Equivalent to `RTCPeerConnection.getStats(null)`.
+     */
+    getStats?(): Promise<RTCStatsReport>;
+}
+export interface KerbcastDataChannel {
+    send(payload: string): void;
+    onOpen(handler: () => void): void;
+    onMessage(handler: (raw: string) => void): void;
+    onClose(handler: () => void): void;
+}
+/** Options for {@link BrowserKerbcastTransport}. */
+export interface BrowserKerbcastTransportOptions {
+    /**
+     * Maximum time (ms) to wait for ICE gathering to complete before proceeding
+     * with whatever candidates have been gathered. Defaults to 2000 ms.
+     *
+     * On LAN paths where the STUN server is unreachable, gathering blocks until
+     * the STUN timeout elapses. Host candidates are all a local LAN stream
+     * needs, so this timeout lets connect proceed without waiting for STUN.
+     */
+    iceGatheringTimeoutMs?: number;
+}
+export declare class BrowserKerbcastTransport implements KerbcastTransport {
+    private readonly opts;
+    constructor(opts?: BrowserKerbcastTransportOptions);
+    createPeer(iceServers: RTCIceServer[]): KerbcastPeer;
+}
+declare class TypedEmitter<E> {
+    private readonly listeners;
+    on<K extends keyof E>(event: K, handler: (data: E[K]) => void): () => void;
+    protected emit<K extends keyof E>(event: K, data: E[K]): void;
+}
+/**
+ * High-level kerbcast sidecar client. Owns the WebRTC peer + the
+ * `kerbcast-control` data channel + the per-camera registry + the
+ * `MediaStream`s for each subscribed camera.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const client = new KerbcastClient({ host: "192.168.1.74", port: 8088 });
+ * await client.connect();
+ *
+ * const cam = client.camera(2592004302);
+ * await cam.setFov(35);
+ * videoEl.srcObject = cam.mediaStream;
+ *
+ * cam.on("change", (state) => { ... });
+ * client.on("adaptive-shed", (event) => { ... });
+ * ```
+ *
+ * Disconnect with {@link disconnect}. The handles returned by
+ * `camera()` remain valid across reconnects; their `mediaStream`
+ * goes null on disconnect and is replaced when the next connect's
+ * tracks arrive.
+ */
+export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
+    private readonly cfg;
+    private readonly transport;
+    private peer;
+    private control;
+    private _state;
+    private _cameras;
+    private readonly handles;
+    private requestedOrder;
+    /** Set when `connect` is given an explicit slot pool. Switches track
+     *  routing from legacy index order to mid-keyed dynamic slots. */
+    private dynamicMode;
+    /** Dynamic mode: transceiver mid -> the live track on that slot. */
+    private readonly trackByMid;
+    /** Dynamic mode: transceiver mid -> the camera bound to that slot
+     *  (populated by SlotMap -- initial bindings announced on Hello). */
+    private readonly flightByMid;
+    /**
+     * Legacy mode: raw incoming track id -> flightId. Populated in handleTrack
+     * so inboundVideoStats() can match inbound-rtp report entries by
+     * trackIdentifier. Cleared on disconnect. Not used in dynamic mode (which
+     * matches by mid instead).
+     */
+    private readonly flightByTrackId;
+    /** Sidecar version reported on `Hello`; null before handshake. */
+    private _sidecarVersion;
+    private _encoderBackend;
+    /** Last-received throttle state from `settings-state`. False until the first push. */
+    private _throttleMainScreen;
+    /**
+     * Mission-time capture clock from `settings-state`. `_captureUt` is null
+     * until the first clock arrives (and against an old sidecar that never
+     * sends one), so consumers treat it as "no clock". `_captureEpoch` bumps
+     * on discontinuities (revert / quickload / scene reload); only the change
+     * is meaningful. `_warpRate` defaults to 1 when the field is absent.
+     */
+    private _captureUt;
+    private _captureEpoch;
+    private _warpRate;
+    constructor(cfg: KerbcastClientConfig, transport?: KerbcastTransport);
+    get state(): KerbcastConnectionState;
+    get cameras(): ReadonlyArray<CameraState>;
+    get sidecarVersion(): string | null;
+    get encoderBackend(): string | null;
+    /**
+     * Current effective state of the "Throttle KSP main render" setting.
+     * Reflects what the plugin has applied (from `settings-state` messages),
+     * not just what was last requested. False until the first push arrives.
+     */
+    get throttleMainScreen(): boolean;
+    /**
+     * Mission-time capture clock, from the sidecar's ~1Hz `settings-state`.
+     * `captureUt` is the KSP universal time (seconds) the current video was
+     * captured at, or null when no clock is known (old plugin/sidecar, or
+     * before the first push). `epoch` bumps on a UT discontinuity so a
+     * consumer can flush and resync. `warpRate` lets a consumer interpolate
+     * `captureUt` between samples; defaults to 1.
+     */
+    get clock(): {
+        captureUt: number | null;
+        epoch: number;
+        warpRate: number;
+    };
+    /**
+     * Send a `set-throttle-main-screen` command to the sidecar, which writes
+     * `global.control.json` for the plugin to apply. The plugin persists the
+     * change in the per-save difficulty parameter. The resulting
+     * `settings-state` broadcast reflects the applied value.
+     */
+    setThrottleMainScreen(enabled: boolean): Promise<void>;
+    /**
+     * Pre-handshake camera discovery via the sidecar's HTTP `/cameras`
+     * endpoint. Useful when the consumer wants to pick which cameras
+     * to subscribe to before opening a peer connection.
+     */
+    discover(): Promise<DiscoveredCamera[]>;
+    /**
+     * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
+     * `connect` while already connected disconnects first.
+     *
+     * Two modes:
+     * - **Legacy** (no `opts.slots`): one transceiver per requested camera;
+     *   an empty array subscribes to every currently-known camera. Tracks
+     *   route by m-line index. Unchanged behaviour.
+     * - **Dynamic** (`opts.slots` set): negotiates a pool of `opts.slots`
+     *   recv-only video slots. `requestedCameras` are the *initial*
+     *   subscription bound to the first slots; spare slots are filled at
+     *   runtime via {@link subscribe}. Tracks route by transceiver mid
+     *   (the sidecar announces bindings via SlotMap), so switching a slot's
+     *   camera needs no renegotiation.
+     */
+    connect(requestedCameras?: number[], opts?: {
+        slots?: number;
+    }): Promise<void>;
+    /** Default signaling: POST the offer to the sidecar's HTTP `/offer`. */
+    private httpNegotiate;
+    disconnect(): void;
+    /**
+     * Stable per-flight-id handle. Creates a new handle on first call
+     * for a given ID; returns the same handle on subsequent calls.
+     */
+    camera(flightId: number): KerbcastCameraHandle;
+    /**
+     * Dynamic mode only: bind a camera to a free slot on the already-connected
+     * peer. The camera's stream appears on its handle once the sidecar answers
+     * with a SlotMap; the sidecar emits an `error` event if no slot is free. No
+     * renegotiation.
+     */
+    subscribe(flightId: number): Promise<void>;
+    /**
+     * Dynamic mode only: release a camera's slot. Its handle's `mediaStream`
+     * goes null once the sidecar confirms with a SlotMap.
+     */
+    unsubscribe(flightId: number): Promise<void>;
+    /**
+     * Internal — resolves the effective noise enabled state for a camera,
+     * merging the per-camera override (if any) with the client-level default.
+     */
+    _resolveNoise(override: Partial<NoiseConfig> | null): boolean;
+    /**
+     * Internal — sends a typed `ClientMessage` over the control
+     * channel. Drops silently if the channel hasn't opened yet (and
+     * logs to console). Public on the camera handle, but consumers
+     * shouldn't need to call this directly.
+     */
+    _send(msg: ClientMessage): Promise<void>;
+    private getOrCreateHandle;
+    private handleTrack;
+    private handleServerMessage;
+    /**
+     * Re-source a resurrected camera's handle from the track the client still
+     * holds for its slot. Called when {@link KerbcastCameraHandle._setState}
+     * reports a Destroyed -> Active transition: the sidecar rebinds the same
+     * track without a new slot-map, so nothing else drives the handle back out
+     * of the sourceless (static) state it entered on destroy.
+     */
+    private _resourceHandle;
+    private setState;
+    /**
+     * Inbound RTP video statistics keyed by flight ID. Returns an empty map
+     * when not connected or when the transport does not implement `getStats`.
+     *
+     * Iterates the stats report and matches `inbound-rtp` + `kind === "video"`
+     * entries to cameras. Legacy mode matches by `trackIdentifier`; dynamic
+     * mode falls back to the `mid` field when `trackIdentifier` is absent
+     * (modern browsers include it; some implementations omit it).
+     */
+    inboundVideoStats(): Promise<Map<number, InboundVideoStats>>;
+    private tearDownStreams;
+}
+export {};