fix(macos): pin the H.264 keyframe interval to 1 s and count dropped video frames

The GOP was left to VideoToolbox; it is now one second by frame count and by duration, like Windows. Frames the writer input was not ready for or refused were dropped silently; recording-stopped now carries droppedVideoFrames.

Author: EtienneLescot

electron/native/screencapturekit/Sources/OpenScreenCaptureCore/CaptureSizing.swift

@@ -86,3 +86,10 @@ public func defaultVideoBitrate(width: Int, height: Int, fps: Int) -> Int {
 	let pixelsPerSecond = Double(max(1, width)) * Double(max(1, height)) * Double(max(1, fps))
 	return min(max(Int(pixelsPerSecond * bitsPerPixel), 2_000_000), 60_000_000)
 }
+
+/// The H.264 keyframe interval, in frames: one second of video, the interval Windows uses.
+/// Left to VideoToolbox it had no bound, and the editor's scrub cost is the GOP length: a
+/// seek decodes from the keyframe before it (getopenscreen/openscreen#937).
+public func videoKeyFrameInterval(fps: Int) -> Int {
+	max(1, fps)
+}

electron/native/screencapturekit/Sources/OpenScreenScreenCaptureKitHelper/ScreenCaptureRecorder.swift

@@ -152,6 +152,9 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 	private var totalPausedDuration = CMTime.zero
 	/// Sample queue only. See `VideoTimestampGate` for the failure it exists to prevent.
 	private var videoTimestampGate = VideoTimestampGate()
+	/// Sample queue only. Frames the writer input was not ready for, or refused, reported in
+	/// `recording-stopped` so a macOS drop rate can be measured at all (#937).
+	private var droppedVideoFrames = 0
 	private var nativeMicrophoneEnabled = false
 	private var outputWidth = 1920
 	private var outputHeight = 1080
@@ -454,8 +457,11 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 					"captureBounds": captureBoundsPayload(),
 				])
 			} else if !appended {
+				droppedVideoFrames += 1
 				reportWriterFailure("video append")
 			}
+		} else {
+			droppedVideoFrames += 1
 		}
 	}
 
@@ -786,6 +792,11 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 				// particular run happened to die. Reordering off is 3/3 clean across
 				// both rates, and a SIGKILL at 25s still leaves 27 readable `moof`.
 				AVVideoAllowFrameReorderingKey: false,
+				// A keyframe every second, by frame count and by time: a still screen
+				// delivers fewer frames than the fps, and the count alone would then
+				// stretch the GOP, which is the editor's scrub cost (#937).
+				AVVideoMaxKeyFrameIntervalKey: videoKeyFrameInterval(fps: request.video.fps),
+				AVVideoMaxKeyFrameIntervalDurationKey: 1,
 			],
 		]
 		let input = AVAssetWriterInput(mediaType: .video, outputSettings: settings)
@@ -908,7 +919,9 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 			}
 		}
 
-		let refusedVideoFrames = sampleQueue.sync { videoTimestampGate.rejectedCount }
+		let (refusedVideoFrames, droppedFrames) = sampleQueue.sync {
+			(videoTimestampGate.rejectedCount, droppedVideoFrames)
+		}
 		if refusedVideoFrames > 1 {
 			emit([
 				"event": "warning",
@@ -931,6 +944,7 @@ final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
 			emit([
 				"event": "recording-stopped",
 				"screenPath": request.outputs.screenPath,
+				"droppedVideoFrames": droppedFrames,
 			])
 		} else {
 			emitError(

electron/native/screencapturekit/Tests/OpenScreenCaptureCoreTests/CaptureSizingTests.swift

@@ -150,4 +150,15 @@ final class CaptureSizingTests: XCTestCase {
 		XCTAssertEqual(defaultVideoBitrate(width: 320, height: 240, fps: 30), 2_000_000)
 		XCTAssertEqual(defaultVideoBitrate(width: 3840, height: 2160, fps: 120), 60_000_000)
 	}
+
+	// MARK: - Keyframe interval (#937)
+
+	func testKeyFrameIntervalIsOneSecondOfFrames() {
+		XCTAssertEqual(videoKeyFrameInterval(fps: 60), 60)
+		XCTAssertEqual(videoKeyFrameInterval(fps: 30), 30)
+	}
+
+	func testKeyFrameIntervalNeverFallsBelowOneFrame() {
+		XCTAssertEqual(videoKeyFrameInterval(fps: 0), 1)
+	}
 }

src/lib/nativeMacRecording.ts

@@ -66,6 +66,8 @@ export type NativeMacHelperRecordingStartedEvent = {
 export type NativeMacHelperRecordingStoppedEvent = {
 	event: "recording-stopped";
 	screenPath: string;
+	/** Frames the writer was not ready for or refused. Absent from helpers built before #937. */
+	droppedVideoFrames?: number;
 };
 
 export type NativeMacHelperWarningEvent = {