Skip to content

The free and privacy-friendly screen recorder with no limits 🎥

14.4 KB
Raw Blame
// Encoder pre-warm. OS encode services (VTDecoderXPCService etc) need
// a few frames before the HW pipeline locks in; diag showed real
// recordings' first ~30 frames running at 6-9fps before settling at
// 30fps. Opens a VideoEncoder with the real config, bursts synthetic
// frames, closes. Fire-and-forget; failure no-ops.
//
// With warm-adopt on (off by default) it keeps the encoder open for the
// recording to adopt instead, since close/reopen loses the session ramp.

import { perfMark, perfSpan } from "../utils/perfMarks";
import {
  PREWARM_MIN_WARM_CHUNKS,
  PREWARM_UNCLAIMED_MAX_MS,
  canAdoptPrewarmedEncoder,
  evaluatePrewarmProgress,
  shouldInvalidateDecoderConfig,
  shouldReconfigureAdoptedEncoder,
} from "./webcodecs/recorderLogic";
import {
  isEncoderPrewarmEnabled,
  isWarmAdoptEnabled,
  loadStartupFlags,
} from "./webcodecs/startupFlags";

let _activeWarmer = null;
let _lastHwError = null;
const PREWARM_HW_ERROR_TTL_MS = 60_000;

// An explicit hardware-encoder error from the prewarm, if recent. Only an
// error counts: a prewarm that merely ended with no chunks is not evidence.
export const getRecentPrewarmHwError = ({ width, height } = {}) => {
  if (!_lastHwError) return null;
  if (_lastHwError.width !== width || _lastHwError.height !== height) {
    return null;
  }
  if (performance.now() - _lastHwError.at > PREWARM_HW_ERROR_TTL_MS) {
    _lastHwError = null;
    return null;
  }
  return _lastHwError.name;
};

const computeFramerate = (config) => {
  const fps = Number(config?.framerate);
  if (!Number.isFinite(fps) || fps <= 0 || fps > 240) return 30;
  return Math.round(fps);
};

const synthesizeAndEncode = (encoder, canvas, ctx, index, framerate, keyFrame) => {
  // Vary content per frame so the encoder exercises the pipeline
  // instead of emitting empty deltas.
  const hue = (index * 17) % 360;
  ctx.fillStyle = `hsl(${hue}, 50%, 35%)`;
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = `hsl(${(hue + 180) % 360}, 50%, 60%)`;
  ctx.fillRect(
    (index % 8) * (canvas.width / 8),
    (index % 6) * (canvas.height / 6),
    canvas.width / 8,
    canvas.height / 6,
  );
  const tsUs = Math.round((index * 1_000_000) / framerate);
  const frame = new VideoFrame(canvas, {
    timestamp: tsUs,
    duration: Math.round(1_000_000 / framerate),
  });
  try {
    encoder.encode(frame, { keyFrame });
  } finally {
    frame.close();
  }
};

const queueSizeOf = (encoder) => {
  try {
    return encoder?.encodeQueueSize ?? 0;
  } catch {
    return 0;
  }
};

/**
 * Open a VideoEncoder, warm it until its encode session has ramped, drain it,
 * and keep it open for adoption. Returns a handle with .close(). Idempotent:
 * a second call while one is active returns the active handle.
 *
 * @param {object} cfg
 * @param {number} cfg.width
 * @param {number} cfg.height
 * @param {string} cfg.codec  e.g. "avc1.64002A"
 * @param {number} [cfg.bitrate]
 * @param {number} [cfg.framerate]
 * @returns {Promise<{close: () => Promise<void>, chunks: number, ok: boolean, warm: boolean}|null>}
 */
