@ksp-gonogo/kerbcast 1.4.0

package/dist/__generated__/types.d.ts

@@ -0,0 +1,529 @@
+export interface AdaptiveShedPayload {
+    level: number;
+    kspFps: number;
+    reason: string;
+}
+/**
+ * Lifecycle state of a camera. Transmitted in `CameraState` so clients
+ * can react to part destruction without a new message type.
+ *
+ * Destroyed is a terminal state — the sidecar never transitions a camera
+ * back to Active after writing the tombstone.
+ */
+export declare enum CameraLifecycle {
+    Active = "active",
+    Destroyed = "destroyed"
+}
+/**
+ * Layer mask. Mirrors `Kerbcast.CameraLayers` on the plugin side.
+ * Receiving clients use this for both the rendered-layer status reports
+ * and per-camera layer requests.
+ */
+export declare enum Layer {
+    Near = "NEAR",
+    Scaled = "SCALED",
+    Far = "FAR",
+    Galaxy = "GALAXY"
+}
+/**
+ * Viewer-selectable resolution preset. Each maps to a fraction of the
+ * operator-configured render size (the settings.cfg Width/Height ceiling):
+ * full = 1.0, threeQuarter = 0.75, half = 0.5, quarter = 0.25. The steps
+ * mirror the plugin's shed-table resolution ladder so the viewer clamp and
+ * the adaptive controller move on the same grid, and a preset can never
+ * exceed the ring's allocated max (every scale is <= 1.0 of the ceiling).
+ *
+ * Presets, not freeform WxH: a fixed menu keeps the unauthenticated
+ * viewer-writable surface tiny and aspect-correct by construction.
+ */
+export declare enum QualityPreset {
+    Full = "full",
+    ThreeQuarter = "threeQuarter",
+    Half = "half",
+    Quarter = "quarter"
+}
+/**
+ * Per-camera snapshot pushed by the sidecar on every state change
+ * (operator API call, adaptive shed, vessel change). Same shape served
+ * by `GET /cameras` so client UIs can treat the two interchangeably.
+ *
+ * Capability fields (`supports_zoom`, `supports_pan`) let clients
+ * render controls only for features each part actually offers — a
+ * fixed-FoV camera shouldn't get a zoom slider, a non-steerable one
+ * shouldn't get a pan stick.
+ */
+export interface CameraState {
+    flightId: number;
+    /**
+     * Part-destruction lifecycle. `Active` for live cameras. `Destroyed`
+     * when the plugin reports the Hullcam part was destroyed in-flight
+     * (collision, overheating, decoupling beyond physics range). Once
+     * destroyed the sidecar stops forwarding frames; the client should
+     * surface a "SIGNAL LOST" overlay and keep the last frame visible.
+     */
+    lifecycle?: CameraLifecycle;
+    partName: string;
+    partTitle: string;
+    cameraName: string;
+    vesselName: string;
+    /** Currently-rendered layers (effective after adaptive shedding). */
+    layers: Layer[];
+    /**
+     * Operator-requested layer mask — the ceiling adaptive shedding
+     * can reduce below. UIs use this to show "scaled is *requested* but
+     * not *active* right now due to fps".
+     */
+    operatorLayers: Layer[];
+    /**
+     * Currently-rendered dimensions (effective after adaptive
+     * resolution downscale). Equal to `operatorWidth` × `operatorHeight`
+     * when no auto-shed is in effect.
+     */
+    renderWidth: number;
+    renderHeight: number;
+    /**
+     * Operator-requested render size — ceiling adaptive downscale can
+     * reduce below.
+     */
+    operatorWidth: number;
+    operatorHeight: number;
+    /**
+     * Whether the part's Hullcam module supports runtime FoV changes
+     * (i.e. it's a `MuMechModuleHullCameraZoom`, not the fixed base
+     * `MuMechModuleHullCamera`). 19 of 21 stock parts do.
+     */
+    supportsZoom: boolean;
+    /** Current effective FoV in degrees. */
+    fov: number;
+    /**
+     * FoV bounds the operator can choose between. Wider than the
+     * camera's "default" — these come from the Hullcam part config.
+     * Equal to `fov` when `supports_zoom == false`.
+     */
+    fovMin: number;
+    fovMax: number;
+    /**
+     * Whether the part supports pan/tilt (kerbcast-side mod extension —
+     * no stock Hullcam parts are steerable, but the extended mod adds
+     * pan to specific parts). False on every shipping part today;
+     * clients should hide pan controls until this flips true.
+     */
+    supportsPan: boolean;
+    panYaw: number;
+    panPitch: number;
+    panYawMin: number;
+    panYawMax: number;
+    panPitchMin: number;
+    panPitchMax: number;
+    /**
+     * Current encoder bitrate target in bits per second. Equals
+     * `target_bitrate_bps` after the consume loop applies receiver
+     * feedback; the two diverge briefly between a REMB arriving and
+     * the consume loop's next tick. Zero when no encoder is running
+     * yet (no subscribers).
+     */
+    encoderBitrateBps: number;
+    /**
+     * Bandwidth target derived from receivers' REMB feedback (min
+     * across active subscribers). Drives the encoder when
+     * significantly diverged. Zero until the first REMB packet
+     * arrives — encoder falls back to the sidecar's CLI default.
+     */
+    targetBitrateBps: number;
+    /**
+     * Effective degrade level (max across subscribers' SetDegrade
+     * requests). 0.0 = perfect, 1.0 = max degradation. Applied
+     * alongside operator render-size + adaptive shed; the encoder
+     * multiplies its effective bitrate by `(1 - 0.7 * level)` and
+     * skips fan-out for a fraction of frames at high levels.
+     */
+    degradeLevel: number;
+    /**
+     * Viewer-requested resolution preset for this camera. Last write
+     * wins across all connected peers; this broadcast is what keeps
+     * every UI consistent. Absent/None = auto: no viewer clamp, the
+     * operator ceiling and the adaptive controller alone decide.
+     */
+    viewerQuality?: QualityPreset;
+    /**
+     * Why the effective resolution sits below what the viewer asked
+     * for (or below the operator ceiling when no preset is set).
+     * `"throttled"` = the adaptive perf machinery is holding the
+     * camera down; the viewer target is honored again on recovery.
+     * Absent/None = the request is fully honored.
+     */
+    qualityLimitedBy?: string;
+}
+export interface CameraSnapshotPayload {
+    cameras: CameraState[];
+}
+export interface CameraStateChangedPayload {
+    state: CameraState;
+}
+export declare enum ErrorSource {
+    Sidecar = "sidecar",
+    Client = "client"
+}
+export interface ErrorPayload {
+    message: string;
+    source?: ErrorSource;
+}
+export interface FlightIdPayload {
+    flightId: number;
+}
+export interface HelloPayload {
+    sidecarVersion: string;
+    encoderBackend: string;
+}
+export interface SetDegradePayload {
+    flightId: number;
+    /**
+     * 0.0 = perfect quality, 1.0 = maximum degradation. Caps and
+     * is per-subscriber: the sidecar applies max across active
+     * subscribers so the noisiest consumer's request wins (same
+     * pattern as REMB picking the min bandwidth).
+     */
+    level: number;
+}
+export interface SetFovPayload {
+    flightId: number;
+    fov: number;
+}
+export interface SetLayersPayload {
+    flightId: number;
+    layers: Layer[];
+}
+export interface SetPanPayload {
+    flightId: number;
+    yaw: number;
+    pitch: number;
+}
+export interface SetPanRatePayload {
+    flightId: number;
+    /**
+     * Normalised yaw velocity, -1..=1. +1 = pan right at the part's
+     * full `PanRateDegPerSec`. Persistent until superseded (a new rate,
+     * including zero, replaces it); the plugin integrates it into the
+     * pan target every frame.
+     */
+    yawRate: number;
+    /**
+     * Normalised pitch velocity, -1..=1. +1 = pan up. Persistent until
+     * superseded.
+     */
+    pitchRate: number;
+}
+export interface SetQualityPayload {
+    flightId: number;
+    /**
+     * Requested resolution preset, or absent/null for auto (clear the
+     * viewer clamp). Future viewer-quality knobs are added here as
+     * optional fields with serde defaults, so older clients keep
+     * parsing; richer controls (bitrate, ladder toggles) stay
+     * operator-only until deliberately opened up.
+     */
+    preset?: QualityPreset;
+}
+export interface SetRenderSizePayload {
+    flightId: number;
+    width: number;
+    height: number;
+}
+export interface SetThrottleMainScreenPayload {
+    /**
+     * When `true`, disable the KSP main flight cameras to free GPU for
+     * kerbcast streams. Persists via the per-save difficulty parameter,
+     * matching the in-game Difficulty Settings toggle.
+     */
+    enabled: boolean;
+}
+export interface SetZoomRatePayload {
+    flightId: number;
+    /**
+     * Normalised zoom velocity, -1..=1. +1 = zoom IN (FoV decreasing)
+     * at the part's full `ZoomRateDegPerSec`. Persistent until
+     * superseded; the plugin integrates it into the FoV target every
+     * frame.
+     */
+    rate: number;
+}
+export interface SettingsStatePayload {
+    /**
+     * Effective value of the "Throttle KSP main render" setting as last
+     * reported by the plugin's `global.status.json`. Reflects what the
+     * plugin has *applied*, not just what was last requested.
+     */
+    throttleMainScreen: boolean;
+    /**
+     * KSP mission time (`Planetarium.GetUniversalTime()`, seconds) at
+     * which the video currently being produced was captured. `None` =
+     * no clock yet (old plugin/sidecar, or first status not seen); a
+     * consumer treats that as "unknown" and keeps a live passthrough.
+     */
+    captureUt?: number;
+    /**
+     * Monotonic counter bumped only on a non-monotonic UT jump (revert,
+     * quickload, scene reload). Consumers resynchronise on any change;
+     * the absolute value is meaningless.
+     */
+    captureEpoch?: number;
+    /**
+     * Current KSP time-warp multiplier, so a consumer can interpolate
+     * `capture_ut` between ~1Hz samples. `None` => treat as 1.0.
+     */
+    timeWarpRate?: number;
+}
+/**
+ * Slot↔camera assignment for the dynamic-subscription model. The sidecar
+ * negotiates a pool of recv-only video transceivers up front; `Subscribe`
+ * binds a camera to a free one and the sidecar announces the binding here.
+ */
+export interface SlotMapPayload {
+    /**
+     * Transceiver `mid` carrying this slot's track. Stable for the
+     * connection's life, so the client keys off it rather than the
+     * fragile `onTrack` arrival order — match against
+     * `RTCTrackEvent.transceiver.mid`.
+     */
+    mid: string;
+    /**
+     * Camera now carried by the slot, or `None` when the slot was freed
+     * by `Unsubscribe`. Serialised as `null` (not omitted) so "freed" is
+     * unambiguous on the wire.
+     */
+    flightId?: number;
+}
+/** Messages sent FROM the client TO the sidecar. */
+export type ClientMessage = 
+/**
+ * First message on a new data channel. Sidecar replies with `Hello`
+ * + a `CameraSnapshot` so the client gets server version + every
+ * camera's full state on one round-trip.
+ */
+{
+    type: "hello";
+    content?: undefined;
+}
+/**
+ * Override the operator layer mask for one camera. Server-wide
+ * state — all consumers see the change.
+ */
+ | {
+    type: "set-layers";
+    content: SetLayersPayload;
+}
+/**
+ * Override the operator render size for one camera. Even pixels
+ * only (H.264 chroma); server caps at the ring's allocated max.
+ */
+ | {
+    type: "set-render-size";
+    content: SetRenderSizePayload;
+}
+/**
+ * Set the camera's field-of-view (degrees). Silently ignored for
+ * parts whose Hullcam module is the fixed base (`supportsZoom ==
+ * false`); clients are expected to clamp to `fovMin / fovMax`
+ * from the camera's `CameraState` before sending.
+ */
+ | {
+    type: "set-fov";
+    content: SetFovPayload;
+}
+/**
+ * Pan/tilt the camera (yaw and pitch, both degrees from the
+ * part's resting forward). No stock Hullcam parts support this
+ * yet — the message is ignored until the planned mod extension
+ * adds steerable mounts to specific parts. Clients should hide
+ * pan controls until `supportsPan == true` for the camera.
+ */
+ | {
+    type: "set-pan";
+    content: SetPanPayload;
+}
+/**
+ * Set a *persistent* pan/tilt velocity (normalised yaw + pitch,
+ * -1..=1). Unlike `SetPan` (a one-shot absolute target), the rate
+ * holds until a new rate — including zero, which stops — supersedes
+ * it; the plugin integrates it into the pan target every frame so
+ * smoothness lives in KSP's frame loop rather than the control-poll
+ * cadence. +yaw = pan right, +pitch = pan up. Ignored (sidecar
+ * replies `Error`) when `supportsPan == false`. Composes with
+ * `SetPan`: an absolute command jumps the target, integration then
+ * continues from there.
+ */
+ | {
+    type: "set-pan-rate";
+    content: SetPanRatePayload;
+}
+/**
+ * Set a *persistent* zoom velocity (normalised, -1..=1). +1 = zoom
+ * IN (FoV decreasing). Holds until a new rate — including zero —
+ * supersedes it; the plugin integrates it into the FoV target every
+ * frame. Ignored (sidecar replies `Error`) when `supportsZoom ==
+ * false`. Composes with the absolute `SetFov` the same way
+ * `SetPanRate` composes with `SetPan`.
+ */
+ | {
+    type: "set-zoom-rate";
+    content: SetZoomRatePayload;
+}
+/**
+ * Request artificial signal degradation. 0.0 = perfect quality,
+ * 1.0 = maximum degradation. Per-subscriber: the sidecar
+ * applies max across active subscribers (slowest consumer
+ * wins, same pattern as REMB bandwidth). Lets consumers signal
+ * to the sidecar "I want to look like the in-game CommNet
+ * antenna is struggling"; sidecar takes the opportunity to
+ * reduce bitrate + skip frames, which both creates the
+ * signal-loss aesthetic AND saves encoder CPU.
+ */
+ | {
+    type: "set-degrade";
+    content: SetDegradePayload;
+}
+/**
+ * Set (or clear, with `preset: null`) a camera's viewer-requested
+ * resolution preset. Server-wide, last write wins across peers; the
+ * resulting `CameraStateChanged` broadcast keeps every UI
+ * consistent. The effective resolution is always
+ * min(operator ceiling, adaptive level, viewer preset): a preset
+ * can never raise quality past the operator's settings.cfg
+ * Width/Height, and the adaptive controller's demotes keep
+ * winning until it recovers. Viewers can NOT change bitrate or
+ * toggle the adaptive machinery through this message.
+ */
+ | {
+    type: "set-quality";
+    content: SetQualityPayload;
+}
+/**
+ * Request an IDR (keyframe) on the next encode tick. Browsers send
+ * this when they've dropped enough frames to be unable to decode
+ * the current P-frame chain. Sidecar forwards to the camera's
+ * encoder.
+ */
+ | {
+    type: "request-keyframe";
+    content: FlightIdPayload;
+}
+/**
+ * Dynamically subscribe to a camera on an already-connected peer. The
+ * sidecar binds it to a free pre-negotiated slot (one of the recv-only
+ * video transceivers from the offer), starts encoding it, forces a
+ * keyframe, and replies with `SlotMap` naming the transceiver `mid` now
+ * carrying it — no renegotiation. Replies with `Error` if no slot is
+ * free (the client should have negotiated enough transceivers up front).
+ */
+ | {
+    type: "subscribe";
+    content: FlightIdPayload;
+}
+/**
+ * Release a camera's slot. The sidecar stops feeding that slot (the
+ * camera sleeps if it has no other subscribers) and replies with
+ * `SlotMap { flightId: null }` for the freed transceiver `mid`.
+ */
+ | {
+    type: "unsubscribe";
+    content: FlightIdPayload;
+}
+/** Response to `Ping`. Browser sends this immediately on receiving each Ping. */
+ | {
+    type: "pong";
+    content?: undefined;
+}
+/**
+ * Graceful teardown. The canonical way for a client to leave: the sidecar
+ * immediately releases every camera this peer is feeding (so they sleep
+ * without waiting for ICE to time out), after which the client may close
+ * the connection. The drop-detection reaper remains the fallback for
+ * ungraceful exits (crash / tab close / network loss) that can't send this.
+ */
+ | {
+    type: "disconnect";
+    content?: undefined;
+}
+/**
+ * Enable or disable the KSP main render throttle globally. Persists
+ * across saves (writes the per-save difficulty parameter). Server-wide:
+ * all peers see the resulting `SettingsState` broadcast.
+ */
+ | {
+    type: "set-throttle-main-screen";
+    content: SetThrottleMainScreenPayload;
+};
+/** Messages sent FROM the sidecar TO the client. */
+export type ServerMessage = 
+/**
+ * Reply to `Hello`. Carries server version + the active encoder
+ * backend's name.
+ */
+{
+    type: "hello";
+    content: HelloPayload;
+}
+/**
+ * Full snapshot of every currently-attached camera. Sent in reply
+ * to `Hello` and on any structural change (vessel switch, ring
+ * added/removed).
+ */
+ | {
+    type: "camera-snapshot";
+    content: CameraSnapshotPayload;
+}
+/**
+ * Single-camera state change. Sent when an operator request applies
+ * or adaptive shedding kicks in. Lets clients update their UI
+ * without re-fetching the whole snapshot.
+ */
+ | {
+    type: "camera-state-changed";
+    content: CameraStateChangedPayload;
+}
+/**
+ * Slot↔camera assignment for the dynamic-subscription model. Sent in
+ * reply to `Subscribe`/`Unsubscribe`: `flightId` is the camera now
+ * carried by transceiver `mid`, or `null` when the slot was freed. The
+ * client maps `mid` to the track it received via `onTrack` and routes
+ * that track to (or away from) the camera's stream — no renegotiation.
+ */
+ | {
+    type: "slot-map";
+    content: SlotMapPayload;
+}
+/**
+ * Adaptive shedding level changed. Reason is human-readable
+ * ("ksp-fps-low", "ksp-fps-recovered") so client UIs can show
+ * *why* quality changed rather than just *that* it did.
+ */
+ | {
+    type: "adaptive-shed";
+    content: AdaptiveShedPayload;
+}
+/**
+ * Malformed / unknown client message. Includes the offending
+ * payload so the client can log it.
+ */
+ | {
+    type: "error";
+    content: ErrorPayload;
+}
+/**
+ * Keepalive probe sent by the sidecar every 5 seconds. Browser responds
+ * with `Pong`; if no Ping arrives within 15s the browser tears down
+ * the connection.
+ */
+ | {
+    type: "ping";
+    content?: undefined;
+}
+/**
+ * Current value of global settings (throttle state). Sent after `Hello`
+ * so a freshly-connected client shows correct state immediately, and
+ * re-broadcast whenever the polled plugin status shows a change.
+ */
+ | {
+    type: "settings-state";
+    content: SettingsStatePayload;
+};

