@ksp-gonogo/kerbcast 1.7.0 → 1.8.0

package/dist/recording.d.ts

@@ -0,0 +1,426 @@
+import type { CameraState } from "./__generated__/types";
+/**
+ * One point on a recording's UT track. `t` is milliseconds since recording
+ * start; `ut` is the KSP universal time (seconds) the capture clock reported
+ * at that instant, or absent when out of flight (no clock).
+ */
+export interface UtSample {
+    t: number;
+    ut?: number;
+}
+/** The finished, in-memory result of a single-feed recording. */
+export interface RecordingHandle {
+    recordingId: string;
+    /** The camera this clip was recorded from. */
+    flightId: number;
+    /** The recorded media, in `mimeType`. */
+    blob: Blob;
+    /** The negotiated container/codec (e.g. `video/mp4;codecs=avc1`). */
+    mimeType: string;
+    /** UT (seconds) at recording start, or absent when out of flight. */
+    utStart?: number;
+    /** UT (seconds) at recording stop, or absent when out of flight. */
+    utEnd?: number;
+    /** ~1Hz (recording-time, UT) series across the clip. Always present. */
+    utSamples: UtSample[];
+    /** `blob.size` in bytes. */
+    byteSize: number;
+    /** Wall-clock recording duration in milliseconds. */
+    durationMs: number;
+}
+/** Options for {@link RecordingController.startRecording}. */
+export interface StartRecordingOptions {
+    /**
+     * Preferred container/codec. Tried first; if MediaRecorder can't support
+     * it, negotiation falls back (mp4 -> webm/vp9 -> webm). Omit to let
+     * negotiation choose.
+     */
+    mimeType?: string;
+    /**
+     * Auto-stop after this many milliseconds. The clip finalizes on its own and
+     * is retrievable via {@link RecordingController.fetchRecording}. Omit for
+     * manual stop only.
+     */
+    maxDurationMs?: number;
+    /**
+     * 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.
+     */
+    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).
+ */
+export declare const ARM_TIMEOUT_MS = 3000;
+/** Options for {@link RecordingController.stopGroupedRecording}. */
+export interface StopGroupedRecordingOptions {
+    /**
+     * Coverage guarantee: hold finalization until every feed's latest UT sample
+     * has passed this UT (seconds), so no feed falls short of the common window.
+     * Omit to stop all feeds at the current moment (best-effort).
+     *
+     * The guarantee only holds for members that are still recording when the
+     * target arrives. A member started with its own `maxDurationMs` can
+     * auto-stop before reaching `targetUt`; that member's `utEnd` then falls
+     * short, which silently narrows (or, if the ranges no longer overlap,
+     * clears) the resulting `commonUtWindow`. Pair a grouped `targetUt` with an
+     * unbounded (or generously long) per-member `maxDurationMs`, or none at all.
+     */
+    targetUt?: number;
+    /**
+     * Bound on how long to wait for `targetUt` coverage before giving up and
+     * finalizing with whatever each feed has captured so far. Guards against a
+     * UT that never arrives (feed out of flight, sim frozen, warp reversed)
+     * hanging the stop forever. Ignored when `targetUt` is omitted. Defaults to
+     * {@link DEFAULT_COVERAGE_TIMEOUT_MS}.
+     */
+    coverageTimeoutMs?: number;
+}
+/** Default {@link StopGroupedRecordingOptions.coverageTimeoutMs}. */
+export declare const DEFAULT_COVERAGE_TIMEOUT_MS = 10000;
+/** The result of {@link RecordingController.startGroupedRecording}. */
+export interface GroupedRecordingStart {
+    groupId: string;
+    /**
+     * The real per-feed recording ids the controller minted internally, in the
+     * order `flightIds` was given. These are the ids that work with the
+     * single-recording surface (`isRecording`, `stopRecording`,
+     * `discardRecording`) for cancelling one member of the group.
+     */
+    recordingIds: string[];
+}
+/** The finished, in-memory result of a grouped (multi-feed) recording. */
+export interface GroupedRecordingHandle {
+    groupId: string;
+    /** One handle per feed, in the order the group was started. */
+    recordings: RecordingHandle[];
+    /**
+     * The UT span all feeds cover: [max(utStart), min(utEnd)] across the clips.
+     * Absent when any clip lacks UT or the ranges don't overlap. Each clip's
+     * own `utSamples` let a consumer map this window to that clip's
+     * recording-time and trim/seek itself (metadata alignment; no physical cut).
+     */
+    commonUtWindow?: [number, number];
+}
+/**
+ * An in-progress recording, surfaced so the UI can draw a REC dot and an
+ * elapsed timer. `groupId` is set when the recording is part of a grouped set.
+ */
+export interface ActiveRecordingInfo {
+    recordingId: string;
+    flightId: number;
+    /** `performance.now()`/`Date.now()` at start, for an elapsed timer. */
+    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.
+     */
+    arming: boolean;
+}
+/**
+ * Everything {@link RecordingController} currently knows, as one referentially
+ * stable object: the same reference between mutations, a new one after each.
+ * That stability is what makes it safe to hand straight to
+ * `useSyncExternalStore` -- a fresh object on every call would spin components
+ * into an infinite render loop.
+ */
+export interface RecordingsSnapshot {
+    /** Finished standalone (non-grouped) clips, newest last. */
+    recordings: RecordingHandle[];
+    /** Finished grouped sets, newest last. */
+    groups: GroupedRecordingHandle[];
+    /** Recordings currently in progress (single + grouped members). */
+    active: ActiveRecordingInfo[];
+}
+/**
+ * Per-camera surface {@link RecordingController} needs: the live stream plus
+ * enough of the full camera handle to drive a forced full-resolution
+ * recording (send the force, observe the resulting render size).
+ */
+export interface RecordingClientCamera {
+    readonly mediaStream: MediaStream | null;
+    readonly state: CameraState | null;
+    /**
+     * The feed's physical/ceiling maximum render size, or `null` when not
+     * known to the client (e.g. `discover()` was never called). When known,
+     * lets the controller recognise a forced feed that has actually reached
+     * its ceiling rather than one merely unchanged since before the force.
+     */
+    readonly maxRenderSize: {
+        width: number;
+        height: number;
+    } | null;
+    setForceFullResolution(force: boolean): Promise<void>;
+    on(event: "change", handler: (state: CameraState) => void): () => void;
+}
+/**
+ * Minimal surface {@link RecordingController} needs from the client. The full
+ * `KerbcastClient` satisfies it; a narrow interface keeps the controller
+ * unit-testable without a whole client.
+ */
+export interface RecordingClient {
+    camera(flightId: number): RecordingClientCamera;
+    readonly clock: {
+        readonly captureUt: number | null;
+    };
+    on(event: "settings-change", handler: (data: unknown) => void): () => void;
+}
+/**
+ * Pick a MediaRecorder mime type. Tries `preferred` first (when given), then
+ * the standard preference order, using `MediaRecorder.isTypeSupported`. Falls
+ * back to `video/webm` when nothing reports support (or the API is absent).
+ */
+export declare function negotiateMimeType(preferred?: string): string;
+/**
+ * Intersection of the feeds' UT ranges: [max(utStart), min(utEnd)]. Returns
+ * undefined if any clip lacks a full range or the spans don't overlap.
+ */
+export declare function commonUtWindow(recordings: RecordingHandle[]): [number, number] | undefined;
+/**
+ * Recording-time (ms since clip start) for a mission UT, linearly interpolated
+ * off a clip's `utSamples`. UT is linear in recording time at constant
+ * time-warp (the launch/landing/docking moments a group captures), so this maps
+ * the common UT window onto each clip's own timeline for a keyframe trim.
+ * Clamps to the sampled span; returns null when the clip has no UT samples.
+ */
+export declare function utToRecordingTimeMs(samples: UtSample[], ut: number): number | null;
+/**
+ * Remux-trims a grouped clip to a recording-time window. Implemented by a
+ * lazily-loaded package (Mediabunny) so single recordings and non-recording
+ * consumers never pull it. Keyframe-boundary remux only: no decode/re-encode.
+ */
+export interface GroupTrimmer {
+    /** Cut `blob` to [startMs, endMs] of its own timeline; resolves a new Blob. */
+    trim(blob: Blob, mimeType: string, startMs: number, endMs: number): Promise<Blob>;
+}
+/** Loads a {@link GroupTrimmer}, or resolves null when trimming is unavailable. */
+export type TrimmerLoader = () => Promise<GroupTrimmer | null>;
+/** Options for {@link RecordingController}. */
+export interface RecordingControllerOptions {
+    /**
+     * Override the grouped-recording trimmer loader (tests inject a fake; a
+     * consumer could supply mp4box.js instead). Defaults to a dynamic
+     * `import("mediabunny")` keyframe remux.
+     */
+    loadTrimmer?: TrimmerLoader;
+}
+/**
+ * Builds a {@link TrimmerLoader} around a caller-supplied module import.
+ * `loadMediabunnyTrimmer` (the default, below) resolves the bare
+ * `import("mediabunny")` specifier for bundler consumers (e.g. gonogo). A
+ * consumer that can't rely on that resolution -- the sidecar's embedded web
+ * page, which serves its own copy of the package locally for an offline/LAN
+ * install with no CDN -- supplies a different `importModule` (e.g. a dynamic
+ * import of a served URL) and passes the result as
+ * {@link RecordingControllerOptions.loadTrimmer}. Resolves null on any
+ * failure, so a group degrades to metadata-only rather than failing.
+ */
+export declare function createMediabunnyTrimmerLoader(importModule: () => Promise<unknown>): TrimmerLoader;
+/**
+ * Owns every in-flight and finished recording for one client. Reached via
+ * `client.recording`. All state is in-memory: a page reload discards it.
+ *
+ * Observable: {@link subscribe} + {@link getSnapshot} let every call site
+ * (a tile's own REC control, a RecordingsTray mounted elsewhere) read the same
+ * state, so a clip started or finished through one is visible to all the
+ * others -- no per-instance state to fall out of sync.
+ */
+export declare class RecordingController {
+    private readonly client;
+    private readonly active;
+    private readonly finished;
+    /** flightId -> recordingId, so a second start on a busy feed is rejected. */
+    private readonly byFlight;
+    private readonly groups;
+    private readonly finishedGroups;
+    /** Per-group trimmer load kicked off at group-start, awaited at stop. */
+    private readonly groupTrimmers;
+    private readonly loadTrimmer;
+    /** 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. */
+    private readonly memberOfGroup;
+    /**
+     * Per-feed force ref-count. The sidecar OR-aggregates force across
+     * viewers already; this is the local mirror so two overlapping
+     * recordings of the same feed (in this one controller) release force
+     * only when the last of them stops.
+     */
+    private readonly forceCounts;
+    /**
+     * Per-feed force-true send status: "pending" while a send is in flight,
+     * "sent" once it has actually succeeded. Absent means neither: either
+     * never attempted, or a prior attempt failed. Distinct from
+     * {@link forceCounts} so a failed send never masquerades as a completed
+     * one; see {@link acquireForce}.
+     */
+    private readonly forceSendState;
+    private readonly listeners;
+    private snapshot;
+    /** While true, {@link rebuild} is a no-op; used to batch startGroupedRecording's
+     *  per-member starts into a single notification once the group is fully set up. */
+    private suppressRebuild;
+    constructor(client: RecordingClient, options?: RecordingControllerOptions);
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe: (fn: () => void) => (() => void);
+    /** The current snapshot; the same object reference until the next mutation. */
+    getSnapshot: () => RecordingsSnapshot;
+    /**
+     * Recompute the snapshot from current state and notify subscribers. Called
+     * at the end of every state-mutating operation, including the async settle
+     * points (recorder stop, grouped stop) where the data actually changes.
+     */
+    private rebuild;
+    /**
+     * Acquire the local force ref-count for a feed; sends
+     * `setForceFullResolution(true)` unless one is already in flight or has
+     * already succeeded for this feed (tracked in {@link forceSendState}, not
+     * just the ref-count reaching 1). The sidecar OR-aggregates force across
+     * viewers already; this ref-count is the belt-and-braces local mirror for
+     * two overlapping recordings of the same feed in this one controller.
+     *
+     * A send failure clears `forceSendState` instead of leaving it "sent", so
+     * it never masquerades as done: a later acquire (e.g. a second overlapping
+     * recording's 1->2 transition) sees the feed as not-yet-forced and retries
+     * the send, rather than silently leaving the feed un-forced forever.
+     */
+    private acquireForce;
+    /**
+     * Release one holder of a feed's force ref-count; sends
+     * `setForceFullResolution(false)` once the count reaches zero. Never goes
+     * below zero (a stray extra release is a no-op, not an underflow). Clears
+     * `forceSendState` too, so a later, unrelated recording of this feed
+     * starts its own send from a clean slate.
+     */
+    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.
+     */
+    private isAtFullResolution;
+    /**
+     * 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
+     * dimensions have ever been reported for this feed). A `null` result
+     * means the caller must keep waiting for a state worth basing readiness
+     * on, rather than latching onto a `{0,0}` placeholder.
+     */
+    private seedResolutionBaseline;
+    /**
+     * Waits for a forced feed to actually render at full resolution.
+     * `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.
+     */
+    private watchResolutionReady;
+    /**
+     * Start recording a feed's live track. Returns a client-minted recordingId
+     * 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.
+     */
+    startRecording(flightId: number, opts?: StartRecordingOptions, inGroup?: boolean): string;
+    /**
+     * Stop a recording and resolve its finished handle. Idempotent per id: a
+     * second call (or a race with maxDurationMs auto-stop) returns the same
+     * pending/settled result.
+     */
+    stopRecording(recordingId: string): Promise<RecordingHandle>;
+    /** Return a finished recording's handle, or undefined if unknown/still active. */
+    fetchRecording(recordingId: string): RecordingHandle | undefined;
+    /** Whether a feed currently has a recording in progress. */
+    isRecording(flightId: number): boolean;
+    /**
+     * Drop a recording. If still active, tears it down without producing a
+     * handle; if finished, frees the stored handle/blob reference. If the id
+     * is a member of a still-active group, pulls it out of that group's member
+     * set too, so a later `stopGroupedRecording` only waits on (and stops) the
+     * ids that remain -- discarding one member no longer corrupts the group.
+     */
+    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.
+     */
+    startGroupedRecording(flightIds: number[], opts?: StartRecordingOptions): GroupedRecordingStart;
+    /**
+     * Stop a grouped recording. With `targetUt`, holds until every feed's latest
+     * UT sample has passed it (coverage guarantee) before stopping any feed;
+     * without it, stops all now. Resolves the grouped handle with the intersected
+     * `commonUtWindow`. See {@link StopGroupedRecordingOptions.targetUt} for the
+     * coverage caveat around a member's own `maxDurationMs`.
+     */
+    stopGroupedRecording(groupId: string, opts?: StopGroupedRecordingOptions): Promise<GroupedRecordingHandle>;
+    /**
+     * Remux-trim one clip to the common UT window, or return it untouched
+     * (metadata-only) when it can't be cut cleanly: a non-mp4 container, an
+     * unmappable window, or a trimmer error. The stored per-clip handle is
+     * replaced with the trimmed one so fetch/discard stay consistent.
+     */
+    private maybeTrim;
+    /** Return a finished grouped recording, or undefined if unknown/still active. */
+    fetchGroupedRecording(groupId: string): GroupedRecordingHandle | undefined;
+    /** Drop a grouped recording and each of its clips. */
+    discardGroupedRecording(groupId: string): void;
+    /**
+     * Resolve once every listed recording's latest UT sample has reached
+     * `targetUt`. UT arrives on the shared ~1Hz clock feed, so this polls the
+     * settings-change stream rather than a wall-clock timer. Bounded by
+     * `timeoutMs`: if coverage never arrives (feed out of flight, sim frozen,
+     * warp reversed), gives up and resolves anyway so the group finalizes with
+     * whatever UT each feed has captured, rather than hanging forever. Always
+     * releases the settings-change subscription, on either exit path.
+     */
+    private awaitCoverage;
+}