export const startEncoderPrewarm = async (cfg) => {
  if (_activeWarmer) return _activeWarmer.handle;
  if (typeof VideoEncoder === "undefined" || typeof VideoFrame === "undefined" || typeof OffscreenCanvas === "undefined") {
    perfMark("Recorder.encoderPrewarm.skipped", { reason: "no-webcodecs" });
    return null;
  }
  if (!cfg || !cfg.width || !cfg.height || !cfg.codec) {
    perfMark("Recorder.encoderPrewarm.skipped", { reason: "no-config" });
    return null;
  }

  const endStart = perfSpan("Recorder.encoderPrewarm.start", {
    w: cfg.width,
    h: cfg.height,
    codec: cfg.codec,
  });

  const state = {
    chunks: 0,
    encoder: null,
    canvas: null,
    ctx: null,
    closed: false,
    claimed: false,
    warm: false,
    config: null,
    framerate: computeFramerate(cfg),
    unclaimedTimer: null,
    // VideoEncoder callbacks are fixed at construction, so everything routes
    // through these: discarded during warmup, swapped to the recorder's on
    // adoption.
    sink: null,
    errorSink: null,
    // Chrome emits decoderConfig (SPS/PPS) only when the reported config
    // changes, so the warm encoder spends it on the discard sink. Keep it to
    // replay for the adopting muxer.
    warmDecoderConfig: null,
  };
  _activeWarmer = state;

  const handle = {
    /** Close the prewarm encoder. Safe to call multiple times. No-op once claimed. */
    close: async () => {
      if (state.closed || state.claimed) return;
      state.closed = true;
      if (state.unclaimedTimer) {
        clearTimeout(state.unclaimedTimer);
        state.unclaimedTimer = null;
      }
      if (state.encoder) {
        try {
          state.encoder.close();
        } catch {}
        state.encoder = null;
      }
      if (_activeWarmer === state) _activeWarmer = null;
      perfMark("Recorder.encoderPrewarm.closed", { chunks: state.chunks });
    },
    get chunks() {
      return state.chunks;
    },
    get warm() {
      return state.warm;
    },
    get ok() {
      return state.encoder != null && state.chunks > 0;
    },
  };
  state.handle = handle;

  // Nothing may await between the guard above and `_activeWarmer = state`:
  // two concurrent starts would both pass it and orphan the loser's encoder.
  // Flags load async, so wait for them here (250ms cap) instead of racing
  // them at their defaults on every recording.
  try {
    await Promise.race([
      loadStartupFlags(),
      new Promise((resolve) => setTimeout(resolve, 250)),
    ]);
  } catch {}
  if (!isEncoderPrewarmEnabled() || state.closed) {
    if (_activeWarmer === state) _activeWarmer = null;
    endStart({ ok: false, reason: "disabled" });
    perfMark("Recorder.encoderPrewarm.skipped", { reason: "disabled" });
    return null;
  }

  try {
    state.encoder = new VideoEncoder({
      output: (chunk, meta) => {
        state.chunks += 1;
        _lastHwError = null;
        if (!state.warmDecoderConfig && meta?.decoderConfig) {
          state.warmDecoderConfig = meta.decoderConfig;
        }
        state.sink?.(chunk, meta);
      },
      error: (err) => {
        if (state.errorSink) {
          state.errorSink(err);
          return;
        }
        _lastHwError = {
          at: performance.now(),
          name: String(err?.name || "error").slice(0, 40),
          width: cfg.width,
          height: cfg.height,
        };
        perfMark("Recorder.encoderPrewarm.encoderError", {
          msg: String(err?.message || err).slice(0, 120),
        });
      },
    });
    const config = {
      codec: cfg.codec,
      width: cfg.width,
      height: cfg.height,
      bitrate: Math.max(500_000, Number(cfg.bitrate) || 4_000_000),
      framerate: state.framerate,
      bitrateMode: "constant",
      latencyMode: "realtime",
      hardwareAcceleration: "prefer-hardware",
    };
    state.encoder.configure(config);
    state.config = config;
    state.canvas = new OffscreenCanvas(cfg.width, cfg.height);
    state.ctx = state.canvas.getContext("2d");
    if (!state.ctx) {
      throw new Error("no-canvas-2d-context");
    }

    // Without adoption there's nothing to gain from holding the session open:
    // only the OS encode service needs warming, and it survives the close.
    if (!isWarmAdoptEnabled()) {
      for (let i = 0; i < 6; i += 1) {
        if (state.closed) return handle;
        synthesizeAndEncode(
          state.encoder,
          state.canvas,
          state.ctx,
          i,
          state.framerate,
          i === 0,
        );
      }
      // close() drops queued frames, so close before the flush lands warms nothing.
      try {
        await Promise.race([
          state.encoder.flush().catch(() => {}),
          new Promise((resolve) => setTimeout(resolve, 1500)),
        ]);
      } catch {}
      await handle.close();
      endStart({ chunks: state.chunks, ok: state.chunks > 0, mode: "burst" });
      return handle;
    }

    // Feed until the session has ramped or a bound trips. No keep-alive ticker
    // afterwards: a chained sub-second timer on a background tab triggers
    // Chrome's intensive throttling, which makes storage IPCs take 11-19s.
    const startedAt = performance.now();
    let framesFed = 0;
    let stopReason = "feeding";
    for (;;) {
      if (state.closed || state.claimed) return handle;
      const progress = evaluatePrewarmProgress({
        chunksOut: state.chunks,
        queueSize: queueSizeOf(state.encoder),
        framesFed,
        elapsedMs: performance.now() - startedAt,
      });
      if (progress.done) {
        stopReason = progress.reason;
        break;
      }
      // Shallow feed: a deep queue hides whether the encoder has caught up,
      // which is the signal we're waiting on.
      if (queueSizeOf(state.encoder) < 4) {
        synthesizeAndEncode(
          state.encoder,
          state.canvas,
          state.ctx,
          framesFed,
          state.framerate,
          framesFed === 0,
        );
        framesFed += 1;
      }
      await new Promise((resolve) => setTimeout(resolve, 4));
    }

    // Drain so the adopting recorder starts at queue 0.
    try {
      await state.encoder.flush();
    } catch {}
    if (state.closed || state.claimed) return handle;

    state.warm =
      state.chunks >= PREWARM_MIN_WARM_CHUNKS &&
      state.encoder?.state === "configured" &&
      queueSizeOf(state.encoder) === 0;

    if (!state.warm) {
      // Never ramped: an open cold encoder is just a held HW slot.
      await handle.close();
      endStart({ chunks: state.chunks, ok: false, reason: stopReason });
      return handle;
    }

    // Safety net for flows that never adopt (MediaRecorder fallback,
    // cancelled start): don't hold the HW slot indefinitely.
    state.unclaimedTimer = setTimeout(() => {
      state.unclaimedTimer = null;
      if (!state.claimed && !state.closed) {
        perfMark("Recorder.encoderPrewarm.unclaimedTimeout", {
          chunks: state.chunks,
        });
        void handle.close();
      }
    }, PREWARM_UNCLAIMED_MAX_MS);

    endStart({ chunks: state.chunks, ok: true, framesFed, reason: stopReason });
    perfMark("Recorder.encoderPrewarm.ready", {
      framerate: state.framerate,
      width: cfg.width,
      height: cfg.height,
      chunks: state.chunks,
      framesFed,
      ms: Math.round(performance.now() - startedAt),
    });
  } catch (err) {
    endStart({ ok: false, error: String(err?.message || err).slice(0, 100) });
    perfMark("Recorder.encoderPrewarm.failed", {
      msg: String(err?.message || err).slice(0, 120),
    });
    if (state.encoder) {
      try {
        state.encoder.close();
      } catch {}
      state.encoder = null;
    }
    if (_activeWarmer === state) _activeWarmer = null;
    return null;
  }

  return handle;
};

