@driftengine/core 3.61.0

package/src/ui/framePacer.ts

@@ -0,0 +1,351 @@
+/**
+ * Deciding which of a render loop's frames go into a recording, and measuring
+ * what came out.
+ *
+ * The measuring half is not diagnostics bolted on afterwards — it is half the
+ * reason this module exists. A clip that "judders" has at least three possible
+ * causes (the renderer missing its rate, the encoder starved of bitrate, the
+ * content itself stepping unevenly) and they are indistinguishable by eye. What
+ * separates them is a number: how many frames the loop produced, how many were
+ * handed to the recorder, and how far apart in wall-clock time those were.
+ *
+ * **The schedule counts animation frames, not milliseconds, and that is the
+ * whole design.** A recorder stamps each frame with the instant it arrived, and
+ * the only instants a render loop can offer are its display's own — so a
+ * schedule expressed in wall-clock slots asks for moments that do not exist. It
+ * then takes the nearest frame either side, alternately early and late, and the
+ * file holds frames of uneven duration: 13.9 ms, 20.8 ms, 13.9 ms on a 144 Hz
+ * panel asked for 60 a second. Capturing every *n*-th frame instead makes every
+ * gap identical by construction, which is what makes the clip play evenly.
+ *
+ * The rate that comes out is therefore the display's rate divided by a whole
+ * number — 60 from 60 Hz, 72 from 144, 60 from 240 — rather than exactly what
+ * was asked for. That is the right trade: a clip at 72 fps whose frames are
+ * evenly spaced is smooth, and one at exactly 60 whose frames are not is the
+ * defect this replaced.
+ *
+ * Two rules the schedule follows, both learned from what a stutter looks like:
+ *
+ * - **Never two captures for one animation frame.** A duplicated frame is a
+ *   frozen instant followed by a double-length step, which reads as a hitch
+ *   even though nothing was dropped. Counting frames makes this true by
+ *   construction.
+ * - **After falling behind, resume — do not catch up.** Firing twice in quick
+ *   succession to make up a missed slot converts one gap into a lurch forward.
+ *   A gap is a frame nobody notices; a lurch is the artefact everybody calls
+ *   lag.
+ */
+export interface FramePacingReport {
+  readonly targetFps: number;
+  /** Animation frames the loop produced while the pacer was running. */
+  readonly rendered: number;
+  /** Frames handed to the recorder. */
+  readonly captured: number;
+  /** Frames per second actually captured, over the whole run. */
+  readonly capturedFps: number;
+  /** Mean wall-clock gap between captured frames, ms. */
+  readonly meanGapMs: number;
+  /** The worst single gap, ms — the one the eye actually notices. */
+  readonly worstGapMs: number;
+  /**
+   * Captures that arrived well outside the cadence the rest of the clip holds.
+   *
+   * Measured against the clip's *own* spacing rather than against the requested
+   * rate, because the two are allowed to differ: a display that divides to 72 fps
+   * or a loop that can only manage 40 both produce a clip whose every frame is
+   * evenly spaced, and neither is a fault. What is a fault is one frame taking
+   * half again as long as its neighbours, and that is what this counts.
+   */
+  readonly slipped: number;
+  /** Animation frames per capture — the schedule the clip actually ran on. */
+  readonly stride: number;
+  readonly elapsedMs: number;
+}
+
+/**
+ * How far outside the established cadence a gap has to fall to count as slipped.
+ * A little over one gap, so ordinary display jitter is not reported as a fault.
+ */
+const SLIP_FACTOR = 1.4;
+/** Weight of the newest gap in the cadence estimate. */
+const CADENCE_EMA = 0.15;
+/**
+ * Animation frames the interval estimate is taken over.
+ *
+ * Sixteen: a quarter of a second at 60 Hz, which is long enough to absorb one bad
+ * sample and short enough that the schedule is settled before anything is recorded.
+ * The estimate is re-taken every time the window fills, so a loop that gets heavier
+ * mid-clip is followed rather than held to a schedule it can no longer keep.
+ */
+const SAMPLE_WINDOW = 16;
+/**
+ * Slack in the stride calculation, as a share of the ratio being floored.
+ *
+ * Half a percent, and it is small because the estimator earns it. A 60 Hz display
+ * asked for 30 fps wants a stride of exactly 2, and a measured interval of 16.6668 ms
+ * gives a ratio of 1.99998 — so a bare `floor` answers 1 and doubles the rate. That
+ * is the entire job: cover a measurement that lands a hair long, and floating point.
+ *
+ * It was five percent while the estimate came from a median, which sits *above* the
+ * display's period and needed the room. A trimmed minimum sits at or just below it,
+ * so the ratio errs high already and slack on top only pushes it over the next
+ * boundary the wrong way: measured at five percent, a 100 Hz panel asked for 60
+ * sometimes recorded 50 instead of 100, because a jittery window read the period as
+ * 8.6 ms and 1.94 became 2.03.
+ */
+const STRIDE_SLACK = 0.005;
+/**
+ * How far past its boundary the measurement has to move before the stride changes,
+ * in whole strides.
+ *
+ * A fifth, and this is the part slack alone could not do. The stride is a *discrete*
+ * choice, so a ratio sitting near a boundary flips it on the noise in the estimate —
+ * and a flip between 1 and 2 doubles the clip's frame rate. Measured on a loop with
+ * 24% frame-time jitter and a true ratio of exactly 2.0: the median of a
+ * sixteen-frame window wanders between 16.7 ms and 18.3 ms, which is a ratio between
+ * 2.0 and 1.82, and the stride flipped five times in a ten-second clip.
+ *
+ * A display's period does not change, so the right default is to keep the schedule
+ * already chosen and demand real evidence to leave it. A fifth of a stride is well
+ * past what a median of sixteen frames is wrong by and well short of a genuine step.
+ */
+const STRIDE_HYSTERESIS = 0.2;
+
+/**
+ * Animation frames per capture, given the target interval, what one animation frame
+ * actually costs, and the schedule already running.
+ *
+ * Rounded down, so the rate that comes out is never *below* the one asked for while
+ * the loop can hold it: a 100 Hz display asked for 60 records 100 rather than 50,
+ * which is more frames than needed and smooth, where the other way round is fewer
+ * frames than promised.
+ *
+ * `current` is held on to unless the measurement has moved clearly past its
+ * boundary — see `STRIDE_HYSTERESIS`. Pass 0 to choose freely.
+ */
+function strideFor(targetIntervalMs: number, frameIntervalMs: number, current = 0): number {
+  if (!(frameIntervalMs > 0)) return Math.max(1, current);
+  const scaled = (targetIntervalMs / frameIntervalMs) * (1 + STRIDE_SLACK);
+  if (
+    current > 0 &&
+    scaled >= current - STRIDE_HYSTERESIS &&
+    scaled < current + 1 + STRIDE_HYSTERESIS
+  ) {
+    return current;
+  }
+  return Math.max(1, Math.floor(scaled));
+}
+
+/**
+ * Second-smallest of `values`, sorted into `scratch`.
+ *
+ * **A trimmed minimum, and the choice of statistic is the whole point.** What is
+ * being estimated is the display's period, and that is a *floor* on how long an
+ * animation frame can take — a frame cannot come back sooner than the next vsync, it
+ * can only take longer and land on a later one. So the low end of the distribution is
+ * where the answer lives, and the mean and the median are both biased above it by
+ * however hard the loop is working.
+ *
+ * Which matters because the estimate feeds a `floor`: a stride of 2 asks whether the
+ * ratio is above or below 2, and an estimator that wanders either side of the answer
+ * flips the clip's frame rate. Measured with a median of sixteen: on a loop with 24%
+ * frame-time jitter and a true ratio of exactly 2, the median wandered between
+ * 16.7 ms and 18.3 ms and the stride flipped, taking a 30 fps request to 36.
+ *
+ * Second-smallest rather than smallest because the minimum has no defence at all
+ * against a bad sample — two callbacks in one frame, a clock that jumped, a tab
+ * waking up — and one of those in a window would set a stride far too long. One
+ * anomaly per sixteen frames is absorbed; two in the same window is not, which is a
+ * trade rather than an oversight.
+ *
+ * Insertion sort into a caller-owned buffer, because this runs inside a render loop
+ * and must not allocate. Sixteen elements nearly in order is a handful of
+ * comparisons; the general case is still trivial at this size.
+ */
+function trimmedMinimum(values: Float64Array, scratch: Float64Array): number {
+  const n = values.length;
+  for (let i = 0; i < n; i++) {
+    const value = values[i] ?? 0;
+    let j = i - 1;
+    while (j >= 0 && (scratch[j] ?? 0) > value) {
+      scratch[j + 1] = scratch[j] ?? 0;
+      j--;
+    }
+    scratch[j + 1] = value;
+  }
+  return scratch[Math.min(1, n - 1)] ?? 0;
+}
+
+export class FramePacer {
+  private readonly intervalMs: number;
+  /** Animation frames per capture. One until the loop's own rate is known. */
+  private strideFrames = 1;
+  private framesSinceCapture = 0;
+  private startMs = 0;
+  private lastCaptureMs = 0;
+  /**
+   * What one animation frame costs, ms — a trimmed minimum over a recent window.
+   *
+   * See `trimmedMinimum` for why the low end and not the middle. Three estimators
+   * were tried before it and each failed in a way worth recording: a running minimum
+   * over all time ratcheted down on anomalies until a clean 120 Hz loop recorded
+   * **24 fps**; a mean was dragged up by every overrunning frame, doubling the rate
+   * for the thirty frames an average takes to decay after one hitch; a median sat too
+   * far above the floor and wandered across the stride boundary.
+   */
+  private frameIntervalMs = 0;
+  /** Recent animation-frame intervals, and a scratch buffer to sort them in. */
+  private readonly samples = new Float64Array(SAMPLE_WINDOW);
+  private readonly sorted = new Float64Array(SAMPLE_WINDOW);
+  private sampleCount = 0;
+  /** The instant last seen, so a frame is only ever counted once. */
+  private lastSeenMs = 0;
+  private seen = false;
+  /** Rolling estimate of the gap the clip is actually holding, for `slipped`. */
+  private cadenceMs = 0;
+  private renderedFrames = 0;
+  private capturedFrames = 0;
+  private gapSumMs = 0;
+  private worstGapMs = 0;
+  private slippedFrames = 0;
+  private started = false;
+
+  constructor(readonly targetFps: number) {
+    this.intervalMs = 1000 / Math.max(targetFps, 1);
+  }
+
+  /**
+   * Whether this animation frame is one the recording wants, without committing.
+   *
+   * The query half of `offer`, and it exists so a caller can decide *before
+   * rendering* whether the frame it is about to draw will be kept. A renderer that
+   * draws every animation frame and then discards most of them spends its whole
+   * budget competing with the frame it means to keep.
+   *
+   * Called once per animation frame, before drawing. That is also where the loop's
+   * own interval is measured, since it is the only call that sees every frame:
+   * `offer` only sees the ones that were drawn.
+   *
+   * Allocation-free: this is called from inside a render loop.
+   */
+  due(nowMs: number): boolean {
+    this.observe(nowMs);
+    if (!this.started) return true;
+    return this.framesSinceCapture >= this.strideFrames;
+  }
+
+  /**
+   * Commit to the frame `due` was asked about.
+   *
+   * **`nowMs` must be the instant `due` was given, not the instant the frame
+   * finished drawing.** Both halves have to agree about when the frame is, or a
+   * frame is counted twice — once on the way in and once on the way out — and the
+   * loop's measured interval comes out at half its true value.
+   *
+   * A caller with nothing to gate may pass whatever clock it has, as long as it is
+   * the same one every frame.
+   */
+  offer(nowMs: number): boolean {
+    this.observe(nowMs);
+    if (!this.started) {
+      this.started = true;
+      this.startMs = nowMs;
+      this.lastCaptureMs = nowMs;
+      this.framesSinceCapture = 0;
+      this.capturedFrames = 1;
+      return true;
+    }
+
+    if (this.framesSinceCapture < this.strideFrames) return false;
+
+    const gap = nowMs - this.lastCaptureMs;
+    this.gapSumMs += gap;
+    if (gap > this.worstGapMs) this.worstGapMs = gap;
+    // Against the cadence so far, and only once there is one to compare with.
+    if (this.cadenceMs > 0 && gap > this.cadenceMs * SLIP_FACTOR) this.slippedFrames++;
+    this.cadenceMs =
+      this.cadenceMs === 0 ? gap : this.cadenceMs + (gap - this.cadenceMs) * CADENCE_EMA;
+    this.lastCaptureMs = nowMs;
+    this.framesSinceCapture = 0;
+    this.capturedFrames++;
+    return true;
+  }
+
+  /** One animation frame seen, for the interval estimate and the frame count. */
+  private observe(nowMs: number): void {
+    if (this.seen && nowMs === this.lastSeenMs) return;
+    const since = this.seen ? nowMs - this.lastSeenMs : 0;
+    this.lastSeenMs = nowMs;
+    this.seen = true;
+    this.renderedFrames++;
+    if (this.started) this.framesSinceCapture++;
+    if (since <= 0) return;
+
+    this.samples[this.sampleCount % SAMPLE_WINDOW] = since;
+    this.sampleCount++;
+    /*
+     * Until there is a window to take a median of, the estimate is the *shortest*
+     * frame seen so far. A schedule is needed before sixteen frames have passed — a
+     * recording that waited would capture all sixteen of them, a burst at the head of
+     * every clip — and of the estimators available before then the minimum is the one
+     * that errs the safe way: it reads the loop as faster than it is, which makes the
+     * stride longer and captures *fewer* frames than intended rather than more.
+     *
+     * The minimum's own failing, that one anomalous frame owns it for good, cannot
+     * bite here: sixteen frames later the median takes over and never gives it back.
+     */
+    if (this.sampleCount < SAMPLE_WINDOW) {
+      if (this.frameIntervalMs === 0 || since < this.frameIntervalMs) {
+        this.frameIntervalMs = since;
+        this.strideFrames = strideFor(this.intervalMs, since);
+      }
+      return;
+    }
+    /*
+     * Re-taken when the window fills rather than on every frame: sorting sixteen
+     * numbers is cheap but this is a render loop, and a display's period does not
+     * change between one frame and the next.
+     */
+    if (this.sampleCount % SAMPLE_WINDOW !== 0) return;
+    this.frameIntervalMs = trimmedMinimum(this.samples, this.sorted);
+    this.strideFrames = strideFor(this.intervalMs, this.frameIntervalMs, this.strideFrames);
+  }
+
+  /**
+   * Forget what has been measured, keep the schedule.
+   *
+   * For a recording with a warm-up in front of it: the frames a device spends
+   * getting an encoder and a driver going are genuinely awful — measured at 411 ms
+   * and 503 ms for a 1080x1920 clip — and they are not what the clip is like. Left in
+   * the report they become the worst gap and a couple of slipped frames, which is the
+   * evidence an export decides whether to warn the player on.
+   *
+   * The schedule survives on purpose: it was chosen from those same frames and it is
+   * still right.
+   */
+  resetMeasurement(): void {
+    this.startMs = this.lastCaptureMs;
+    this.capturedFrames = 1;
+    this.renderedFrames = 0;
+    this.gapSumMs = 0;
+    this.worstGapMs = 0;
+    this.slippedFrames = 0;
+    this.cadenceMs = 0;
+  }
+
+  get report(): FramePacingReport {
+    const elapsedMs = this.started ? Math.max(this.lastCaptureMs - this.startMs, 0) : 0;
+    const gaps = Math.max(this.capturedFrames - 1, 0);
+    return {
+      targetFps: this.targetFps,
+      rendered: this.renderedFrames,
+      captured: this.capturedFrames,
+      capturedFps: elapsedMs > 0 ? (gaps * 1000) / elapsedMs : 0,
+      meanGapMs: gaps > 0 ? this.gapSumMs / gaps : 0,
+      worstGapMs: this.worstGapMs,
+      slipped: this.slippedFrames,
+      stride: this.strideFrames,
+      elapsedMs,
+    };
+  }
+}

