Stabilize detached WebRTC daemons

Author: DjDeveloperr

cli/XCWH264Encoder.m

@@ -11,7 +11,7 @@
 static const int32_t XCWMaximumLowLatencySoftwareEncodedDimension = 1170;
 static const int32_t XCWTargetRealTimeFrameRate = 60;
 static const int32_t XCWTargetSoftwareFrameRate = 60;
-static const int32_t XCWTargetLowLatencySoftwareFrameRate = 30;
+static const int32_t XCWTargetLowLatencySoftwareFrameRate = 15;
 static const NSUInteger XCWMaximumInFlightFrames = 2;
 static const int32_t XCWMinimumAverageBitRate = 18000000;
 static const int32_t XCWMinimumSoftwareAverageBitRate = 3000000;
@@ -24,9 +24,9 @@
 static const uint64_t XCWSoftwareMaximumFrameIntervalUs = 50000;
 static const uint64_t XCWSoftwareFrameIntervalStepUs = 5556;
 static const NSUInteger XCWSoftwareHealthyFrameWindow = 4;
-static const uint64_t XCWLowLatencySoftwareMinimumFrameIntervalUs = 33333;
-static const uint64_t XCWLowLatencySoftwareInitialFrameIntervalUs = 33333;
-static const uint64_t XCWLowLatencySoftwareMaximumFrameIntervalUs = 100000;
+static const uint64_t XCWLowLatencySoftwareMinimumFrameIntervalUs = 66667;
+static const uint64_t XCWLowLatencySoftwareInitialFrameIntervalUs = 66667;
+static const uint64_t XCWLowLatencySoftwareMaximumFrameIntervalUs = 133333;
 static const uint64_t XCWLowLatencySoftwareFrameIntervalStepUs = 11111;
 static const NSUInteger XCWLowLatencySoftwareHealthyFrameWindow = 8;
 

client/src/features/stream/streamWorkerClient.ts

