Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

fix(linux): give up when no first frame follows the portal picker

EtienneLescotf389e55ed16e
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index bd92ad49d..51050943b 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -490,4 +490,95 @@ describe("LinuxNativeCaptureSession", () => {
await pending;
expect(settled).toBe(true);
});
+
+ describe("first-frame timeout (#1101)", () => {
+ // Only the timers are faked: the fake helper's stdout still needs real
+ // ticks to deliver its events, which `setImmediate` gives.
+ const flushEvents = () => new Promise((resolve) => setImmediate(resolve));
+
+ async function startFaked(deferStart = false) {
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+ const session = newSession(deferStart);
+ const started = session.start();
+ helper.emitEvent({ event: "ready", timestampMs: 1_000 });
+ await flushEvents();
+ await started;
+ return session;
+ }
+
+ async function answerPicker() {
+ helper.emitEvent({ event: "source-selected", timestampMs: 1_100, nodeId: 42 });
+ await flushEvents();
+ }
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ /**
+ * A stream that never delivers a frame and never reports an error used to
+ * leave the start hanging forever, with the HUD stuck before recording.
+ */
+ it("fails the start and kills the helper when no frame follows the picker", async () => {
+ const session = await startFaked(true);
+ await answerPicker();
+
+ // A countdown between the answer and the arm is not first-frame time.
+ vi.advanceTimersByTime(60_000);
+ expect(helper.killed).toBe(false);
+
+ session.arm();
+ const outcome = expect(session.waitUntilCapturing()).rejects.toThrow(
+ /could not start screen capture/,
+ );
+ vi.advanceTimersByTime(9_999);
+ expect(helper.killed).toBe(false);
+ vi.advanceTimersByTime(1);
+
+ await outcome;
+ expect(helper.killed).toBe(true);
+ });
+
+ /** A human reading the picker has no upper bound; only what follows does. */
+ it("does not start the clock until the picker has answered", async () => {
+ const session = await startFaked();
+
+ let settled = false;
+ const capturing = session.waitUntilCapturing().finally(() => {
+ settled = true;
+ });
+ const outcome = expect(capturing).rejects.toThrow(/could not start screen capture/);
+ vi.advanceTimersByTime(600_000);
+ await flushEvents();
+ expect(settled).toBe(false);
+ expect(helper.killed).toBe(false);
+
+ await answerPicker();
+ vi.advanceTimersByTime(10_000);
+
+ await outcome;
+ expect(helper.killed).toBe(true);
+ });
+
+ it("leaves a capture whose first frame arrived in time running", async () => {
+ const session = await startFaked();
+
+ const capturing = session.waitUntilCapturing();
+ await answerPicker();
+ vi.advanceTimersByTime(9_000);
+ helper.emitEvent({
+ event: "capture-started",
+ timestampMs: 1_200,
+ path: "/tmp/recording.mp4",
+ width: 800,
+ height: 600,
+ fps: 30,
+ });
+ await flushEvents();
+ await capturing;
+
+ vi.advanceTimersByTime(60_000);
+ expect(helper.killed).toBe(false);
+ });
+ });
});
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index bdccf3f75..2c2a74766 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -23,13 +23,26 @@ import { findPipeWireCursorHelperPath } from "../cursor/recording/pipeWireCursor
* TIMEOUTS. `ready` arrives in milliseconds and means the helper loaded
* libpipewire and reached the portal. `capture-started` cannot arrive until a
* human has clicked through the compositor's dialog, which has no upper bound —
- * so it is deliberately NOT on a timer. The caller shows its own UI for that
- * wait; a timeout here would cancel recordings whose user was merely reading the
- * dialog.
+ * so the picker is deliberately NOT on a timer. The caller shows its own UI for
+ * that wait; a timeout there would cancel recordings whose user was merely
+ * reading the dialog. Once the picker has answered, the first frame IS bounded:
+ * see [`FIRST_FRAME_TIMEOUT_MS`].
*/
const READY_TIMEOUT_MS = 5_000;
const STOP_TIMEOUT_MS = 15_000;
+/**
+ * How long the first frame may take once the picker has answered (#1101).
+ *
+ * Normal start-up after the answer is well under that: connect the stream,
+ * negotiate a format (twice when a DMA-BUF allocation failure falls back to
+ * shared memory, #1069), skip up to eight crop-less frames, probe the encoder
+ * ladder. The helper's own give-ups land inside it too — 60 failed imports in a
+ * row is 1–2 s — so a helper that CAN say what went wrong does, and this only
+ * catches a stream that stays silent. Without it, frames the shim never
+ * delivers leave the HUD waiting forever, with nothing on screen to say so.
+ */
+const FIRST_FRAME_TIMEOUT_MS = 10_000;
export interface LinuxCaptureConfig {
outputPath: string;
@@ -79,6 +92,7 @@ export class LinuxNativeCaptureSession {
private capturing = false;
private startedResolve: (() => void) | null = null;
private startedReject: ((error: Error) => void) | null = null;
+ private firstFrameTimer: NodeJS.Timeout | null = null;
private sourceSelected = false;
private sourceSelectedResolve: (() => void) | null = null;
@@ -187,9 +201,9 @@ export class LinuxNativeCaptureSession {
/**
* Resolves once the user has answered the compositor's picker.
*
- * No timeout, for the same reason as [`waitUntilCapturing`]: a human is
- * reading a dialog and there is no upper bound on that. Resolves immediately
- * if the answer already arrived, so callers need not race the event.
+ * No timeout: a human is reading a dialog and there is no upper bound on
+ * that. Resolves immediately if the answer already arrived, so callers need
+ * not race the event.
*
* A session started WITHOUT `deferStart` still reports this — it simply
* arrives moments before capture rather than being waited on.
@@ -223,8 +237,9 @@ export class LinuxNativeCaptureSession {
}
/**
- * Resolves when the first frame has been encoded — i.e. once the user has
- * answered the portal picker. No timeout, on purpose: see the class doc.
+ * Resolves when the first frame has been encoded. The picker's wait is not
+ * timed; the first frame after it is, and the helper is killed if it never
+ * comes. See the class doc.
*/
waitUntilCapturing(): Promise<void> {
if (!this.process) {
@@ -236,11 +251,48 @@ export class LinuxNativeCaptureSession {
return Promise.resolve();
}
return new Promise<void>((resolve, reject) => {
- this.startedResolve = resolve;
- this.startedReject = reject;
+ const settle = () => {
+ if (this.firstFrameTimer) {
+ clearTimeout(this.firstFrameTimer);
+ this.firstFrameTimer = null;
+ }
+ };
+ this.startedResolve = () => {
+ settle();
+ resolve();
+ };
+ this.startedReject = (error) => {
+ settle();
+ reject(error);
+ };
+ this.startFirstFrameTimer();
});
}
+ /**
+ * Starts the first-frame clock once a capture wait is pending AND the picker
+ * has answered, whichever comes last. Never earlier: a prepared session sits
+ * answered through the whole countdown, and the picker itself has no bound.
+ */
+ private startFirstFrameTimer() {
+ if (!this.sourceSelected || !this.startedReject || this.firstFrameTimer) {
+ return;
+ }
+ this.firstFrameTimer = setTimeout(() => {
+ this.firstFrameTimer = null;
+ const reject = this.startedReject;
+ this.startedResolve = null;
+ this.startedReject = null;
+ this.kill();
+ reject?.(
+ new Error(
+ "OpenScreen could not start screen capture: the screen share delivered no " +
+ `frame within ${FIRST_FRAME_TIMEOUT_MS / 1000} s.`,
+ ),
+ );
+ }, FIRST_FRAME_TIMEOUT_MS);
+ }
+
pause() {
if (this.paused) {
return;
@@ -374,6 +426,7 @@ export class LinuxNativeCaptureSession {
this.sourceSelectedResolve?.();
this.sourceSelectedResolve = null;
this.sourceSelectedReject = null;
+ this.startFirstFrameTimer();
return;
case "stream-started":