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
// Headless CLI mode: boots Electron without HUD/tray/menu, drives a hidden
// renderer window (windowType=cli-export | cli-record) that reuses the app's
// existing export and recording pipelines, and reports progress on stdio.
import fs from "node:fs/promises";
import path from "node:path";
import readline from "node:readline";
import { app, BrowserWindow, ipcMain, Menu, net, session, systemPreferences } from "electron";
import type { CliProgressEvent, CliSourcesResult } from "../../src/lib/cliContracts";
import { renameWithRetry } from "../atomic-rename";
import { isDiagnosticModeEnabled } from "../diagnostics/main-log-file";
import { getInstallChannel, ownsItsUpdates } from "../install-channel";
import { getSelectedDesktopSource, registerIpcHandlers } from "../ipc/handlers";
import { openVideoInHiddenWindow } from "../mcp/hidden-video";
import { serveMcpOverStdio } from "../mcp/stdio-server";
import { readReleaseLookup, refreshReleaseLookup, updateNotice } from "../mcp/update-notice";
import { registerSttIpc, shutdownStt } from "../stt";
import { sendUsagePing, USAGE_PING_INTERVAL_MS } from "../usage-ping";
import { createRunnerWindow } from "../windows";
import { CLI_USAGE, type CliCommand } from "./args";
import { openGuiFromCli } from "./openGui";
import { runInfoCommand, runPackCommand } from "./projectCommands";
import { createRunnerHost } from "./runnerHost";
import { isolateCliSessionData } from "./sessionData";
import { openStdin } from "./stdin";
interface CliOutput {
json: boolean;
event(event: string, data?: Record<string, unknown>): void;
info(message: string): void;
error(message: string): void;
progress(p: CliProgressEvent): void;
}
// stdout/stderr may be a closed pipe (`openscreen export | head`); writes must
// never take the process down — Electron would show a GUI error dialog.
function safeWrite(stream: NodeJS.WriteStream, text: string): void {
try {
stream.write(text);
} catch {
// EPIPE or closed stream; drop the output.
}
}
// Timestamped startup milestones on stderr. A process that stops answering says
// nothing about where it stopped, and `openscreen sources` has hung on roughly
// half of its headless CI runs while emitting no renderer output whatsoever --
// which rules out everything after the renderer starts and leaves everything
// before it. These narrow that down without guessing.
//
// Gated on the existing diagnostic flag, so a normal run is byte-identical and
// no other packaging path can observe this.
const startedAt = Date.now();
function milestone(name: string): void {
if (!isDiagnosticModeEnabled()) return;
safeWrite(
process.stderr,
`[milestone +${Date.now() - startedAt}ms] ${name}
`,
);
}
function createOutput(json: boolean): CliOutput {
const isTty = process.stdout.isTTY === true;
let progressLineActive = false;
let lastProgressText = "";
const clearProgressLine = () => {
if (progressLineActive) {
safeWrite(process.stdout, "\n");
progressLineActive = false;
}
};
return {
json,
event(event, data = {}) {
if (json) {
safeWrite(process.stdout, `${JSON.stringify({ event, ...data })}\n`);
}
},
info(message) {
if (json) return;
clearProgressLine();
safeWrite(process.stdout, `${message}\n`);
},
error(message) {
clearProgressLine();
if (json) {
safeWrite(process.stdout, `${JSON.stringify({ event: "error", message })}\n`);
} else {
safeWrite(process.stderr, `Error: ${message}\n`);
}
},
progress(p) {
if (json) {
safeWrite(process.stdout, `${JSON.stringify({ event: "progress", ...p })}\n`);
return;
}
const frames =
p.currentFrame !== undefined && p.totalFrames
? ` frame ${p.currentFrame}/${p.totalFrames}`
: "";
const eta =
p.estimatedTimeRemaining !== undefined && Number.isFinite(p.estimatedTimeRemaining)
? ` ETA ${Math.max(0, Math.round(p.estimatedTimeRemaining))}s`
: "";
const phase = p.phase ? ` [${p.phase}]` : "";
const text = `Exporting ${Math.round(p.percentage)}%${frames}${eta}${phase}`;
if (isTty) {
if (text === lastProgressText) return;
lastProgressText = text;
safeWrite(process.stdout, `\r\x1b[2K${text}`);
progressLineActive = true;
} else {
// Piped/non-TTY consumers get one line per whole-percent (or phase) change.
const coarse = `${Math.round(p.percentage)}%${phase}`;
if (coarse === lastProgressText) return;
lastProgressText = coarse;
safeWrite(process.stdout, `${text}\n`);
}
},
};
}
function registerAppHandlersForCli(cliWindowRef: () => BrowserWindow | null) {
// The recording/export pipelines are driven through the same IPC surface the
// GUI uses. Window-management callbacks become no-ops; "switch-to-editor"
// (fired by the recorder hook after it stores a finished session) is handled
// by the runner itself, so an inert factory is enough.
const noop = () => {
// Intentionally empty: CLI mode has no HUD/tray/editor windows to manage.
};
const notAvailable = () => {
throw new Error("Window not available in CLI mode");
};
return registerIpcHandlers(
noop, // createEditorWindow: recording finished; runner drives completion
notAvailable, // createSourceSelectorWindow
notAvailable, // createCountdownOverlayWindow
notAvailable, // createNotesWindow
cliWindowRef,
() => null,
() => null,
() => null,
noop, // onRecordingStateChange: no tray to update
noop, // switchToHud
);
}
function printSources(output: CliOutput, sources: CliSourcesResult): void {
if (output.json) {
// The "done" event already carries the payload; nothing extra to print.
return;
}
const lines: string[] = [];
lines.push("Displays:");
for (const display of sources.displays) {
lines.push(` ${display.index} ${display.name} (${display.id})`);
}
lines.push("Windows:");
if (sources.windows.length === 0) {
lines.push(" (none)");
}
for (const win of sources.windows) {
lines.push(` - ${win.name}`);
}
lines.push("Microphones:");
if (sources.microphoneLabelsUnavailable) {
lines.push(" (labels unavailable — grant microphone permission to see device names)");
} else if (sources.microphones.length === 0) {
lines.push(" (none)");
}
for (const mic of sources.microphones) {
lines.push(` - ${mic.label}`);
}
lines.push("Cameras:");
if (sources.cameraLabelsUnavailable) {
lines.push(" (labels unavailable — grant camera permission to see device names)");
} else if (sources.cameras.length === 0) {
lines.push(" (none)");
}
for (const camera of sources.cameras) {
lines.push(` - ${camera.label}`);
}
output.info(lines.join("\n"));
}
async function writeProjectFile(projectOut: string, projectData: unknown): Promise<void> {
await fs.mkdir(path.dirname(projectOut), { recursive: true });
await fs.writeFile(projectOut, JSON.stringify(projectData, null, 2), "utf8");
}
function setupRecordStopSignals(stop: (reason: string) => void): void {
// SIGINT covers Ctrl+C everywhere; SIGTERM never fires on Windows, where
// stdin "stop" or --duration are the graceful alternatives (see website/docs/cli.md).
process.on("SIGINT", () => stop("SIGINT"));
process.on("SIGTERM", () => stop("SIGTERM"));
try {
// Touching process.stdin can throw on Windows GUI-subsystem builds when
// spawned with stdio "ignore"; signals and --duration still work then.
const rl = readline.createInterface({ input: openStdin() });
rl.on("line", (line) => {
const trimmed = line.trim().toLowerCase();
if (trimmed === "stop" || trimmed === "q" || trimmed === "quit") {
stop("stdin");
}
});
rl.on("close", () => {
// stdin EOF is not a stop signal: agents may spawn the CLI with
// stdin closed and stop it via SIGINT/--duration instead.
});
} catch {
// stdin unavailable; signals and --duration still work.
}
}
/** Both file-only commands write through the same EPIPE-safe stdout writer. */
const writeStdout = (text: string) => safeWrite(process.stdout, text);
export function runCli(command: CliCommand): void {
milestone(`runCli entered (${command.kind})`);
if (command.kind === "help") {
safeWrite(process.stdout, CLI_USAGE);
app.exit(0);
return;
}
if (command.kind === "error") {
safeWrite(process.stderr, `Error: ${command.message}\n\n${CLI_USAGE}`);
app.exit(2);
return;
}
isolateCliSessionData(app);
const output = createOutput(command.json === true);
// stdout belongs to the CLI protocol (NDJSON / progress); reroute the app's
// own console chatter (e.g. "[native-sck] starting…") to stderr.
const stringifyArg = (value: unknown): string => {
if (typeof value === "string") return value;
if (value instanceof Error) return value.stack ?? value.message;
try {
return JSON.stringify(value) ?? String(value);
} catch {
return String(value);
}
};
for (const level of ["log", "info", "warn", "error", "debug"] as const) {
console[level] = (...args: unknown[]) => {
safeWrite(process.stderr, `${args.map(stringifyArg).join(" ")}\n`);
};
}
// A consumer closing the pipe (`openscreen export | head`) must not crash the
// process, and main-process exceptions must never surface as Electron's GUI
// error dialog — report on stderr and exit non-zero instead.
const ignoreStreamError = () => {
// Intentionally empty: EPIPE from a closed consumer is not an error here.
};
process.stdout.on("error", ignoreStreamError);
process.stderr.on("error", ignoreStreamError);
process.on("uncaughtException", (error) => {
safeWrite(process.stderr, `Fatal: ${error?.stack ?? String(error)}\n`);
app.exit(1);
});
process.on("unhandledRejection", (reason) => {
safeWrite(
process.stderr,
`Fatal (unhandled rejection): ${reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)}\n`,
);
app.exit(1);
});
// Set once cli-done has been received; suppresses the window-all-closed
// failure path during the normal teardown race after a successful run.
let finished = false;
// GPU may be unavailable in CI/servers; let Chromium fall back to SwiftShader
// so the WebGL-based export renderer still works.
app.commandLine.appendSwitch("enable-unsafe-swiftshader");
// Never show the dock icon for CLI runs, and hand a launch of the app that macOS routed
// to this process on to the GUI (see openGui.ts).
if (process.platform === "darwin") {
app.dock?.hide();
app.on("activate", () => openGuiFromCli(process.execPath, Date.now(), () => app.dock?.hide()));
// No application menu either. That menu shows whenever this hidden process comes to the
// front, as it does while it hands a launch on to the GUI, and its Quit (Cmd+Q) would end
// the agent's MCP server rather than anything the user knowingly started. On macOS
// Electron installs its default menu on `will-finish-launching`, unless a menu was set
// first, so this null has to come now, while the main script loads. It only stops that
// default: a null never touches the native menu, which still holds a bare Quit. The empty
// menu set once the app is ready replaces that one.
Menu.setApplicationMenu(null);
void app.whenReady().then(() => Menu.setApplicationMenu(Menu.buildFromTemplate([])));
}
app.on("window-all-closed", () => {
// Completion is signalled via cli-done; a vanished window is a failure
// only while the run is still in flight. The MCP server outlives its runners.
if (finished || command.kind === "mcp") return;
output.error("Renderer window closed unexpectedly");
app.exit(1);
});
milestone("awaiting app ready");
void app
.whenReady()
.then(async () => {
milestone("app ready");
if (command.kind === "info") {
const code = await runInfoCommand(command.projectPath, command.json === true, writeStdout);
app.exit(code);
return;
}
if (command.kind === "pack") {
const code = await runPackCommand(
command.projectPath,
command.outDir,
command.json === true,
writeStdout,
);
app.exit(code);
return;
}
milestone("resolving userData path");
const userDataDir = app.getPath("userData");
milestone(`userData = ${userDataDir}`);
// No recordings folder made here: it may be one the user chose, on a drive that is
// gone, and `export` has no use for it. A record run makes it in the storage check
// every take goes through, which reports such a folder instead of crashing the run.
// Media/screen permissions for the renderer (mic metering, future browser
// capture paths). Mirrors the GUI allowlist.
const allowed = [
"media",
"audioCapture",
"microphone",
"videoCapture",
"camera",
"screen",
"display-capture",
];
session.defaultSession.setPermissionCheckHandler((_wc, permission) =>
allowed.includes(permission),
);
session.defaultSession.setPermissionRequestHandler((_wc, permission, callback) =>
callback(allowed.includes(permission)),
);
// Browser-pipeline recording fallback (e.g. Linux, missing native helper)
// resolves the pre-selected source exactly like the GUI does.
session.defaultSession.setDisplayMediaRequestHandler(
(request, callback) => {
const source = getSelectedDesktopSource();
if (!request.videoRequested || !source) {
callback({});
return;
}
callback({
video: source,
...(request.audioRequested && process.platform === "win32"
? { audio: "loopback" as const }
: {}),
});
},
{ useSystemPicker: false },
);
milestone("session permission handlers registered");
if (command.kind === "record" && command.mic && process.platform === "darwin") {
const micStatus = systemPreferences.getMediaAccessStatus("microphone");
if (micStatus !== "granted") {
await systemPreferences.askForMediaAccess("microphone");
}
}
milestone("media access checked");
let cliWindow: BrowserWindow | null = null;
const { agentServices } = registerAppHandlersForCli(() => cliWindow);
milestone("app handlers registered");
// Speech-to-text backs the captions command; registered by the GUI boot
// path (main.ts) rather than registerIpcHandlers.
registerSttIpc(ipcMain);
milestone("stt ipc registered");
// Registered by the GUI boot path (main.ts) rather than registerIpcHandlers;
// the renderer's i18n init invokes it unconditionally.
ipcMain.handle("set-locale", () => {
// Locale only affects GUI menus/tray, which do not exist in CLI mode.
});
ipcMain.handle("update-global-shortcut", () => ({ success: false }));
// The latest runner is the app's "main window" for the recording handlers, as the
// HUD is in the GUI.
const runners = createRunnerHost(ipcMain, (windowType): BrowserWindow => {
const runnerWindow = createRunnerWindow(windowType);
cliWindow = runnerWindow;
return runnerWindow;
});
if (command.kind === "mcp") {
// Only where the app updates itself: elsewhere a package manager already does, and
// opening the app would not change that.
const tellsAboutUpdates = app.isPackaged && ownsItsUpdates(getInstallChannel());
await serveMcpOverStdio({
...agentServices,
userDataDir,
runners,
openVideo: openVideoInHiddenWindow,
updateNotice: tellsAboutUpdates
? (updateNotice(app.getVersion(), readReleaseLookup(userDataDir)) ?? undefined)
: undefined,
// The Whisper helper is a process of its own: it must not outlive this one.
onClose: () => void shutdownStt().finally(() => app.exit(0)),
});
milestone("mcp server listening on stdio");
if (tellsAboutUpdates) {
refreshReleaseLookup({
userData: userDataDir,
currentVersion: app.getVersion(),
fetchLatest: (url, init) => net.fetch(url, init),
}).catch(() => {
// Offline or rate-limited: the next session looks again. Nothing to report,
// and stdout is the protocol.
});
}
// An install driven only by an agent is an active install too. Same ping, state
// file and opt-outs as the GUI's, and it writes nothing: stdout is the protocol.
// The other commands stay silent: they are scripts and CI more often than people.
const pingUsage = () =>
void sendUsagePing(userDataDir, {
version: app.getVersion(),
os: process.platform,
arch: process.arch,
channel: getInstallChannel(),
surface: "mcp",
});
pingUsage();
setInterval(pingUsage, USAGE_PING_INTERVAL_MS).unref();
return;
}
if (command.kind === "record") {
const stop = (reason: string) => {
output.info(`Stopping recording (${reason})…`);
output.event("stopping", { reason });
cliWindow?.webContents.send("cli-stop-recording");
};
setupRecordStopSignals(stop);
}
// The project as the captions runner reads it. Transcribing takes minutes; a save made
// meanwhile must not be lost under the runner's older copy.
const captionsSource =
command.kind === "captions"
? await fs.readFile(command.projectPath, "utf8").catch(() => null)
: null;
milestone("cli ipc registered; starting the runner");
const run = runners.start(command, {
onRequest: () => milestone("renderer asked for the request"),
onLog: (level, message) => {
if (level === "error") {
output.error(message);
} else {
output.info(message);
output.event("log", { message });
}
},
onProgress: (progress) => output.progress(progress),
});
const runnerWindow = run.window;
milestone(`runner window created (${command.kind})`);
runnerWindow.webContents.on("did-finish-load", () => milestone("renderer did-finish-load"));
runnerWindow.webContents.on("dom-ready", () => milestone("renderer dom-ready"));
// Surface renderer console errors/warnings on stderr — the hidden window
// has no other way to show what went wrong (toasts are invisible).
runnerWindow.webContents.on("console-message", (details) => {
if (details.level === "error" || details.level === "warning") {
safeWrite(process.stderr, `[renderer] ${details.message}\n`);
}
});
// A crash or a failed load ends the run through `run.done`, reported below.
app.on("child-process-gone", (_e, details) => {
milestone(`child-process-gone: ${details.type} (${details.reason})`);
});
output.event("started", { command: command.kind });
const result = await run.done;
milestone(`renderer reported done (success=${result.success})`);
finished = true;
try {
if (result.success && command.kind === "record" && command.projectOut) {
if (result.projectData !== undefined) {
await writeProjectFile(command.projectOut, result.projectData);
result.projectPath = command.projectOut;
}
}
if (result.success && command.kind === "captions" && result.projectData !== undefined) {
// Written beside the file first, checked, then renamed over it: a reader never sees
// a half-written project, and the window left for a save to slip in is the rename.
// ponytail: no cross-process file lock exists to close it; add one if the app
// ever saves this file while the CLI runs.
// The real file, not a symlink to it, keeping its permissions.
const target = await fs.realpath(command.projectPath);
const { mode } = await fs.stat(target);
const tmpPath = `${target}.${process.pid}.tmp`;
// "wx": a file or symlink already at that path is refused, never written through,
// and so never removed below either.
await fs.writeFile(tmpPath, JSON.stringify(result.projectData, null, 2), {
encoding: "utf8",
mode: 0o600,
flag: "wx",
});
try {
await fs.chmod(tmpPath, mode & 0o777);
const current = await fs.readFile(target, "utf8").catch(() => null);
if (current !== captionsSource) {
throw new Error(
`${command.projectPath} changed while it was being captioned, so nothing was written. Run captions again.`,
);
}
await renameWithRetry(tmpPath, target);
} finally {
await fs.rm(tmpPath, { force: true }).catch(() => undefined);
}
}
// -o writes where no wrapper can redirect. stdout itself is fine --
// Chromium logs to stderr -- but a caller does not control what wraps
// this process, and xvfb-run on Ubuntu merges the two, which is enough
// to make `sources --json | jq` fail under the very tool used to run a
// GUI binary headlessly.
if (result.success && command.kind === "sources" && command.jsonOutPath && result.sources) {
// Same as writeProjectFile above: `record --project out/x` creates
// `out/`, so `sources -o out/x.json` has to as well. Without it a
// fully successful enumeration is lost on every channel at once --
// the ENOENT lands in the catch below, which clears result.success
// and so skips printSources and the `done` payload alike.
await fs.mkdir(path.dirname(command.jsonOutPath), { recursive: true });
// Write beside the target and rename over it. writeFile truncates
// first, so a failure part-way through -- a full disk is the easy
// case -- would leave a half-written file where website/docs/cli.md promises
// an earlier run's result is untouched by a later failure. rename is
// atomic within a directory, so the reader sees the old file or the
// new one and never a torn one.
const tmpOutPath = `${command.jsonOutPath}.${process.pid}.tmp`;
try {
await fs.writeFile(tmpOutPath, `${JSON.stringify(result.sources, null, 2)}\n`, "utf8");
await renameWithRetry(tmpOutPath, command.jsonOutPath);
} catch (writeError) {
// Best-effort: the original error is what the caller needs to see.
await fs.rm(tmpOutPath, { force: true }).catch(() => undefined);
throw writeError;
}
}
} catch (error) {
result.success = false;
result.error = `Run succeeded but writing the output file failed: ${String(error)}`;
}
if (result.success) {
for (const warning of result.warnings ?? []) {
output.info(`Warning: ${warning}`);
output.event("warning", { message: warning });
}
if (command.kind === "sources" && result.sources) {
printSources(output, result.sources);
} else if (command.kind === "captions") {
output.info(
`Captions on: ${result.captionCount ?? 0} caption(s) from the transcript → ${result.projectPath}`,
);
} else if (command.kind === "export") {
output.info(`Exported ${result.format ?? ""} → ${result.outputPath}`);
} else {
output.info(`Recording saved → ${result.screenVideoPath}`);
if (result.cursorDataPath) output.info(`Cursor data → ${result.cursorDataPath}`);
if (result.projectPath) output.info(`Project → ${result.projectPath}`);
}
output.event("done", { ...result });
} else {
output.error(result.error ?? "Unknown failure");
output.event("done", { success: false, error: result.error });
}
// Give the renderer a beat to resolve the invoke before exiting.
// and stop the Whisper helper `captions` started, which would outlive this process.
setTimeout(() => void shutdownStt().finally(() => app.exit(result.success ? 0 : 1)), 50);
})
.catch((error) => {
output.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
app.exit(1);
});
}