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
// Builds the native Metal/VideoToolbox compositor addon (crates/compositor-view-napi)
// and vendors it to electron/native/compositor-view/build/compositor_view.node — the
// path compositorViewService.ts's candidate list resolves at runtime.
//
// The macOS twin of build-windows-compositor-addon.mjs. Where that one has to sweep
// for vcvarsall to put MSVC on PATH, this one only needs the Xcode command-line tools
// (`xcrun` finds the SDK and libclang for bindgen, see crates/compositor/build.rs).
//
// FFMPEG — the one thing that is NOT symmetric. On Windows, scripts/fetch-ffmpeg.mjs
// vendors BtbN's pinned "-lgpl-shared" build into crates/thirdparty/. BtbN publishes
// no macOS target (that script exits 1 on darwin, by design), so there is no
// equivalent download and the tree has to be built locally. `--print-ffmpeg-recipe`
// prints the exact configure line; the LGPL posture is the part that matters and is
// not negotiable:
//
// * NO --enable-gpl and NO --enable-nonfree. ffmpeg is LGPL by default and becomes
// GPL the moment either is passed (x264/x265 come in with --enable-gpl), which
// would relicense this MIT app. Same rule fetch-ffmpeg.mjs enforces on Windows
// with `ffmpeg -L`.
// * --enable-shared: the addon dynamically links libavcodec/libavformat/… .
//
// A Homebrew ffmpeg will NOT do as a drop-in: brew's formula builds with
// --enable-gpl. It is fine to develop against, never fine to ship.
import { execFileSync, spawn } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.join(__dirname, "..");
const CRATES_DIR = path.join(ROOT, "crates");
const BUILD_OUT_DIR = path.join(ROOT, "electron", "native", "compositor-view", "build");
/** Where crates/compositor/build.rs looks for the macOS ffmpeg tree when MAC_FFMPEG_DIR is unset. */
const VENDORED_FFMPEG_DIR = path.join(
CRATES_DIR,
"thirdparty",
"ffmpeg-n8.1.2-macos64-lgpl-shared",
);
const FFMPEG_RECIPE = `
# ffmpeg 8.1.2, LGPL, shared — the tree crates/compositor/build.rs expects.
# Run from an unpacked https://ffmpeg.org/releases/ffmpeg-8.1.2.tar.xz:
./configure \\
--prefix="${VENDORED_FFMPEG_DIR}" \\
--enable-shared --disable-static \\
--disable-doc --disable-debug \\
--enable-videotoolbox --enable-audiotoolbox \\
--disable-x86asm --arch=arm64 --enable-neon --cc=clang
make -j"$(sysctl -n hw.ncpu)" && make install
# No --enable-gpl, no --enable-nonfree: either one relicenses OpenScreen under the GPL.
`.trim();
function run(command, args, options = {}) {
return new Promise((resolve, reject) => {
const child = spawn(command, args, { stdio: "inherit", cwd: CRATES_DIR, ...options });
child.on("error", reject);
child.on("close", (code) =>
code === 0
? resolve()
: reject(new Error(`${command} ${args.join(" ")} exited with ${code}`)),
);
});
}
if (process.argv.includes("--print-ffmpeg-recipe")) {
console.log(FFMPEG_RECIPE);
process.exit(0);
}
if (process.platform !== "darwin") {
console.log("Skipping native Metal compositor addon build: macOS-only.");
process.exit(0);
}
// The addon links ffmpeg, so a missing tree is a hard stop with the recipe attached
// rather than a bindgen error 200 lines deep in cargo output.
const macFfmpegDir = process.env.MAC_FFMPEG_DIR ?? VENDORED_FFMPEG_DIR;
if (!fs.existsSync(path.join(macFfmpegDir, "include"))) {
throw new Error(
`No ffmpeg SDK at ${macFfmpegDir} (looked for its include/).\n` +
"Set MAC_FFMPEG_DIR, or build the vendored tree:\n\n" +
`${FFMPEG_RECIPE}\n`,
);
}
const cargo = path.join(os.homedir(), ".cargo", "bin", "cargo");
if (!fs.existsSync(cargo)) {
throw new Error(`cargo not found at ${cargo}. Install Rust (https://rustup.rs) first.`);
}
// cwd = crates/ so cargo picks up crates/.cargo/config.toml, same as the Windows script.
await run(cargo, ["build", "-p", "compositor-view-napi", "--release"], {
env: { ...process.env, MAC_FFMPEG_DIR: macFfmpegDir },
});
// cdylib on macOS is a .dylib; node's require() wants the .node extension but does not
// care what is inside — it dlopens it and calls the napi entry point either way.
const builtDylib = path.join(CRATES_DIR, "target", "release", "libcompositor_view.dylib");
if (!fs.existsSync(builtDylib)) {
throw new Error(`Compositor addon build completed but ${builtDylib} was not found.`);
}
/**
* Install by atomic rename, NEVER by copying over the existing file.
*
* macOS validates code pages lazily against the Mach-O signature. Overwriting a
* loaded `.node` in place leaves the kernel's page cache holding pages from the OLD
* binary on a vnode whose signature is now the NEW one, and the next process to fault
* one of those pages is killed outright:
*
* signal: SIGKILL (Code Signature Invalid)
* termination: { namespace: "CODESIGNING", indicator: "Invalid Page" }
*
* No JS error, no stack — the app just dies at `require()`. It only bites on the
* SECOND build onwards, which is what makes it so confusing: the addon works, you
* change one line of Rust, and now nothing loads.
*
* Writing to a temp name in the same directory and renaming gives the new content a
* fresh inode, so the stale pages belong to a vnode nothing will fault again.
*/
function installAtomically(from, to) {
fs.mkdirSync(path.dirname(to), { recursive: true });
const tmp = `${to}.${process.pid}.tmp`;
fs.copyFileSync(from, tmp);
fs.renameSync(tmp, to);
}
/**
* Every Mach-O load command that points outside the OS's own prefixes. `otool -D`/`-L`
* both echo the filename on the first line, so both lists skip it.
*/
function absolutePaths(file) {
const id = execFileSync("otool", ["-D", file], { encoding: "utf8" })
.split("\n")
.slice(1) // first line is the filename echoed back
.map((l) => l.trim())
.filter(Boolean);
const deps = execFileSync("otool", ["-L", file], { encoding: "utf8" })
.split("\n")
.slice(1) // ditto
.map((l) => l.trim().split(" ")[0])
.filter(Boolean);
return [...id, ...deps].filter(
(p) => p.startsWith("/") && !p.startsWith("/usr/lib/") && !p.startsWith("/System/"),
);
}
/**
* Vendors the ffmpeg dylibs next to the addon and rewrites every install name to
* `@rpath`, so the packaged app loads its own copies instead of a build-machine path.
*
* Straight out of `cargo`, the `.node` references its dependencies by ABSOLUTE path
* (`otool -L` shows `/Users/…/crates/thirdparty/…/libavcodec.62.dylib`). That works on
* the machine that built it and nowhere else — the installed app would fail at
* `require()` with a dyld error naming a directory the user has never had. Windows does
* not hit this because `LoadLibrary` searches `PATH`, which is what
* `ensureFfmpegSharedDllsOnPath()` prepends; macOS has no such search, so the fix has to
* be baked into the binary.
*
* Three edits per artefact:
* - each dylib's own id becomes `@rpath/<name>`;
* - every inter-library reference (libavcodec -> libavutil, and so on) is rewritten;
* - the addon gains `@loader_path` as an rpath, so `@rpath/libavutil.60.dylib`
* resolves next to `compositor_view.node` — which is exactly where electron-builder
* puts them via the mac `extraResources` filter `darwin-*/*`.
*
* Re-signing is required and not optional: `install_name_tool` invalidates the existing
* ad-hoc signature, and macOS kills a process that faults a page of a binary whose
* signature no longer matches (the same `SIGKILL (Code Signature Invalid)` documented on
* `installAtomically` above).
*/
function vendorFfmpegDylibs(nodePath, ffmpegDir) {
const outDir = path.dirname(nodePath);
const libDir = path.join(ffmpegDir, "lib");
const linked = execFileSync("otool", ["-L", nodePath], { encoding: "utf8" })
.split("\n")
.map((line) => line.trim().split(" ")[0])
.filter((p) => /\/lib(av|sw)\w+\.\d+\.dylib$/.test(p));
if (linked.length === 0) {
throw new Error(`${nodePath} links no ffmpeg dylib — nothing to vendor, which is wrong.`);
}
const names = linked.map((p) => path.basename(p));
for (const name of names) {
const from = path.join(libDir, name);
if (!fs.existsSync(from)) {
throw new Error(`Missing ${from}; the addon links it but the SDK does not ship it.`);
}
const to = path.join(outDir, name);
fs.copyFileSync(from, to);
fs.chmodSync(to, 0o755);
execFileSync("install_name_tool", ["-id", `@rpath/${name}`, to]);
}
// Inter-library references, and the addon's own.
for (const target of [...names.map((n) => path.join(outDir, n)), nodePath]) {
const deps = execFileSync("otool", ["-L", target], { encoding: "utf8" })
.split("\n")
.map((line) => line.trim().split(" ")[0])
.filter((p) => p.startsWith("/") && /lib(av|sw)\w+\.\d+\.dylib$/.test(p));
for (const dep of deps) {
execFileSync("install_name_tool", ["-change", dep, `@rpath/${path.basename(dep)}`, target]);
}
execFileSync("install_name_tool", ["-add_rpath", "@loader_path", target]);
// install_name_tool invalidates the signature; re-sign ad-hoc.
execFileSync("codesign", ["--force", "--sign", "-", target]);
}
// cargo stamps the cdylib's own id with the absolute path it was built at
// (`crates/target/release/deps/libcompositor_view.dylib`). Nothing resolves
// through it — `require()` dlopens the file by path and never reads
// LC_ID_DYLIB — so this is not a load failure. It is a build-machine path,
// complete with the builder's home directory and checkout name, shipped
// inside a release artefact: it defeats reproducible builds and leaks a
// filesystem layout to anyone who runs `otool -D` on the installed app.
execFileSync("install_name_tool", ["-id", `@rpath/${path.basename(nodePath)}`, nodePath]);
execFileSync("codesign", ["--force", "--sign", "-", nodePath]);
// The old check only grepped for `lib(av|sw)`, so it could not have caught
// the id above — nor any future non-ffmpeg dependency that arrives absolute.
// Assert the real invariant instead: nothing outside the OS's own prefixes
// may be referenced by absolute path.
for (const file of [nodePath, ...names.map((n) => path.join(outDir, n))]) {
const remaining = absolutePaths(file);
if (remaining.length > 0) {
throw new Error(
`${path.basename(file)} still references build-machine paths after rewriting: ` +
remaining.join(", "),
);
}
}
console.log(`Vendored ${names.length} ffmpeg dylibs next to ${path.basename(nodePath)}`);
console.log(`No absolute build-machine paths remain in ${path.basename(nodePath)} or its dylibs`);
}
/**
* Stages the SDK's `ffmpeg` BINARY next to the addon's vendored dylibs, so the packaged
* app has the CLI that `resolveFfmpeg()` (electron/media/audioPeaks.ts) and native STT
* audio extraction (electron/stt/extractAudio.ts) spawn.
*
* Without it the .app carries libav*.dylib but no executable, and every transcription on
* a machine without a system ffmpeg dies with FfmpegUnavailableError — the failure the
* renderer can only show as "Failed to fetch" (#616). Windows never had this gap: its
* installer ships `ffmpeg-shared.exe` beside the DLLs it links.
*
* The binary leaves `make install` referencing the SDK's lib/ — by absolute path or by
* `@executable_path/../lib/`, depending on the configure — and neither survives the move
* into electron-builder's extraResources. Rewriting every lib reference to `@rpath/<name>`
* and adding `@loader_path` points it at the very dylibs `vendorFfmpegDylibs` put beside
* it, whose ids already are `@rpath/<name>`.
*/
function stageFfmpegBinary(outDir, ffmpegDir) {
const from = path.join(ffmpegDir, "bin", "ffmpeg");
if (!fs.existsSync(from)) {
throw new Error(`No ffmpeg binary at ${from}; the SDK tree is incomplete.`);
}
const to = path.join(outDir, "ffmpeg");
installAtomically(from, to);
fs.chmodSync(to, 0o755);
const deps = execFileSync("otool", ["-L", to], { encoding: "utf8" })
.split("\n")
.map((line) => line.trim().split(" ")[0])
.filter((p) => /(^\/|@executable_path).*lib(av|sw)\w+\.\d+\.dylib$/.test(p));
if (deps.length === 0) {
throw new Error(`${to} links no ffmpeg dylib — nothing to rewrite, which is wrong.`);
}
// The CLI links more of the SDK than the addon does (libavdevice, libpostproc, …).
// Refresh every direct dependency, including files vendorFfmpegDylibs already staged.
// The output directory persists between local builds, so keeping an existing file could
// mix a new CLI with an old SDK dylib or preserve a half-rewritten file from an interrupted
// run. Replacing the complete set also gives every file the same atomic-install guarantee
// as the addon and CLI.
const stagedLibraries = [];
for (const dep of new Set(deps)) {
const name = path.basename(dep);
const staged = path.join(outDir, name);
const sdkLib = path.join(ffmpegDir, "lib", name);
if (!fs.existsSync(sdkLib)) {
throw new Error(`Missing ${sdkLib}; the binary links it but the SDK does not ship it.`);
}
installAtomically(sdkLib, staged);
fs.chmodSync(staged, 0o755);
execFileSync("install_name_tool", ["-id", `@rpath/${name}`, staged]);
stagedLibraries.push(staged);
}
for (const file of [...stagedLibraries, to]) {
const fileDeps = execFileSync("otool", ["-L", file], { encoding: "utf8" })
.split("\n")
.map((line) => line.trim().split(" ")[0])
.filter((p) => /(^\/|@executable_path).*lib(av|sw)\w+\.\d+\.dylib$/.test(p));
for (const dep of fileDeps) {
execFileSync("install_name_tool", ["-change", dep, `@rpath/${path.basename(dep)}`, file]);
}
execFileSync("install_name_tool", ["-add_rpath", "@loader_path", file]);
// install_name_tool invalidates the signature; re-sign ad-hoc.
execFileSync("codesign", ["--force", "--sign", "-", file]);
}
for (const file of [...stagedLibraries, to]) {
const remaining = absolutePaths(file);
if (remaining.length > 0) {
throw new Error(
`${path.basename(file)} still references build-machine paths after rewriting: ` +
remaining.join(", "),
);
}
}
console.log(`Staged ffmpeg binary at ${to} (rewritten to @rpath beside the vendored dylibs)`);
}
/**
* Refuses to package a GPL ffmpeg. `--enable-gpl` pulls x264/x265 in and relicenses this
* MIT app; a Homebrew ffmpeg is exactly that and is an easy thing to point MAC_FFMPEG_DIR
* at by accident. Same check `fetch-ffmpeg.mjs` runs on the Windows build.
*/
function assertLgpl(ffmpegDir) {
const bin = path.join(ffmpegDir, "bin", "ffmpeg");
if (!fs.existsSync(bin)) {
console.warn(`No ffmpeg binary at ${bin}; skipping the licence check.`);
return;
}
const banner = execFileSync(bin, ["-hide_banner", "-L"], { encoding: "utf8" });
if (/GNU General Public License/i.test(banner) || !/Lesser General Public/i.test(banner)) {
throw new Error(
`${ffmpegDir} is not an LGPL build — its own -L banner says so.\n` +
"Homebrew's ffmpeg is GPL (--enable-gpl). Build the LGPL tree instead:\n\n" +
`${FFMPEG_RECIPE}\n`,
);
}
console.log("ffmpeg licence: LGPL (checked via `ffmpeg -L`)");
}
assertLgpl(macFfmpegDir);
const dest = path.join(BUILD_OUT_DIR, "compositor_view.node");
installAtomically(builtDylib, dest);
// The arch-tagged dir is the first candidate compositorViewService.ts probes, and the
// one electron-builder ships via extraResources. Keeping both in sync means a dev build
// and a packaged build load the same binary.
const archBinDir = path.join(ROOT, "electron", "native", "bin", `darwin-${process.arch}`);
const archDest = path.join(archBinDir, "compositor_view.node");
installAtomically(builtDylib, archDest);
// Only the arch-tagged copy ships (mac `extraResources`, filter `darwin-*/*`), so that
// is the one that gets its dylibs and its @rpath.
vendorFfmpegDylibs(archDest, macFfmpegDir);
stageFfmpegBinary(archBinDir, macFfmpegDir);
console.log(`Built ${builtDylib}`);
console.log(`Copied ${dest}`);
console.log(`Copied ${archDest}`);
console.log(
`\nThe shipped copy (${archDest}) carries its own LGPL ffmpeg dylibs and resolves them\n` +
"through @rpath/@loader_path, so the packaged app does not depend on this machine's\n" +
"paths. The dev copy under electron/native/compositor-view/build/ keeps its absolute\n" +
"links, which is fine — it never leaves this checkout.",
);