feat: record-video captures real H.264 streams instead of screenshot polling

[subdiox]

Summary

record-video was capped around ~8-10 fps because it polled screenshots and re-encoded every frame. It now captures real video via each platform's native recording facility, muxed straight into MP4 (passthrough — no re-encode):

• iOS uses idb's native in-process file recorder (FBSimulator.startRecording(toFile:configuration:)), which drives FBSimulatorVideoStream in eager H.264 mode at a constant --fps (1-60, default 30) and muxes to .mp4 via its own AVAssetWriter-backed file writer. --fps maps directly to the stream's cadence, so the requested rate is honored and playback is smooth.
• Android pipes adb screenrecord --output-format=h264 at the device's native variable frame rate (measured ~50-60 fps under motion, vs ~7-8 before) into a hand-rolled H.264 Annex-B → MP4 passthrough muxer (idb doesn't drive Android). --fps is ignored there; --quality/--scale map to bitrate/size. Recordings past the API < 34 per-invocation limit are stitched across screenrecord restarts.

--fps range widened 1-30 → 1-60 (default 10 → 30). The legacy screenshot/screencap recorders are retained as automatic fallbacks if the native path is unavailable.

Architecture note: this PR originally hand-rolled the same H.264-stream-to-MP4 passthrough muxing for iOS too. A later merge from upstream's idb migration (76639e4d → 1f6943f8) added a first-class native file recorder to idb itself using that same architecture, so iOS now calls straight through to it instead of re-implementing it. Android still needs the custom muxer since idb doesn't touch Android at all.

Demo

Settings-screen scroll recorded with the new pipeline (no LINE app involved; alternating up/down scroll):

iOS — 60 fps constant	Android — native variable rate
sim-use-ios-settings.mp4	sim-use-android-settings.mp4

New infrastructure

Android-only H.264 Annex-B → MP4 passthrough muxer under Sources/iOSSimBackend/Util/ (co-located there since only SimUse, the executable target, can see both AndroidBackend and iOSSimBackend):

• AnnexBStreamParser — chunk-wise NAL-unit splitting + access-unit assembly (exp-Golomb first_mb_in_slice, emulation-prevention handling)
• H264PassthroughRecorder — AVAssetWriter passthrough with host-clock variable-rate PTS; graceful zero-frame + segment-restart handling
• H264MuxingPipeline — thread-safe parse→append glue
• AdbStreamingProcess (AndroidBackend) — long-running adb child with incremental binary stdout

Testing

• Unit (make test, no device): parser (NAL splitting, chunk boundaries, exp-Golomb), muxer (AVCC framing, monotonic PTS, real fixture round-trip → playable MP4, zero-frame error), pipeline, Android screenrecord/wm size argument construction. 849 tests green (only 5 pre-existing unrelated failures).
• Live: iOS verified on a booted simulator (native recorder, ~30/60 fps, short-grace SIGTERM finalize ×5, repeated rapid back-to-back recordings to probe a cold-start zero-frames edge case found during review — did not reproduce against the current idb). Android verified on an emulator (screenrecord h264 stream, --bit-rate now reaches the device at default scale too, --size scaling, SDK 36 --time-limit 0).

🤖 Generated with Claude Code

[onevcat]

Thanks a lot for this PR! The new H.264 passthrough pipeline is a big improvement, and the code and tests are in great shape.

I pulled the branch and tested it live on both platforms (iOS simulator + Android emulator, SDK 36): build, all 1123 unit tests, recording under motion, --fps / --scale handling, SIGTERM with a short-grace SIGKILL, flag validation, and --json output all check out. The recorded videos look correct and play at the right speed.

During live testing I found three issues — one real behavior gap (1) and two smaller ones (2, 3). Details are in the inline comments. Could you confirm and fix?

1. Android: --quality is silently ignored at the default --scale 1.0 — --bit-rate is only passed to screenrecord when --scale < 1.0, which contradicts the PR description and README.
2. iOS: constant-frame-rate layout has no guard against stream under-delivery — if the stream drops frames, the video silently plays back faster than real time (non-blocking suggestion).
3. iOS: mid-stream errors don't mention the partial file — the MP4 is already finalized and on disk, but the error message doesn't say so, unlike the Android branch (minor).

[onevcat]

--quality does nothing on Android unless --scale < 1.0.

size is only detected when scale < 1.0, and bitrate is derived from size via size.map { ... } — so at the default scale, --bit-rate is never passed and --quality is silently ignored.

