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 fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { gunzipSync } from "node:zlib";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import {
describeSalvagedTake,
inspectNativeMacCapture,
nativeMacSalvageTarget,
salvageNativeMacCapture,
} from "./nativeMacCaptureSalvage";
/**
* The fixtures are real takes from the macOS helper (Mac mini M1, macOS 26.5) with
* every `mdat` payload zeroed and then gzipped, so they keep AVAssetWriter's exact
* box structure — sample tables, fragments, the size-0 tail — in a few KB. The
* expected frame counts are ffmpeg's packet counts on the ORIGINAL files; zeroing
* payloads does not move a single box.
*
* - writer-died-4s: shipped 1.11.0-rc.1 helper, writer failed with -16364 (3 moof).
* - writer-died-1s-no-moof: the same death within the first second (mvex, 0 moof).
* - helper-killed-29s: main helper SIGKILLed 30 s in (28 moof, size-0 tail mdat).
* - helper-killed-9s-main: main helper after #661, SIGKILLed 10 s in.
* - clean-flat-8s: a clean stop, which finishWriting rewrites flat.
*/
const FIXTURES = path.join(__dirname, "__fixtures__", "macos-fmp4");
/** Box offsets in helper-killed-29s, read off the original file. */
const KILLED_29S = {
moov: 1_201_426,
firstMoof: 2_371_612,
lastMoof: 35_918_587,
wide: 35_919_355,
tailMdat: 35_919_363,
};
let dir: string;
beforeAll(async () => {
dir = await fs.mkdtemp(path.join(os.tmpdir(), "native-mac-salvage-"));
});
afterAll(async () => {
await fs.rm(dir, { recursive: true, force: true });
});
/** A private copy of a fixture, optionally cut to its first `bytes` bytes. */
async function take(fixture: string, bytes?: number) {
const data = gunzipSync(await fs.readFile(path.join(FIXTURES, `${fixture}.mp4.gz`)));
const target = path.join(
dir,
`${fixture}-${bytes ?? "whole"}-${Math.random().toString(36).slice(2)}.mp4`,
);
await fs.writeFile(target, bytes === undefined ? data : data.subarray(0, bytes));
return target;
}
async function sizeOf(filePath: string) {
return (await fs.stat(filePath)).size;
}
describe("inspectNativeMacCapture on real helper output", () => {
it.each([
["writer-died-4s", 231, 4],
["writer-died-1s-no-moof", 58, 1],
["helper-killed-29s", 1652, 29],
["helper-killed-9s-main", 513, 9],
["clean-flat-8s", 461, 8],
])("finds every frame ffmpeg reads in %s", async (fixture, frames, seconds) => {
const inspection = await inspectNativeMacCapture(await take(fixture));
expect(inspection).toMatchObject({ ok: true, videoSamples: frames });
if (!inspection.ok) throw new Error("unreachable");
expect(inspection.validBytes).toBe(inspection.fileBytes);
expect(Math.abs(inspection.durationSec - seconds)).toBeLessThan(0.2);
});
/**
* #571's check rejected this file at random: its last `mdat` has a size field of 0,
* and mp4box aborted whenever a read-chunk boundary fell inside it.
*/
it("reads a take whose last mdat declares size 0, with no read-size dependence", async () => {
const file = await take("helper-killed-29s", KILLED_29S.tailMdat + 8);
await expect(inspectNativeMacCapture(file)).resolves.toMatchObject({
ok: true,
videoSamples: 1652,
});
});
/** The fragment still being written when the take died: a final mdat cut short. */
it("accepts a final mdat cut short, keeping the fragments indexed before it", async () => {
const file = await take("helper-killed-29s", KILLED_29S.lastMoof - 1000);
const inspection = await inspectNativeMacCapture(file);
expect(inspection).toMatchObject({ ok: true, videoSamples: 1596 });
if (!inspection.ok) throw new Error("unreachable");
expect(inspection.validBytes).toBe(inspection.fileBytes);
});
it("marks where a torn moof starts without changing the file", async () => {
const file = await take("helper-killed-29s", KILLED_29S.lastMoof + 300);
const inspection = await inspectNativeMacCapture(file);
expect(inspection).toMatchObject({
ok: true,
validBytes: KILLED_29S.lastMoof,
videoSamples: 1596,
});
expect(await sizeOf(file)).toBe(KILLED_29S.lastMoof + 300);
});
it("rejects a file whose movie header is torn", async () => {
const file = await take("helper-killed-29s", KILLED_29S.moov + 500);
await expect(inspectNativeMacCapture(file)).resolves.toMatchObject({
ok: false,
reason: "no movie header in the readable part of the file",
});
});
it("rejects a file cut before its movie header", async () => {
const file = await take("helper-killed-29s", 600_000);
await expect(inspectNativeMacCapture(file)).resolves.toMatchObject({ ok: false });
});
it("rejects something that is not an MP4 at all", async () => {
const file = path.join(dir, "notes.txt");
await fs.writeFile(file, "this is not a recording\n".repeat(10));
await expect(inspectNativeMacCapture(file)).resolves.toMatchObject({
ok: false,
reason: "not an MP4 file",
});
});
it("rejects a file that is not there", async () => {
await expect(inspectNativeMacCapture(path.join(dir, "missing.mp4"))).resolves.toMatchObject({
ok: false,
});
});
});
describe("salvageNativeMacCapture", () => {
it("leaves a readable take exactly as it is", async () => {
const file = await take("writer-died-4s");
const before = await sizeOf(file);
await expect(salvageNativeMacCapture(file)).resolves.toMatchObject({
ok: true,
screenVideoPath: file,
videoSamples: 231,
truncatedBytes: 0,
});
expect(await sizeOf(file)).toBe(before);
});
/**
* A file cut inside a moof opens nowhere (ffmpeg, libavformat and Chromium all
* refuse it), though mp4box accepts it. Cut back to that moof it opens with every
* earlier fragment: ffmpeg reads 1596 frames from exactly this cut.
*/
it("cuts a torn last moof off and keeps every fragment before it", async () => {
const file = await take("helper-killed-29s", KILLED_29S.lastMoof + 300);
await expect(salvageNativeMacCapture(file)).resolves.toMatchObject({
ok: true,
videoSamples: 1596,
truncatedBytes: 300,
});
expect(await sizeOf(file)).toBe(KILLED_29S.lastMoof);
});
it("keeps the first second when the first moof is the torn one", async () => {
const file = await take("helper-killed-29s", KILLED_29S.firstMoof + 300);
await expect(salvageNativeMacCapture(file)).resolves.toMatchObject({
ok: true,
videoSamples: 58,
});
expect(await sizeOf(file)).toBe(KILLED_29S.firstMoof);
});
/** Players skip these 4 bytes anyway; the cut is a precaution, and it loses nothing. */
it("cuts off a box header left half-written at the end", async () => {
const file = await take("helper-killed-29s", KILLED_29S.wide + 4);
await expect(salvageNativeMacCapture(file)).resolves.toMatchObject({
ok: true,
videoSamples: 1652,
truncatedBytes: 4,
});
});
/** Nothing is cut from a file that cannot be recovered anyway. */
it("does not touch a file it cannot recover", async () => {
const file = await take("helper-killed-29s", KILLED_29S.moov + 500);
await expect(salvageNativeMacCapture(file)).resolves.toMatchObject({ ok: false });
expect(await sizeOf(file)).toBe(KILLED_29S.moov + 500);
});
});
describe("nativeMacSalvageTarget", () => {
const TARGET = "/rec/recording-1.mp4";
it("salvages the requested file once the helper has exited", () => {
expect(
nativeMacSalvageTarget(
{ ok: false, reason: "helper-failed", message: "x", exited: true },
TARGET,
),
).toBe(TARGET);
});
/** Salvage truncates; a helper that did not exit may still be inside finishWriting. */
it("never salvages a file a helper that did not exit may still be writing", () => {
expect(
nativeMacSalvageTarget(
{ ok: false, reason: "stop-timeout", message: "x", exited: false },
TARGET,
),
).toBeNull();
});
it("has nothing to salvage after a stop that worked", () => {
expect(nativeMacSalvageTarget({ ok: true, screenVideoPath: TARGET }, TARGET)).toBeNull();
});
it("has nothing to salvage when no file was requested", () => {
expect(
nativeMacSalvageTarget(
{ ok: false, reason: "helper-failed", message: "x", exited: true },
null,
),
).toBeNull();
});
});
describe("describeSalvagedTake", () => {
/** Verbatim from the helper, in the disk-full end-to-end run. */
it("keeps the helper's sentence and adds a description that says something", () => {
expect(
describeSalvagedTake(
'Recording stopped: the video file could not be written (writer status: Error Domain=AVFoundationErrorDomain Code=-11807 "Disk Full" UserInfo={NSLocalizedDescription=Disk Full, NSUnderlyingError=0x9e326c930 {Error Domain=NSPOSIXErrorDomain Code=28 "No space left on device"}, NSLocalizedRecoverySuggestion=Make room by deleting existing files and try again., NSLocalizedFailureReason=There is not enough available space to continue the file writing.}).',
35.01,
),
).toBe(
"Recording stopped after 0:35: the video file could not be written (Disk Full). The part recorded until then was saved.",
);
});
/** The -16364 writer death this whole path started from; its description is generic. */
it("does not replace the helper's sentence with a generic NSError description", () => {
expect(
describeSalvagedTake(
'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), NSLocalizedDescription=The operation could not be completed, NSUnderlyingError=0x1 {Error Domain=NSOSStatusErrorDomain Code=-16364 "(null)"}}).',
73.01,
),
).toBe(
"Recording stopped after 1:13: the video file could not be written. The part recorded until then was saved.",
);
});
it("reads a bare NSError by its description", () => {
expect(
describeSalvagedTake(
'Error Domain=com.apple.ScreenCaptureKit.SCStreamErrorDomain Code=-3815 "The stream was stopped by the system." UserInfo={NSLocalizedDescription=The stream was stopped by the system.}',
12,
),
).toBe(
"Recording stopped after 0:12: The stream was stopped by the system. The part recorded until then was saved.",
);
});
it("uses the whole message when there is no NSError in it", () => {
expect(describeSalvagedTake("The recorder stopped unexpectedly (signal SIGKILL).", 9)).toBe(
"Recording stopped after 0:09: The recorder stopped unexpectedly (signal SIGKILL). The part recorded until then was saved.",
);
});
/** Measured: a 35 s disk-full take whose frame durations sum to 34.98 s. */
it("rounds the length rather than cutting a second off it", () => {
expect(describeSalvagedTake("Disk Full", 34.983333)).toBe(
"Recording stopped after 0:35: Disk Full. The part recorded until then was saved.",
);
});
it("counts hours on a long take", () => {
expect(describeSalvagedTake("Disk Full", 3725)).toBe(
"Recording stopped after 1:02:05: Disk Full. The part recorded until then was saved.",
);
});
});