@ksp-gonogo/kerbcast 1.4.0

package/src/__generated__/types.ts

@@ -0,0 +1,488 @@
+/*
+ Generated by typeshare 1.13.4
+*/
+
+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 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 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 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 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 };
+