I verified this on a live emulator by capturing the device-side command line during recording (adb shell ps -ef | grep screenrecord):

• --quality 20 (default scale): screenrecord --output-format=h264 --time-limit 0 - — no --bit-rate
• --quality 20 --scale 0.5: screenrecord --output-format=h264 --time-limit 0 --bit-rate 3499200 --size 540x1200 - — works

This contradicts the PR description and README, which say --quality maps to bitrate on Android.

Suggested fix: always detect the display size via wm size (if detection fails, fall back to not passing --bit-rate), pass --bit-rate unconditionally, and keep passing --size only when scale < 1.0. detectScaledSize / parseWMSize can be reused as-is, so this should be a ~3-line change. (Alternatively, document the limitation and print a note like the --fps one — but making the code match the documented semantics seems better.)

[subdiox]

Fixed — display size is now detected unconditionally (detectSize), so bitrate is always computed regardless of --scale. Only the --size argument itself stays scale-gated.

Verified live (adb shell ps -ef | grep screenrecord) at default scale, both quality settings:

• --quality 80 (this CLI's actual default): --bit-rate 46061568 (previously absent entirely — screenrecord fell back to its own fixed ~20 Mbps default regardless of --quality). This is the representative case; roughly a 2.3x bitrate change from before.
• --quality 20: --bit-rate 19740672 — coincidentally close to screenrecord's own default, since quality≈20 happens to be near the formula's break-even point. Flagging so the numbers aren't read as "barely changed" in general.

Added bitrateWithoutSizeAtDefaultScale + scaledSize unit tests. (654d423)

[onevcat]

Non-blocking suggestion: guard CFR mode against stream under-delivery.

CFR mode trusts the frame count unconditionally: PTS is frameIndex / fps, so if FBSimulatorVideoStream delivers fewer frames than requested, the video is silently time-compressed and plays back faster than real time.

I hit this once during live testing: starting a 60 fps recording right after stopping a previous one produced only 77 frames over ~6 s of wall clock, i.e. a 1.28 s video that plays ~5x too fast. It didn't reproduce in controlled runs (60 fps at full size under motion tracked wall clock fine), so it looks like a cold-start / encoder-still-releasing edge case — but when it happens there is no hint to the caller, which is a silent semantic error for agent consumers.

A cheap guard: at finish time, compare framesAppended / frameRate against the actual wall-clock recording duration, and print a stderr warning when they diverge by more than ~20%. That keeps the smooth CFR playback while making the failure mode visible.

[subdiox]

Added a diagnostic guard (not a fix to the underlying under-delivery, since you flagged this as non-blocking): finish() now compares framesAppended / frameRate against the actual wall-clock recording duration and warns on stderr when they diverge by more than ~20% (threshold configurable). Factored into a pure isUnderDelivered helper with unit tests, including your exact repro numbers (77 frames / 60fps / ~6s). The recording itself is unchanged — this only makes the failure mode visible. (654d423)

[subdiox]

Follow-up: a later merge from upstream's idb migration (76639e4d → 1f6943f8) added a native in-process file recorder (FBSimulator.startRecording(toFile:configuration:)) that does exactly what our own hand-rolled H.264 stream → MP4 passthrough mux was doing for iOS — now as idb's own maintained code. iOS has been switched to call it directly, so the custom FBVideoStreamConfiguration/createStream integration is gone for iOS.

Consequence for this comment: since iOS no longer lays out its own PTS (idb's native encoder produces correct timing internally), the isUnderDelivered guard and the frameRate (CFR) mode in H264PassthroughRecorder became dead code — nothing calls them anymore (Android is the only remaining user of that class, and it's always variable-rate). I removed both, along with their unit tests, in ba2b75d.

I also re-tested the cold-start scenario you found (77 frames over ~6s) with several rapid back-to-back recordings against the new idb — it didn't reproduce, consistent with upstream's video-layer rewrite.

[onevcat]

Minor: mid-stream errors should mention the partial file.

If the stream fails mid-recording, the MP4 has already been finalized successfully by this point and stays on disk — but the user only sees Failed to record video: ... with no hint that a playable partial recording exists. The Android branch handles the equivalent case with "...partial recording saved to ".

Suggest aligning the wording so the iOS error also points at the partial file.

[subdiox]

Fixed — mid-stream errors after the MP4 was already finalized now say "partial recording saved to <path>", matching the Android wording. Wording-only change; doesn't affect recording behavior. (654d423)

[onevcat]

LGTM!
@subdiox Fantastic work and this is solved in a really beautiful way. Thank you very much!