@ksp-gonogo/kerbcast 1.11.0-rc.4 → 1.11.0

package/README.md

@@ -63,6 +63,11 @@ Commands can be sent as soon as `connect` resolves. Any sent before the
 control channel has opened wait for it, and reject if it has not opened
 within 10 s or the client disconnects first.
 
+Kerbcast streams H.264 only. A browser that offers none (some Firefox builds
+ship without OpenH264) is refused, and `connect` rejects with an
+`OfferRefusedError` whose `code` is `ErrorCode.CodecUnsupported` and whose
+message says what to change.
+
 ### Pre-handshake discovery
 
 ```ts
@@ -89,6 +94,65 @@ const setLayers: ClientMessage = {
 controlChannel.send(JSON.stringify(setLayers));
 ```
 
+### Encoded-frame transforms
+
+`cam.setEncodedTransform(factory)` runs your transform on a camera's encoded
+frames before the browser decodes them. It always runs before Kerbcast's
+static and frame lock, so anything it does (holding frames back, dropping
+them) shows up in `cam.mediaStream` with the static still drawn on top.
+
+Kerbcast installs the transform on whichever receiver carries the camera. A
+transform instance works on one receiver only, so you pass a factory:
+Kerbcast calls it for a fresh instance when the camera is bound, again when a
+slot rebind moves the camera to another receiver, and again after a
+reconnect. A receiver the camera leaves goes back to passthrough, and frames
+the old instance still holds are dropped. `setEncodedTransform(null)`
+detaches. It works in both legacy and dynamic slot modes.
+
+It needs `encodedTransforms: true` when the client is constructed, and
+`setEncodedTransform` throws without it. The option gives every receiver a
+passthrough transform from the start, because Chrome only honours a receiver
+transform that was in place before negotiation. It costs a worker hop per
+frame for every camera, so leave it off unless you use this. The passthrough
+worker loads from a `blob:` URL, so a Content Security Policy must allow
+`worker-src blob:`. `setEncodedTransform` also throws when the browser has no
+install path; `client.encodedTransformPath` reports which one you will get:
+
+- `"script"`: return an `RTCRtpScriptTransform` (Chrome, Safari and Firefox)
+- `"streams"`: return a `TransformStream` of `RTCEncodedVideoFrame`, run on the main thread over `createEncodedStreams()` (older Chrome)
+
+A one-second delay on the `"script"` path:
+
+```ts
+const client = new KerbcastClient({ host, port, encodedTransforms: true });
+const worker = new Worker(new URL("./delay-worker.js", import.meta.url));
+
+client.camera(2592004302).setEncodedTransform(({ flightId, path }) =>
+  path === "script"
+    ? new RTCRtpScriptTransform(worker, { flightId, delayMs: 1000 })
+    : delayStream(1000),
+);
+
+// delay-worker.js
+onrtctransform = ({ transformer }) => {
+  const { delayMs } = transformer.options;
+  transformer.readable
+    .pipeThrough(
+      new TransformStream({
+        transform(frame, controller) {
+          setTimeout(() => controller.enqueue(frame), delayMs);
+        },
+      }),
+    )
+    .pipeTo(transformer.writable)
+    .catch(() => {}); // a replaced instance is aborted
+};
+```
+
+`delayStream` is the same `TransformStream` built on the main thread. A
+factory that throws, or returns the wrong kind for the path, is reported as a
+client `error` event carrying the camera's `flightId`.
+
 ## Per-camera capabilities
 
 `CameraState` includes capability flags so consumers render only the
@@ -291,6 +355,14 @@ await client.setCommandAim(hill.flightId, null);
 A station watching a craft is the same with
 `{ kind: CommandVantageKind.Station, station: "KSC" }` and a `vessel` aim.
 
+A `vessel` aim, or an `orbit` or `positionAt` aim's `subjectPersistentId`,
+must name a craft in the camera's `commandCentre.targets`. One that is not
+there (a craft merged into another by docking, or destroyed) makes
+`setCommandAim` reject with a `CommandTargetUnknownError`; a call that races
+the list changing comes back as an `error` event with code
+`ErrorCode.CommandTargetUnknown`. Before the game has reported the camera's
+list, the aim is sent and the game decides.
+
 ### The command lock
 
 A mod in game can take a lock on every command camera's aim

package/dist/__generated__/types.d.ts

