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 } from "node:child_process";
/**
* Stopping a native macOS (ScreenCaptureKit) recording, as a unit that can be
* tested — the macOS twin of `nativeWindowsCaptureStop.ts`, which exists for
* the same reason: `electron/ipc/handlers.ts` cannot be loaded from a test.
*
* # Why the stop settles on the helper's exit, not on its first error
*
* The helper speaks two kinds of error. `writer-failed-during-capture` and
* `capture-stopped-with-error` say that the take ended on its own; the helper
* then shuts down by itself (issue #621, PR #655) and still reports how that
* went, with `recording-stopped` or `writer-failed`. The stop used to reject on
* the first `"event":"error"` in the whole buffered output, so a take whose
* capture stopped but whose file was finalized was thrown away with an error,
* and a take whose writer died was rejected before the helper had finished
* writing anything down.
*
* The helper always exits once it has received `stop` and finished (its command
* loop runs `await recorder.stop(); exit(0)`), after its last word. So the one
* moment at which the output is complete and the file is no longer being
* written is the process's `close`. That is also where Windows settles.
*/
/** Outer bound on a stop. Unchanged from the wait this replaced. */
export const NATIVE_MAC_CAPTURE_STOP_TIMEOUT_MS = 30_000;
/** How the helper process ended, as Node's `close` reports it. */
export type NativeMacCaptureExit = {
code: number | null;
signal: NodeJS.Signals | null;
};
export type NativeMacCaptureStopResult =
| {
ok: true;
screenVideoPath: string;
/** Why the take ended before the user stopped it, when it did. */
warning?: string;
}
| {
ok: false;
reason: "helper-failed" | "stop-timeout";
message: string;
/** False when the helper was still running when the wait gave up. */
exited: boolean;
};
/**
* Errors after which the helper stops itself and still reports a terminal
* outcome. They explain a stop; they never settle one.
*/
const INTERRUPTION_ERROR_CODES = new Set([
"writer-failed-during-capture",
"capture-stopped-with-error",
]);
/** Shown when a finished take could not capture the system audio it was asked for. */
export const SYSTEM_AUDIO_LOST_WARNING = "System audio could not be recorded for this take.";
type HelperEvent = Record<string, unknown>;
function parseHelperEvent(line: string): HelperEvent | null {
const candidates = [line];
// stdout and stderr drain into one buffer chunk by chunk, so a stderr line can
// end up glued onto the front of a JSON event.
const braceIndex = line.indexOf("{");
if (braceIndex > 0) {
candidates.push(line.slice(braceIndex));
}
for (const candidate of candidates) {
try {
const parsed = JSON.parse(candidate);
if (parsed && typeof parsed === "object" && typeof parsed.event === "string") {
return parsed as HelperEvent;
}
} catch {
// Not an event; the helper log also carries plain text.
}
}
return null;
}
export function readNativeMacHelperEvents(output: string): HelperEvent[] {
const events: HelperEvent[] = [];
for (const line of output.split(/\r?\n/)) {
const trimmed = line.trim();
if (!trimmed) {
continue;
}
const event = parseHelperEvent(trimmed);
if (event) {
events.push(event);
}
}
return events;
}
/** `Array.prototype.findLast`, which the project's ES library target predates. */
function lastWhere(events: HelperEvent[], matches: (event: HelperEvent) => boolean) {
for (let index = events.length - 1; index >= 0; index -= 1) {
if (matches(events[index])) {
return events[index];
}
}
return undefined;
}
function messageOf(event: HelperEvent) {
if (typeof event.message === "string" && event.message.trim()) {
return event.message.trim();
}
return typeof event.code === "string" ? event.code : "Native macOS capture failed";
}
function describeExit(exit: NativeMacCaptureExit) {
if (exit.signal) {
return `The recorder stopped unexpectedly (signal ${exit.signal}).`;
}
if (exit.code === 0) {
return "The recorder exited without reporting a finished recording.";
}
return `The recorder stopped unexpectedly (exit code ${exit.code ?? "unknown"}).`;
}
/**
* What the helper's output says about a stop, or null while it has not said
* enough yet. `exit` is null while the helper is still running.
*/
export function readNativeMacStopOutcome(
output: string,
exit: NativeMacCaptureExit | null,
targetPath: string | null,
): NativeMacCaptureStopResult | null {
const events = readNativeMacHelperEvents(output);
const isInterruption = (event: HelperEvent) =>
typeof event.code === "string" && INTERRUPTION_ERROR_CODES.has(event.code);
const stopped = lastWhere(events, (event) => event.event === "recording-stopped");
const errors = events.filter((event) => event.event === "error");
const interruption = errors.find(isInterruption);
const failure = lastWhere(errors, (event) => !isInterruption(event));
// Not a failure of the take: the video and every other track are fine. But the system
// audio the user asked for is silence, and a finished take with no word about it would
// only be found out on playback.
const systemAudioLost = events.some(
(event) => event.event === "warning" && event.code === "system-audio-unavailable",
);
const exited = exit !== null;
// A finalized file outranks anything said before it: this is the take the
// user would otherwise lose.
if (stopped) {
const reportedPath =
typeof stopped.screenPath === "string" && stopped.screenPath ? stopped.screenPath : null;
const screenVideoPath = reportedPath ?? targetPath;
if (!screenVideoPath) {
return {
ok: false,
reason: "helper-failed",
message: "Native macOS capture did not return an output path.",
exited,
};
}
const warnings: string[] = [];
if (interruption) {
const reason = messageOf(interruption).replace(/[.\s]+$/, "");
warnings.push(`Recording ended early (${reason}). The part recorded until then was saved.`);
}
if (systemAudioLost) {
warnings.push(SYSTEM_AUDIO_LOST_WARNING);
}
return warnings.length > 0
? { ok: true, screenVideoPath, warning: warnings.join(" ") }
: { ok: true, screenVideoPath };
}
if (failure) {
// The interruption is what the user can act on ("the video file could not be
// written"); the terminal error that follows it is the raw NSError behind it.
return {
ok: false,
reason: "helper-failed",
message: messageOf(interruption ?? failure),
exited,
};
}
if (!exit) {
return null;
}
// Exit 0 with no terminal word is the command loop reaching stdin EOF without a
// `stop` — nothing in the app closes that pipe, and `stop()` always reports
// before its exit(0). It keeps the meaning the stop wait gave it before this
// module (the requested file), except after an interruption, when nothing
// finalized that file.
if (exit.code === 0 && !exit.signal && targetPath && !interruption) {
return { ok: true, screenVideoPath: targetPath };
}
return {
ok: false,
reason: "helper-failed",
message: interruption ? messageOf(interruption) : describeExit(exit),
exited: true,
};
}
/**
* Waits for the helper to finish a stop and says how it went.
*
* Resolves rather than rejects, like the Windows wait: the caller needs to tell
* a helper failure apart from a timeout, and a discard has to proceed either
* way.
*/
export function waitForNativeMacCaptureStop(options: {
proc: ChildProcessWithoutNullStreams;
/** Path we asked the helper to write, used when it exits 0 without saying so. */
targetPath: string | null;
/** The accumulated helper output; read lazily so late chunks are included. */
readOutput: () => string;
/**
* How the helper exited, once its output drain has seen `close`. Read from the
* drain rather than from `proc.exitCode`, because `exit` can fire before the
* last output chunk has been read.
*/
readExit: () => NativeMacCaptureExit | null;
timeoutMs?: number;
}): Promise<NativeMacCaptureStopResult> {
const { proc, targetPath, readOutput, readExit } = options;
const timeoutMs = options.timeoutMs ?? NATIVE_MAC_CAPTURE_STOP_TIMEOUT_MS;
const settleFromExit = (exit: NativeMacCaptureExit): NativeMacCaptureStopResult =>
readNativeMacStopOutcome(readOutput(), exit, targetPath) ?? {
ok: false,
reason: "helper-failed",
message: describeExit(exit),
exited: true,
};
// The helper may already be gone: killed or crashed. (One that stopped itself
// stays alive until it is sent `stop`.) Node never re-emits `close`, so waiting
// for one would burn the whole timeout on a recorder that has nothing left to say.
const alreadyExited = readExit();
if (alreadyExited) {
return Promise.resolve(settleFromExit(alreadyExited));
}
return new Promise<NativeMacCaptureStopResult>((resolve) => {
const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
cleanup();
resolve(settleFromExit(readExit() ?? { code, signal }));
};
const onError = (error: Error) => {
cleanup();
resolve({
ok: false,
reason: "helper-failed",
message: error.message,
exited: proc.exitCode !== null || proc.signalCode !== null,
});
};
const cleanup = () => {
clearTimeout(timer);
proc.off("close", onClose);
proc.off("error", onError);
};
const timer = setTimeout(() => {
cleanup();
// A helper that already reported a finalized file but has not exited still
// left a complete recording behind. It is not killed here: one that has not
// reported may be inside a slow finishWriting, and this helper has no
// shutdown ceiling that would make killing it safe.
const outcome = readNativeMacStopOutcome(readOutput(), null, targetPath);
resolve(
outcome ?? {
ok: false,
reason: "stop-timeout",
message: "The recorder did not finish saving in time.",
exited: false,
},
);
}, timeoutMs);
proc.once("close", onClose);
proc.once("error", onError);
});
}
/**
* Sends `stop` to a helper that can still hear it. Returns whether it was sent.
*
* A helper that already exited has closed its command pipe, and writing to it
* raises EPIPE or ERR_STREAM_DESTROYED on `proc.stdin`.
*/
export function sendNativeMacStopCommand(proc: ChildProcessWithoutNullStreams): boolean {
if (proc.exitCode !== null || proc.signalCode !== null || !proc.stdin.writable) {
return false;
}
proc.stdin.write("stop\n");
return true;
}
/**
* The files a discarded take leaves behind, whatever its stop returned: a take
* thrown away after its writer died used to stay on disk as an orphan .mp4,
* because removing it depended on the stop having worked.
*/
export function nativeMacDiscardTargets(
result: NativeMacCaptureStopResult,
targetPath: string | null,
): string[] {
const screenVideoPath = result.ok ? result.screenVideoPath : targetPath;
return screenVideoPath ? [screenVideoPath, `${screenVideoPath}.cursor.json`] : [];
}