@@ -8,8 +8,8 @@ import type {
 
 const HAVE_CURRENT_DATA = 2;
 const WEBRTC_CONTROL_CHANNEL_LABEL = "simdeck-control";
-const WEBRTC_FIRST_FRAME_TIMEOUT_MS = 3500;
-const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 3500;
+const WEBRTC_FIRST_FRAME_TIMEOUT_MS = 10000;
+const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 8000;
 
 let activeWebRtcControlChannel: RTCDataChannel | null = null;
 let activeStreamClient: StreamWorkerClient | null = null;
@@ -50,7 +50,7 @@ class WebRtcStreamClient implements StreamClientBackend {
   private lastVideoFrameAt = 0;
   private peerConnection: RTCPeerConnection | null = null;
   private reconnectTimeout = 0;
-  private renderVideoToCanvas = false;
+  private reportedVideoConfig = false;
   private shouldReconnect = false;
   private stats: StreamStats = createEmptyStreamStats();
   private video: HTMLVideoElement | null = null;
@@ -62,7 +62,6 @@ class WebRtcStreamClient implements StreamClientBackend {
 
   attachCanvas(canvasElement: HTMLCanvasElement) {
     this.canvas = canvasElement;
-    this.canvas.classList.remove("stream-canvas-webrtc-render");
   }
 
   clear() {
@@ -80,6 +79,7 @@ class WebRtcStreamClient implements StreamClientBackend {
     const generation = ++this.connectGeneration;
     this.shouldReconnect = true;
     this.diagnostics = createWebRtcDiagnostics();
+    this.reportedVideoConfig = false;
     this.stats = createEmptyStreamStats();
     this.onMessage({
       type: "status",
@@ -122,18 +122,13 @@ class WebRtcStreamClient implements StreamClientBackend {
         }
         const stream = event.streams[0] ?? new MediaStream([event.track]);
         const video = document.createElement("video");
-        this.renderVideoToCanvas = shouldRenderWebRtcVideoThroughCanvas();
-        canvasElement.classList.toggle(
-          "stream-canvas-webrtc-render",
-          this.renderVideoToCanvas,
-        );
         video.autoplay = true;
-        video.className = this.renderVideoToCanvas
-          ? "stream-video stream-video-canvas-source"
-          : "stream-video";
+        video.className = "stream-video";
         video.disablePictureInPicture = true;
         video.muted = true;
         video.playsInline = true;
+        video.setAttribute("playsinline", "");
+        video.setAttribute("webkit-playsinline", "");
         video.preload = "auto";
         (video as HTMLVideoElement & { latencyHint?: string }).latencyHint =
           "interactive";
@@ -151,14 +146,7 @@ class WebRtcStreamClient implements StreamClientBackend {
             return;
           }
           this.syncCanvasSize(video.videoWidth, video.videoHeight);
-          this.onMessage({
-            type: "video-config",
-            size: { height: video.videoHeight, width: video.videoWidth },
-          });
-          this.onMessage({
-            type: "status",
-            status: { detail: "WebRTC media connected", state: "streaming" },
-          });
+          this.reportVideoConfig(video.videoWidth, video.videoHeight);
           this.scheduleVideoFrame();
         };
         video.addEventListener("loadedmetadata", startPlayback);
@@ -168,6 +156,7 @@ class WebRtcStreamClient implements StreamClientBackend {
         void video.play().catch(() => {
           // The readiness listeners above retry once the media stream has data.
         });
+        this.scheduleVideoFrame();
       };
 
       peerConnection.onconnectionstatechange = () => {
@@ -250,8 +239,7 @@ class WebRtcStreamClient implements StreamClientBackend {
       this.video.remove();
     }
     this.video = null;
-    this.canvas?.classList.remove("stream-canvas-webrtc-render");
-    this.renderVideoToCanvas = false;
+    this.reportedVideoConfig = false;
     this.controlChannel?.close();
     if (activeWebRtcControlChannel === this.controlChannel) {
       activeWebRtcControlChannel = null;
@@ -487,13 +475,9 @@ class WebRtcStreamClient implements StreamClientBackend {
       this.video.videoHeight > 0
     ) {
       this.syncCanvasSize(this.video.videoWidth, this.video.videoHeight);
+      this.reportVideoConfig(this.video.videoWidth, this.video.videoHeight);
       const now = performance.now();
       const renderStartedAt = performance.now();
-      if (this.renderVideoToCanvas) {
-        this.canvas
-          .getContext("2d")
-          ?.drawImage(this.video, 0, 0, this.canvas.width, this.canvas.height);
-      }
       const latestRenderMs = performance.now() - renderStartedAt;
       this.stats.decodedFrames += 1;
       this.stats.renderedFrames += 1;
@@ -530,6 +514,21 @@ class WebRtcStreamClient implements StreamClientBackend {
     this.animationFrame = window.requestAnimationFrame(this.drawVideoFrame);
   }
 
+  private reportVideoConfig(width: number, height: number) {
+    if (this.reportedVideoConfig) {
+      return;
+    }
+    this.reportedVideoConfig = true;
+    this.onMessage({
+      type: "video-config",
+      size: { height, width },
+    });
+    this.onMessage({
+      type: "status",
+      status: { detail: "WebRTC media connected", state: "streaming" },
+    });
+  }
+
   private cancelVideoFrameCallback() {
     if (!this.videoFrameCallback || !this.video) {
       return;
@@ -620,14 +619,6 @@ function configureReceiverCodecPreferences(transceiver: RTCRtpTransceiver) {
   ]);
 }
 
-function shouldRenderWebRtcVideoThroughCanvas(): boolean {
-  const userAgent = window.navigator.userAgent;
-  return (
-    /Safari/i.test(userAgent) &&
-    !/Chrome|Chromium|CriOS|Edg|OPR/i.test(userAgent)
-  );
-}
-
 function iceServers(): RTCIceServer[] {
   const params = new URLSearchParams(window.location.search);
   const raw = params.get("iceServers") ?? "stun:stun.l.google.com:19302";

client/src/styles/components.css

@@ -1167,10 +1167,6 @@
   pointer-events: none;
 }
 
-.stream-canvas-webrtc-render {
-  z-index: 1;
-}
-
 .stream-video {
   position: absolute;
   inset: 0;
@@ -1183,11 +1179,6 @@
   pointer-events: none;
 }
 
-.stream-video-canvas-source {
-  z-index: 0;
-  opacity: 0;
-}
-
 .accessibility-picker-layer {
   position: absolute;
   inset: 0;

docs/cli/commands.md

@@ -68,6 +68,9 @@ Print daemon metadata for the current project:
 simdeck daemon status
 ```
 
+Detached daemons report the supervisor PID and `logPath`; the supervised child
+process is restarted automatically after recoverable server exits.
+
 ### `daemon restart`
 
 Stop the daemon for the current project, then start a fresh one with the same

docs/cli/flags.md

@@ -35,7 +35,7 @@ Targets a specific running SimDeck daemon for commands that support the HTTP fas
 | `--advertise-host` | matches local host    | Hostname or IP printed for LAN browser access.                                  |
 | `--client-root`    | bundled `client/dist` | Override the static browser client directory.                                   |
 | `--video-codec`    | `h264-software`       | One of `h264` or `h264-software`. See [Video Pipeline](/guide/video).           |
-| `--low-latency`    | `false`               | Software H.264 profile for slower runners: caps at 30 fps and favors freshness. |
+| `--low-latency`    | `false`               | Software H.264 profile for slower runners: caps at 15 fps and favors freshness. |
 | `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                          |
 
 The public commands generate an access token automatically. Use `simdeck daemon status` to read it for direct API callers.

docs/guide/daemon.md

@@ -61,7 +61,7 @@ This starts or reuses the project daemon, serves the bundled browser client, and
 | `--advertise-host` | matches local host    | Hostname or IP advertised to browser clients.                                     |
 | `--client-root`    | bundled `client/dist` | Override the static browser client directory.                                     |
 | `--video-codec`    | `h264-software`       | One of `h264` or `h264-software`. See [Video](/guide/video).                      |
-| `--low-latency`    | `false`               | Software H.264 profile for slower runners; caps at 30 fps and drops stale frames. |
+| `--low-latency`    | `false`               | Software H.264 profile for slower runners; caps at 15 fps and drops stale frames. |
 | `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                            |
 
 Example:
@@ -76,7 +76,10 @@ simdeck ui --bind 0.0.0.0 --advertise-host 192.168.1.50 --open
 simdeck daemon status
 ```
 
-The status output includes the daemon URL, PID, project root, and access token. Local same-origin browser use does not require copying the token; direct remote API callers should send it as `X-SimDeck-Token` or `Authorization: Bearer <token>`.
+The status output includes the daemon URL, supervisor PID, project root, access
+token, and detached daemon log path. Local same-origin browser use does not
+require copying the token; direct remote API callers should send it as
+`X-SimDeck-Token` or `Authorization: Bearer <token>`.
 
 ## Restart
 

docs/guide/troubleshooting.md

@@ -87,7 +87,7 @@ The encoder did not produce a keyframe within 3 seconds. The most common causes:
 
   On virtualized CI Macs where hardware H.264 is unavailable, keep
   `h264-software`. If the stream still falls behind, restart with
-  `--video-codec h264-software --low-latency`; that profile caps at 30 fps,
+  `--video-codec h264-software --low-latency`; that profile caps at 15 fps,
   drops stale pending frames, and caps the longest edge at 1170 pixels before backlog
   turns into visible stream delay.
 

docs/guide/video.md

@@ -23,10 +23,12 @@ For slower runners, add `--low-latency` with software H.264:
 simdeck daemon start --video-codec h264-software --low-latency
 ```
 
-Low-latency mode caps software H.264 at 30 fps, keeps a single in-flight frame,
+Low-latency mode caps software H.264 at 15 fps, keeps a single in-flight frame,
 scales the longest edge to 1170 pixels, and backs off FPS more aggressively when
-encode pressure rises. It is CLI-only because it is meant for less capable
-machines where freshness matters more than maximum smoothness.
+encode pressure rises. WebRTC refresh pacing uses the same 15 fps floor so the
+server does not keep waking capture/encode faster than the stream can consume.
+It is CLI-only because it is meant for less capable machines where freshness
+matters more than maximum smoothness.
 
 The chosen codec is reported to clients in the JSON `videoCodec` field on `GET /api/health`.
 
@@ -58,7 +60,7 @@ A few practical guidelines:
 - **Start on the default for compatibility.** `h264-software` works without requiring the hardware encoder, but full-resolution latency can be high.
 - **Switch to `h264` on local Apple Silicon when hardware encode is available.** Hardware H.264 gives the smoothest local preview with the least CPU.
 - **Switch to `h264-software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 60 fps, and backs off dynamically under encode latency.
-- **Use `h264-software --low-latency` on virtualized CI Macs when hardware encode is unavailable.** This profile caps at 30 fps, uses a single pending frame, reduces the longest edge to 1170 pixels, and backs off before software encode latency turns into seconds of stream delay.
+- **Use `h264-software --low-latency` on virtualized CI Macs when hardware encode is unavailable.** This profile caps at 15 fps, uses a single pending frame, reduces the longest edge to 1170 pixels, and backs off before software encode latency turns into seconds of stream delay.
 
 ## Tuning with metrics
 

server/src/main.rs

@@ -41,6 +41,7 @@ use std::time::{Duration, Instant};
 use tracing::info;
 
 const RECOVERABLE_RESTART_EXIT_CODE: i32 = 75;
+const SUPERVISED_DAEMON_METADATA_PID_ENV: &str = "SIMDECK_DAEMON_METADATA_PID";
 const RESTART_ON_CORE_SIMULATOR_MISMATCH_ENV: &str = "SIMDECK_RESTART_ON_CORE_SIMULATOR_MISMATCH";
 const SERVER_FD_RESTART_THRESHOLD: usize = 4096;
 const SERVER_HEALTH_WATCHDOG_INITIAL_DELAY: Duration = Duration::from_secs(15);
@@ -510,6 +511,8 @@ struct DaemonMetadata {
     pairing_code: Option<String>,
     binary_path: PathBuf,
     started_at: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    log_path: Option<PathBuf>,
 }
 
 #[derive(Clone, Debug)]
@@ -572,6 +575,7 @@ fn ensure_project_daemon_with_status(
 fn start_project_daemon(options: DaemonLaunchOptions) -> anyhow::Result<DaemonMetadata> {
     let project_root = project_root()?;
     let metadata_path = daemon_metadata_path_for_root(&project_root)?;
+    let log_path = daemon_log_path_for_root(&project_root)?;
     let port = choose_daemon_port(options.port)?;
     let access_token = auth::generate_access_token();
     let pairing_code = auth::generate_pairing_code();
@@ -606,11 +610,43 @@ fn start_project_daemon(options: DaemonLaunchOptions) -> anyhow::Result<DaemonMe
         args.push(client_root.to_string_lossy().into_owned());
     }
 
-    let child = ProcessCommand::new(&executable)
+    let log_stdout = fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&log_path)
+        .with_context(|| format!("open daemon log {}", log_path.display()))?;
+    let log_stderr = log_stdout
+        .try_clone()
+        .with_context(|| format!("clone daemon log {}", log_path.display()))?;
+    let supervisor_script = format!(
+        r#"trap 'if [ -n "$child" ]; then kill "$child" 2>/dev/null; wait "$child" 2>/dev/null; fi; exit 0' TERM INT
+while :; do
+  {metadata_pid_env}=$$ "$@" &
+  child=$!
+  wait "$child"
+  status=$?
+  child=
+  if [ "$status" -eq {recoverable_restart_exit_code} ] || [ "$status" -ge 128 ]; then
+    printf '[simdeck-supervisor] daemon exited with status %s; restarting\n' "$status" >&2
+    sleep 1
+    continue
+  fi
+  exit "$status"
+done
+"#,
+        metadata_pid_env = SUPERVISED_DAEMON_METADATA_PID_ENV,
+        recoverable_restart_exit_code = RECOVERABLE_RESTART_EXIT_CODE
+    );
+
+    let child = ProcessCommand::new("/bin/sh")
+        .arg("-c")
+        .arg(supervisor_script)
+        .arg("simdeck-supervisor")
+        .arg(&executable)
         .args(args)
         .stdin(Stdio::null())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
+        .stdout(Stdio::from(log_stdout))
+        .stderr(Stdio::from(log_stderr))
         .spawn()
         .context("start project SimDeck daemon")?;
 
@@ -622,6 +658,7 @@ fn start_project_daemon(options: DaemonLaunchOptions) -> anyhow::Result<DaemonMe
         pairing_code: Some(pairing_code),
         binary_path: executable,
         started_at: now_secs(),
+        log_path: Some(log_path),
     };
     write_daemon_metadata(&metadata)?;
     wait_for_daemon(&metadata, Duration::from_secs(15))?;
@@ -787,6 +824,14 @@ fn daemon_metadata_path_for_root(root: &Path) -> anyhow::Result<PathBuf> {
         .join(format!("{:016x}.json", hasher.finish())))
 }
 
+fn daemon_log_path_for_root(root: &Path) -> anyhow::Result<PathBuf> {
+    let mut hasher = DefaultHasher::new();
+    root.to_string_lossy().hash(&mut hasher);
+    Ok(env::temp_dir()
+        .join("simdeck")
+        .join(format!("{:016x}.log", hasher.finish())))
+}
+
 fn daemon_metadata_paths() -> anyhow::Result<Vec<PathBuf>> {
     let dir = env::temp_dir().join("simdeck");
     if !dir.exists() {
@@ -950,6 +995,7 @@ fn run_foreground_ui(selector: Option<String>) -> anyhow::Result<()> {
         pairing_code: Some(pairing_code.clone()),
         binary_path: executable,
         started_at: now_secs(),
+        log_path: None,
     };
     write_daemon_metadata(&metadata)?;
 
@@ -978,6 +1024,13 @@ fn run_foreground_ui(selector: Option<String>) -> anyhow::Result<()> {
     result
 }
 
+fn supervised_daemon_metadata_pid() -> Option<u32> {
+    env::var(SUPERVISED_DAEMON_METADATA_PID_ENV)
+        .ok()
+        .and_then(|value| value.parse::<u32>().ok())
+        .filter(|pid| *pid > 0)
+}
+
 fn detect_lan_ip() -> Option<IpAddr> {
     for target in ["8.8.8.8:80", "1.1.1.1:80"] {
         let socket = UdpSocket::bind((Ipv4Addr::UNSPECIFIED, 0)).ok()?;
@@ -1111,14 +1164,16 @@ fn main() -> anyhow::Result<()> {
                 env::set_current_dir(&project_root).with_context(|| {
                     format!("set daemon project root to {}", project_root.display())
                 })?;
+                let log_path = daemon_log_path_for_root(&project_root).ok();
                 write_daemon_metadata(&DaemonMetadata {
                     project_root,
-                    pid: std::process::id(),
+                    pid: supervised_daemon_metadata_pid().unwrap_or_else(std::process::id),
                     http_url: format!("http://127.0.0.1:{port}"),
                     access_token: access_token.clone(),
                     pairing_code: pairing_code.clone(),
                     binary_path: env::current_exe().context("resolve daemon executable")?,
                     started_at: now_secs(),
+                    log_path,
                 })?;
                 let result = serve_with_appkit(
                     port,