@@ -362,6 +362,15 @@ export interface CameraState {
      */
     operatorWidth: number;
     operatorHeight: number;
+    /**
+     * Configured capture size: the most this camera renders at (settings.cfg
+     * `MaxQuality` or `Width`/`Height`, or a kerbal face camera's square
+     * ring). Its aspect is the feed's shape: auto-resolution picks a size at
+     * this aspect and never follows the viewer's box. Absent from a sidecar
+     * that predates the field.
+     */
+    maxWidth?: number;
+    maxHeight?: number;
     /**
      * Whether the part's Hullcam module supports runtime FoV changes
      * (i.e. it's a `MuMechModuleHullCameraZoom`, not the fixed base
@@ -623,7 +632,18 @@ export declare enum ErrorCode {
     /** The named camera exists but its part is gone. */
     CameraDestroyed = "camera-destroyed",
     /** A command authority in game holds the command cameras' aim lock. */
-    CommandLocked = "command-locked"
+    CommandLocked = "command-locked",
+    /**
+     * A command aim names a craft that is not in the camera's latest
+     * `commandCentre.targets`, for example one merged away in a dock.
+     */
+    CommandTargetUnknown = "command-target-unknown",
+    /**
+     * `POST /offer` refused: the offer's video carries no H.264 with
+     * packetization-mode=1, the only video Kerbcast sends. A browser
+     * without H.264 support (some Firefox builds lack OpenH264) offers none.
+     */
+    CodecUnsupported = "codec-unsupported"
 }
 export interface ErrorPayload {
     message: string;
@@ -664,6 +684,11 @@ export interface FrameStampPayload {
 export interface HelloPayload {
     sidecarVersion: string;
     encoderBackend: string;
+    /**
+     * True when this sidecar sends `FrameStamp` to a client that asks with
+     * `SetFrameStamps`. Absent from sidecars older than 1.11.
+     */
+    frameStamps?: boolean;
 }
 /**
  * A consumer reporting its OWN current display size in px for one camera.
@@ -735,6 +760,9 @@ export interface SetFovPayload {
     flightId: number;
     fov: number;
 }
+export interface SetFrameStampsPayload {
+    enabled: boolean;
+}
 export interface SetLayersPayload {
     flightId: number;
     layers: Layer[];
@@ -1094,6 +1122,15 @@ export type ClientMessage =
  | {
     type: "set-throttle-main-screen";
     content: SetThrottleMainScreenPayload;
+}
+/**
+ * Start or stop `FrameStamp` messages on this peer's control channel.
+ * Off until asked for, so clients that predate stamps never receive
+ * them. Send only to a sidecar whose `Hello` has `frameStamps: true`.
+ */
+ | {
+    type: "set-frame-stamps";
+    content: SetFrameStampsPayload;
 };
 /** Messages sent FROM the sidecar TO the client. */
 export type ServerMessage = 
@@ -1179,7 +1216,8 @@ export type ServerMessage =
 }
 /**
  * Capture UT of one frame about to go out on a video track, keyed by
- * its RTP timestamp. One per frame per track.
+ * its RTP timestamp. One per frame per track, only to a peer that
+ * enabled them with `SetFrameStamps`.
  */
  | {
     type: "frame-stamp";

package/dist/__generated__/types.js

@@ -172,4 +172,15 @@ export var ErrorCode;
     ErrorCode["CameraDestroyed"] = "camera-destroyed";
     /** A command authority in game holds the command cameras' aim lock. */
     ErrorCode["CommandLocked"] = "command-locked";
+    /**
+     * A command aim names a craft that is not in the camera's latest
+     * `commandCentre.targets`, for example one merged away in a dock.
+     */
+    ErrorCode["CommandTargetUnknown"] = "command-target-unknown";
+    /**
+     * `POST /offer` refused: the offer's video carries no H.264 with
+     * packetization-mode=1, the only video Kerbcast sends. A browser
+     * without H.264 support (some Firefox builds lack OpenH264) offers none.
+     */
+    ErrorCode["CodecUnsupported"] = "codec-unsupported";
 })(ErrorCode || (ErrorCode = {}));

package/dist/client.d.ts

