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
// Pure argv parser for the OpenScreen CLI. No Electron imports so it can be
// unit-tested under plain vitest.
import path from "node:path";
import {
CAPTION_WORDS_PER_LINE_MAX,
CAPTION_WORDS_PER_LINE_MIN,
} from "../../src/lib/ai-edition/captions/wordsPerLine";
import {
type CliExportRequest,
type CliRecordRequest,
type CliRequest,
isAudioExportFormat,
} from "../../src/lib/cliContracts";
import {
GIF_SIZE_PRESETS,
type GifSizePreset,
MP4_FRAME_RATES,
} from "../../src/lib/exporter/types";
export interface CliInfoCommand {
kind: "info";
projectPath: string;
}
export interface CliHelpCommand {
kind: "help";
}
export interface CliErrorCommand {
kind: "error";
message: string;
}
/** Serve the MCP tools on stdin/stdout, to the agent that started this process. */
export interface CliMcpCommand {
kind: "mcp";
}
export type CliCommand = (
| CliRequest
| CliInfoCommand
| CliPackCommand
| CliMcpCommand
| CliHelpCommand
| CliErrorCommand
) & {
/** Machine-readable NDJSON output on stdout instead of human progress. */
json?: boolean;
/**
* Write the machine-readable result here rather than onto stdout.
*
* stdout is correct as it stands -- Chromium logs to stderr, and nothing this
* process runs writes anywhere it should not. What a caller cannot control is
* the wrapper around it. Ubuntu's xvfb-run, which is how a GUI binary gets run
* headlessly in the first place, folds the command's stderr into its stdout;
* under it, `sources --json | jq` sees Chromium's diagnostics ahead of the JSON
* and fails. That is not hypothetical -- it is what the first attempt to script
* this command did.
*
* A named file is a channel no wrapper can redirect into. It also sidesteps
* shell quoting and encoding, which matters more on Windows than on POSIX.
*
* Note the shapes differ, and website/docs/cli.md says so: stdout carries the payload
* inside the NDJSON `done` envelope because it is one event in a stream, while
* the file carries the bare payload because a file is not a stream. Written on
* success only.
*/
jsonOutPath?: string;
};
const SUBCOMMANDS = new Set([
"export",
"record",
"sources",
"pack",
"captions",
"info",
"mcp",
"help",
"--help",
"-h",
]);
export const CLI_USAGE = `OpenScreen CLI
Usage:
openscreen export <project.openscreen> [options] Render a project to MP4/GIF, or its audio to WAV/M4A
openscreen record [options] Record the screen headlessly
openscreen sources [--json] [-o <file>] List displays, windows, microphones and cameras
openscreen pack <project.openscreen> --out <dir> Copy project + media into one portable folder
openscreen captions <project.openscreen> Transcribe (on-device Whisper) and turn captions on
[--min-words <1-12>] [--max-words <1-12>]
openscreen info <project.openscreen> [--json] Inspect a project file
openscreen mcp Serve the agent tools over MCP on stdio
openscreen help Show this help
Export options:
-o, --out <path> Output file (.mp4, .gif, .wav or .m4a). Default: next to the project file
--format <mp4|gif|wav|m4a>
Override the format stored in the project. wav and m4a write
the project's audio only, as the MP4 export mixes it
--track <audioId> WAV/M4A only: write this imported audio track alone
--quality <medium|good|source>
MP4 quality (default: from project)
--fps <24|30|60> MP4 frame rate (default 60)
--gif-fps <15|20|25|30> GIF frame rate (default: from project)
--gif-size <small|medium|large|original>
GIF size preset (default: from project)
--gif-loop, --no-gif-loop GIF loops forever, or plays once (default: from project)
--auto-zoom Add automatic zooms from cursor telemetry (editor's magic wand)
--audio <file> Mix a voiceover audio file into the MP4 (mp3/wav/m4a)
--audio-mode <mix|replace>
Layer over the recording's audio (default) or replace it
--audio-offset <seconds> Delay before the voiceover starts (default 0)
--json NDJSON progress/result on stdout
Record options (recording is saved into the app's recordings directory):
--display <n> Screen index to record (default 0)
--window <title> Record the first window whose title contains <title>
--mic Capture the default microphone
--mic-device <name> Microphone device name (implies --mic)
--system-audio Capture system audio
--camera Record the default webcam beside the screen
--camera-device <name> Camera device name (implies --camera)
--cursor <editable-overlay|system>
Cursor capture mode (default editable-overlay)
--duration <seconds> Stop automatically after this long
--project <out.openscreen>
Write a ready-to-export project file when done
--json NDJSON events on stdout
Stopping a recording: send SIGINT/SIGTERM, type "stop" + Enter on stdin,
or pass --duration.
`;
function takeValue(argv: string[], i: number, flag: string): [string, number] {
const next = argv[i + 1];
// "" is rejected alongside a missing value: an unset variable in a wrapper
// (`openscreen sources -o "$OUT"`) reaches us as an empty argument, and every
// caller here feeds the result to resolvePath, where path.resolve(cwd, "")
// returns cwd. That turns a typo into a directory path, which then fails much
// later as EISDIR from the write — after the work is done and discarded —
// instead of as the parse error the same mistake gets when the value is
// omitted entirely.
if (next === undefined || next === "" || next.startsWith("--")) {
throw new Error(`${flag} requires a value`);
}
return [next, i + 1];
}
function resolvePath(p: string, cwd: string): string {
return path.isAbsolute(p) ? p : path.resolve(cwd, p);
}
/**
* Extracts CLI arguments from process.argv. Returns null when no subcommand is
* present (normal GUI launch). `firstArgIndex` should be 1 for packaged builds
* and 2 when running via `electron <app-path> ...`.
*/
export function parseCliArgs(
argv: string[],
firstArgIndex: number,
cwd: string = process.cwd(),
): CliCommand | null {
const rawArgs = argv.slice(firstArgIndex).filter((a) => !a.startsWith("--inspect"));
// Skip *leading* Chromium/Electron switches (e.g. the AppImage's required
// `--no-sandbox`) so `Openscreen --no-sandbox export demo.openscreen` still
// enters CLI mode. Only leading dash-tokens are skipped — everything after
// the subcommand belongs to the subcommand parser. `--help`/`-h` are ours.
let subIndex = 0;
while (
subIndex < rawArgs.length &&
rawArgs[subIndex].startsWith("-") &&
rawArgs[subIndex] !== "--help" &&
rawArgs[subIndex] !== "-h"
) {
subIndex++;
}
const args = rawArgs.slice(subIndex);
const sub = args[0];
if (!sub || !SUBCOMMANDS.has(sub)) return null;
if (sub === "help" || sub === "--help" || sub === "-h") return { kind: "help" };
try {
if (sub === "export") return parseExport(args.slice(1), cwd);
if (sub === "record") return parseRecord(args.slice(1), cwd);
if (sub === "sources") return parseSources(args.slice(1), cwd);
if (sub === "pack") return parsePack(args.slice(1), cwd);
if (sub === "captions") return parseCaptions(args.slice(1), cwd);
if (sub === "mcp") {
if (args.length > 1) throw new Error(`Unexpected argument for mcp: ${args[1]}`);
return { kind: "mcp" };
}
return parseInfo(args.slice(1), cwd);
} catch (error) {
return { kind: "error", message: error instanceof Error ? error.message : String(error) };
}
}
function parseExport(args: string[], cwd: string): CliCommand {
const request: CliExportRequest & { json?: boolean } = {
kind: "export",
projectPath: "",
outPath: null,
format: null,
quality: null,
mp4FrameRate: 60,
gifFrameRate: null,
gifSizePreset: null,
gifLoop: null,
autoZoom: false,
audioPath: null,
audioMode: "mix",
audioOffsetSec: 0,
};
for (let i = 0; i < args.length; i++) {
const arg = args[i];
switch (arg) {
case "-o":
case "--out": {
const [value, next] = takeValue(args, i, arg);
request.outPath = resolvePath(value, cwd);
i = next;
break;
}
case "--format": {
const [value, next] = takeValue(args, i, arg);
if (value !== "mp4" && value !== "gif" && !isAudioExportFormat(value)) {
throw new Error(`--format must be mp4, gif, wav or m4a, got "${value}"`);
}
request.format = value;
i = next;
break;
}
case "--quality": {
const [value, next] = takeValue(args, i, arg);
if (value !== "medium" && value !== "good" && value !== "source") {
throw new Error(`--quality must be medium, good or source, got "${value}"`);
}
request.quality = value;
i = next;
break;
}
case "--fps": {
const [value, next] = takeValue(args, i, arg);
const fps = MP4_FRAME_RATES.find((rate) => rate === Number(value));
if (fps === undefined) {
throw new Error(`--fps must be ${MP4_FRAME_RATES.join(", ")}, got "${value}"`);
}
request.mp4FrameRate = fps;
i = next;
break;
}
case "--gif-fps": {
const [value, next] = takeValue(args, i, arg);
const fps = Number(value);
if (fps !== 15 && fps !== 20 && fps !== 25 && fps !== 30) {
throw new Error(`--gif-fps must be 15, 20, 25 or 30, got "${value}"`);
}
request.gifFrameRate = fps;
i = next;
break;
}
case "--gif-size": {
const [value, next] = takeValue(args, i, arg);
const size = (Object.keys(GIF_SIZE_PRESETS) as GifSizePreset[]).find((s) => s === value);
if (size === undefined) {
throw new Error(`--gif-size must be small, medium, large or original, got "${value}"`);
}
request.gifSizePreset = size;
i = next;
break;
}
case "--gif-loop":
case "--no-gif-loop":
request.gifLoop = arg === "--gif-loop";
break;
case "--track": {
const [value, next] = takeValue(args, i, arg);
request.audioTrackId = value;
i = next;
break;
}
case "--auto-zoom":
request.autoZoom = true;
break;
case "--audio": {
const [value, next] = takeValue(args, i, arg);
request.audioPath = resolvePath(value, cwd);
i = next;
break;
}
case "--audio-mode": {
const [value, next] = takeValue(args, i, arg);
if (value !== "mix" && value !== "replace") {
throw new Error(`--audio-mode must be mix or replace, got "${value}"`);
}
request.audioMode = value;
i = next;
break;
}
case "--audio-offset": {
const [value, next] = takeValue(args, i, arg);
const seconds = Number(value);
if (!Number.isFinite(seconds) || seconds < 0) {
throw new Error(
`--audio-offset must be a non-negative number of seconds, got "${value}"`,
);
}
request.audioOffsetSec = seconds;
i = next;
break;
}
case "--json":
request.json = true;
break;
default:
if (arg.startsWith("-")) throw new Error(`Unknown export option: ${arg}`);
if (request.projectPath) throw new Error(`Unexpected extra argument: ${arg}`);
request.projectPath = resolvePath(arg, cwd);
}
}
if (!request.projectPath) throw new Error("export requires a <project.openscreen> path");
if (request.outPath) {
const ext = path.extname(request.outPath).toLowerCase();
const extFormat = ext.slice(1);
if (extFormat !== "mp4" && extFormat !== "gif" && !isAudioExportFormat(extFormat)) {
throw new Error(`--out must end in .mp4, .gif, .wav or .m4a, got "${request.outPath}"`);
}
if (request.format && request.format !== extFormat) {
throw new Error(`--format ${request.format} conflicts with --out extension ${ext}`);
}
request.format = extFormat;
}
// After --out resolves the format, so `--audio … -o out.gif` is caught too.
if (request.audioPath && (request.format === "gif" || isAudioExportFormat(request.format))) {
throw new Error("--audio is only supported for MP4 exports");
}
if (request.audioTrackId && !isAudioExportFormat(request.format)) {
throw new Error("--track is only supported for audio exports (.wav or .m4a)");
}
// The MP4 options: a GIF is sized from the source and has its own frame rate.
if (request.format !== "mp4" && request.format !== null && request.quality) {
throw new Error("--quality is only supported for MP4 exports");
}
if (request.format === "gif" && args.includes("--fps")) {
throw new Error("--fps is only supported for MP4 exports (use --gif-fps)");
}
// And the GIF options, on an MP4 they would not change.
const gifFlag = ["--gif-fps", "--gif-size", "--gif-loop", "--no-gif-loop"].find((flag) =>
args.includes(flag),
);
if (request.format !== "gif" && request.format !== null && gifFlag) {
throw new Error(`${gifFlag} is only supported for GIF exports`);
}
return request;
}
function parseRecord(args: string[], cwd: string): CliCommand {
const request: CliRecordRequest & { json?: boolean } = {
kind: "record",
displayIndex: 0,
windowTitle: null,
mic: false,
micDevice: null,
systemAudio: false,
camera: false,
cameraDevice: null,
cursorMode: "editable-overlay",
durationMs: null,
projectOut: null,
};
for (let i = 0; i < args.length; i++) {
const arg = args[i];
switch (arg) {
case "--display": {
const [value, next] = takeValue(args, i, arg);
const index = Number(value);
if (!Number.isInteger(index) || index < 0) {
throw new Error(`--display must be a non-negative integer, got "${value}"`);
}
request.displayIndex = index;
i = next;
break;
}
case "--window": {
const [value, next] = takeValue(args, i, arg);
request.windowTitle = value;
i = next;
break;
}
case "--mic":
request.mic = true;
break;
case "--mic-device": {
const [value, next] = takeValue(args, i, arg);
request.mic = true;
request.micDevice = value;
i = next;
break;
}
case "--system-audio":
request.systemAudio = true;
break;
case "--camera":
request.camera = true;
break;
case "--camera-device": {
const [value, next] = takeValue(args, i, arg);
request.camera = true;
request.cameraDevice = value;
i = next;
break;
}
case "--cursor": {
const [value, next] = takeValue(args, i, arg);
if (value !== "editable-overlay" && value !== "system") {
throw new Error(`--cursor must be editable-overlay or system, got "${value}"`);
}
request.cursorMode = value;
i = next;
break;
}
case "--duration": {
const [value, next] = takeValue(args, i, arg);
const seconds = Number(value);
if (!Number.isFinite(seconds) || seconds <= 0) {
throw new Error(`--duration must be a positive number of seconds, got "${value}"`);
}
request.durationMs = Math.round(seconds * 1000);
i = next;
break;
}
case "--project": {
const [value, next] = takeValue(args, i, arg);
if (!value.endsWith(".openscreen")) {
throw new Error(`--project must end in .openscreen, got "${value}"`);
}
request.projectOut = resolvePath(value, cwd);
i = next;
break;
}
case "--json":
request.json = true;
break;
default:
throw new Error(`Unknown record option: ${arg}`);
}
}
return request;
}
function parseSources(args: string[], cwd: string): CliCommand {
let json = false;
let jsonOutPath: string | undefined;
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === "--json") {
json = true;
} else if (arg === "-o" || arg === "--out") {
const [value, next] = takeValue(args, i, arg);
jsonOutPath = resolvePath(value, cwd);
i = next;
} else {
throw new Error(`Unknown sources option: ${arg}`);
}
}
return { kind: "sources", json, jsonOutPath };
}
export interface CliPackCommand {
kind: "pack";
projectPath: string;
outDir: string;
}
function parsePack(args: string[], cwd: string): CliCommand {
let projectPath = "";
let outDir = "";
let json = false;
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === "-o" || arg === "--out") {
const [value, next] = takeValue(args, i, arg);
outDir = resolvePath(value, cwd);
i = next;
} else if (arg === "--json") {
json = true;
} else if (arg.startsWith("-")) {
throw new Error(`Unknown pack option: ${arg}`);
} else if (projectPath) {
throw new Error(`Unexpected extra argument: ${arg}`);
} else {
projectPath = resolvePath(arg, cwd);
}
}
if (!projectPath) throw new Error("pack requires a <project.openscreen> path");
if (!outDir) throw new Error("pack requires --out <directory>");
return { kind: "pack", projectPath, outDir, json };
}
function parseCaptions(args: string[], cwd: string): CliCommand {
let projectPath = "";
let minWordsPerCaption = 2;
let maxWordsPerCaption = 7;
let json = false;
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === "--min-words" || arg === "--max-words") {
const [value, next] = takeValue(args, i, arg);
const count = Number(value);
// The editor's caption settings clamp to the same range, so a larger value would
// write a project the editor then shows differently.
if (
!Number.isInteger(count) ||
count < CAPTION_WORDS_PER_LINE_MIN ||
count > CAPTION_WORDS_PER_LINE_MAX
) {
throw new Error(
`${arg} must be an integer from ${CAPTION_WORDS_PER_LINE_MIN} to ${CAPTION_WORDS_PER_LINE_MAX}, got "${value}"`,
);
}
if (arg === "--min-words") minWordsPerCaption = count;
else maxWordsPerCaption = count;
i = next;
} else if (arg === "--json") {
json = true;
} else if (arg.startsWith("-")) {
throw new Error(`Unknown captions option: ${arg}`);
} else if (projectPath) {
throw new Error(`Unexpected extra argument: ${arg}`);
} else {
projectPath = resolvePath(arg, cwd);
}
}
if (!projectPath) throw new Error("captions requires a <project.openscreen> path");
if (minWordsPerCaption > maxWordsPerCaption) {
throw new Error("--min-words cannot exceed --max-words");
}
return { kind: "captions", projectPath, minWordsPerCaption, maxWordsPerCaption, json };
}
function parseInfo(args: string[], cwd: string): CliCommand {
let projectPath = "";
let json = false;
for (const arg of args) {
if (arg === "--json") {
json = true;
} else if (arg.startsWith("-")) {
throw new Error(`Unknown info option: ${arg}`);
} else if (projectPath) {
throw new Error(`Unexpected extra argument: ${arg}`);
} else {
projectPath = resolvePath(arg, cwd);
}
}
if (!projectPath) throw new Error("info requires a <project.openscreen> path");
return { kind: "info", projectPath, json };
}