replicas-computer 0.3.13 → 0.3.15

package/dist/index.js

@@ -2937,7 +2937,7 @@ async function computerStatusCommand() {
 }
 
 // src/version.ts
-var COMPUTER_USE_VERSION = "0.3.13";
+var COMPUTER_USE_VERSION = "0.3.15";
 var COMPUTER_USE_PROTOCOL_VERSION = 1;
 
 // src/program.ts
@@ -3251,13 +3251,17 @@ import { createInterface } from "readline";
 
 // src/rtp.ts
 var RTP_HEADER_BYTES = 12;
+var NAL_SLICE = 1;
 var NAL_IDR = 5;
+var NAL_SEI = 6;
 var NAL_SPS = 7;
+var SEI_RECOVERY_POINT = 6;
 var NAL_STAP_A = 24;
 var NAL_FU_A = 28;
 var nalType = (byte) => byte & 31;
 var headerBytesOf = (packet) => RTP_HEADER_BYTES + (packet[0] & 15) * 4;
 var joinable = (nal) => nal === NAL_IDR || nal === NAL_SPS;
+var refreshFrame = (nal) => nalType(nal[0]) === NAL_SLICE || nalType(nal[0]) === NAL_SEI && nal[1] === SEI_RECOVERY_POINT;
 var isRtp = (data) => data.length >= RTP_HEADER_BYTES && data[0] >> 6 === 2 && (data[1] < 192 || data[1] > 223);
 var rtpPayload = (packet) => packet.subarray(headerBytesOf(packet));
 function aggregatedNals(payload) {
@@ -3286,7 +3290,10 @@ function isKeyframeStart(payload) {
     const fragment = fragmentHeader(payload);
     return fragment.start && joinable(fragment.type);
   }
-  if (type === NAL_STAP_A) return aggregatedNals(payload).nals.some((nal) => joinable(nalType(nal[0])));
+  if (type === NAL_STAP_A) {
+    const { nals } = aggregatedNals(payload);
+    return nals.some((nal) => joinable(nalType(nal[0]))) && !nals.some(refreshFrame);
+  }
   return joinable(type);
 }
 var RtpSplicer = class {
@@ -3363,6 +3370,8 @@ var RtpClock = class {
 };
 var startCode = new Uint8Array([0, 0, 0, 1]);
 var H264RtpAssembler = class {
+  /** Frames abandoned for a missing or out-of-order packet; every delta after one is undecodable until a keyframe. */
+  discarded = 0;
   clock = new RtpClock(9e4);
   chunks = [];
   key = false;
@@ -3380,6 +3389,7 @@ var H264RtpAssembler = class {
   }
   push(packet) {
     if (this.timestamp !== void 0 && packet.timestamp !== this.timestamp) {
+      if (this.chunks.length > 0 || this.damaged) this.discarded += 1;
       this.clearFrame();
     }
     this.timestamp ??= packet.timestamp;
@@ -3412,6 +3422,7 @@ var H264RtpAssembler = class {
     } else this.damaged = true;
     if (!packet.marker) return null;
     if (this.damaged || this.fragmentType !== void 0 || this.chunks.length === 0) {
+      this.discarded += 1;
       this.clearFrame();
       return null;
     }
@@ -3469,7 +3480,9 @@ function superviseEncoder(options) {
     const warmupFrames = active ? options.warmupFrames ?? 0 : 0;
     const command = options.command?.() ?? "ffmpeg";
     const args = options.args(socket.address().port, warmupFrames);
-    const child = spawn3(command, args, { env: options.env, stdio: ["ignore", options.onOutput ? "pipe" : "ignore", "pipe"] });
+    const child = spawn3(command, args, { env: options.env, stdio: [options.controllable?.(command) ? "pipe" : "ignore", options.onOutput ? "pipe" : "ignore", "pipe"] });
+    child.stdin?.on("error", () => {
+    });
     child.stderr?.on("data", (chunk) => process.stderr.write(`[desktop-stream] ${chunk}`));
     const generation = { id: ++nextId, child, socket, live: true, startedAt: Date.now(), warmupFrames };
     candidate = generation;
@@ -3539,10 +3552,18 @@ function superviseEncoder(options) {
     candidate = void 0;
     active = void 0;
   });
+  const control = (line) => {
+    for (const generation of [candidate, active]) {
+      if (generation?.live && generation.child.stdin?.writable) generation.child.stdin.write(`${line}
+`);
+    }
+    return Boolean(active?.live && active.child.stdin?.writable);
+  };
   return {
     start,
     replace,
     stop,
+    control,
     running: () => Boolean(active && alive(active.child)),
     replacing: () => Boolean(candidate),
     generation: () => active?.id ?? 0,
@@ -3625,9 +3646,13 @@ function validInput(value) {
   switch (value.type) {
     case "release":
     case "keyframe":
+    case "retry-webrtc":
+    case "webrtc-ready":
       return true;
     case "theme":
       return value.theme === "light" || value.theme === "dark";
+    case "standby":
+      return typeof value.standby === "boolean";
     case "ping":
     case "pong":
       return finite(value.sentAt);
@@ -4069,13 +4094,14 @@ var WebRtcViewer = class {
 // src/video-encoder.ts
 var captureBinary = resolve2(dirname6(fileURLToPath(import.meta.url)), "..", "dist", "replicas-capture");
 function superviseVideoEncoder(options) {
-  const { display: display2, width: width2, height: height2, fps: fps2, colorMode: colorMode2 } = options;
+  const { display: display2, width: width2, height: height2, colorMode: colorMode2 } = options;
   const env = { ...process.env, DISPLAY: display2 };
   let nativeCapture = process.env.REPLICAS_DESKTOP_STREAM_CAPTURE !== "ffmpeg" && existsSync6(captureBinary);
   let captureMetrics;
   const encoder = superviseEncoder({
     label: "video",
     command: () => nativeCapture ? captureBinary : "ffmpeg",
+    controllable: (command) => command === captureBinary,
     onFailure: (command) => {
       if (command !== captureBinary) return;
       nativeCapture = false;
@@ -4098,7 +4124,7 @@ function superviseVideoEncoder(options) {
     onPacket: options.onPacket,
     joinable: (packet) => isKeyframeStart(rtpPayload(packet)),
     args: (udpPort, warmupFrames) => {
-      const { quality, keyframeMs, profile: videoProfile, intraRefresh, pixelFormat, chromaQpOffset, preset } = options.params();
+      const { quality, keyframeMs, fps: fps2, profile: videoProfile, intraRefresh, pixelFormat, chromaQpOffset, preset } = options.params();
       const keyframeInterval = Math.max(1, Math.round(fps2 * keyframeMs / 1e3));
       if (nativeCapture) return [
         "--width",
@@ -4232,6 +4258,8 @@ function superviseVideoEncoder(options) {
   });
   return {
     ...encoder,
+    /** Native capture takes keyframe, quality and frame-rate changes over stdin; ffmpeg needs a replacement for each. */
+    controllable: () => nativeCapture,
     capture: () => ({
       captureBackend: (encoder.command() ?? (nativeCapture ? captureBinary : "ffmpeg")) === captureBinary ? "native" : "ffmpeg",
       captureMetrics: captureMetrics?.generation === encoder.generation() && Date.now() - captureMetrics.at <= 2500 ? captureMetrics : void 0
@@ -4445,6 +4473,8 @@ var width = Number.parseInt(process.env.REPLICAS_DESKTOP_WIDTH || String(DESKTOP
 var height = Number.parseInt(process.env.REPLICAS_DESKTOP_HEIGHT || String(DESKTOP_VIEWER_HEIGHT), 10);
 var basePreset = availableParallelism2() >= 4 ? "superfast" : "ultrafast";
 var fps = Number.parseInt(process.env.REPLICAS_DESKTOP_STREAM_FPS || "", 10) || 60;
+var standbyFps = 5;
+var standbyRung = 5;
 var port = Number.parseInt(process.env.REPLICAS_DESKTOP_STREAM_PORT || String(DESKTOP_STREAM_PORT), 10);
 var display = process.env.REPLICAS_DESKTOP_DISPLAY?.replace(/^([^:])/, ":$1") || ":99";
 var webrtcEnabled = process.env.REPLICAS_DESKTOP_STREAM_WEBRTC !== "0";
@@ -4475,6 +4505,7 @@ var qualityLadder = (profile) => rungCaps.map((kbps, index) => ({ kbps, crf: pro
 var fullChromaMinKbps = 8e3;
 var fallbackKeyframeMs = 250;
 var webrtcStartupRung = 2;
+var descentMemoryMs = 18e4;
 var targetBacklogMs = 120;
 var congestedBacklogMs = 250;
 var congestedDecodeQueue = 3;
@@ -4554,7 +4585,8 @@ async function runMediaServer() {
   let activeProfile = "balanced";
   let adaptive = true;
   let rung = 0;
-  let descents = 0;
+  let descents = [];
+  let failedRung = -1;
   let congestedSeconds = 0;
   let comfortableSeconds = 0;
   let cleanTransportSeconds = 0;
@@ -4573,6 +4605,8 @@ async function runMediaServer() {
   let encoderFps = 0;
   let videoWanted = false;
   let encoderSignature = "";
+  let encoderDescription = "";
+  let encoderLive = { crf: 0, kbps: 0, fps: 0 };
   let encoderStop;
   let joinKeyframe;
   let lastVideoAt = 0;
@@ -4601,13 +4635,19 @@ async function runMediaServer() {
     if (accepted.length === 0) return "main";
     return PROFILE_ORDER.find((candidate) => (!requires420 || candidate !== "high444") && accepted.every((set) => set.has(candidate))) ?? "baseline";
   };
+  const allStandby = () => viewers.size > 0 && [...viewers.values()].every((viewer) => viewer.standby);
+  const streamFps = () => allStandby() ? Math.min(fps, standbyFps) : fps;
   const encoderParams = () => {
-    const quality = ladder()[rung];
+    const quality = ladder()[allStandby() ? Math.max(rung, standbyRung) : rung];
+    const encodeFps = streamFps();
     const sockets = socketViewers().length > 0;
-    const keyframeMs = sockets ? Math.min(quality.keyframeMs, fallbackKeyframeMs) : quality.keyframeMs;
+    const onDemand = videoEncoder.controllable();
+    const keyframeMs = onDemand ? 0 : sockets ? Math.min(quality.keyframeMs, fallbackKeyframeMs) : quality.keyframeMs;
     const videoProfile = profile();
-    const intraRefresh = !sockets;
+    const intraRefresh = !onDemand && !sockets;
     const pixelFormat = videoProfile === "high444" ? "yuv444p" : "yuv420p";
+    const live = `rung ${rung} \xB7 crf ${quality.crf} \xB7 ${encodeFps} fps`;
+    const restart = `${activeProfile} \xB7 ${preset} \xB7 ${videoProfile} \xB7 keyframe ${keyframeMs ? `${keyframeMs}ms${intraRefresh ? " refresh" : ""}` : "on demand"}`;
     return {
       quality,
       preset,
@@ -4615,8 +4655,10 @@ async function runMediaServer() {
       keyframeMs,
       intraRefresh,
       pixelFormat,
+      fps: encodeFps,
       chromaQpOffset: profiles[activeProfile].chromaQpOffset,
-      signature: `rung ${rung} \xB7 ${activeProfile} crf ${quality.crf} \xB7 ${preset} \xB7 ${videoProfile} \xB7 keyframe ${keyframeMs}ms${intraRefresh ? " refresh" : ""}`
+      signature: onDemand ? restart : `${live} \xB7 ${restart}`,
+      description: `${live} \xB7 ${restart}`
     };
   };
   const budgetBps = () => ladder()[rung].kbps * 1e3 * budgetFactor;
@@ -4637,6 +4679,7 @@ async function runMediaServer() {
       if (!keyframe2 && (viewer.waitingForKeyframe || queueMs(viewer) > targetBacklogMs || socket.bufferedAmount > fallbackBufferedBytes)) {
         viewer.waitingForKeyframe = true;
         viewer.withheldFrames += 1;
+        if (videoEncoder.controllable() && queueMs(viewer) <= targetBacklogMs && socket.bufferedAmount <= fallbackBufferedBytes) requestKeyframe("socket viewer caught up", void 0, viewer);
         continue;
       }
       if (keyframe2) viewer.waitingForKeyframe = false;
@@ -4663,12 +4706,12 @@ async function runMediaServer() {
       }
     }
     const last = Boolean(packet[1] & 128);
-    videoSplicer.splice(packet, generation, Math.round(9e4 / fps));
+    videoSplicer.splice(packet, generation, Math.round(9e4 / streamFps()));
     let rtp;
     let sockets = false;
     for (const viewer of viewers.values()) {
       if (viewer.fallback) sockets = true;
-      else viewer.rtc?.enqueueVideo(rtp ??= withPlayoutDelay(packet, PLAYOUT_DELAY_ID), frameId, keyframe, last);
+      viewer.rtc?.enqueueVideo(rtp ??= withPlayoutDelay(packet, PLAYOUT_DELAY_ID), frameId, keyframe, last);
     }
     frameStart = last;
     if (last) {
@@ -4677,7 +4720,12 @@ async function runMediaServer() {
     }
     if (!sockets) return;
     const parsed = parseRtpPacket(packet);
+    const discarded = videoAssembler.discarded;
     const frame = parsed && videoAssembler.push(parsed);
+    if (videoAssembler.discarded !== discarded) {
+      for (const viewer of socketViewers()) viewer.waitingForKeyframe = true;
+      if (videoEncoder.controllable()) requestKeyframe("socket frame lost");
+    }
     if (frame) broadcast(mediaPacket(frame.key ? 1 /* VideoKey */ : 2 /* VideoDelta */, frame.timestamp, frame.data), frame.key);
   };
   const onAudioPacket = (packet, generation) => {
@@ -4688,7 +4736,7 @@ async function runMediaServer() {
     let sockets = false;
     for (const viewer of viewers.values()) {
       if (viewer.fallback) sockets = true;
-      else viewer.rtc?.sendAudio(packet);
+      viewer.rtc?.sendAudio(packet);
     }
     if (!sockets) return;
     const parsed = parseRtpPacket(packet);
@@ -4699,13 +4747,12 @@ async function runMediaServer() {
     display,
     width,
     height,
-    fps,
     colorMode,
     params: encoderParams,
     onPacket: onVideoPacket,
     record
   });
-  const expectedFps = () => videoEncoder.capture().captureBackend === "native" ? Math.max(1, Math.min(fps, encoderFps)) : fps;
+  const expectedFps = () => videoEncoder.capture().captureBackend === "native" ? Math.max(1, Math.min(streamFps(), encoderFps)) : streamFps();
   const audioEncoder = superviseEncoder({
     label: "audio",
     log: (message) => record("audio encoder", message),
@@ -4763,20 +4810,30 @@ async function runMediaServer() {
   const ensureEncoders = () => {
     clearTimeout(encoderStop);
     void audioEncoder.start();
-    const { signature } = encoderParams();
+    const { signature, description, quality, fps: encodeFps } = encoderParams();
+    const live = { crf: quality.crf, kbps: quality.kbps, fps: encodeFps };
     if (!videoWanted) {
       videoWanted = true;
       encoderSignature = signature;
-      record("encoder", signature);
+      encoderDescription = description;
+      encoderLive = live;
+      record("encoder", description);
       void videoEncoder.start();
       return false;
     }
-    if (signature === encoderSignature) return false;
-    encoderSignature = signature;
-    lastSwapAt = Date.now();
-    record("encoder", signature);
-    void videoEncoder.replace();
-    return true;
+    if (description !== encoderDescription) record("encoder", description);
+    encoderDescription = description;
+    if (signature !== encoderSignature) {
+      encoderSignature = signature;
+      encoderLive = live;
+      lastSwapAt = Date.now();
+      void videoEncoder.replace();
+      return true;
+    }
+    if (live.crf !== encoderLive.crf || live.kbps !== encoderLive.kbps) videoEncoder.control(`quality ${live.crf} ${live.kbps}`);
+    if (live.fps !== encoderLive.fps) videoEncoder.control(`fps ${live.fps}`);
+    encoderLive = live;
+    return false;
   };
   const syncEncoder = () => videoWanted && viewers.size > 0 && ensureEncoders();
   const stopEncodersSoon = () => {
@@ -4794,8 +4851,9 @@ async function runMediaServer() {
     const quality = ladder()[next];
     record(next > rung ? "quality down" : "quality up", `rung ${rung} \u2192 ${next} (${quality.kbps} kbps cap, crf ${quality.crf}): ${reason}`);
     if (next > rung) {
-      if (now - lastDescentAt > 1e4) descents += 1;
+      if (now - lastDescentAt > 1e4) descents.push(now);
       lastDescentAt = now;
+      failedRung = rung;
       if (now - lastAscentAt < 15e3) {
         blockedRung = rung;
         blockedUntil = now + 12e4;
@@ -4811,7 +4869,8 @@ async function runMediaServer() {
   const resetLadder = (request) => {
     rung = request.transport === "webrtc" && request.adaptive ? webrtcStartupRung : 0;
     cleanTransportSeconds = 0;
-    descents = 0;
+    descents = [];
+    failedRung = -1;
     lastDescentAt = 0;
     lastAscentAt = 0;
     congestedSeconds = 0;
@@ -4831,6 +4890,7 @@ async function runMediaServer() {
     const sent = Math.min(...recentVideoKbps);
     return remb !== void 0 && earlier !== void 0 && remb <= earlier.kbps && sent > 500 && remb < sent * 0.9;
   };
+  const loaded = () => Math.min(...recentVideoKbps) > 500;
   const signals = (viewer, stats) => {
     const now = Date.now();
     if (viewer.fallback) {
@@ -4841,22 +4901,24 @@ async function runMediaServer() {
     }
     const stableSince = stableRttWindows.get(viewer)?.since;
     return [
-      ...viewer.rttFloorMs > viewer.rtcBaselineMs + 40 && (stableSince === void 0 || now - stableSince < 2e3) ? [`rtt floor ${Math.round(viewer.rttFloorMs)} ms over ${Math.round(viewer.rtcBaselineMs)} ms baseline`] : [],
+      ...viewer.rttFloorMs > viewer.rtcBaselineMs + 40 && (stableSince === void 0 || now - stableSince < 2e3) && loaded() ? [`rtt floor ${Math.round(viewer.rttFloorMs)} ms over ${Math.round(viewer.rtcBaselineMs)} ms baseline`] : [],
       ...stats.videoFps < expectedFps() * 0.6 && viewer.lowFpsReports >= 2 ? [`decoded ${stats.videoFps.toFixed(0)} fps`] : [],
-      ...(stats.lossPercent ?? 0) > 3 ? [`loss ${(stats.lossPercent ?? 0).toFixed(1)}%`] : [],
-      ...(stats.jitterBufferMs ?? 0) > 80 ? [`jitter buffer ${(stats.jitterBufferMs ?? 0).toFixed(0)} ms`] : []
+      ...(stats.lossPercent ?? 0) > 3 && loaded() ? [`loss ${(stats.lossPercent ?? 0).toFixed(1)}%`] : [],
+      ...(stats.jitterBufferMs ?? 0) > 80 && loaded() ? [`jitter buffer ${(stats.jitterBufferMs ?? 0).toFixed(0)} ms`] : []
     ];
   };
   const lowFpsObservationAt = /* @__PURE__ */ new WeakMap();
-  const severe = (viewer, stats) => !viewer.fallback && ((stats.lossPercent ?? 0) > 10 || stats.videoFps < expectedFps() * 0.25 && viewer.lowFpsReports >= 2);
+  const severe = (viewer, stats) => !viewer.fallback && ((stats.lossPercent ?? 0) > 10 && loaded() || stats.videoFps < expectedFps() * 0.25 && viewer.lowFpsReports >= 2);
   let lastSevereDescentAt = 0;
   const descendSevere = (now, trigger) => {
     comfortableSeconds = 0;
     congestedSeconds = 0;
     if (!adaptive || now - lastSevereDescentAt < 1e3) return;
     lastSevereDescentAt = now;
+    const sent = Math.min(...recentVideoKbps);
     const estimates = [...viewers.values()].flatMap((viewer) => {
-      const reported = viewer.stats && now - viewer.stats.at < 750 ? viewer.stats.availableKbps ?? 0 : 0;
+      const available = viewer.stats && now - viewer.stats.at < 750 ? viewer.stats.availableKbps ?? 0 : 0;
+      const reported = sent > 500 && available < sent * 0.9 ? available : 0;
       const remb = rembBelowSent(viewer, now) ? freshRemb(viewer, now) ?? 0 : 0;
       return [...reported > 0 ? [reported] : [], ...remb > 0 ? [remb] : []];
     });
@@ -4873,10 +4935,13 @@ async function runMediaServer() {
     videoKbps = Math.round((videoBytes - bytesAtTick) * 8 / 1e3);
     bytesAtTick = videoBytes;
     if (recentVideoKbps.push(videoKbps) > 3) recentVideoKbps.shift();
-    if (viewers.size === 0) return;
+    if (viewers.size === 0) {
+      starvedSeconds = 0;
+      return;
+    }
     const { captureBackend, captureMetrics } = videoEncoder.capture();
-    const captureBusy = captureBackend !== "native" || !captureMetrics || captureMetrics.busyMs / captureMetrics.elapsedMs > 0.8;
-    if (videoEncoder.running() && encoderFps < fps * 0.9 && captureBusy) {
+    const captureBusy = captureBackend !== "native" || (captureMetrics ? captureMetrics.busyMs / captureMetrics.elapsedMs > 0.8 : videoEncoder.activeForMs() > 2500);
+    if (videoEncoder.running() && encoderFps < streamFps() * 0.9 && captureBusy) {
       cleanTransportSeconds = 0;
       congestedSeconds = 0;
       comfortableSeconds = 0;
@@ -4924,15 +4989,16 @@ async function runMediaServer() {
       return;
     }
     congestedSeconds = Math.max(0, congestedSeconds - 0.5);
-    if (descents === 0 && reporting.some((viewer) => !viewer.fallback && (viewer.rttFloorMs > viewer.rtcBaselineMs + 20 || (viewer.stats.playbackDroppedPercent ?? 0) > 5 && cleanTransportSeconds < 15))) {
+    descents = descents.filter((at) => now - at < descentMemoryMs);
+    if (descents.length === 0 && reporting.some((viewer) => !viewer.fallback && (viewer.rttFloorMs > viewer.rtcBaselineMs + 20 && loaded() || (viewer.stats.playbackDroppedPercent ?? 0) > 5 && cleanTransportSeconds < 15))) {
       comfortableSeconds = 0;
       return;
     }
     comfortableSeconds += 1;
-    const startupSeconds = reporting.every((viewer) => !viewer.fallback) ? 2 : 3;
-    const recoverySeconds = lastAscentAt > lastDescentAt && cleanTransportSeconds >= 15 ? 15 : Math.min(60, 15 * 2 ** Math.min(descents, 2));
-    if (comfortableSeconds < (descents === 0 ? startupSeconds : recoverySeconds)) return;
     const target = Math.max(0, rung - 1);
+    const startupSeconds = reporting.every((viewer) => !viewer.fallback) ? 2 : 3;
+    const retrySeconds = lastAscentAt > lastDescentAt && cleanTransportSeconds >= 15 ? 15 : Math.min(60, 15 * 2 ** Math.min(descents.length - 1, 2));
+    if (comfortableSeconds < (descents.length > 0 && target <= failedRung ? retrySeconds : startupSeconds)) return;
     if (target === blockedRung && now < blockedUntil) return;
     setRung(target, `${comfortableSeconds}s comfortable, ${cleanTransportSeconds}s clean transport`);
   }, 1e3);
@@ -5012,9 +5078,18 @@ async function runMediaServer() {
 `);
   }, telemetryIntervalMs);
   telemetry.unref();
+  let lastKeyframeRequestAt = 0;
   const requestKeyframe = (reason, joinedAt, requestingViewer) => {
     const now = Date.now();
     if (!videoWanted || viewers.size === 0 || videoEncoder.replacing() || lastKeyframeAt < now - videoEncoder.activeForMs() || joinedAt !== void 0 && lastKeyframeAt > joinedAt) return;
+    if (videoEncoder.controllable()) {
+      const rttMs = requestingViewer?.rtc?.rttMs ?? requestingViewer?.stats?.rttMs ?? 0;
+      if (joinedAt === void 0 && now - Math.max(lastKeyframeAt, lastKeyframeRequestAt) < Math.max(300, rttMs + 150)) return;
+      if (!videoEncoder.control("keyframe")) return;
+      lastKeyframeRequestAt = now;
+      record("keyframe", reason);
+      return;
+    }
     const startup = requestingViewer && !requestingViewer.hasDecodedFrame && now - requestingViewer.connectedAt < 1e4;
     const wait = (joinedAt === void 0 ? startup ? 500 : 2e3 : 350) - (now - lastSwapAt);
     if (wait > 0) {
@@ -5024,7 +5099,9 @@ async function runMediaServer() {
       }
       return;
     }
-    if (!startup && encoderParams().keyframeMs - (now - lastKeyframeAt) <= 350) return;
+    const { keyframeMs, intraRefresh } = encoderParams();
+    const untilPeriodic = keyframeMs - (now - lastKeyframeAt);
+    if (!startup && !intraRefresh && untilPeriodic >= 0 && untilPeriodic <= 350) return;
     lastSwapAt = now;
     record("keyframe", reason);
     void videoEncoder.replace();
@@ -5037,16 +5114,51 @@ async function runMediaServer() {
       process.stderr.write(`[desktop-stream] webrtc fallback diagnostics: ${JSON.stringify(entry)}
 `);
     }
-    if (viewer.fallback) return;
+    const retried = viewer.rtc;
+    viewer.rtc?.close();
+    viewer.rtc = void 0;
+    if (viewer.fallback) {
+      if (retried) record("webrtc retry failed", reason);
+      return;
+    }
     viewer.fallback = true;
     viewer.waitingForKeyframe = true;
     viewer.input.release();
-    viewer.rtc?.close();
-    viewer.rtc = void 0;
     record("fallback to socket", reason);
     if (!syncEncoder()) requestKeyframe("socket fallback");
   };
   const optional = (value, max) => value === void 0 ? void 0 : clamp(value, 0, max);
+  const openWebRtc = (viewer, reply, iceServers) => {
+    try {
+      viewer.rtc = new WebRtcViewer({ iceServers, iceTransportPolicy: "all", portRange: icePorts, budgetBps: budgetBps() }, {
+        offer: (sdp) => reply({ type: "offer", sdp }),
+        candidate: (candidate, mid) => reply({ type: "candidate", candidate, mid }),
+        message: (message, answer) => handleMessage(viewer, message, answer),
+        keyframe: (reason) => {
+          if (reason === "stale" && Date.now() - lastDescentAt > 1e3) descendSevere(Date.now(), "send queue went stale and was cut back to a keyframe");
+          requestKeyframe(reason === "pli" ? "receiver pli" : "stale send queue", void 0, viewer);
+        },
+        remb: (bitsPerSecond) => {
+          if (viewer.rembs.push({ kbps: bitsPerSecond / 1e3, at: Date.now() }) > 16) viewer.rembs.shift();
+        },
+        connected: () => {
+          record("webrtc connected", viewer.rtc?.path ?? void 0);
+          requestKeyframe("viewer joined", Date.now());
+        },
+        // A viewer that loses its peer cannot send the key-ups for whatever it
+        // was holding, and its socket may stay open for a long time yet. A socket
+        // viewer trying WebRTC again still sends its input over the socket.
+        disconnected: (state) => {
+          record(`webrtc ${state}`);
+          if (!viewer.fallback) viewer.input.release();
+          if (state === "failed") reply({ type: "webrtc-failed" });
+        }
+      });
+    } catch (error) {
+      record("webrtc error", `could not create a peer connection: ${error instanceof Error ? error.message : String(error)}`);
+      reply({ type: "webrtc-failed" });
+    }
+  };
   const handleMessage = (viewer, message, reply) => {
     switch (message.type) {
       case "ping":
@@ -5124,7 +5236,7 @@ async function runMediaServer() {
         }
         if (viewer.stats.videoFps > 0) viewer.hasDecodedFrame = true;
         if (viewer.stats.videoFps >= expectedFps() * 0.8) viewer.everHealthy = true;
-        if (encoderHealthyTicks >= 3 && videoEncoder.running() && [...viewers.values()].every((v) => !v.fallback && v.stats && now - v.stats.at < 750 && now - v.connectedAt > 2500 && (v.stats.videoPacketsPerSecond ?? 0) > 0 && (v.stats.lossPercent ?? 0) > 10)) descendSevere(now, "every viewer reports over 10% loss");
+        if (encoderHealthyTicks >= 3 && videoEncoder.running() && loaded() && [...viewers.values()].every((v) => !v.fallback && v.stats && now - v.stats.at < 750 && now - v.connectedAt > 2500 && (v.stats.videoPacketsPerSecond ?? 0) > 0 && (v.stats.lossPercent ?? 0) > 10)) descendSevere(now, "every viewer reports over 10% loss");
         return;
       }
       case "answer":
@@ -5137,12 +5249,35 @@ async function runMediaServer() {
       case "fallback":
         enterFallback(viewer, message.reason, message.failure);
         return;
+      // A socket viewer whose WebRTC attempt failed tries again in the background;
+      // the socket keeps carrying its media until the new peer shows video.
+      case "retry-webrtc": {
+        const ice = webrtc && viewer.fallback && !viewer.rtc && viewer.request.transport === "webrtc" ? currentIceServers() : void 0;
+        if (!ice) return;
+        record("retrying webrtc", "socket media continues meanwhile");
+        openWebRtc(viewer, reply, ice.native);
+        return;
+      }
+      case "webrtc-ready":
+        if (!viewer.fallback || !viewer.rtc?.connected) return;
+        viewer.fallback = false;
+        viewer.withheldFrames = 0;
+        record("back on webrtc", viewer.rtc.path ?? void 0);
+        syncEncoder();
+        return;
       case "keyframe":
-        if (!viewer.fallback) requestKeyframe("viewer watchdog", void 0, viewer);
+        if (viewer.fallback) viewer.waitingForKeyframe = true;
+        if (!viewer.fallback || videoEncoder.controllable()) requestKeyframe(viewer.fallback ? "socket viewer decoder reset" : "viewer watchdog", void 0, viewer);
         return;
       case "theme":
         applyDesktopTheme(message.theme);
         return;
+      case "standby":
+        if (viewer.standby === message.standby) return;
+        viewer.standby = message.standby;
+        record(message.standby ? "viewer standby" : "viewer active", `${[...viewers.values()].filter((v) => v.standby).length} of ${viewers.size} in standby`);
+        syncEncoder();
+        return;
       default:
         viewer.input.handle(message);
     }
@@ -5185,6 +5320,8 @@ async function runMediaServer() {
         audioBytes,
         videoKbps,
         encoderFps,
+        streamFps: streamFps(),
+        standbyViewers: all.filter((viewer) => viewer.standby).length,
         ...videoEncoder.capture(),
         cpu,
         clientStats: all.flatMap((viewer) => viewer.stats ? [viewer.stats] : []),
@@ -5238,13 +5375,14 @@ async function runMediaServer() {
       socket.destroy();
       return;
     }
-    webSocketServer.handleUpgrade(request, socket, head, (client) => webSocketServer.emit("connection", client, parseStreamRequest(url.searchParams, defaultRequest)));
+    webSocketServer.handleUpgrade(request, socket, head, (client) => webSocketServer.emit("connection", client, parseStreamRequest(url.searchParams, defaultRequest), url.searchParams.get("standby") === "1"));
   });
-  webSocketServer.on("connection", (socket, request) => {
+  webSocketServer.on("connection", (socket, request, standby) => {
     const viewer = {
       socket,
       input: new InputBridge(display, width, height),
       request,
+      standby,
       fallback: false,
       waitingForKeyframe: true,
       withheldFrames: 0,
@@ -5269,7 +5407,7 @@ async function runMediaServer() {
       if (!adaptive) rung = 0;
     }
     viewers.set(socket, viewer);
-    record("viewer connected", `${request.transport} requested, ${viewers.size} connected`);
+    record("viewer connected", `${request.transport} requested${standby ? " in standby" : ""}, ${viewers.size} connected`);
     const reply = (message) => {
       if (socket.readyState === WebSocket2.OPEN) socket.send(JSON.stringify(message));
     };
@@ -5278,36 +5416,7 @@ async function runMediaServer() {
     const fallbackProfile = profile() === "high444" ? "main" : profile();
     const configMessage = { ...config, videoCodec: H264_PROFILES[fallbackProfile].codec, iceServers: ice?.browser, request };
     reply(configMessage);
-    if (ice) {
-      try {
-        viewer.rtc = new WebRtcViewer({ iceServers: ice.native, iceTransportPolicy: "all", portRange: icePorts, budgetBps: budgetBps() }, {
-          offer: (sdp) => reply({ type: "offer", sdp }),
-          candidate: (candidate, mid) => reply({ type: "candidate", candidate, mid }),
-          message: (message, answer) => handleMessage(viewer, message, answer),
-          keyframe: (reason) => {
-            if (reason === "stale") descendSevere(Date.now(), "send queue went stale and was cut back to a keyframe");
-            requestKeyframe(reason === "pli" ? "receiver pli" : "stale send queue", void 0, viewer);
-          },
-          remb: (bitsPerSecond) => {
-            if (viewer.rembs.push({ kbps: bitsPerSecond / 1e3, at: Date.now() }) > 16) viewer.rembs.shift();
-          },
-          connected: () => {
-            record("webrtc connected", viewer.rtc?.path ?? void 0);
-            requestKeyframe("viewer joined", Date.now());
-          },
-          // A viewer that loses its peer cannot send the key-ups for whatever it
-          // was holding, and its socket may stay open for a long time yet.
-          disconnected: (state) => {
-            record(`webrtc ${state}`);
-            viewer.input.release();
-            if (state === "failed") reply({ type: "webrtc-failed" });
-          }
-        });
-      } catch (error) {
-        record("webrtc error", `could not create a peer connection: ${error instanceof Error ? error.message : String(error)}`);
-        reply({ type: "webrtc-failed" });
-      }
-    }
+    if (ice) openWebRtc(viewer, reply, ice.native);
     if (!viewer.rtc) enterFallback(viewer, request.transport === "webrtc" ? "webrtc unavailable" : "websocket requested");
     ensureEncoders();
     socket.on("message", (raw, binary) => {