@@ -92,6 +92,20 @@ export interface KerbcastCameraHandle {
      * without noise so only the text overlay renders.
      */
     setShowStatic(enabled: boolean): void;
+    /**
+     * Run a transform on this camera's encoded frames before they are decoded,
+     * and so before Kerbcast's static and frame lock see them. Kerbcast calls
+     * `factory` for a fresh instance each time the camera lands on a receiver
+     * (connect, slot rebind, reconnect) and removes it from a receiver the
+     * camera leaves; frames the old instance still holds are discarded. The
+     * setting persists across reconnects. `null` detaches.
+     *
+     * Needs {@link KerbcastClientConfig.encodedTransforms}; throws without it,
+     * or when the browser has no install path. Failures while installing
+     * (the factory throws, or returns the wrong kind for the path) surface as
+     * client `error` events.
+     */
+    setEncodedTransform(factory: EncodedTransformFactory | null): void;
     on<K extends keyof KerbcastCameraEvents>(event: K, handler: (data: KerbcastCameraEvents[K]) => void): () => void;
 }
 /** Event payloads emitted by a {@link KerbcastCameraHandle}. */
@@ -103,6 +117,26 @@ export interface KerbcastCameraEvents {
     /** Frames stopped arriving on a live source (`true`) / resumed (`false`). */
     stall: boolean;
 }