/**
 * Take over the warm encoder for a real recording, or dispose it: the caller
 * opens its own straight after, and a lingering warm session contends for the
 * same VideoToolbox slot on macOS.
 *
 * @param {object} config  the recording's VideoEncoderConfig
 * @param {(chunk: any, meta: any) => void} sink  the recorder's output handler
 * @param {(err: any) => void} errorSink  the recorder's error handler
 * @param {{allowAdopt?: boolean, preferSoftware?: boolean}} [opts]
 * @returns {{encoder: any, reconfigured: boolean}|null}
 */
export const claimPrewarmedEncoder = (config, sink, errorSink, opts = {}) => {
  const state = _activeWarmer;
  const adoptable = canAdoptPrewarmedEncoder({
    hasWarmer: Boolean(state),
    warm: Boolean(state?.warm),
    claimed: Boolean(state?.claimed),
    closed: Boolean(state?.closed),
    encoderState: state?.encoder?.state ?? null,
    disabled: !isWarmAdoptEnabled(),
    allowAdopt: opts.allowAdopt !== false,
    preferSoftware:
      opts.preferSoftware === true ||
      config?.hardwareAcceleration === "prefer-software",
  });

  if (!adoptable) {
    if (state) {
      perfMark("Recorder.encoderPrewarm.adoptSkipped", {
        warm: Boolean(state.warm),
        claimed: Boolean(state.claimed),
        encoderState: state.encoder?.state ?? null,
        allowAdopt: opts.allowAdopt !== false,
      });
    }
    // Only a track eligible to adopt may dispose. Cloud starts screen and
    // camera together, and the camera (allowAdopt:false) arriving first would
    // close the warm encoder out from under the screen track's claim.
    if (opts.allowAdopt !== false) {
      void closeActiveEncoderPrewarm();
    }
    return null;
  }

  try {
    // Redirect output/error before any reconfigure so nothing the encoder
    // emits from here on is discarded.
    state.sink = sink || null;
    state.errorSink = errorSink || null;
    // Always reconfigure, even for an identical config. Chrome emits
    // decoderConfig (the SPS/PPS the muxer needs) only when the reported config
    // changes, and the warm encoder already spent that on the discard sink.
    const warmConfigBefore = state.config;
    const dimsChanged = shouldReconfigureAdoptedEncoder(warmConfigBefore, config);
    state.encoder.configure(config);
    state.config = config;
    state.claimed = true;
    if (state.unclaimedTimer) {
      clearTimeout(state.unclaimedTimer);
      state.unclaimedTimer = null;
    }
    const encoder = state.encoder;
    // Ownership passes to the recorder, which closes it at stop.
    _activeWarmer = null;
    perfMark("Recorder.encoderPrewarm.adopted", {
      dimsChanged,
      chunks: state.chunks,
      width: config?.width ?? null,
      height: config?.height ?? null,
    });
    return {
      encoder,
      reconfigured: dimsChanged,
      // Only drop the replay when the SPS is invalidated (codec or coded dims).
      // A bitrate-only reconfigure (the normal cloud case) leaves it correct and
      // Chrome may not re-emit one, so nulling it gives a header-only file.
      decoderConfigFallback: shouldInvalidateDecoderConfig(warmConfigBefore, config)
        ? null
        : state.warmDecoderConfig,
    };
  } catch (err) {
    perfMark("Recorder.encoderPrewarm.adoptFailed", {
      msg: String(err?.message || err).slice(0, 120),
    });
    state.sink = null;
    state.errorSink = null;
    state.claimed = false;
    void closeActiveEncoderPrewarm();
    return null;
  }
};

/** Returns the active prewarm handle if one exists, else null. */
export const getActiveEncoderPrewarm = () => _activeWarmer?.handle || null;

/** Synchronously close any active prewarm. Safe at any time. */
export const closeActiveEncoderPrewarm = async () => {
  const h = getActiveEncoderPrewarm();
  if (h) {
    try {
      await h.close();
    } catch {}
  }
};