Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
import { type ChildProcessByStdio, spawn } from "node:child_process";
import type { Readable, Writable } from "node:stream";
import type { CursorRecordingData } from "../../../src/native/contracts";
import {
type CursorPauseRange,
compactCursorTelemetryPauseRanges,
} from "../cursor/recording/cursorPauseRanges";
import {
NdjsonLineReader,
PipeWireCursorAccumulator,
type PipeWireHelperEvent,
} from "../cursor/recording/pipeWireCursorAccumulator";
import { findPipeWireCursorHelperPath } from "../cursor/recording/pipeWireCursorRecordingSession";
/**
* Drives the Linux capture helper for a full recording: video, audio and cursor
* telemetry from ONE portal session.
*
* WHY ONE SESSION MATTERS ENOUGH TO BUILD THIS. `SelectSources` may be called
* once per portal session, so a second process means a second picker. Before
* this, Linux users picked a source twice — once for Chromium's
* `getDisplayMedia` and once for the cursor helper — and the two captures could
* legitimately be of different things, because each picker was answered
* separately. That is also why the cursor overlay never lined up: the telemetry
* described one stream and the pixels came from another.
*
* 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 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;
/**
* The most of the helper's output [`helperOutput`] keeps, in UTF-8 bytes: the 64 KiB
* Save Diagnostics writes of each helper. Only the newest is kept, as on Windows and
* macOS.
*/
const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
export interface LinuxCaptureConfig {
outputPath: string;
cursorMode: "metadata" | "embedded";
fps: number;
bitrate?: number;
audio: {
system: { enabled: boolean };
microphone: { enabled: boolean; deviceName?: string; gain: number };
};
maxCursorSamples: number;
/**
* Negotiate the portal and stop there, until [`arm`] is called.
*
* Splits "the user has chosen what to share" from "pixels are flowing" so a
* countdown can sit between them. Without it the countdown runs first and the
* picker appears afterwards, which is backwards: the picker's wait has no
* upper bound, so the countdown finishes while the user is still reading a
* dialog they have not been shown yet.
*/
deferStart?: boolean;
}
/** What the portal handed over. `undefined` means the backend did not say. */
export type LinuxCaptureSourceKind = "monitor" | "window" | "virtual";
export interface LinuxCaptureResult {
path: string;
durationMs: number;
frames: number;
droppedFrames: number;
cursor: CursorRecordingData;
/** What the portal actually granted, when it said. */
sourceKind?: LinuxCaptureSourceKind;
videoEncoder?: string;
}
export class LinuxNativeCaptureSession {
private readonly cursor: PipeWireCursorAccumulator;
private readonly lines = new NdjsonLineReader();
private process: ChildProcessByStdio<Writable, Readable, Readable> | null = null;
private readyResolve: (() => void) | null = null;
private readyReject: ((error: Error) => void) | null = null;
private readyTimer: NodeJS.Timeout | null = null;
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;
private sourceSelectedReject: ((error: Error) => void) | null = null;
private armed = false;
private stopped: LinuxCaptureResult | null = null;
private stoppedResolve: (() => void) | null = null;
private stoppedReject: ((error: Error) => void) | null = null;
private sourceKind: LinuxCaptureSourceKind | undefined;
private negotiatedCursorMode: LinuxCaptureConfig["cursorMode"] | undefined;
private videoEncoder: string | undefined;
private lastError: string | null = null;
private paused = false;
private helperOutputText = "";
private cursorRecordingStartMs = 0;
private cursorPauseStartedAtMs: number | null = null;
private cursorPauseRanges: CursorPauseRange[] = [];
constructor(private readonly config: LinuxCaptureConfig) {
this.cursor = new PipeWireCursorAccumulator(config.maxCursorSamples);
}
/**
* Spawns the helper and resolves once it reports `ready` — which is BEFORE
* the portal picker is raised. Call [`waitUntilCapturing`] to wait for the
* user to answer it.
*/
async start(): Promise<void> {
const helperPath = findPipeWireCursorHelperPath();
if (!helperPath) {
throw new Error(
"The Linux capture helper is not available. Build it with `npm run build:native:linux`.",
);
}
this.cursor.reset(Date.now());
this.lines.reset();
this.cursorRecordingStartMs = 0;
this.cursorPauseStartedAtMs = null;
this.cursorPauseRanges = [];
this.paused = false;
const request = {
outputPath: this.config.outputPath,
cursorMode: this.config.cursorMode,
video: {
fps: this.config.fps,
...(this.config.bitrate ? { bitrate: this.config.bitrate } : {}),
},
audio: this.config.audio,
...(this.config.deferStart ? { deferStart: true } : {}),
};
const child = spawn(helperPath, [JSON.stringify(request)], {
stdio: ["pipe", "pipe", "pipe"],
});
this.process = child;
child.stdout.setEncoding("utf8");
child.stdout.on("data", (chunk: string) => this.handleStdout(chunk));
child.stderr.setEncoding("utf8");
child.stderr.on("data", (chunk: string) => {
this.appendHelperOutput(chunk);
const message = chunk.trim();
if (message) {
console.error("[capture-linux]", message);
}
});
child.once("exit", (code, signal) => {
this.process = null;
const reason =
this.lastError ??
`the Linux capture helper exited (code=${code ?? "null"}, signal=${signal ?? "null"})`;
this.rejectReady(new Error(reason));
this.startedReject?.(new Error(reason));
this.startedReject = null;
this.startedResolve = null;
// A session held open across a countdown can die before it is armed —
// the user revoking the share from the compositor's indicator, or
// closing the window they picked. Whoever is waiting on the picker
// has to learn that rather than wait forever.
this.sourceSelectedReject?.(new Error(reason));
this.sourceSelectedReject = null;
this.sourceSelectedResolve = null;
// A clean exit after `capture-stopped` is the normal path; anything
// else means the file may not have its trailer.
if (this.stopped) {
this.stoppedResolve?.();
} else {
this.stoppedReject?.(new Error(reason));
}
this.stoppedResolve = null;
this.stoppedReject = null;
});
child.once("error", (error) => {
this.process = null;
this.rejectReady(error);
});
try {
await new Promise<void>((resolve, reject) => {
this.readyResolve = resolve;
this.readyReject = reject;
this.readyTimer = setTimeout(() => {
this.rejectReady(new Error("Timed out waiting for the Linux capture helper"));
}, READY_TIMEOUT_MS);
});
} catch (error) {
this.kill();
throw error;
}
}
/**
* Resolves once the user has answered the compositor's picker.
*
* 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.
*/
waitUntilSourceSelected(): Promise<void> {
if (this.sourceSelected) {
return Promise.resolve();
}
if (!this.process) {
return Promise.reject(new Error("The Linux capture helper is not running."));
}
return new Promise<void>((resolve, reject) => {
this.sourceSelectedResolve = resolve;
this.sourceSelectedReject = reject;
});
}
/**
* Releases a deferred session: connect to PipeWire and start encoding.
*
* Safe to call on a session that was not deferred (the helper ignores the
* verb) and safe to call twice, so a caller never has to track whether a
* prepare happened.
*/
arm() {
if (this.armed) {
return;
}
this.armed = true;
this.write("record");
}
/**
* 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) {
return Promise.reject(new Error("The Linux capture helper is not running."));
}
// A previously observed capture-started event must not bypass the helper
// liveness check above.
if (this.capturing) {
return Promise.resolve();
}
return new Promise<void>((resolve, 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;
}
this.write("pause");
this.paused = true;
this.cursorPauseStartedAtMs = Date.now();
}
resume() {
if (!this.paused) {
return;
}
this.write("resume");
this.completeCursorPauseRange();
this.paused = false;
}
private completeCursorPauseRange(endMs = Date.now()) {
if (this.cursorPauseStartedAtMs === null || this.cursorRecordingStartMs <= 0) return;
this.cursorPauseRanges.push({
startMs: Math.max(0, this.cursorPauseStartedAtMs - this.cursorRecordingStartMs),
endMs: Math.max(0, endMs - this.cursorRecordingStartMs),
});
this.cursorPauseStartedAtMs = null;
}
get isPaused() {
return this.paused;
}
/**
* What the portal granted. Known from `stream-started`, so it is populated by
* the time [`waitUntilCapturing`] resolves.
*
* `undefined` means the backend did not report a kind — which is NOT the same
* as "a screen", and callers must not collapse the two. Guessing is what this
* whole field exists to stop.
*/
get grantedSourceKind(): LinuxCaptureSourceKind | undefined {
return this.sourceKind;
}
/**
* The cursor mode the helper really negotiates, known once `start()` resolves.
* A portal without EMBEDDED gets METADATA instead (#1357), so the cursor has
* to be drawn by the editor even though the system cursor was asked for.
*/
get cursorMode(): LinuxCaptureConfig["cursorMode"] {
return this.negotiatedCursorMode ?? this.config.cursorMode;
}
/**
* What the helper said in this session, for Save Diagnostics' `helperOutput.linux`:
* its stderr as written and every stdout line except `cursor-sample`, which comes
* at the capture rate and would push everything else out. Still readable after the
* helper exits, which is when a bug report asks for it.
*/
get helperOutput(): string {
return this.helperOutputText;
}
private appendHelperOutput(text: string) {
this.helperOutputText += text;
if (Buffer.byteLength(this.helperOutputText, "utf8") <= HELPER_OUTPUT_MAX_BYTES) {
return;
}
const bytes = Buffer.from(this.helperOutputText, "utf8");
let start = bytes.length - HELPER_OUTPUT_MAX_BYTES;
// A continuation byte (0b10xxxxxx) is the middle of a character: start at the
// next one, so the kept text never opens on a replacement character.
while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) {
start += 1;
}
this.helperOutputText = bytes.subarray(start).toString("utf8");
}
/**
* Asks the helper to write the trailer and exit, then returns what it made.
*
* Waits for the PROCESS to exit rather than for `capture-stopped` alone: the
* MP4's moov atom is written during teardown, and returning a path to a file
* whose index is still being written would hand the app an unplayable
* recording.
*/
async stop(): Promise<LinuxCaptureResult> {
const child = this.process;
if (!child) {
if (this.stopped) {
return this.stopped;
}
throw new Error("The Linux capture helper is not running.");
}
this.completeCursorPauseRange();
const exited = new Promise<void>((resolve, reject) => {
this.stoppedResolve = resolve;
this.stoppedReject = reject;
});
this.write("stop");
try {
child.stdin.end();
} catch {
// Already closed if the helper died on its own; the exit handler runs.
}
const timer = setTimeout(() => {
console.error("[capture-linux] helper did not exit in time; terminating");
this.kill();
}, STOP_TIMEOUT_MS);
try {
await exited;
} finally {
clearTimeout(timer);
}
if (!this.stopped) {
throw new Error(this.lastError ?? "The Linux capture helper produced no output file.");
}
return this.stopped;
}
/** Kills the helper and discards whatever it wrote. */
discard() {
this.kill();
}
private write(command: string) {
try {
this.process?.stdin.write(`${command}\n`);
} catch {
// The helper is gone; stop()/exit already reports that.
}
}
private kill() {
const child = this.process;
if (!child || child.killed) {
return;
}
child.kill("SIGTERM");
setTimeout(() => {
if (!child.killed) {
child.kill("SIGKILL");
}
}, 500).unref();
}
private handleStdout(chunk: string) {
this.lines.push(chunk, (line) => {
let payload: PipeWireHelperEvent;
try {
payload = JSON.parse(line) as PipeWireHelperEvent;
} catch (error) {
this.appendHelperOutput(`${line}\n`);
console.error("Failed to parse Linux capture helper output:", error, line);
return;
}
if (payload.event !== "cursor-sample") {
this.appendHelperOutput(`${line}\n`);
}
this.handleEvent(payload);
});
}
private handleEvent(payload: PipeWireHelperEvent) {
switch (payload.event) {
case "ready":
if (payload.cursorMode === "metadata" || payload.cursorMode === "embedded") {
this.negotiatedCursorMode = payload.cursorMode;
}
this.resolveReady();
return;
case "source-selected":
if (payload.sourceKind) {
this.sourceKind = payload.sourceKind;
}
this.sourceSelected = true;
console.info(
"[capture-linux] source selected",
JSON.stringify({ sourceKind: payload.sourceKind ?? null }),
);
this.sourceSelectedResolve?.();
this.sourceSelectedResolve = null;
this.sourceSelectedReject = null;
this.startFirstFrameTimer();
return;
case "stream-started":
if (payload.sourceKind) {
this.sourceKind = payload.sourceKind;
}
// The source kind is logged unconditionally for the same reason
// as the audio node: when someone reports "I picked a window and
// got my whole screen", this line is the answer, and it is the
// only place the truth appears — the app cannot name a source
// when asking the portal, so nothing upstream knows it.
console.info(
"[capture-linux] portal stream started",
JSON.stringify({
width: payload.width,
height: payload.height,
sourceKind: payload.sourceKind ?? null,
}),
);
return;
case "audio-source":
// Logged unconditionally: when someone reports "that is not my
// microphone", this line is the answer.
console.info(
"[capture-linux] audio source",
JSON.stringify({
role: payload.role,
requested: payload.requested ?? null,
node: payload.node ?? null,
}),
);
if (payload.requested && !payload.node) {
console.warn(
`[capture-linux] no PipeWire node matched ${JSON.stringify(payload.requested)}; ` +
"the session default source was recorded instead",
);
}
return;
case "encoder-selection":
this.videoEncoder = payload.video;
console.info(
"[capture-linux] encoder",
JSON.stringify({ video: payload.video, rejected: payload.rejected ?? [] }),
);
return;
case "capture-started":
// Cursor samples started flowing when the helper did, which was
// before the portal picker. The recording's zero is HERE, so the
// telemetry is re-based onto it and anything from during the
// picker is dropped rather than left pinned to the start.
this.cursor.rebase(payload.timestampMs);
this.cursorRecordingStartMs = payload.timestampMs;
this.capturing = true;
console.info(
"[capture-linux] capture started",
JSON.stringify({ width: payload.width, height: payload.height, fps: payload.fps }),
);
this.startedResolve?.();
this.startedResolve = null;
this.startedReject = null;
return;
case "cursor-sample":
this.cursor.addSample(payload);
return;
case "capture-stopped":
this.stopped = {
path: payload.path,
durationMs: payload.durationMs,
frames: payload.frames,
droppedFrames: payload.dropped,
cursor: compactCursorTelemetryPauseRanges(
this.cursor.toRecordingData(),
this.cursorPauseRanges,
),
...(this.sourceKind ? { sourceKind: this.sourceKind } : {}),
...(this.videoEncoder ? { videoEncoder: this.videoEncoder } : {}),
};
console.info(
"[capture-linux] capture stopped",
JSON.stringify({
frames: payload.frames,
dropped: payload.dropped,
durationMs: payload.durationMs,
convertMs: payload.convertMs,
uploadMs: payload.uploadMs,
encodeMs: payload.encodeMs,
}),
);
return;
case "warning":
console.warn(`[capture-linux] ${payload.code}: ${payload.message}`);
return;
case "error":
console.error(`[capture-linux] ${payload.code}: ${payload.message}`);
// Kept so the process-exit handler can report the CAUSE rather
// than just the exit code, which on its own says nothing useful.
this.lastError = payload.message;
this.rejectReady(new Error(payload.message));
this.sourceSelectedReject?.(new Error(payload.message));
this.sourceSelectedReject = null;
this.sourceSelectedResolve = null;
return;
case "debug":
console.info("[capture-linux][debug]", JSON.stringify(payload));
return;
}
}
private resolveReady() {
const resolve = this.readyResolve;
this.clearReadyState();
resolve?.();
}
private rejectReady(error: Error) {
const reject = this.readyReject;
this.clearReadyState();
reject?.(error);
}
private clearReadyState() {
if (this.readyTimer) {
clearTimeout(this.readyTimer);
this.readyTimer = null;
}
this.readyResolve = null;
this.readyReject = null;
}
}