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";
import { EventEmitter } from "node:events";
import { PassThrough, Writable } from "node:stream";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
type NativeMacCaptureExit,
nativeMacDiscardTargets,
readNativeMacHelperEvents,
readNativeMacStopOutcome,
SYSTEM_AUDIO_LOST_WARNING,
sendNativeMacStopCommand,
waitForNativeMacCaptureStop,
} from "./nativeMacCaptureStop";
const TARGET = "/rec/recording-1.mp4";
/** What the helper prints, one JSON event per line. */
function line(event: Record<string, unknown>) {
return `${JSON.stringify(event)}\n`;
}
// The messages as the Swift helper really prints them: the interruption embeds the
// writer's NSError, and a stream the system stopped reports its NSError alone.
const WRITER_DIED_MESSAGE =
'Recording stopped: the video file could not be written (video append: Error Domain=AVFoundationErrorDomain Code=-11800 "The operation could not be completed" UserInfo={NSLocalizedFailureReason=An unknown error occurred (-16364)}).';
const CAPTURE_STOPPED_MESSAGE =
'Error Domain=com.apple.ScreenCaptureKit.SCStreamErrorDomain Code=-3815 "The stream was stopped by the system." UserInfo={NSLocalizedDescription=The stream was stopped by the system.}';
const started = line({ event: "recording-started", width: 3840, height: 2160 });
const stopped = line({ event: "recording-stopped", screenPath: TARGET });
const writerDied = line({
event: "error",
code: "writer-failed-during-capture",
message: WRITER_DIED_MESSAGE,
});
const writerFailed = line({
event: "error",
code: "writer-failed",
message: "Error Domain=AVFoundationErrorDomain Code=-11800",
});
const captureStopped = line({
event: "error",
code: "capture-stopped-with-error",
message: CAPTURE_STOPPED_MESSAGE,
});
/**
* Stands in for openscreen-screencapturekit-helper. `exitCode`/`signalCode` are
* real `ChildProcess` properties the code under test reads, and `exit()` records
* the exit the way the output drain in handlers.ts does before `close` reaches
* any later listener.
*/
class FakeHelper extends EventEmitter {
stdout = new PassThrough();
stderr = new PassThrough();
stdin: Writable;
written: string[] = [];
exitCode: number | null = null;
signalCode: NodeJS.Signals | null = null;
recordedExit: NativeMacCaptureExit | null = null;
constructor() {
super();
const written = this.written;
this.stdin = new Writable({
write(chunk, _encoding, callback) {
written.push(chunk.toString());
callback();
},
});
}
exit(code: number | null, signal: NodeJS.Signals | null = null) {
this.exitCode = code;
this.signalCode = signal;
this.recordedExit = { code, signal };
this.emit("close", code, signal);
}
}
function asProc(helper: FakeHelper) {
return helper as unknown as ChildProcessWithoutNullStreams;
}
let helper: FakeHelper;
beforeEach(() => {
vi.useFakeTimers();
helper = new FakeHelper();
});
afterEach(() => {
vi.useRealTimers();
});
function waitForStop(readOutput: () => string, timeoutMs?: number) {
return waitForNativeMacCaptureStop({
proc: asProc(helper),
targetPath: TARGET,
readOutput,
readExit: () => helper.recordedExit,
timeoutMs,
});
}
describe("readNativeMacHelperEvents", () => {
it("reads an event glued behind stderr text", () => {
const events = readNativeMacHelperEvents(`2026-09-14 helper log line${stopped}`);
expect(events).toEqual([{ event: "recording-stopped", screenPath: TARGET }]);
});
it("skips plain text and objects that are not events", () => {
expect(readNativeMacHelperEvents('warming up\n{"not":"an event"}\n{broken\n')).toEqual([]);
});
});
describe("readNativeMacStopOutcome", () => {
it("takes the path the helper reported", () => {
expect(readNativeMacStopOutcome(started + stopped, null, "/elsewhere.mp4")).toEqual({
ok: true,
screenVideoPath: TARGET,
});
});
it("falls back to the requested path when the report names none", () => {
expect(
readNativeMacStopOutcome(
line({ event: "recording-stopped" }),
{ code: 0, signal: null },
TARGET,
),
).toEqual({ ok: true, screenVideoPath: TARGET });
});
/**
* The shape that used to lose a finalized take: capture stopped on its own, the
* helper finished the file anyway, and the stop rejected on the earlier error.
*/
it("keeps a take whose capture stopped on its own but whose file was finalized", () => {
expect(readNativeMacStopOutcome(started + captureStopped + stopped, null, TARGET)).toEqual({
ok: true,
screenVideoPath: TARGET,
warning: `Recording ended early (${CAPTURE_STOPPED_MESSAGE}). The part recorded until then was saved.`,
});
});
it("tells the user when the system audio they asked for could not be recorded", () => {
const tapFailed = line({
event: "warning",
code: "system-audio-unavailable",
message: "System audio could not be captured: AudioDeviceStart failed (OSStatus -1)",
});
expect(readNativeMacStopOutcome(started + tapFailed + stopped, null, TARGET)).toEqual({
ok: true,
screenVideoPath: TARGET,
warning: SYSTEM_AUDIO_LOST_WARNING,
});
});
it("keeps both the early end and the lost system audio in one warning", () => {
const tapFailed = line({ event: "warning", code: "system-audio-unavailable" });
const outcome = readNativeMacStopOutcome(
started + tapFailed + captureStopped + stopped,
null,
TARGET,
);
expect(outcome).toMatchObject({ ok: true, screenVideoPath: TARGET });
expect(outcome?.ok && outcome.warning).toContain("Recording ended early");
expect(outcome?.ok && outcome.warning).toContain(SYSTEM_AUDIO_LOST_WARNING);
});
it("says why the take ended rather than quoting the raw writer error", () => {
expect(readNativeMacStopOutcome(started + writerDied + writerFailed, null, TARGET)).toEqual({
ok: false,
reason: "helper-failed",
message: WRITER_DIED_MESSAGE,
exited: false,
});
});
/** The replay that used to reject a stop before the helper had even been told to stop. */
it("does not settle on an interruption alone while the helper is still running", () => {
expect(readNativeMacStopOutcome(started + writerDied, null, TARGET)).toBeNull();
});
it("keeps the old behaviour for a helper that exits 0 without a word", () => {
expect(readNativeMacStopOutcome(started, { code: 0, signal: null }, TARGET)).toEqual({
ok: true,
screenVideoPath: TARGET,
});
});
/** Exit 0 after an interruption only means the command pipe closed; nothing was finalized. */
it("does not call exit 0 after an interruption a finished recording", () => {
expect(
readNativeMacStopOutcome(started + writerDied, { code: 0, signal: null }, TARGET),
).toEqual({
ok: false,
reason: "helper-failed",
message: WRITER_DIED_MESSAGE,
exited: true,
});
});
it("reports a killed helper by its signal instead of dumping its log", () => {
expect(readNativeMacStopOutcome(started, { code: null, signal: "SIGKILL" }, TARGET)).toEqual({
ok: false,
reason: "helper-failed",
message: "The recorder stopped unexpectedly (signal SIGKILL).",
exited: true,
});
});
it("refuses a finalized report with no path to point at", () => {
expect(
readNativeMacStopOutcome(
line({ event: "recording-stopped" }),
{ code: 0, signal: null },
null,
),
).toMatchObject({ ok: false, reason: "helper-failed" });
});
});
describe("waitForNativeMacCaptureStop", () => {
it("waits for the helper to exit even when an error is already buffered", async () => {
let output = started + writerDied;
let settled = false;
const pending = waitForStop(() => output).then((result) => {
settled = true;
return result;
});
await vi.advanceTimersByTimeAsync(1_000);
expect(settled).toBe(false);
output += writerFailed;
helper.exit(0);
await expect(pending).resolves.toMatchObject({
ok: false,
message: WRITER_DIED_MESSAGE,
exited: true,
});
});
it("resolves with the finalized path once the helper exits", async () => {
let output = started;
const pending = waitForStop(() => output);
output += stopped;
helper.exit(0);
await expect(pending).resolves.toEqual({ ok: true, screenVideoPath: TARGET });
});
/** Node never re-emits `close`, so a dead helper must not cost the whole timeout. */
it("settles immediately when the helper has already exited", async () => {
helper.exit(null, "SIGKILL");
const result = await waitForStop(() => started);
expect(result).toEqual({
ok: false,
reason: "helper-failed",
message: "The recorder stopped unexpectedly (signal SIGKILL).",
exited: true,
});
expect(vi.getTimerCount()).toBe(0);
});
it("keeps a finalized recording when the helper never exits", async () => {
const pending = waitForStop(() => started + stopped, 30_000);
await vi.advanceTimersByTimeAsync(30_000);
await expect(pending).resolves.toEqual({ ok: true, screenVideoPath: TARGET });
});
it("reports a timeout, without claiming the helper exited, when it never finishes", async () => {
const pending = waitForStop(() => started, 30_000);
await vi.advanceTimersByTimeAsync(30_000);
await expect(pending).resolves.toEqual({
ok: false,
reason: "stop-timeout",
message: "The recorder did not finish saving in time.",
exited: false,
});
});
it("reports a process error as a helper failure", async () => {
const pending = waitForStop(() => started);
helper.emit("error", new Error("spawn EACCES"));
await expect(pending).resolves.toEqual({
ok: false,
reason: "helper-failed",
message: "spawn EACCES",
exited: false,
});
});
});
describe("sendNativeMacStopCommand", () => {
it("tells a running helper to stop", () => {
expect(sendNativeMacStopCommand(asProc(helper))).toBe(true);
expect(helper.written).toEqual(["stop\n"]);
});
it("does not write to a helper that already exited", () => {
helper.exit(null, "SIGKILL");
expect(sendNativeMacStopCommand(asProc(helper))).toBe(false);
expect(helper.written).toEqual([]);
});
it("does not write to a command pipe that is already closed", () => {
helper.stdin.destroy();
expect(sendNativeMacStopCommand(asProc(helper))).toBe(false);
});
});
describe("nativeMacDiscardTargets", () => {
it("removes the file the helper finalized", () => {
expect(nativeMacDiscardTargets({ ok: true, screenVideoPath: "/rec/a.mp4" }, TARGET)).toEqual([
"/rec/a.mp4",
"/rec/a.mp4.cursor.json",
]);
});
/** The orphan: a take thrown away after its writer died. */
it("removes the requested file when the stop failed", () => {
expect(
nativeMacDiscardTargets(
{ ok: false, reason: "helper-failed", message: WRITER_DIED_MESSAGE, exited: true },
TARGET,
),
).toEqual([TARGET, `${TARGET}.cursor.json`]);
});
it("removes the requested file when the stop timed out", () => {
expect(
nativeMacDiscardTargets(
{ ok: false, reason: "stop-timeout", message: "timed out", exited: false },
TARGET,
),
).toEqual([TARGET, `${TARGET}.cursor.json`]);
});
it("has nothing to remove when no file was ever requested", () => {
expect(
nativeMacDiscardTargets(
{ ok: false, reason: "helper-failed", message: "x", exited: true },
null,
),
).toEqual([]);
});
});