+/**
+ * How a peer installs encoded transforms. `"script"` sets an
+ * `RTCRtpScriptTransform` as the receiver's `transform`, used wherever the
+ * browser has it; `"streams"` runs a main-thread `TransformStream` over the
+ * receiver's `createEncodedStreams()`, used on Chrome builds without it.
+ */
+export type EncodedTransformPath = "script" | "streams";
+/** A transform over encoded video frames: an `RTCRtpScriptTransform` on the `"script"` path, a `TransformStream` on `"streams"`. */
+export type EncodedTransform = RTCRtpScriptTransform | TransformStream<RTCEncodedVideoFrame, RTCEncodedVideoFrame>;
+/** Passed to an {@link EncodedTransformFactory}. */
+export interface EncodedTransformContext {
+    flightId: number;
+    /** Which kind of {@link EncodedTransform} to return. */
+    path: EncodedTransformPath;
+}
+/**
+ * Builds a transform instance for one receiver. An instance is single-use,
+ * so Kerbcast asks for a new one whenever the camera moves receiver.
+ */
+export type EncodedTransformFactory = (ctx: EncodedTransformContext) => EncodedTransform;
 /** Configuration for {@link KerbcastClient} construction. */
 export interface KerbcastClientConfig {
     /** Sidecar host (matches the sidecar's `--http-bind`). */
@@ -130,6 +164,18 @@ export interface KerbcastClientConfig {
      * Default false.
      */
     frameLock?: boolean;
+    /**
+     * Enable {@link KerbcastCameraHandle.setEncodedTransform}. Every receiver
+     * then carries a passthrough transform from creation, because Chrome only
+     * honours a receiver transform that was in place before negotiation and
+     * stops a receiver's frames when its transform is cleared. This routes
+     * every camera's frames through a worker (or, on Chrome builds without
+     * `RTCRtpScriptTransform`, a main-thread `createEncodedStreams` pipe), so
+     * it is off by default. The worker is a `blob:` URL, so a page with a
+     * Content Security Policy must allow `worker-src blob:`. Set it before
+     * connecting; a peer keeps the path it was created with.
+     */
+    encodedTransforms?: boolean;
     /**
      * ICE gathering timeout in milliseconds. Passed to the default
      * {@link BrowserKerbcastTransport}; ignored when a custom transport is
@@ -256,6 +302,27 @@ export declare class CommandLockedError extends Error {
     readonly code = ErrorCode.CommandLocked;
     constructor(owner: string);
 }
+/**
+ * {@link KerbcastClient.setCommandAim} refused because the aim's craft (a
+ * `vessel` aim's craft, or an `orbit` or `positionAt` aim's subject) is not in
+ * the camera's `commandCentre.targets`, for example one merged away in a dock.
+ */
+export declare class CommandTargetUnknownError extends Error {
+    readonly flightId: number;
+    readonly persistentId: number;
+    readonly code = ErrorCode.CommandTargetUnknown;
+    constructor(flightId: number, persistentId: number);
+}
+/**
+ * The sidecar refused `POST /offer` with a reason, for example
+ * `ErrorCode.CodecUnsupported` when the browser offers no H.264 video.
+ */
+export declare class OfferRefusedError extends Error {
+    readonly status: number;
+    readonly reason: string;
+    readonly code?: ErrorCode | undefined;
+    constructor(status: number, reason: string, code?: ErrorCode | undefined);
+}
 /** How long {@link KerbcastClient.createCommandCamera} waits for the camera by default. */
 export declare const COMMAND_CAMERA_CREATE_TIMEOUT_MS = 35000;
 /**
@@ -324,7 +391,17 @@ export interface KerbcastClientEvents {
  * implementation to exercise the state machine without a real peer.
  */
 export interface KerbcastTransport {
-    createPeer(iceServers: RTCIceServer[]): KerbcastPeer;
+    createPeer(iceServers: RTCIceServer[], opts?: KerbcastPeerOptions): KerbcastPeer;
+    /**
+     * The encoded-transform path a peer created with `opts` would use, or null
+     * when it has none. Optional; a transport without it offers no path.
+     */
+    encodedTransformPath?(opts: KerbcastPeerOptions): EncodedTransformPath | null;
+}
+/** Peer creation options passed to {@link KerbcastTransport.createPeer}. */
+export interface KerbcastPeerOptions {
+    /** Mirrors {@link KerbcastClientConfig.encodedTransforms}. */
+    encodedTransforms?: boolean;
 }
 export interface KerbcastPeer {
     addRecvOnlyTransceiver(): void;
@@ -343,6 +420,12 @@ export interface KerbcastPeer {
      * changes. Equivalent to `RTCPeerConnection.getStats(null)`.
      */
     getStats?(): Promise<RTCStatsReport>;
+    /**
+     * Install `transform` on the receiver of slot `mid`, replacing any
+     * previous one; `null` restores passthrough. Throws when the receiver is
+     * unknown or the transform's kind does not match the peer's path.
+     */
+    setReceiverTransform?(mid: string, transform: EncodedTransform | null): void;
 }
 export interface KerbcastDataChannel {
     send(payload: string): void;
@@ -365,7 +448,8 @@ export interface BrowserKerbcastTransportOptions {
 export declare class BrowserKerbcastTransport implements KerbcastTransport {
     private readonly opts;
     constructor(opts?: BrowserKerbcastTransportOptions);
-    createPeer(iceServers: RTCIceServer[]): KerbcastPeer;
+    encodedTransformPath(opts: KerbcastPeerOptions): EncodedTransformPath | null;
+    createPeer(iceServers: RTCIceServer[], opts?: KerbcastPeerOptions): KerbcastPeer;
 }
 declare class TypedEmitter<E> {
     private readonly listeners;
@@ -424,6 +508,12 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * matches by mid instead).
      */
     private readonly flightByTrackId;
+    /** Legacy mode: transceiver mid -> the camera routed to it by index. */
+    private readonly legacyFlightByMid;
+    /** The encoded-transform path the current peer was created with. */
+    private peerTransformPath;
+    /** Receivers holding a camera's encoded transform, by mid, with the factory that built it. */
+    private readonly transformInstalls;
     /** Sidecar version reported on `Hello`; null before handshake. */
     private _sidecarVersion;
     private _encoderBackend;
@@ -634,6 +724,11 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * (`commandTrack.authority`): it holds the lock and only it can aim. A
      * refusal that races the lock being taken arrives as an `error` event with
      * code `ErrorCode.CommandLocked` instead.
+     *
+     * Rejects with a {@link CommandTargetUnknownError} when the aim's craft is
+     * not in the camera's `commandCentre.targets` (a craft merged away in a
+     * dock, say). A refusal that races the list changing arrives as an `error`
+     * event with code `ErrorCode.CommandTargetUnknown`.
      */
     setCommandAim(flightId: number, aim: CommandAim | null): Promise<void>;
     /**
@@ -696,6 +791,20 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * (modern browsers include it; some implementations omit it).
      */
     inboundVideoStats(): Promise<Map<number, InboundVideoStats>>;
+    /** The encoded-transform path this client's next peer will use, or null when it has none. */
+    get encodedTransformPath(): EncodedTransformPath | null;
+    private peerOptions;
+    /** Internal: throws unless {@link KerbcastCameraHandle.setEncodedTransform} can work here. */
+    _assertEncodedTransforms(): void;
+    /**
+     * Internal: bring each receiver's installed transform in line with the
+     * camera now bound to it. A receiver whose camera or factory changed loses
+     * its instance; a bound camera with a factory gets a fresh one.
+     */
+    _syncEncodedTransforms(): void;
+    private clearEncodedTransforms;
+    private setReceiverTransform;
+    private emitTransformError;
     private tearDownStreams;
 }
 export {};