package/src/ui/frameRecorder.ts

@@ -0,0 +1,333 @@
+import { supportedClipMimeType } from './clipMime.ts';
+import { ExportTarget, clipBitrate, exportSizeFor } from './exportTarget.ts';
+import type { LockableSurface } from './exportTarget.ts';
+import type { FrameOverlay } from './frameOverlay.ts';
+import type { FramePacingReport } from './framePacer.ts';
+
+export const DEFAULT_CLIP_FPS = 30;
+
+/**
+ * Recording what is on a canvas — or on a prepared export target — to a file.
+ *
+ * A convenience on top of the replay, not the feature. The replay itself is
+ * what makes a run worth posting; this saves the trouble of reaching for a
+ * screen recorder — and where the browser cannot do it, saying so plainly beats
+ * producing a file that will not play.
+ *
+ * Deliberately not a server-side render. That is the "proper" answer and it is
+ * a backend, a queue, a storage bill and a moderation problem, for something
+ * the browser already does.
+ *
+ * **The honest limit, and it belongs here rather than in a commit message:**
+ * `MediaRecorder` timestamps every frame by wall clock, and that is measured
+ * rather than assumed — a probe recording requested frames at gaps of 8.6 / 24.5 /
+ * 8.1 / 28.6 ms and `ffprobe` read the MP4's own timestamps back as 8.8 / 24.2 /
+ * 8.1 / 28.5 ms, `avg_frame_rate=7110000/120161`. Two things follow.
+ *
+ * An export has to run in real time: there is no in-browser way to render a clip
+ * slower than real time and have the audio line up, short of shipping our own
+ * muxer, which is a dependency and the standing rule says no. So the export can be
+ * *paced* (see `ExportTarget`) and *measured*, but it cannot be given more time.
+ *
+ * And a constant-rate file is not on offer either. What is on offer is a file whose
+ * frames are evenly spaced *and* hold moments the same distance apart, which is
+ * what a viewer reads as smooth — so the schedule captures every n-th animation
+ * frame and the content follows the wall clock. A device that cannot hold the
+ * target rate then produces a slower clip rather than a juddering one, and the
+ * measurement in `pacing` says which it was.
+ */
+export interface FrameRecorderOptions {
+  /**
+   * Record the canvas directly, at `fps`. Simple and appropriate for a debug
+   * capture; for a clip anybody else will see, prefer `stream` from an
+   * `ExportTarget`, which fixes the aspect, stamps the mark and paces the
+   * frames.
+   */
+  readonly canvas?: HTMLCanvasElement;
+  /** A prepared video stream, e.g. `ExportTarget.acquire()`. Wins over `canvas`. */
+  readonly stream?: MediaStream;
+  /** Mixed into the clip. Omit for a silent recording. */
+  readonly audio?: MediaStream | null;
+  /**
+   * Frames per second wanted — a floor, not a promise.
+   *
+   * The schedule counts animation frames (see `FramePacer`), so what comes out is
+   * the loop's own rate divided by a whole number. Asking for 60 on a 144 Hz panel
+   * records 72; asking for it on a loop that can only deliver 40 records 40.
+   */
+  readonly fps?: number;
+  /**
+   * Bits per second for video. Defaults to a figure scaled from the frame's
+   * pixel count and rate — a constant is generous at one size and starved at
+   * another, and a starved encoder on high-motion footage looks like stutter.
+   */
+  readonly videoBitsPerSecond?: number;
+  /**
+   * Record at a fixed frame size rather than at whatever the canvas happens to
+   * be, compositing the scene and an optional mark into it.
+   *
+   * This is what makes an export a *product* rather than a screen capture: the
+   * frame is the requested shape whatever the window is, the mark is inside the
+   * video where a DOM overlay could never be, and frames are handed over one at a
+   * time so none is ever recorded twice.
+   */
+  readonly target?: {
+    /** The canvas the scene is drawn into. */
+    readonly source: HTMLCanvasElement;
+    /** Whoever owns that canvas's drawing-buffer size — normally the renderer. */
+    readonly surface: LockableSurface;
+    readonly width: number;
+    readonly height: number;
+    readonly overlay?: FrameOverlay | ((width: number, height: number) => FrameOverlay);
+    /**
+     * Drawn live into every composed frame, after the scene and the baked mark.
+     *
+     * For anything that changes frame to frame — a speedometer, a clock — which the
+     * baked `overlay` cannot express at all. See `ExportTargetOptions.drawFrame`.
+     */
+    readonly drawFrame?: (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+    /**
+     * What the renderer is currently managing, frames per second. A device below
+     * the target rate records at a smaller frame instead: a slightly softer clip
+     * that holds its rate beats a full-size one that judders. Omit for no
+     * measurement, which is treated as no evidence rather than as bad news.
+     */
+    readonly measuredFps?: number;
+    /** Forwarded to `ExportTargetOptions.presentedFrames`; see `duplicateFrame` below. */
+    readonly presentedFrames?: () => number;
+  };
+}
+
+export class FrameRecorder {
+  private recorder: MediaRecorder | null = null;
+  private chunks: Blob[] = [];
+  private readonly mime: string;
+  private target: ExportTarget | null = null;
+  private targetStream: MediaStream | null = null;
+
+  constructor(private readonly options: FrameRecorderOptions) {
+    const mime = supportedClipMimeType();
+    if (mime === null) throw new Error('This browser cannot record video.');
+    if (
+      options.canvas === undefined &&
+      options.stream === undefined &&
+      options.target === undefined
+    ) {
+      throw new Error('A recording needs a canvas, a stream or a target.');
+    }
+    this.mime = mime;
+  }
+
+  get mimeType(): string {
+    return this.mime;
+  }
+
+  /**
+   * Take over the render surface before recording starts.
+   *
+   * Separate from `start` because the aspect has to be in force *before* the
+   * first frame anybody records: the camera composes for `renderer.aspect`, so
+   * locking and recording in the same breath would put a screen-shaped shot in
+   * the first frames of a vertical clip. Returns the frame size that will be
+   * recorded, which is not always the one requested — see `measuredFps`.
+   */
+  prepare(): { width: number; height: number; reduced: boolean } | null {
+    const options = this.options.target;
+    if (options === undefined) return null;
+    if (this.target !== null) {
+      return { width: this.target.width, height: this.target.height, reduced: false };
+    }
+    const fps = this.options.fps ?? DEFAULT_CLIP_FPS;
+    // The measurement was taken while rendering the *window*, so it is handed in
+    // with the pixel count it was taken at — see `exportSizeFor`.
+    const size = exportSizeFor(
+      options.width,
+      options.height,
+      options.measuredFps ?? 0,
+      fps,
+      options.source.width * options.source.height,
+    );
+    this.target = new ExportTarget({
+      source: options.source,
+      surface: options.surface,
+      width: size.width,
+      height: size.height,
+      fps,
+      ...(options.overlay === undefined ? {} : { overlay: options.overlay }),
+      ...(options.drawFrame === undefined ? {} : { drawFrame: options.drawFrame }),
+      ...(options.presentedFrames === undefined
+        ? {}
+        : { presentedFrames: options.presentedFrames }),
+    });
+    this.targetStream = this.target.acquire();
+    return size;
+  }
+
+  /**
+   * Whether the frame about to be drawn will be kept. True when there is no
+   * fixed target, so a caller can gate its render pass unconditionally.
+   *
+   * Call once per animation frame, drawing or not: the instant is kept and reused
+   * when the frame is handed over, so one clock decides and commits.
+   */
+  captureDue(nowMs: number): boolean {
+    return this.target?.captureDue(nowMs) ?? true;
+  }
+
+  /**
+   * One rendered frame, offered to the recording.
+   *
+   * Call at the very end of the render pass. Cheap and false when there is no
+   * fixed target, so a caller can hand every frame over unconditionally. Takes no
+   * instant — it uses the one `captureDue` was given for this frame.
+   */
+  frameRendered(): boolean {
+    return this.target?.frameRendered() ?? false;
+  }
+
+  /**
+   * What the pacing actually was, or null when recording the canvas directly.
+   *
+   * The measurement is the point rather than a diagnostic afterthought: an export
+   * that ran below its target rate produced a juddering file, and the only honest
+   * options are to say so or to have not measured.
+   */
+  get pacing(): FramePacingReport | null {
+    return this.target === null ? null : this.target.pacing;
+  }
+
+  /**
+   * Whether the frame `frameRendered` just composited repeats the one before it.
+   *
+   * False without a target, and false when `presentedFrames` was never supplied — the same
+   * two "no evidence yet" cases `pacing` already has to account for. See
+   * `ExportTarget.duplicateFrame`, which this only forwards.
+   */
+  get duplicateFrame(): boolean {
+    return this.target?.duplicateFrame ?? false;
+  }
+
+  /**
+   * Start the measurement over, keeping the schedule.
+   *
+   * For a caller that records a warm-up in front of the clip proper: what a device
+   * costs while an encoder gets going is not what the clip is like, and the report is
+   * what the export decides whether to warn the player on.
+   */
+  resetPacing(): void {
+    this.target?.resetPacing();
+  }
+
+  start(): void {
+    if (this.recorder !== null) return;
+    const { canvas, audio, fps = DEFAULT_CLIP_FPS } = this.options;
+
+    if (this.options.target !== undefined) this.prepare();
+    const source = this.targetStream ?? this.options.stream ?? canvas?.captureStream(fps) ?? null;
+    if (source === null) throw new Error('A recording needs a canvas, a stream or a target.');
+
+    /*
+     * A fresh stream rather than the source one. Adding the audio tracks to a
+     * stream the caller owns means stopping the recording would stop the audio
+     * graph's capture track too, and a second export would then come out silent.
+     */
+    const stream = new MediaStream();
+    for (const track of source.getVideoTracks()) stream.addTrack(track);
+    if (audio != null) {
+      for (const track of audio.getAudioTracks()) stream.addTrack(track);
+    }
+
+    this.chunks = [];
+    this.recorder = new MediaRecorder(stream, {
+      mimeType: this.mime,
+      videoBitsPerSecond: this.options.videoBitsPerSecond ?? this.defaultBitrate(stream, fps),
+    });
+    this.recorder.ondataavailable = (event): void => {
+      if (event.data.size > 0) this.chunks.push(event.data);
+    };
+    this.recorder.start();
+  }
+
+  /**
+   * Resolves with the finished clip, or null if nothing was recorded.
+   *
+   * The surface goes back before the promise resolves either way. A cancelled
+   * export that left the drawing buffer pinned to 1080x1920 would leave the game
+   * rendering into the wrong shape for the rest of the session.
+   */
+  async stop(): Promise<Blob | null> {
+    const recorder = this.recorder;
+    if (recorder === null) {
+      this.release();
+      return null;
+    }
+    this.recorder = null;
+
+    await new Promise<void>((resolve) => {
+      recorder.onstop = (): void => resolve();
+      try {
+        recorder.stop();
+      } catch {
+        resolve();
+      }
+    });
+    this.release();
+
+    if (this.chunks.length === 0) return null;
+    return new Blob(this.chunks, { type: this.mime });
+  }
+
+  /** Give the render surface back. Safe at any point, and idempotent. */
+  release(): void {
+    this.target?.release();
+    this.target = null;
+    this.targetStream = null;
+  }
+
+  /**
+   * Bitrate from whatever the frame's real size turns out to be.
+   *
+   * Read from the track where possible, because that is the authority: a stream
+   * from a composited target has nothing to do with the canvas that was passed
+   * in, and guessing from the wrong one is how a 1080x1920 clip ends up encoded
+   * at a bitrate chosen for a 400-pixel window.
+   */
+  private defaultBitrate(stream: MediaStream, fps: number): number {
+    const track = stream.getVideoTracks()[0];
+    const settings = track?.getSettings();
+    const width = settings?.width ?? this.options.canvas?.width ?? 1280;
+    const height = settings?.height ?? this.options.canvas?.height ?? 720;
+    return clipBitrate(width, height, fps);
+  }
+}
+
+/**
+ * Hand a file to the player.
+ *
+ * `navigator.share` where it exists, because on a phone that is one tap into
+ * the app they were going to post to anyway; a download otherwise. A file in
+ * the Downloads folder that nobody can find is most of the way to no export at
+ * all.
+ */
+export async function offerClip(blob: Blob, filename: string): Promise<void> {
+  const file = new File([blob], filename, { type: blob.type });
+
+  if (typeof navigator.canShare === 'function' && navigator.canShare({ files: [file] })) {
+    try {
+      await navigator.share({ files: [file] });
+      return;
+    } catch {
+      // Cancelled, or refused. Fall through to a download rather than leaving
+      // the player with nothing.
+    }
+  }
+
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.click();
+  // Revoked on the next turn: doing it synchronously races the download in
+  // some browsers and produces an empty file.
+  setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}