Skip to content

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

Encoder queue headroom, frozen static-screen captures, and recording diagnostics

Alyssa X00eca2db819c
diff --git a/package-lock.json b/package-lock.json
index c9bdb13..7337e99 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "screenity",
- "version": "4.5.6",
+ "version": "4.6.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "screenity",
- "version": "4.5.6",
+ "version": "4.6.2",
"hasInstallScript": true,
"dependencies": {
"@babel/plugin-transform-react-jsx": "^7.27.1",
@@ -11231,9 +11231,10 @@
}
},
"node_modules/shell-quote": {
- "version": "1.8.3",
- "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz",
- "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==",
+ "version": "1.10.0",
+ "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.10.0.tgz",
+ "integrity": "sha512-w1aiOKwKuRgtwAReIIj89puqg+I7GvX4IbLrvmhXbzQsj1+Zwi4VO3+fa6ZF91TWSjIxoEkKnMeHcLEODK5ZXA==",
+ "license": "MIT",
"engines": {
"node": ">= 0.4"
},
diff --git a/package.json b/package.json
index 432edea..c065a61 100755
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "screenity",
- "version": "4.6.2",
+ "version": "4.6.4",
"description": "The free and privacy-friendly screen recorder with no sign in needed.",
"scripts": {
"build": "cross-env NODE_ENV=production node utils/build.js",
diff --git a/src/manifest.json b/src/manifest.json
index dc6aec0..817d4b0 100755
--- a/src/manifest.json
+++ b/src/manifest.json
@@ -3,7 +3,7 @@
"name": "__MSG_extName__",
"description": "__MSG_extDesc__",
"default_locale": "en",
- "version": "4.6.2",
+ "version": "4.6.4",
"background": {
"service_worker": "background.bundle.js"
},
diff --git a/src/pages/CloudRecorder/CloudRecorder.jsx b/src/pages/CloudRecorder/CloudRecorder.jsx
index 16ed745..0e64cf8 100644
--- a/src/pages/CloudRecorder/CloudRecorder.jsx
+++ b/src/pages/CloudRecorder/CloudRecorder.jsx
@@ -321,6 +321,10 @@ const CloudRecorder = () => {
const recoveryExportedRef = useRef(false);
const screenTrackLostRef = useRef(false);
const screenTrackMonitor = useRef(null);
+ // null = not muted; the reported flag keeps the breadcrumb to one per
+ // mute stretch.
+ const screenTrackMutedSinceRef = useRef(null);
+ const screenTrackMuteReportedRef = useRef(false);
// Capture identity (recordingType/surface enums only, no labels/URLs) for
// forensic telemetry, so a frozen session's capture mechanism is known.
const captureContextRef = useRef(null);
@@ -701,6 +705,18 @@ const CloudRecorder = () => {
event: {
type: eventPayload.event,
t: eventPayload.ts || Date.now(),
+ // `recording_forensic_event` is one type covering many events (track
+ // mute/end, visibility, focus, page freeze). Without name/tMs the
+ // whole forensic channel lands indistinguishable.
+ name: typeof eventPayload.name === "string" ? eventPayload.name : null,
+ tMs:
+ typeof eventPayload.tMs === "number" ? eventPayload.tMs : null,
+ // How long the screen track stayed `muted`
+ // (screen-track-muted-sustained / -mute-cleared).
+ mutedMs:
+ typeof eventPayload.mutedMs === "number"
+ ? eventPayload.mutedMs
+ : null,
trackType: eventPayload.trackType || null,
offsetBytes:
typeof eventPayload.offset === "number"
@@ -752,6 +768,35 @@ const CloudRecorder = () => {
: null,
encoderStickyReason:
eventPayload.encoderStickyReason || encoderSticky.reason || null,
+ // Capture identity. `event` is a fixed allowlist, so these were
+ // dropped client-side before the server sanitizer saw them: that's
+ // why upload_sessions logs recordingType/isTab/region as "unknown" on
+ // every session. Enums and booleans only, no labels or URLs.
+ recordingType: eventPayload.recordingType || recordingType.current || null,
+ isTab:
+ typeof eventPayload.isTab === "boolean"
+ ? eventPayload.isTab
+ : Boolean(isTab.current),
+ region:
+ typeof eventPayload.region === "boolean"
+ ? eventPayload.region
+ : Boolean(regionRef.current),
+ // Null on tab capture: displaySurface only exists on getDisplayMedia
+ // tracks, so isTab/region are what separate tab from screen.
+ screenSurface:
+ eventPayload.screenSurface ||
+ captureContextRef.current?.screenSurface ||
+ null,
+ // "No sound in my recording" is unanswerable without knowing whether
+ // they asked for sound at all.
+ micActive:
+ typeof eventPayload.micActive === "boolean"
+ ? eventPayload.micActive
+ : Boolean(audioIntent.current?.micActive),
+ systemAudio:
+ typeof eventPayload.systemAudio === "boolean"
+ ? eventPayload.systemAudio
+ : Boolean(audioIntent.current?.systemAudio),
storageBackend: eventPayload.storageBackend || null,
storageInitMs:
typeof eventPayload.storageInitMs === "number"
@@ -764,6 +809,9 @@ const CloudRecorder = () => {
// event types (recording_heartbeat, recording_stop_diag,
// recording_failed_bundle); null otherwise. The server
// sanitizer drops them cleanly when absent.
+ // In `event`, not at the request root: nested objects here are a
+ // shape the server sanitizes, an unknown root key risks the body.
+ encodeStats: eventPayload.encodeStats || null,
screenDiag: eventPayload.screenDiag || null,
cameraDiag: eventPayload.cameraDiag || null,
audioDiag: eventPayload.audioDiag || null,
@@ -902,12 +950,24 @@ const CloudRecorder = () => {
Number(cameraUploader.current?.offset) ||
0;
const serverBytesConfirmed = screenServerBytes + cameraServerBytes;
+ // Peak queue depth and backpressure drops ride the outcome event: it's
+ // the only fleet-wide read on whether the steady cap fits hardware we
+ // can't test. Tagged by track, since a hardware screen encoder and a
+ // software camera encoder queue very differently.
+ const screenStats = screenRecorder.current?.getEncodeStats?.() || null;
+ const cameraStats = cameraRecorder.current?.getEncodeStats?.() || null;
+ const encodeStats = screenStats
+ ? { ...screenStats, track: "screen" }
+ : cameraStats
+ ? { ...cameraStats, track: "camera" }
+ : null;
void emitUploadTelemetry("recording_outcome", {
outcome,
durationMs,
chunksPersisted,
serverBytesConfirmed,
uploaderType: "cloud_recorder",
+ encodeStats,
...extra,
});
};
@@ -1285,6 +1345,8 @@ const CloudRecorder = () => {
const bindScreenTrack = (track) => {
if (!track) return;
screenTrackLostRef.current = false;
+ screenTrackMutedSinceRef.current = null;
+ screenTrackMuteReportedRef.current = false;
// Capture identity from the bound track (fires on every acquisition path).
// Enums and booleans only, no track.label/title/URL.
try {
@@ -1414,6 +1476,35 @@ const CloudRecorder = () => {
);
stopRecording(true, "screen-track-monitor-ended");
}
+ return;
+ }
+
+ // `muted` with readyState still "live" delivers nothing, but the
+ // static-frame fallback keeps re-encoding the last frame so every other
+ // guard sees a healthy recording. Observe-only: mute fires transiently
+ // (crbug 40200910), so stopping here would kill recoverable sessions.
+ const muted = track.muted === true;
+ if (muted && !screenTrackMutedSinceRef.current) {
+ screenTrackMutedSinceRef.current = Date.now();
+ } else if (!muted && screenTrackMutedSinceRef.current) {
+ logForensicEvent("screen-track-mute-cleared", {
+ mutedMs: Date.now() - screenTrackMutedSinceRef.current,
+ });
+ screenTrackMutedSinceRef.current = null;
+ screenTrackMuteReportedRef.current = false;
+ }
+ if (
+ muted &&
+ screenTrackMutedSinceRef.current &&
+ !screenTrackMuteReportedRef.current &&
+ Date.now() - screenTrackMutedSinceRef.current >= 10000
+ ) {
+ // Once per sustained mute, not every 5s tick.
+ screenTrackMuteReportedRef.current = true;
+ logScreenTrackEvent("monitor-muted-sustained", track);
+ logForensicEvent("screen-track-muted-sustained", {
+ mutedMs: Date.now() - screenTrackMutedSinceRef.current,
+ });
}
}, 5000);
};
@@ -4164,6 +4255,13 @@ const CloudRecorder = () => {
},
});
screenRecorder.current = screenSelection.recorder;
+ // Only WebCodecsTrackRecorder disposes the prewarm. On the
+ // MediaRecorder fallback nothing would, leaving a configured hardware
+ // encoder held for the whole recording (the prewarm no longer
+ // self-closes after 6 frames).
+ if (screenSelection.kind !== "webcodecs") {
+ closeActiveEncoderPrewarm().catch(() => {});
+ }
encoderKinds.screen = screenSelection.kind;
trackContainers.screen = screenSelection.container;
trackCodecs.screen = screenSelection.codec;
@@ -6374,8 +6472,21 @@ const CloudRecorder = () => {
// warm the OS encoder so the real one hits 30fps from frame 1
// instead of crawling for the first ~30 frames. mirrors Recorder.jsx.
try {
- const w = Number(settings.width) || 0;
- const h = Number(settings.height) || 0;
+ const rawW = Number(settings.width) || 0;
+ const rawH = Number(settings.height) || 0;
+ // The screen encoder is hard-capped at 1080p (WEBCODECS_CAP) and
+ // WCR downscales onto its resize canvas, so warm at the encode
+ // size rather than the capture size.
+ const hasSize = rawW > 0 && rawH > 0;
+ const capFit = hasSize
+ ? Math.min(1920 / rawW, 1080 / rawH, 1)
+ : 1;
+ const w = hasSize
+ ? Math.max(2, Math.round((rawW * capFit) / 2) * 2)
+ : 0;
+ const h = hasSize
+ ? Math.max(2, Math.round((rawH * capFit) / 2) * 2)
+ : 0;
if (w > 0 && h > 0) {
const { fastRecorderProbe } = await chrome.storage.local.get([
"fastRecorderProbe",
diff --git a/src/pages/CloudRecorder/encoder/WebCodecsTrackRecorder.js b/src/pages/CloudRecorder/encoder/WebCodecsTrackRecorder.js
index c41a9f2..1b72e68 100644
--- a/src/pages/CloudRecorder/encoder/WebCodecsTrackRecorder.js
+++ b/src/pages/CloudRecorder/encoder/WebCodecsTrackRecorder.js
@@ -4,6 +4,7 @@
import { WebCodecsRecorder } from "../../Recorder/webcodecs/WebCodecsRecorder";
import { closeActiveEncoderPrewarm } from "../../Recorder/encoderPrewarm";
+import { isWarmAdoptEnabled } from "../../Recorder/webcodecs/startupFlags";
const dispatchError = (cb, err) => {
if (typeof cb !== "function") return;
@@ -27,6 +28,7 @@ export class WebCodecsTrackRecorder {
this.preferSoftware = Boolean(options.preferSoftware);
// Namespaces the decoderConfig sidecar so dual-track keys don't collide.
this.trackKind = options.trackKind || "default";
+ this.encodeStats = null;
// MediaRecorder-shape fields used by callers.
this._state = "inactive";
this.ondataavailable = null;
@@ -58,6 +60,16 @@ export class WebCodecsTrackRecorder {
return this._recorder?.actualVideoCodec || null;
}
+ // Falls back to the live recorder so a session that never finalized (stall,
+ // zero frames, failed start) still reports its counters.
+ getEncodeStats() {
+ try {
+ return this.encodeStats || this._recorder?.getEncodeStats?.() || null;
+ } catch {
+ return this.encodeStats || null;
+ }
+ }
+
// Diagnostic counters; safe to poll mid-recording and after stop.
// Returns null before the inner recorder is constructed.
getDiagSnapshot() {
@@ -95,7 +107,13 @@ export class WebCodecsTrackRecorder {
}
};
- const handleFinalized = () => {
+ const handleFinalized = (payload) => {
+ // Keep the encoder's own numbers. onFinalized was called for its side
+ // effect and the payload dropped, so every prod session recorded
+ // encodeStats: null.
+ try {
+ this.encodeStats = this._recorder?.getEncodeStats?.() || null;
+ } catch {}
if (this._finalizedResolved) return;
this._finalizedResolved = true;
this._state = "inactive";
@@ -144,7 +162,13 @@ export class WebCodecsTrackRecorder {
} catch {}
};
+ // Screen only: the prewarm is sized and hardware-preferred for screen,
+ // and cloud's camera track is often forced to software anyway.
+ const adoptPrewarm =
+ isWarmAdoptEnabled() && this.trackKind === "screen" && !this.preferSoftware;
+
this._recorder = new WebCodecsRecorder(this.stream, {
+ allowPrewarmAdopt: adoptPrewarm,
onChunk: handleChunk,
onFinalized: handleFinalized,
onError: handleError,
@@ -162,9 +186,15 @@ export class WebCodecsTrackRecorder {
this._state = "recording";
// MediaRecorder.start() is sync to callers; dispatch and route errors
- // via onerror. Release the prewarm HW slot first or VideoToolbox contends.
+ // via onerror. Release the prewarm HW slot first or VideoToolbox
+ // contends, unless this track adopts it. Camera never disposes it: that
+ // would race the screen track's claim.
+ const releasePrewarm = () => {
+ if (adoptPrewarm || this.trackKind !== "screen") return null;
+ return closeActiveEncoderPrewarm().catch(() => {});
+ };
Promise.resolve()
- .then(() => closeActiveEncoderPrewarm().catch(() => {}))
+ .then(releasePrewarm)
.then(() => this._recorder.start())
.catch((err) => handleError(err));
}
diff --git a/src/pages/Recorder/Recorder.jsx b/src/pages/Recorder/Recorder.jsx
index bcf1879..5d8aed1 100644
--- a/src/pages/Recorder/Recorder.jsx
+++ b/src/pages/Recorder/Recorder.jsx
@@ -25,6 +25,7 @@ import {
startEncoderPrewarm,
closeActiveEncoderPrewarm,
} from "./encoderPrewarm";
+import { isWarmAdoptEnabled } from "./webcodecs/startupFlags";
import { getUserMediaWithFallback } from "../utils/mediaDeviceFallback";
import { startAudioStream as acquireMicStream } from "../utils/startAudioStream";
import { shouldAcquireMicAtStart } from "../utils/micAcquisitionPolicy";
@@ -1299,7 +1300,13 @@ const Recorder = () => {
// Fire-and-forget: awaiting leaves a reader gap that macOS reads as
// "no demand" and puts capture to sleep (5s re-spin, frozen first frame).
- endPrewarm({ keepClear: true, keepWriter: true });
+ // keepEncoderWarm: the path into a recording, so the warm encoder has to
+ // survive for the recorder to adopt it. The claim disposes it otherwise.
+ endPrewarm({
+ keepClear: true,
+ keepWriter: true,
+ keepEncoderWarm: isWarmAdoptEnabled(),
+ });
recordingStartTime.current = Date.now();
@@ -1950,12 +1957,15 @@ const Recorder = () => {
audioBitsPerSecond,
});
- // Close prewarm before opening the real encoder; some macOS
- // configs only allow one VTDecoder per process. The OS
- // service stays warm for several seconds after close.
- try {
- await closeActiveEncoderPrewarm();
- } catch {}
+ // With warm-adopt on, the recorder claims (or disposes) the prewarmed
+ // encoder itself, so closing here would throw the warm session away.
+ // Otherwise close first: some macOS configs only allow one VTDecoder
+ // per process.
+ if (!isWarmAdoptEnabled()) {
+ try {
+ await closeActiveEncoderPrewarm();
+ } catch {}
+ }
recorder.current = new WebCodecsRecorder(liveStream.current, {
width,
@@ -2432,6 +2442,9 @@ const Recorder = () => {
try {
if (!recorder.current) {
+ // MediaRecorder never adopts the warm encoder; release the HW
+ // slot rather than leaving it to the unclaimed-prewarm timeout.
+ closeActiveEncoderPrewarm().catch(() => {});
try {
recorder.current = createMediaRecorder(liveStream.current, {
audioBitsPerSecond,
@@ -3039,7 +3052,11 @@ const Recorder = () => {
}
}
- async function endPrewarm({ keepClear = false, keepWriter = false } = {}) {
+ async function endPrewarm({
+ keepClear = false,
+ keepWriter = false,
+ keepEncoderWarm = false,
+ } = {}) {
const ctrl = prewarmRef.current;
prewarmRef.current = null;
if (!keepClear) {
@@ -3058,12 +3075,13 @@ const Recorder = () => {
.catch(() => {});
}
}
- // Tear down the encoder prewarm too; if endPrewarm runs because
- // the user cancelled the start flow, the prewarm encoder would
- // otherwise sit ticking its keep-alive every 800ms.
- try {
- await closeActiveEncoderPrewarm();
- } catch {}
+ // Tear down the encoder prewarm too, so a cancelled start flow doesn't
+ // leave an encoder sitting on a HW slot.
+ if (!keepEncoderWarm) {
+ try {
+ await closeActiveEncoderPrewarm();
+ } catch {}
+ }
await stopPrewarm(ctrl);
}
@@ -4066,13 +4084,37 @@ const Recorder = () => {
beginPrewarm(liveStream.current);
- // Open a synthetic encoder so the OS service is warm by the time
- // the real encoder opens. Closed in preflight; failure no-ops.
+ // Warm a real encoder so the recording starts ramped instead of dropping
+ // its opening frames. Adopted (or disposed) in preflight; failure no-ops.
try {
const vTrack = liveStream.current?.getVideoTracks?.()[0];
const settings = vTrack?.getSettings?.() || {};
- const w = Number(settings.width) || 0;
- const h = Number(settings.height) || 0;
+ const rawW = Number(settings.width) || 0;
+ const rawH = Number(settings.height) || 0;
+ // Capture is oversampled 2x but the encoder runs at the tier, so warm
+ // at the tier. Same fit maths as preflight.
+ let w = rawW;
+ let h = rawH;
+ try {
+ // Only worth paying for when an encoder will actually be adopted:
+ // these are sequential storage IPCs on the start path, which a
+ // throttled background tab can take 11-19s to answer.
+ if (!isWarmAdoptEnabled()) throw new Error("warm-adopt-disabled");
+ const { qualityValue: storedQuality } = await chrome.storage.local.get([
+ "qualityValue",
+ ]);
+ const { isPro, maxQuality } = await getFreeCaptureCaps();
+ const tierQuality = isPro
+ ? storedQuality
+ : clampQualityValue(storedQuality, maxQuality);
+ const { width: tierW, height: tierH } =
+ getResolutionForQuality(tierQuality);
+ if (rawW > 0 && rawH > 0 && tierW > 0 && tierH > 0) {
+ const fit = Math.min(tierW / rawW, tierH / rawH, 1);
+ w = Math.max(2, Math.round((rawW * fit) / 2) * 2);
+ h = Math.max(2, Math.round((rawH * fit) / 2) * 2);
+ }
+ } catch {}
if (w > 0 && h > 0) {
const probeData = await chrome.storage.local.get([
"fastRecorderProbe",
diff --git a/src/pages/Recorder/encoderPrewarm.js b/src/pages/Recorder/encoderPrewarm.js
index af6f96b..870fe78 100644
--- a/src/pages/Recorder/encoderPrewarm.js
+++ b/src/pages/Recorder/encoderPrewarm.js
@@ -3,8 +3,24 @@
// 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;
@@ -39,10 +55,18 @@ const synthesizeAndEncode = (encoder, canvas, ctx, index, framerate, keyFrame) =
}
};
+const queueSizeOf = (encoder) => {
+ try {
+ return encoder?.encodeQueueSize ?? 0;
+ } catch {
+ return 0;
+ }
+};
+
/**
- * Start a prewarm encoder that opens, encodes a few frames, and
- * stays open. Returns a handle with .close(). Idempotent: a second
- * call while one is active returns the active handle.
+ * 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
@@ -50,7 +74,7 @@ const synthesizeAndEncode = (encoder, canvas, ctx, index, framerate, keyFrame) =
* @param {string} cfg.codec e.g. "avc1.64002A"
* @param {number} [cfg.bitrate]
* @param {number} [cfg.framerate]
- * @returns {Promise<{close: () => Promise<void>, ms: number, chunks: number, ok: boolean}>}
+ * @returns {Promise<{close: () => Promise<void>, chunks: number, ok: boolean, warm: boolean}|null>}
*/
export const startEncoderPrewarm = async (cfg) => {
if (_activeWarmer) return _activeWarmer.handle;
@@ -75,51 +99,90 @@ export const startEncoderPrewarm = async (cfg) => {
canvas: null,
ctx: null,
closed: false,
+ claimed: false,
+ warm: false,
+ config: null,
framerate: computeFramerate(cfg),
- keepAliveTimer: null,
- keepAliveIndex: 0,
+ 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. */
+ /** Close the prewarm encoder. Safe to call multiple times. No-op once claimed. */
close: async () => {
- if (state.closed) return;
+ if (state.closed || state.claimed) return;
state.closed = true;
- if (state.keepAliveTimer) {
- clearInterval(state.keepAliveTimer);
- state.keepAliveTimer = null;
+ if (state.unclaimedTimer) {
+ clearTimeout(state.unclaimedTimer);
+ state.unclaimedTimer = null;
}
if (state.encoder) {
try {
- // No flush; the goal was OS-side warmup, not the chunks.
state.encoder.close();
} catch {}
+ state.encoder = null;
}
- _activeWarmer = 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: () => {
+ output: (chunk, meta) => {
state.chunks += 1;
+ if (!state.warmDecoderConfig && meta?.decoderConfig) {
+ state.warmDecoderConfig = meta.decoderConfig;
+ }
+ state.sink?.(chunk, meta);
},
error: (err) => {
+ if (state.errorSink) {
+ state.errorSink(err);
+ return;
+ }
perfMark("Recorder.encoderPrewarm.encoderError", {
msg: String(err?.message || err).slice(0, 120),
});
},
});
- state.encoder.configure({
+ const config = {
codec: cfg.codec,
width: cfg.width,
height: cfg.height,
@@ -128,40 +191,109 @@ export const startEncoderPrewarm = async (cfg) => {
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");
}
- // Burst 6 frames (1 keyframe + 5 deltas) then close. No
- // keep-alive ticker: an 800ms timer on the background tab
- // triggers Chrome's intensive throttling, which makes storage
- // IPCs take 11-19s and wedges start. OS encode service stays
- // warm for a few seconds, covers most countdown windows.
- const BURST_COUNT = 6;
- for (let i = 0; i < BURST_COUNT; i++) {
- if (state.closed) return handle;
- synthesizeAndEncode(state.encoder, state.canvas, state.ctx, i, state.framerate, i === 0);
+ // 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,
+ );
+ }
+ try {
+ state.encoder.flush().catch(() => {});
+ } catch {}
+ await handle.close();
+ endStart({ chunks: state.chunks, ok: state.chunks > 0, mode: "burst" });
+ return handle;
}
- // Flush + close fire-and-forget so the caller isn't blocked.
- try {
- state.encoder.flush().catch(() => {});
- } catch {}
+
+ // 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 {
- state.encoder.close();
+ await state.encoder.flush();
} catch {}
- state.encoder = null;
- state.closed = true;
- _activeWarmer = null;
+ if (state.closed || state.claimed) return handle;
+
+ state.warm =
+ state.chunks >= PREWARM_MIN_WARM_CHUNKS &&
+ state.encoder?.state === "configured" &&
+ queueSizeOf(state.encoder) === 0;
- endStart({ chunks: state.chunks, ok: true });
- perfMark("Recorder.encoderPrewarm.closed", { chunks: state.chunks });
+ 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) });
@@ -174,13 +306,105 @@ export const startEncoderPrewarm = async (cfg) => {
} catch {}
state.encoder = null;
}
- _activeWarmer = 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;
diff --git a/src/pages/Recorder/webcodecs/WebCodecsRecorder.js b/src/pages/Recorder/webcodecs/WebCodecsRecorder.js
index fc9fb34..1c36689 100644
--- a/src/pages/Recorder/webcodecs/WebCodecsRecorder.js
+++ b/src/pages/Recorder/webcodecs/WebCodecsRecorder.js
@@ -17,13 +17,23 @@ import {
AVC_MAX_PIXELS,
VIDEO_DIM_HARD_CAP,
computeAvcCappedDimensions,
+ computeEffectiveQueueCap,
+ computeStartupQueueCap,
+ computeSteadyQueueCap,
isAacRateInSpec,
isReclaimErrorMessage,
shouldFailZeroChunksAtStop,
shouldResetReclaimCounter,
shouldThrottleReclaimRebuild,
shouldTriggerSleepRecovery,
+ STARTUP_CAUGHT_UP_QUEUE,
+ STARTUP_CAUGHT_UP_RUN,
+ STARTUP_HARD_FRAME_LIMIT,
+ STARTUP_HARD_MS,
+ STARTUP_QUEUE_CAP,
} from "./recorderLogic";
+import { getStartupFlags } from "./startupFlags";
+import { claimPrewarmedEncoder } from "../encoderPrewarm";
// Lazy-load Mp4MuxerWrapper so its ~3MB mediabunny static import doesn't
// drag into recorder.bundle.js cold start (dominates click-record latency).
let _mp4MuxerWrapperPromise = null;
@@ -167,9 +177,56 @@ export class WebCodecsRecorder {
// Backpressure: feeding faster than the encoder drains grows the
// queue unbounded and chunks stop emitting (28-byte failure).
// Past threshold, drop the next frame and force a keyframe.
+ //
+ // 16, not 4: a ~170ms hiccup walks the queue 0->4 in ~5 frames and the
+ // drop lands before encode(), costing 2-4 frames mid-recording. 12 still
+ // dropped occasionally; 24 was no better and twice the memory.
+ // start() lowers it per-resolution: ~130MB at 1080p, ~530MB at 4K.
+ this._encoderMaxQueueSizeExplicit =
+ Number.isFinite(options.encoderMaxQueueSize) ||
+ Number.isFinite(
+ /** @type {any} */ (globalThis).__screenityEncoderMaxQueueSizeForTests,
+ );
this._encoderMaxQueueSize = Number.isFinite(options.encoderMaxQueueSize)
? options.encoderMaxQueueSize
- : 4;
+ : Number.isFinite(
+ /** @type {any} */ (globalThis)
+ .__screenityEncoderMaxQueueSizeForTests,
+ )
+ ? /** @type {any} */ (globalThis)
+ .__screenityEncoderMaxQueueSizeForTests
+ : 16;
+ // Cold-start grace: a fresh HW encoder spikes the queue for under a second
+ // while its session comes up. Buffer that, then latch back to the steady cap.
+ this._startupMaxQueueSize = Number.isFinite(options.startupMaxQueueSize)
+ ? options.startupMaxQueueSize
+ : STARTUP_QUEUE_CAP;
+ this._startupWindowClosed = false;
+ this._startupCaughtUpRun = 0;
+ this._startupFirstFrameAt = null;
+ this._startupFramesSeen = 0;
+ this._startupBufferEngaged = false;
+ this._framesBufferedAtStart = 0;
+ // How long the elastic cap stays available. Overridable without a rebuild,
+ // same pattern as the watchdog test knobs above.
+ this._startupHardMs = Number.isFinite(options.startupHardMs)
+ ? options.startupHardMs
+ : Number.isFinite(
+ /** @type {any} */ (globalThis).__screenityStartupWindowMsForTests,
+ )
+ ? /** @type {any} */ (globalThis).__screenityStartupWindowMsForTests
+ : STARTUP_HARD_MS;
+ this._startupHardFrameLimit = Number.isFinite(options.startupHardFrameLimit)
+ ? options.startupHardFrameLimit
+ : Number.isFinite(
+ /** @type {any} */ (globalThis)
+ .__screenityStartupWindowFramesForTests,
+ )
+ ? /** @type {any} */ (globalThis)
+ .__screenityStartupWindowFramesForTests
+ : STARTUP_HARD_FRAME_LIMIT;
+ this._adoptedPrewarmEncoder = false;
+ this._adoptedDecoderConfig = null;
this._forceNextKeyframe = false;
this._droppedForBackpressureCount = 0;
// Audio: same pattern, deeper queue. Frames are smaller / more
@@ -281,6 +338,9 @@ export class WebCodecsRecorder {
// Black placeholder frames synthesized before the first real frame to
// bridge macOS static-screen first-frame starvation (see readVideoLoop).
this._syntheticFirstFrameCount = 0;
+ // In-flight reads, hoisted so a fallback timeout cannot orphan them.
+ this._pendingVideoRead = null;
+ this._pendingAudioRead = null;
this._firstChunkAt = null;
this._encoderConstructCount = 0;
this._videoEncoderStateAtStop = null;
@@ -368,6 +428,19 @@ export class WebCodecsRecorder {
this._lastChunkAt = null;
this._lastFailureCode = null;
this._forceNextKeyframe = false;
+ this._startupWindowClosed = false;
+ this._startupCaughtUpRun = 0;
+ this._startupFirstFrameAt = null;
+ this._startupFramesSeen = 0;
+ this._startupBufferEngaged = false;
+ this._framesBufferedAtStart = 0;
+ this._adoptedPrewarmEncoder = false;
+ this._adoptedDecoderConfig = null;
+ // A read hoisted by the previous recording is bound to a cancelled reader:
+ // left set, the next readVideoLoop resolves {done:true} on its first
+ // iteration and records nothing.
+ this._pendingVideoRead = null;
+ this._pendingAudioRead = null;
this._droppedForBackpressureCount = 0;
this._droppedAudioForBackpressureCount = 0;
this._peakVideoEncodeQueueSize = 0;
@@ -472,6 +545,23 @@ export class WebCodecsRecorder {
this.log("[WCR] Target:", this.targetWidth, "x", this.targetHeight);
+ // Now that dims are known, bound the steady cap by bytes: 16 frames is
+ // ~130MB at 1080p but ~530MB at 4K, and this one never reverts. 1080p
+ // keeps the measured 16, 4K falls back toward the historical 4.
+ if (!this._encoderMaxQueueSizeExplicit) {
+ this._encoderMaxQueueSize = computeSteadyQueueCap({
+ width: this.targetWidth,
+ height: this.targetHeight,
+ });
+ }
+ if (!Number.isFinite(this.options.startupMaxQueueSize)) {
+ this._startupMaxQueueSize = computeStartupQueueCap({
+ width: this.targetWidth,
+ height: this.targetHeight,
+ steadyCap: this._encoderMaxQueueSize,
+ });
+ }
+
const fps = this.options.fps || 30;
this._frameDurationUs = Math.round(1_000_000 / fps);
this._keyFrameIntervalFrames = Math.max(30, Math.round(fps * 2));
@@ -949,6 +1039,9 @@ export class WebCodecsRecorder {
firstChunkSeen: this._firstChunkSeen,
framesFromMSTP: this._framesFromMSTP,
syntheticFirstFrameCount: this._syntheticFirstFrameCount,
+ // Last-frame repeats from the static-frame fallback. High here against
+ // a near-zero framesFromMSTP means a frozen recording.
+ staticFrameSyntheticCount: this._staticFrameSyntheticCount,
muxerBytes: muxerStats?.totalEmittedBytes ?? null,
muxerEmits: muxerStats?.emitCount ?? null,
muxerFinalizeOk,
@@ -980,6 +1073,11 @@ export class WebCodecsRecorder {
video: this._peakVideoEncodeQueueSize,
audio: this._peakAudioEncodeQueueSize,
},
+ startupBuffer: {
+ engaged: this._startupBufferEngaged,
+ framesBuffered: this._framesBufferedAtStart,
+ adoptedWarmEncoder: this._adoptedPrewarmEncoder === true,
+ },
flushMs: {
video: this._videoFlushMs ?? null,
audio: this._audioFlushMs ?? null,
@@ -1042,8 +1140,29 @@ export class WebCodecsRecorder {
this._stopping = false;
}
- // Read-only snapshot of the diagnostic counters and encoder choice.
- // Safe to call mid-recording and at stop; never throws.
+ // Readable at any time: stop() early-returns once the recorder isn't
+ // running, so onFinalized is missing on exactly the sessions worth
+ // explaining (zero-frame exit, spent stall budget, failed start).
+ getEncodeStats() {
+ return {
+ peakEncodeQueueVideo: this._peakVideoEncodeQueueSize ?? null,
+ peakEncodeQueueAudio: this._peakAudioEncodeQueueSize ?? null,
+ droppedForBackpressureVideo: this._droppedForBackpressureCount ?? null,
+ droppedForBackpressureAudio:
+ this._droppedAudioForBackpressureCount ?? null,
+ // Submissions to encode(), not muxer output (that's chunksOut).
+ framesEncoded: this.frameCount ?? null,
+ chunksOut: this._chunksOut ?? null,
+ steadyQueueCap: this._encoderMaxQueueSize ?? null,
+ // Drops inside the startup window were judged against this, not the
+ // steady cap; without it droppedForBackpressureVideo can't be read.
+ startupQueueCap: this._startupMaxQueueSize ?? null,
+ startupBufferEngaged: this._startupBufferEngaged ?? null,
+ framesBufferedAtStart: this._framesBufferedAtStart ?? null,
+ adoptedWarmEncoder: this._adoptedPrewarmEncoder === true,
+ };
+ }
+
getDiagSnapshot() {
let firstChunkLatencyMs = null;
if (this._firstChunkAt != null && this._videoStartUs != null) {
@@ -1093,6 +1212,23 @@ export class WebCodecsRecorder {
this.paused = true;
this.pauseStartUs = performance.now() * 1000;
+ // Drop in-flight reads: the loop short-circuits while paused, so one
+ // pending from before would deliver a stale frame on resume.
+ const staleVideoRead = this._pendingVideoRead;
+ const staleAudioRead = this._pendingAudioRead;
+ this._pendingVideoRead = null;
+ this._pendingAudioRead = null;
+ for (const stale of [staleVideoRead, staleAudioRead]) {
+ if (!stale) continue;
+ stale
+ .then((r) => {
+ try {
+ r?.value?.close?.();
+ } catch {}
+ })
+ .catch(() => {});
+ }
+
// Release the HW slot up front so long pauses don't burn the
// reclaim cap. Chrome reclaims at ~60s, w3c/webcodecs#363.
this._encodersClosedForPause = true;
@@ -1124,6 +1260,16 @@ export class WebCodecsRecorder {
}
// Force a keyframe so the decoder doesn't reference pre-pause frames.
this._forceNextKeyframe = true;
+ // The rebuilt encoder is cold and ramps like it did at start, so reopen
+ // the grace window. Floored on pause length: without it, a user tapping
+ // pause/resume holds the startup cap (and its memory) all session.
+ const pausedMs = (nowUs - this.pauseStartUs) / 1000;
+ if (pausedMs >= 1000) {
+ this._startupWindowClosed = false;
+ this._startupCaughtUpRun = 0;
+ this._startupFirstFrameAt = null;
+ this._startupFramesSeen = 0;
+ }
}
this.paused = false;
@@ -1159,6 +1305,27 @@ export class WebCodecsRecorder {
cancelWithTimeout(this.audioReader),
]);
+ // cancel() settles any hoisted read; close the frame it yields so the last
+ // one isn't leaked.
+ const drainPendingRead = async (pending) => {
+ if (!pending) return;
+ try {
+ const r = await Promise.race([
+ pending,
+ new Promise((resolve) => setTimeout(() => resolve(null), 500)),
+ ]);
+ try {
+ r?.value?.close?.();
+ } catch {}
+ } catch {}
+ };
+ await Promise.all([
+ drainPendingRead(this._pendingVideoRead),
+ drainPendingRead(this._pendingAudioRead),
+ ]);
+ this._pendingVideoRead = null;
+ this._pendingAudioRead = null;
+
try {
this.videoEncoder?.close();
} catch {}
@@ -1243,6 +1410,11 @@ export class WebCodecsRecorder {
video: this._peakVideoEncodeQueueSize,
audio: this._peakAudioEncodeQueueSize,
},
+ startupBuffer: {
+ engaged: this._startupBufferEngaged,
+ framesBuffered: this._framesBufferedAtStart,
+ adoptedWarmEncoder: this._adoptedPrewarmEncoder === true,
+ },
flushMs: {
video: this._videoFlushMs ?? null,
audio: this._audioFlushMs ?? null,
@@ -1556,6 +1728,13 @@ export class WebCodecsRecorder {
// Extract output/error callbacks so the prefer-software retry below
// can rebuild the VideoEncoder with the same handlers.
const videoEncoderOutput = (chunk, meta) => {
+ // An adopted encoder already emitted its decoderConfig to the prewarm's
+ // discard sink, and Chrome only re-emits when the reported config
+ // changes. Without a replay of the one captured at warmup the muxer
+ // throws ("must include a decoder configuration") on a header-only file.
+ if (!meta?.decoderConfig && this._adoptedDecoderConfig) {
+ meta = { ...(meta || {}), decoderConfig: this._adoptedDecoderConfig };
+ }
// E2E hook: drop the first N chunks to drive the no-first-chunk
// watchdog in tests.
const _g = /** @type {any} */ (globalThis);
@@ -1723,6 +1902,49 @@ export class WebCodecsRecorder {
: [],
});
}
+ // Adopt-or-create: a prewarmed encoder has already paid the session ramp
+ // that costs the opening frames, so take it over instead of opening a cold
+ // one. A claim that can't hand it over disposes it, freeing the HW slot.
+ let adopted = null;
+ try {
+ // Adoption skips the configure() path below, so tests forcing a
+ // configure failure there need a fresh encoder.
+ const gHooks = /** @type {any} */ (globalThis);
+ const forcedConfigureTest =
+ gHooks.__screenityForceConfigureHwQuotaError === true ||
+ gHooks.__screenityForceConfigureSwQuotaError === true;
+ // Guarded like _rebuildVideoEncoder's replacement: once this encoder
+ // isn't the active one (rebuild, pause, stop) its late errors must not
+ // burn the reclaim budget or fail a healthy recording.
+ const adoptedErrorHandler = (err) => {
+ if (this.videoEncoder !== adopted?.encoder) return;
+ videoEncoderError(err);
+ };
+ adopted = claimPrewarmedEncoder(config, videoEncoderOutput, adoptedErrorHandler, {
+ allowAdopt: this.options.allowPrewarmAdopt !== false && !forcedConfigureTest,
+ preferSoftware: this.options.preferSoftware === true,
+ });
+ } catch (adoptErr) {
+ this.warn("[WCR] prewarm adopt threw; using a fresh encoder", adoptErr);
+ adopted = null;
+ }
+ if (adopted?.encoder) {
+ this.videoEncoder = adopted.encoder;
+ this._adoptedPrewarmEncoder = true;
+ this._adoptedDecoderConfig = adopted.decoderConfigFallback || null;
+ this._activeVideoConfig = config;
+ // configure() always runs at adoption; the flag says whether the config
+ // differed, not whether a reconfigure happened.
+ this.log("[WCR] adopted prewarmed VideoEncoder", {
+ configChanged: adopted.reconfigured,
+ codec: codecLabel,
+ });
+ perfMark("WCR.videoEncoder.adopted", {
+ configChanged: adopted.reconfigured,
+ });
+ return;
+ }
+
this.videoEncoder = new VideoEncoder({
output: videoEncoderOutput,
error: videoEncoderError,
@@ -2511,17 +2733,25 @@ export class WebCodecsRecorder {
// emitting and the stall watchdog would misfire. Reuse the
// last canvas on timeout to keep chunks flowing.
const STATIC_FRAME_FALLBACK_MS = 1500;
- const readResult = await Promise.race([
- this.videoReader
+ // Hoisted, not re-issued per iteration. A read that loses the race
+ // isn't cancelled: it stays queued and later eats a frame nobody
+ // encodes or closes, so on a static screen every timeout costs the
+ // next real frame.
+ if (!this._pendingVideoRead) {
+ this._pendingVideoRead = this.videoReader
.read()
.then((v) => ({ ...v, isSyntheticTimeout: false }))
.catch(() => ({
done: true,
value: null,
isSyntheticTimeout: false,
- })),
- new Promise((resolve) =>
- setTimeout(
+ }));
+ }
+ let fallbackTimer = null;
+ const readResult = await Promise.race([
+ this._pendingVideoRead,
+ new Promise((resolve) => {
+ fallbackTimer = setTimeout(
() =>
resolve({
done: false,
@@ -2529,9 +2759,14 @@ export class WebCodecsRecorder {
isSyntheticTimeout: true,
}),
STATIC_FRAME_FALLBACK_MS,
- ),
- ),
+ );
+ }),
]);
+ if (!readResult.isSyntheticTimeout) {
+ // Consumed: clear before any early continue below.
+ this._pendingVideoRead = null;
+ if (fallbackTimer) clearTimeout(fallbackTimer);
+ }
let isSynthetic = false;
let frame = null;
@@ -2640,10 +2875,49 @@ export class WebCodecsRecorder {
this._peakVideoEncodeQueueSize = vQueueSize;
}
+ // Startup grace window: while the encoder ramps, buffer instead of
+ // dropping. Frames carry wall-clock PTS, so they encode late but the
+ // file stays complete. Latches to the steady cap once it closes.
+ let effectiveQueueCap = this._encoderMaxQueueSize;
+ if (!this._startupWindowClosed) {
+ if (this._startupFirstFrameAt === null) {
+ this._startupFirstFrameAt = performance.now();
+ }
+ this._startupFramesSeen += 1;
+ if (vQueueSize <= STARTUP_CAUGHT_UP_QUEUE) {
+ this._startupCaughtUpRun += 1;
+ } else {
+ this._startupCaughtUpRun = 0;
+ }
+ effectiveQueueCap = computeEffectiveQueueCap({
+ framesSinceStart: this._startupFramesSeen,
+ elapsedMs: performance.now() - this._startupFirstFrameAt,
+ caughtUp: this._startupCaughtUpRun >= STARTUP_CAUGHT_UP_RUN,
+ steadyCap: this._encoderMaxQueueSize,
+ startupCap: this._startupMaxQueueSize,
+ hardFrameLimit: this._startupHardFrameLimit,
+ hardMs: this._startupHardMs,
+ disabled: getStartupFlags().startupBufferDisabled,
+ });
+ if (effectiveQueueCap <= this._encoderMaxQueueSize) {
+ this._startupWindowClosed = true;
+ effectiveQueueCap = this._encoderMaxQueueSize;
+ } else if (
+ vQueueSize > this._encoderMaxQueueSize &&
+ vQueueSize <= effectiveQueueCap
+ ) {
+ // Counts only frames the wider cap actually saves (above the
+ // steady cap, still inside the grace cap). Counting ones that
+ // drop anyway would overstate the fix in telemetry.
+ this._startupBufferEngaged = true;
+ this._framesBufferedAtStart += 1;
+ }
+ }
+
// Backpressure: drop the frame and force a keyframe next so
// the stream stays decodable. An unbounded queue can stop
// emitting chunks entirely.
- if (vQueueSize > this._encoderMaxQueueSize) {
+ if (vQueueSize > effectiveQueueCap) {
this._droppedForBackpressureCount += 1;
this._forceNextKeyframe = true;
this._videoFrameIndex = i + 1;
@@ -2706,8 +2980,10 @@ export class WebCodecsRecorder {
// the reclaim case to a rebuild, not a drop into a dead encoder.
if (encErr?.name === "QuotaExceededError") {
const q = this.videoEncoder?.encodeQueueSize ?? 0;
- // Well below the ~30 backpressure cap.
- if (q <= 5) {
+ // A near-empty queue only meant reclaim while the cap was 4;
+ // at 16 a real reclaim looks like backpressure and silently
+ // skips the rebuild. Chrome names reclaims in the message.
+ if (isReclaimErrorMessage(encErr) || q <= 5) {
this._videoFrameIndex = i + 1;
this._forceNextKeyframe = true;
this.warn(
@@ -2973,18 +3249,28 @@ export class WebCodecsRecorder {
try {
while (this.running) {
- const readResult = await Promise.race([
- this.audioReader
+ // Hoisted for the same reason as the video read: a losing read
+ // isn't cancelled and would eat the next packet.
+ if (!this._pendingAudioRead) {
+ this._pendingAudioRead = this.audioReader
.read()
.then((v) => ({ ...v, timedOut: false }))
- .catch(() => ({ done: true, timedOut: false })),
- new Promise((r) =>
- setTimeout(
+ .catch(() => ({ done: true, timedOut: false }));
+ }
+ let audioFallbackTimer = null;
+ const readResult = await Promise.race([
+ this._pendingAudioRead,
+ new Promise((r) => {
+ audioFallbackTimer = setTimeout(
() => r({ value: null, done: false, timedOut: true }),
SILENCE_TIMEOUT_MS,
- ),
- ),
+ );
+ }),
]);
+ if (!readResult.timedOut) {
+ this._pendingAudioRead = null;
+ if (audioFallbackTimer) clearTimeout(audioFallbackTimer);
+ }
if (readResult.timedOut) {
const trackEnded =
diff --git a/src/pages/Recorder/webcodecs/recorderLogic.js b/src/pages/Recorder/webcodecs/recorderLogic.js
index a67a3f3..d698220 100644
--- a/src/pages/Recorder/webcodecs/recorderLogic.js
+++ b/src/pages/Recorder/webcodecs/recorderLogic.js
@@ -84,6 +84,178 @@ export function computeAvcCappedDimensions({
return { width, height, capped: { perDim: perDimCapped, area: areaCapped } };
}
+// Backpressure ate ~67% of the opening frames at 1080p while a cold encoder
+// ramped. Buffered frames keep wall-clock PTS, so they encode late but land.
+export const STARTUP_QUEUE_CAP = 60;
+// Whichever hits first ends the grace window.
+export const STARTUP_HARD_FRAME_LIMIT = 90;
+export const STARTUP_HARD_MS = 3000;
+// Drained depth, and how many frames must hold there to count as caught up.
+export const STARTUP_CAUGHT_UP_QUEUE = 2;
+export const STARTUP_CAUGHT_UP_RUN = 10;
+
+// 4, not NV12's 1.5: canvas-backed frames stay RGBA until the encoder converts
+// them, so NV12 undercounts the queue by ~2.7x.
+export const FRAME_BYTES_PER_PIXEL = 4;
+
+// The startup window is transient (~1s) so it can borrow more; the steady
+// depth is held all recording, and 16 frames at 4K would cost ~530MB.
+export const STARTUP_QUEUE_BYTE_BUDGET = 384 * 1024 * 1024;
+export const STEADY_QUEUE_BYTE_BUDGET = 160 * 1024 * 1024;
+export const STEADY_QUEUE_CAP = 16;
+export const STEADY_QUEUE_MIN = 4;
+
+export function computeStartupQueueCap({
+ width,
+ height,
+ maxFrames = STARTUP_QUEUE_CAP,
+ byteBudget = STARTUP_QUEUE_BYTE_BUDGET,
+ steadyCap = 4,
+} = {}) {
+ if (
+ !Number.isFinite(width) ||
+ !Number.isFinite(height) ||
+ width <= 0 ||
+ height <= 0
+ ) {
+ return maxFrames;
+ }
+ const frameBytes = width * height * FRAME_BYTES_PER_PIXEL;
+ const byFrames = Math.floor(byteBudget / frameBytes);
+ return Math.max(steadyCap, Math.min(maxFrames, byFrames));
+}
+
+// Steady-state backpressure cap, bounded by the same byte budget. Unlike the
+// startup window this depth is a sustained memory cost, not a transient one.
+export function computeSteadyQueueCap({
+ width,
+ height,
+ maxFrames = STEADY_QUEUE_CAP,
+ byteBudget = STEADY_QUEUE_BYTE_BUDGET,
+ minFrames = STEADY_QUEUE_MIN,
+} = {}) {
+ if (
+ !Number.isFinite(width) ||
+ !Number.isFinite(height) ||
+ width <= 0 ||
+ height <= 0
+ ) {
+ return maxFrames;
+ }
+ const frameBytes = width * height * FRAME_BYTES_PER_PIXEL;
+ const byFrames = Math.floor(byteBudget / frameBytes);
+ return Math.max(minFrames, Math.min(maxFrames, byFrames));
+}
+
+// Cap for the frame about to be encoded. Returns the steady cap once the
+// encoder catches up or the window expires; the caller latches that answer
+// so the window never reopens.
+export function computeEffectiveQueueCap({
+ framesSinceStart = 0,
+ elapsedMs = 0,
+ caughtUp = false,
+ steadyCap = 4,
+ startupCap = STARTUP_QUEUE_CAP,
+ hardFrameLimit = STARTUP_HARD_FRAME_LIMIT,
+ hardMs = STARTUP_HARD_MS,
+ disabled = false,
+} = {}) {
+ const steady = Number.isFinite(steadyCap) ? steadyCap : 4;
+ if (disabled) return steady;
+ if (caughtUp) return steady;
+ if (Number.isFinite(hardFrameLimit) && framesSinceStart > hardFrameLimit) {
+ return steady;
+ }
+ if (Number.isFinite(hardMs) && elapsedMs > hardMs) return steady;
+ const startup = Number.isFinite(startupCap) ? startupCap : steady;
+ return Math.max(steady, startup);
+}
+
+// Early-exit bar for the warm loop, bounded by frames/ms so a stuck warm
+// gives up. The bar for counting as warm is PREWARM_MIN_WARM_CHUNKS.
+export const PREWARM_READY_CHUNKS = 30;
+export const PREWARM_MAX_FRAMES = 150;
+export const PREWARM_MAX_MS = 4000;
+// 1, not a real count: a slow cold encoder emits only a handful in the warm
+// window and is still warm (measured: 4 chunks, then 0 drops at queue 0).
+export const PREWARM_MIN_WARM_CHUNKS = 1;
+// An unclaimed warm encoder holds a HW slot. If nothing adopts it in this
+// window the recording took another path; close it.
+export const PREWARM_UNCLAIMED_MAX_MS = 20000;
+
+// Warm-until-ready predicate: enough chunks out AND the queue drained, or a
+// bound was hit (ready=false, done=true means give up and stop feeding).
+export function evaluatePrewarmProgress({
+ chunksOut = 0,
+ queueSize = 0,
+ framesFed = 0,
+ elapsedMs = 0,
+ minChunks = PREWARM_READY_CHUNKS,
+ maxFrames = PREWARM_MAX_FRAMES,
+ maxMs = PREWARM_MAX_MS,
+} = {}) {
+ if (chunksOut >= minChunks && queueSize === 0) {
+ return { ready: true, done: true, reason: "warm" };
+ }
+ if (framesFed >= maxFrames) {
+ return { ready: false, done: true, reason: "frame-limit" };
+ }
+ if (elapsedMs >= maxMs) {
+ return { ready: false, done: true, reason: "time-limit" };
+ }
+ return { ready: false, done: false, reason: "feeding" };
+}
+
+// The warm encoder was configured at the ceiling; the recording may run at
+// smaller dims. Reconfiguring a drained encoder is free but pointless when
+// nothing the session cares about differs.
+export function shouldReconfigureAdoptedEncoder(warmConfig, finalConfig) {
+ if (!warmConfig || !finalConfig) return true;
+ const keys = [
+ "codec",
+ "width",
+ "height",
+ "bitrate",
+ "framerate",
+ "bitrateMode",
+ "latencyMode",
+ "hardwareAcceleration",
+ ];
+ return keys.some((k) => {
+ const a = warmConfig[k];
+ const b = finalConfig[k];
+ if (a === undefined && b === undefined) return false;
+ return a !== b;
+ });
+}
+
+// Only what the SPS describes invalidates the captured decoderConfig: codec
+// and coded dims. Bitrate/framerate/latencyMode don't, and nulling the replay
+// for those loses the header-only-file safety net for no reason.
+export function shouldInvalidateDecoderConfig(warmConfig, finalConfig) {
+ if (!warmConfig || !finalConfig) return true;
+ return ["codec", "width", "height"].some(
+ (k) => warmConfig[k] !== finalConfig[k],
+ );
+}
+
+// Adoption gate. The warm encoder is hardware-preferred, so a session that
+// asked for software must build its own.
+export function canAdoptPrewarmedEncoder({
+ hasWarmer = false,
+ warm = false,
+ claimed = false,
+ closed = false,
+ encoderState = null,
+ disabled = false,
+ allowAdopt = true,
+ preferSoftware = false,
+} = {}) {
+ if (disabled || !allowAdopt || preferSoftware) return false;
+ if (!hasWarmer || !warm || claimed || closed) return false;
+ return encoderState === "configured";
+}
+
// Skip a rebuild if the last one was within the throttle window;
// otherwise encoder.error fires per frame and burns the cap in ms.
export function shouldThrottleReclaimRebuild(
diff --git a/src/pages/Recorder/webcodecs/startupFlags.js b/src/pages/Recorder/webcodecs/startupFlags.js
new file mode 100644
index 0000000..adcd699
--- /dev/null
+++ b/src/pages/Recorder/webcodecs/startupFlags.js
@@ -0,0 +1,60 @@
+// Startup frame-loss flags, read from chrome.storage.local once at import.
+// Nothing writes them and there's no UI or remote config, so they're
+// per-machine DevTools switches; changing what users get needs a release.
+//
+// Only startEncoderPrewarm waits on the read (250ms cap): a throttled tab can
+// take 11-19s to answer a storage IPC. Defaults apply until it lands.
+
+const FLAG_KEYS = [
+ "webcodecsStartupBufferDisabled",
+ "webcodecsWarmAdoptEnabled",
+ "webcodecsEncoderPrewarmDisabled",
+];
+
+const _flags = {
+ startupBufferDisabled: false,
+ // Opt-IN: adoption holds a second VideoEncoder across the codec-selection
+ // ladder, so on a machine at its encoder-session cap (Windows/NVENC with
+ // Zoom or OBS) the prefer-hardware probe can fail against our own warm one.
+ warmAdoptEnabled: false,
+ // Disabling adoption alone still runs the warm-up, which warms the OS encode
+ // service; this is the only way to get a genuinely cold encoder.
+ encoderPrewarmDisabled: false,
+};
+let _loading = null;
+
+export const loadStartupFlags = () => {
+ if (_loading) return _loading;
+ _loading = (async () => {
+ try {
+ const stored = await chrome.storage.local.get(FLAG_KEYS);
+ _flags.startupBufferDisabled =
+ stored?.webcodecsStartupBufferDisabled === true;
+ _flags.warmAdoptEnabled = stored?.webcodecsWarmAdoptEnabled === true;
+ _flags.encoderPrewarmDisabled =
+ stored?.webcodecsEncoderPrewarmDisabled === true;
+ } catch {}
+ return _flags;
+ })();
+ return _loading;
+};
+
+export const getStartupFlags = () => _flags;
+
+export const isStartupBufferEnabled = () => !_flags.startupBufferDisabled;
+
+export const isWarmAdoptEnabled = () => _flags.warmAdoptEnabled === true;
+
+export const isEncoderPrewarmEnabled = () => !_flags.encoderPrewarmDisabled;
+
+// Escape hatch for a test that cannot seed chrome.storage. The e2e specs do
+// seed storage directly, so nothing uses this today.
+export const __setStartupFlagsForTests = (next) => {
+ Object.assign(_flags, next);
+};
+
+try {
+ if (typeof chrome !== "undefined" && chrome?.storage?.local) {
+ void loadStartupFlags();
+ }
+} catch {}
diff --git a/src/pages/Region/Recorder.jsx b/src/pages/Region/Recorder.jsx
index c4de404..f644857 100644
--- a/src/pages/Region/Recorder.jsx
+++ b/src/pages/Region/Recorder.jsx
@@ -15,6 +15,11 @@ import {
preloadWebCodecsModules,
} from "../Recorder/webcodecs/WebCodecsRecorder";
import { startPrewarm, stopPrewarm } from "../Recorder/streamWarmup";
+import {
+ startEncoderPrewarm,
+ closeActiveEncoderPrewarm,
+} from "../Recorder/encoderPrewarm";
+import { isWarmAdoptEnabled } from "../Recorder/webcodecs/startupFlags";
import {
debugRecordingEvent,
resetRecordingDebugSession,
@@ -1440,6 +1445,10 @@ const Recorder = () => {
recdbgTotalBytes = 0;
mediaRecorderStartAt = Date.now();
+ // MediaRecorder never adopts the warm encoder; release the HW slot
+ // rather than leaving it to the unclaimed-prewarm timeout.
+ closeActiveEncoderPrewarm().catch(() => {});
+
recorder.current = new MediaRecorder(liveStream.current, {
mimeType: mimeType,
audioBitsPerSecond: audioBitsPerSecond,
@@ -2418,6 +2427,35 @@ const Recorder = () => {
const endCropTo = perfSpan("Region.Recorder cropTo");
await track.cropTo(target.current);
endCropTo();
+
+ // Warm a real encoder for the recorder to adopt; cropTo is the only
+ // dead time region gets. Gated on adoption unlike the other call
+ // sites: region has no countdown, so its start path is the most
+ // latency-sensitive and this block costs a storage read.
+ try {
+ if (!isWarmAdoptEnabled()) throw new Error("warm-adopt-disabled");
+ const cropSettings = track.getSettings?.() || {};
+ const rawW = Number(cropSettings.width) || width || 0;
+ const rawH = Number(cropSettings.height) || height || 0;
+ if (rawW > 0 && rawH > 0) {
+ // Same tier fit the recorder encodes at.
+ const fit = Math.min(width / rawW, height / rawH, 1);
+ const warmW = Math.max(2, Math.round((rawW * fit) / 2) * 2);
+ const warmH = Math.max(2, Math.round((rawH * fit) / 2) * 2);
+ const { fastRecorderProbe } = await chrome.storage.local.get([
+ "fastRecorderProbe",
+ ]);
+ const probeConfig =
+ fastRecorderProbe?.details?.selectedVideoConfig || null;
+ void startEncoderPrewarm({
+ width: warmW,
+ height: warmH,
+ codec: probeConfig?.codec || "avc1.64002A",
+ bitrate: Number(probeConfig?.bitrate) || 4_000_000,
+ framerate: Number(probeConfig?.framerate) || fps || 30,
+ });
+ }
+ } catch {}
} else {
chrome.runtime.sendMessage({
type: "recording-error",