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 ChildProcessWithoutNullStreams, spawn } from "node:child_process";
import { EventEmitter } from "node:events";
import { PassThrough, Writable } from "node:stream";
/**
* Apple's system picker on macOS 15.2+, and the long-lived helper that records from it.
*
* A capture started from `SCContentSharingPicker` needs no Screen Recording grant and never
* raises macOS 15's "bypass the system private window picker" alert: the user's pick is
* the consent. That consent lives in a filter that cannot leave the helper process, so one
* helper (`--picker-session`) stays up for the whole app session, shows the picker, and
* records every take from the retained pick. See PickerSession.swift.
*
* The rest of the macOS recording code was written against one helper process per take:
* it reads a take's events from `proc.stdout`, sends `pause`/`resume`/`stop` on
* `proc.stdin`, and treats `close` as "this take's output is complete". `startTake`
* therefore hands back a `TakeProcess` with exactly that surface, carrying only this
* take's lines and "exiting" on the session's `take-ended`, so start, stop, salvage and
* the mid-capture error watch all run unchanged.
*/
/** The id prefix of a source picked in Apple's picker. It is not a desktopCapturer id. */
export const MAC_PICKER_SOURCE_PREFIX = "mac-picker:";
export function isMacPickerSourceId(id: unknown): boolean {
return typeof id === "string" && id.startsWith(MAC_PICKER_SOURCE_PREFIX);
}
/**
* 15.2, not 14.0 where the picker API starts: the filter only reports which display or
* window was picked, and where, from 15.2 -- and the cursor telemetry needs that.
*/
export function supportsMacSystemPicker(systemVersion: string): boolean {
const [major = 0, minor = 0] = systemVersion.split(".").map((part) => Number.parseInt(part, 10));
return major > 15 || (major === 15 && minor >= 2);
}
let systemPickerUnavailable = false;
/**
* For the rest of this run, sources come from the app's own picker: the session could not
* start (a helper that predates `--picker-session`, or none at all).
*/
export function markMacSystemPickerUnavailable() {
systemPickerUnavailable = true;
}
/**
* Whether this Mac picks sources in Apple's picker. Also true while the helper has not
* been tried yet; `OPENSCREEN_MAC_SOURCE_PICKER=legacy` forces the app's own picker.
*/
export function macSystemPickerEnabled(): boolean {
return (
process.platform === "darwin" &&
!systemPickerUnavailable &&
process.env.OPENSCREEN_MAC_SOURCE_PICKER !== "legacy" &&
supportsMacSystemPicker(process.getSystemVersion())
);
}
export interface MacPickerSelection {
kind: "display" | "window";
displayId: number | null;
windowId: number | null;
/** Window title, empty for a display. */
title: string;
/** Owning app of a picked window, empty for a display. */
appName: string;
/** Global frame, points, top-left origin: what the cursor telemetry normalises against. */
bounds: { x: number; y: number; width: number; height: number };
}
type HelperEvent = Record<string, unknown> & { event?: unknown };
const READY_TIMEOUT_MS = 5_000;
function parseEvent(line: string): HelperEvent | null {
try {
const parsed: unknown = JSON.parse(line);
return parsed && typeof parsed === "object" ? (parsed as HelperEvent) : null;
} catch {
return null;
}
}
function asNumber(value: unknown): number | null {
return typeof value === "number" && Number.isFinite(value) ? value : null;
}
export function parsePickerSelection(event: HelperEvent): MacPickerSelection | null {
const bounds = event.bounds as Record<string, unknown> | undefined;
const x = asNumber(bounds?.x);
const y = asNumber(bounds?.y);
const width = asNumber(bounds?.width);
const height = asNumber(bounds?.height);
if (x === null || y === null || width === null || height === null) {
return null;
}
return {
kind: event.kind === "window" ? "window" : "display",
displayId: asNumber(event.displayId),
windowId: asNumber(event.windowId),
title: typeof event.title === "string" ? event.title : "",
appName: typeof event.appName === "string" ? event.appName : "",
bounds: { x, y, width, height },
};
}
/**
* One take, dressed as the per-take helper process the recording code expects.
* Only the members that code touches exist; the cast at `startTake` says so.
*/
class TakeProcess extends EventEmitter {
readonly stdout = new PassThrough();
readonly stderr = new PassThrough();
readonly stdin: Writable;
exitCode: number | null = null;
signalCode: NodeJS.Signals | null = null;
killed = false;
private sawError = false;
private sawStopped = false;
constructor(private readonly command: (line: string) => boolean) {
super();
const take = this;
this.stdin = new Writable({
write(chunk, _encoding, callback) {
// The single-take protocol's bare words (`pause`, `resume`, `stop`) are also
// the session's, so they pass through as they are.
for (const line of String(chunk).split(/\r?\n/)) {
if (line.trim() && !take.ended) {
take.command(line.trim());
}
}
callback();
},
});
}
get ended() {
return this.exitCode !== null || this.signalCode !== null;
}
deliver(line: string, event: HelperEvent | null) {
if (event?.event === "error") {
this.sawError = true;
}
if (event?.event === "recording-stopped") {
this.sawStopped = true;
}
this.stdout.write(`${line}\n`);
}
/**
* The session's `take-ended`, read as the single-take helper's exit: 0 when the take
* finished its file or never failed, 1 when it reported an error and no file.
*/
end(signal: NodeJS.Signals | null = null) {
if (this.ended) {
return;
}
if (signal) {
this.signalCode = signal;
} else {
this.exitCode = this.sawError && !this.sawStopped ? 1 : 0;
}
this.stdin.end();
this.stdout.end();
this.stderr.end();
this.emit("exit", this.exitCode, this.signalCode);
// `close` after the streams have flushed, as for a real child process.
setImmediate(() => this.emit("close", this.exitCode, this.signalCode));
}
/** A take cannot be killed on its own without killing every later one: stop it. */
kill() {
this.killed = true;
if (!this.ended) {
this.command("stop");
}
return true;
}
}
export class MacPickerSession {
private proc: ChildProcessWithoutNullStreams | null = null;
private starting: Promise<boolean> | null = null;
private selection: MacPickerSelection | null = null;
/** The windows the picker was told to leave out, as of the last `present`. */
private presentedExclusions: readonly number[] = [];
/** The windows the retained pick leaves out: baked into its filter, fixed until the next pick. */
private selectionExclusions: readonly number[] = [];
/** Whether the retained pick leaves out the whole app, windows it opens later included. */
private selectionExcludesApp = false;
private take: TakeProcess | null = null;
private pendingPick: ((selection: MacPickerSelection | null) => void) | null = null;
private lineBuffer = "";
/** Set by `dispose`: the helper exiting is then the app's doing, not something to report. */
private disposed = false;
constructor(
private readonly helperPath: string,
private readonly spawnHelper: typeof spawn = spawn,
) {}
getSelection(): MacPickerSelection | null {
return this.selection;
}
/**
* Forgets a screen pick that does not leave out every one of `windowIds`.
*
* The windows a screen pick leaves out are the ones the picker was told about when it
* was shown, baked into the pick's filter. A take cannot add one: a fresh filter needs
* the Screen Recording grant this picker exists to avoid. So once the HUD or the notes
* window is not one the pick knows -- the HUD is a new window after every trip through
* the editor -- the pick would record it, and only picking again leaves it out (#965).
* A window pick records that one window and is never affected, and neither is a take
* already running: its filter is set, and its cursor telemetry still reads the pick.
*
* Nor is a pick the helper reports as leaving out the whole app (`excludesApp`): that
* exclusion covers windows created after the pick, so a screen picked in the editor's
* Record mode, before the HUD exists, is still good at Start (#996). A helper that
* predates the flag never sends it, and its picks are checked by window id as before.
*/
forgetSelectionUnlessExcluding(windowIds: readonly number[]) {
if (
this.selection?.kind !== "display" ||
this.selectionExcludesApp ||
(this.take && !this.take.ended)
) {
return;
}
if (!windowIds.every((windowId) => this.selectionExclusions.includes(windowId))) {
this.selection = null;
}
}
/** Starts the helper if it is not running. Resolves false when it cannot. */
start(): Promise<boolean> {
if (this.proc) {
return Promise.resolve(true);
}
this.starting ??= new Promise<boolean>((resolve) => {
let proc: ChildProcessWithoutNullStreams;
try {
proc = this.spawnHelper(this.helperPath, ["--picker-session"], {
stdio: ["pipe", "pipe", "pipe"],
}) as ChildProcessWithoutNullStreams;
} catch (error) {
console.warn("[mac-picker] could not start the picker session:", error);
this.starting = null;
resolve(false);
return;
}
const timer = setTimeout(() => {
console.warn("[mac-picker] the picker session never reported ready");
proc.kill();
settle(false);
}, READY_TIMEOUT_MS);
const settle = (ok: boolean) => {
clearTimeout(timer);
this.starting = null;
resolve(ok);
};
proc.stdout.on("data", (chunk: Buffer) => {
this.lineBuffer += chunk.toString();
const lines = this.lineBuffer.split(/\r?\n/);
this.lineBuffer = lines.pop() ?? "";
for (const line of lines) {
if (!line.trim()) {
continue;
}
const event = parseEvent(line);
if (event?.event === "picker-session-ready") {
this.proc = proc;
console.info(`[mac-picker] picker session started (pid ${proc.pid})`);
settle(true);
continue;
}
this.route(line, event);
}
});
proc.stderr.on("data", (chunk: Buffer) => {
const text = chunk.toString();
if (this.take) {
this.take.stderr.write(text);
} else {
console.warn(`[mac-picker] ${text.trim()}`);
}
});
proc.stdin.on("error", (error) => console.warn("[mac-picker] command pipe error:", error));
proc.on("error", (error) => {
console.warn("[mac-picker] helper error:", error);
settle(false);
});
proc.once("close", (code, signal) => {
this.reportSessionExit(code, signal);
this.onSessionGone(signal ?? "SIGTERM");
settle(false);
});
});
return this.starting;
}
/**
* Shows Apple's picker. Resolves with what the user picked, or null when they cancelled
* or the picker could not open. No timeout: a person is choosing.
*/
async present(
excludedWindowIds: number[],
hideDesktopIcons = false,
): Promise<MacPickerSelection | null> {
if (!(await this.start())) {
return null;
}
// A second click while the picker is up re-presents it; the first caller gets the
// same answer as the second.
const previous = this.pendingPick;
const answer = new Promise<MacPickerSelection | null>((resolve) => {
this.pendingPick = (selection) => {
previous?.(selection);
resolve(selection);
};
});
this.presentedExclusions = [...excludedWindowIds];
const sent = this.send({
command: "present",
excludedWindowIds,
modes: ["display", "window"],
hideDesktopIcons,
});
if (sent) {
console.info("[mac-picker] showing Apple's picker");
} else {
// Nothing will ever answer a picker that was never shown: say so now rather than
// leave the caller (and the HUD it hid) waiting on the session's exit.
console.warn("[mac-picker] could not reach the picker session to show the picker");
this.resolvePick(null);
}
return answer;
}
/**
* Starts a take from the retained pick. The returned object stands in for the per-take
* helper process; see the module comment.
*/
startTake(request: unknown): ChildProcessWithoutNullStreams {
if (!this.proc || !this.selection) {
throw new Error("Pick a screen or window in the system picker first.");
}
if (this.take && !this.take.ended) {
throw new Error("A recording is already running in the picker session.");
}
const take = new TakeProcess((line) => this.send(line));
this.take = take;
this.send({ command: "start", request });
return take as unknown as ChildProcessWithoutNullStreams;
}
/** Ends the session with the app. Closing stdin makes the helper stop and exit. */
dispose() {
this.disposed = true;
this.proc?.stdin.end();
this.proc = null;
}
private send(command: string | Record<string, unknown>): boolean {
const proc = this.proc;
if (!proc || !proc.stdin.writable) {
return false;
}
proc.stdin.write(`${typeof command === "string" ? command : JSON.stringify(command)}\n`);
return true;
}
private route(line: string, event: HelperEvent | null) {
switch (event?.event) {
case "picker-presented":
return;
case "picker-selected": {
const selection = parsePickerSelection(event);
if (selection) {
this.selection = selection;
this.selectionExclusions = this.presentedExclusions;
this.selectionExcludesApp = event.excludesApp === true;
// Kind and size only: a window's title is the user's business, and these
// lines end up pasted into public bug reports.
const { width, height } = selection.bounds;
console.info(`[mac-picker] picked a ${selection.kind} (${width}x${height})`);
} else {
console.warn("[mac-picker] the picker answered with a pick that has no frame");
}
this.resolvePick(selection);
return;
}
case "picker-cancelled":
case "picker-failed":
if (event.event === "picker-failed") {
console.warn("[mac-picker] the picker failed:", event.message);
} else {
console.info("[mac-picker] the picker was cancelled");
}
this.resolvePick(null);
return;
case "take-ended":
this.take?.end();
this.take = null;
return;
}
if (this.take) {
this.take.deliver(line, event);
} else if (event?.event === "error" || event?.event === "warning") {
console.warn("[mac-picker] session:", line);
}
}
private resolvePick(selection: MacPickerSelection | null) {
const pending = this.pendingPick;
this.pendingPick = null;
pending?.(selection);
}
/**
* Says how the helper went, and what it took with it. Without this a helper that dies
* while Apple's picker is up leaves no trace: the HUD comes back with nothing picked and
* the app prints nothing at all (#1021). Silent when the app ended the session itself.
*/
private reportSessionExit(code: number | null, signal: NodeJS.Signals | null) {
if (this.disposed) {
return;
}
const how = signal ? `signal ${signal}` : `code ${code}`;
let during = "";
if (this.pendingPick) {
during = " while Apple's picker was up";
} else if (this.take && !this.take.ended) {
during = " during a take";
}
console.warn(`[mac-picker] the picker session exited (${how})${during}`);
}
private onSessionGone(signal: NodeJS.Signals) {
this.proc = null;
this.lineBuffer = "";
// The pick lived in that process; it is gone with it.
this.selection = null;
this.take?.end(signal);
this.take = null;
this.resolvePick(null);
}
}