package/dist/__generated__/types.js

@@ -0,0 +1,50 @@
+/*
+ Generated by typeshare 1.13.4
+*/
+/**
+ * Lifecycle state of a camera. Transmitted in `CameraState` so clients
+ * can react to part destruction without a new message type.
+ *
+ * Destroyed is a terminal state — the sidecar never transitions a camera
+ * back to Active after writing the tombstone.
+ */
+export var CameraLifecycle;
+(function (CameraLifecycle) {
+    CameraLifecycle["Active"] = "active";
+    CameraLifecycle["Destroyed"] = "destroyed";
+})(CameraLifecycle || (CameraLifecycle = {}));
+/**
+ * Layer mask. Mirrors `Kerbcast.CameraLayers` on the plugin side.
+ * Receiving clients use this for both the rendered-layer status reports
+ * and per-camera layer requests.
+ */
+export var Layer;
+(function (Layer) {
+    Layer["Near"] = "NEAR";
+    Layer["Scaled"] = "SCALED";
+    Layer["Far"] = "FAR";
+    Layer["Galaxy"] = "GALAXY";
+})(Layer || (Layer = {}));
+/**
+ * Viewer-selectable resolution preset. Each maps to a fraction of the
+ * operator-configured render size (the settings.cfg Width/Height ceiling):
+ * full = 1.0, threeQuarter = 0.75, half = 0.5, quarter = 0.25. The steps
+ * mirror the plugin's shed-table resolution ladder so the viewer clamp and
+ * the adaptive controller move on the same grid, and a preset can never
+ * exceed the ring's allocated max (every scale is <= 1.0 of the ceiling).
+ *
+ * Presets, not freeform WxH: a fixed menu keeps the unauthenticated
+ * viewer-writable surface tiny and aspect-correct by construction.
+ */
+export var QualityPreset;
+(function (QualityPreset) {
+    QualityPreset["Full"] = "full";
+    QualityPreset["ThreeQuarter"] = "threeQuarter";
+    QualityPreset["Half"] = "half";
+    QualityPreset["Quarter"] = "quarter";
+})(QualityPreset || (QualityPreset = {}));
+export var ErrorSource;
+(function (ErrorSource) {
+    ErrorSource["Sidecar"] = "sidecar";
+    ErrorSource["Client"] = "client";
+})(ErrorSource || (ErrorSource = {}));