fix: Windows recording dies ~1s in — write-stall platform contract + libopenh264 software fallback (#149)

[TheOrcDev]

Fixes #149.

What was wrong

Two coupled defects on the raw yuv420p FIFO leg that Windows recordings use (no VideoToolbox there), confirming @petercr's excellent diagnosis:

1. The raw FIFO writer's deadline was the recording queue's 250ms age budget. It was anchored at frame submit time and also served as the sliding no-progress window — so a frame that waited out a Media Foundation pause in the latest-wins mailbox was declared dead before its first byte, and the Windows-specific 30s RAW_VIDEO_FIFO_FRAME_WRITE_HARD_TIMEOUT was unreachable. MF pauses draining the pipe for seconds at a time → healthy recording condemned as terminal ~1 second in.
2. Software h264_mf runs below realtime (0.86x at 1080p30 on the reporter's device), so the pipe backs up structurally — no timeout tuning saves an encoder that can't keep up.

The fix

Write-stall tolerance is now a platform contract, decoupled from queue age (encoder_bridge.rs):

• New RAW_VIDEO_FIFO_WRITE_STALL_TOLERANCE: 10s on Windows, elsewhere the existing 2s hard timeout.
• The write deadline anchors at write start, never submit time.
• QueuedRawVideoFrame no longer carries a timestamp at all — the writer is structurally unable to drop a frame by age. Age is a queue-admission concern; recording law: late frames are written, only a zero-byte-progress pipe is fatal.

libopenh264 replaces software h264_mf as the Windows fallback (recording.rs):

• FfmpegH264Platform::WindowsSoftware → libopenh264 + yuv420p with -rc_mode bitrate -allow_skip_frames 1 (per the real-device benchmark: ~2.5x realtime at 1080p30/8Mbps with the bundled ffmpeg, which carries libopenh264 and no libx264).
• New EncodeBackend::SoftwareOpenH264 (wire value software-open-h264) pinned in the protocol serde test, shared/backend.ts, and the diagnostics tab formatter.
• Hardware Media Foundation stays the probed fast path — this only changes what we fall back to when the exact-profile hardware probe fails.

Relationship to #141

Complementary: #141 disables the hardware probe on a box where it misbehaves; this PR fixes the contract that killed the session and makes the software fallback actually able to keep up. After this lands, a failed/disabled hardware probe degrades to a working openh264 recording instead of a dead one.

Not in this PR (future work): tee-backed hardware probe against a real capture sample (option 3); bundling libx264 (option 4 — unnecessary, GPL).

Tests

• New: stale-frame test (a mailbox-delayed frame MUST still be written), stall-tolerance contract test (tolerance > queue age budget, ≤ hard timeout, 10s on Windows).
• Updated: Windows-software encoder arg/backend pins; stalled-sink test now asserts failure within the platform tolerance + slack.
• Gates: cargo test -p videorc-backend 1310 green, cargo clippy -- -D warnings, cargo fmt --check, pnpm typecheck/lint/format:check.
• No Windows box locally — real-device confirmation requested from the reporter on the issue.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a Windows software H.264 encoding fallback using OpenH264.
  • Diagnostics now clearly display the OpenH264 software encoder.

• Bug Fixes

  • Improved recording reliability during temporary platform pauses by preventing healthy recordings from being aborted prematurely.
  • Updated Windows software encoding settings for more reliable bitrate control and frame handling.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2a35c35c-e1d8-4994-8de6-6820083d7ff4

📥 Commits

Reviewing files that changed from the base of the PR and between 430f355 and 3598d19.

📒 Files selected for processing (5)

• apps/desktop/src/renderer/src/components/tabs/diagnostics-tab.tsx
• apps/desktop/src/shared/backend.ts
• crates/videorc-backend/src/encoder_bridge.rs
• crates/videorc-backend/src/protocol.rs
• crates/videorc-backend/src/recording.rs

---

📝 Walkthrough

Walkthrough

Changes

Encoder fallback and raw FIFO behavior

Layer / File(s)	Summary
OpenH264 backend contract and selection crates/videorc-backend/src/protocol.rs, crates/videorc-backend/src/recording.rs, apps/desktop/src/shared/backend.ts, apps/desktop/src/renderer/src/components/tabs/diagnostics-tab.tsx	Adds the software-open-h264 backend, selects libopenh264 with bitrate-based rate control on Windows, and updates labels and tests.
Raw FIFO write-start deadline crates/videorc-backend/src/encoder_bridge.rs	Removes queued-frame timestamps and bases raw FIFO deadlines on write-start stall tolerance and hard frame-write limits, with updated queue, stop, allocation, and timeout tests.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RawYuv420pEncodingLoop
  participant QueuedRawVideoFrame
  participant RawWriterLoop
  participant RawVideoFIFO
  RawYuv420pEncodingLoop->>QueuedRawVideoFrame: enqueue frame without submitted_at
  QueuedRawVideoFrame->>RawWriterLoop: deliver pending latest frame
  RawWriterLoop->>RawVideoFIFO: start frame write
  RawWriterLoop->>RawVideoFIFO: complete frame within stall tolerance or hard timeout

Loading

Possibly related PRs

• TheOrcDev/videorc#75: Changes related raw-video FIFO timeout and write-side deadline behavior.
• TheOrcDev/videorc#79: Changes Windows EncodeBackend plumbing and backend labels.
• TheOrcDev/videorc#141: Changes Windows H.264 software encoder selection.

Suggested reviewers: petercr

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/windows-mf-fifo-stall

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}