feat: add configurable recordings save location

electron/electron-env.d.ts

@@ -427,6 +427,14 @@ interface Window {
 		revealInFolder: (
 			filePath: string,
 		) => Promise<{ success: boolean; error?: string; message?: string }>;
+		getRecordingsDir: () => Promise<{ path: string; isDefault: boolean }>;
+		chooseRecordingsDir: () => Promise<
+			{ success: true; path: string } | { success: false; canceled?: boolean; message?: string }
+		>;
+		resetRecordingsDir: () => Promise<
+			{ success: true; path: string } | { success: false; message?: string }
+		>;
+		checkRecordingDiskSpace: () => Promise<{ success: true } | { success: false; error: string }>;
 		getShortcuts: () => Promise<Record<string, unknown> | null>;
 		saveShortcuts: (shortcuts: unknown) => Promise<{ success: boolean; error?: string }>;
 		updateGlobalShortcut: (binding: {

electron/ipc/handlers.ts

@@ -62,7 +62,7 @@ import { AppSettingsStore } from "../app-settings";
 import { isDiagnosticModeEnabled, mainLogBuffer } from "../diagnostics/main-log-buffer";
 import { mainT } from "../i18n";
 import { getInstallChannel } from "../install-channel";
-import { RECORDINGS_DIR } from "../main";
+import { getRecordingsDirInfo, RECORDINGS_DIR, setRecordingsDir } from "../main";
 import { type AudioPeaksResult, getAudioPeaks } from "../media/audioPeaks";
 import {
 	readCursorRecordingFile as readCursorRecordingFileFrom,
@@ -84,6 +84,7 @@ import { findPipeWireCursorHelperPath } from "../native-bridge/cursor/recording/
 import type { CursorRecordingSession } from "../native-bridge/cursor/recording/session";
 import { toHelperRect } from "../native-bridge/helperCoordinates";
 import { scoreDeviceNameMatch } from "../recording/deviceNameMatching";
+import { checkDiskSpace } from "../recording/diskSpaceCheck";
 import {
 	describeSalvagedTake,
 	nativeMacSalvageTarget,
@@ -219,6 +220,23 @@ function hasAllowedImportVideoExtension(filePath: string): boolean {
 	return ALLOWED_IMPORT_VIDEO_EXTENSIONS.has(path.extname(filePath).toLowerCase());
 }
 
+/**
+ * Refuses to start a recording when the recordings directory's filesystem is
+ * critically low on space. Before this, low disk space was only discovered
+ * once the user tried to save — after the take was already lost. Returns
+ * `null` when there is enough room (or the check itself couldn't run, which
+ * must never block a recording that would otherwise have worked).
+ */
+async function lowDiskSpaceStartError(): Promise<{ success: false; error: string } | null> {
+	const status = await checkDiskSpace(RECORDINGS_DIR);
+	if (!status.low) return null;
+	const availableMb = Math.max(0, Math.floor(status.availableBytes / (1024 * 1024)));
+	return {
+		success: false,
+		error: mainT("dialogs", "recording.lowDiskSpace", { availableMb }),
+	};
+}
+
 // Imported audio (issue #350). Kept separate from the video set so the two
 // pickers stay honest — an audio picker must not approve a video path and vice
 // versa. A SUBSET of SUPPORTED_AUDIO_EXTENSIONS in the document service, which
@@ -2097,6 +2115,53 @@ export function registerIpcHandlers(
 		BrowserWindow.getAllWindows(),
 	);
 
+	ipcMain.handle("get-recordings-dir", () => {
+		return getRecordingsDirInfo();
+	});
+
+	ipcMain.handle("check-recording-disk-space", async () => {
+		const diskSpaceError = await lowDiskSpaceStartError();
+		return diskSpaceError ?? { success: true };
+	});
+
+	ipcMain.handle("choose-recordings-dir", async () => {
+		const dialogOptions = buildDialogOptions(
+			{
+				title: mainT("dialogs", "fileDialogs.selectRecordingsFolder"),
+				defaultPath: RECORDINGS_DIR,
+				properties: ["openDirectory", "createDirectory"] as Array<
+					"openDirectory" | "createDirectory"
+				>,
+			},
+			getMainWindow(),
+		);
+		const result = await dialog.showOpenDialog(dialogOptions);
+		if (result.canceled || result.filePaths.length === 0) {
+			return { success: false, canceled: true };
+		}
+		try {
+			const resolved = await setRecordingsDir(result.filePaths[0]);
+			return { success: true, path: resolved };
+		} catch (error) {
+			console.error("Failed to switch recordings folder:", error);
+			return {
+				success: false,
+				message: "Failed to switch recordings folder",
+				error: String(error),
+			};
+		}
+	});
+
+	ipcMain.handle("reset-recordings-dir", async () => {
+		try {
+			const resolved = await setRecordingsDir(null);
+			return { success: true, path: resolved };
+		} catch (error) {
+			console.error("Failed to reset recordings folder:", error);
+			return { success: false, message: "Failed to reset recordings folder", error: String(error) };
+		}
+	});
+
 	ipcMain.handle("request-camera-access", async () => {
 		if (process.platform !== "darwin") {
 			return { success: true, granted: true, status: "granted" };
@@ -2442,6 +2507,8 @@ export function registerIpcHandlers(
 				if (!findPipeWireCursorHelperPath()) {
 					return { success: false, error: "Native Linux capture helper is not available." };
 				}
+				const diskSpaceError = await lowDiskSpaceStartError();
+				if (diskSpaceError) return diskSpaceError;
 
 				const recordingId =
 					typeof request?.recordingId === "number" && Number.isFinite(request.recordingId)
@@ -2640,6 +2707,8 @@ export function registerIpcHandlers(
 						error: "Native Windows capture request is missing a source.",
 					};
 				}
+				const diskSpaceError = await lowDiskSpaceStartError();
+				if (diskSpaceError) return diskSpaceError;
 
 				const recordingId =
 					typeof request.recordingId === "number" && Number.isFinite(request.recordingId)
@@ -2865,6 +2934,8 @@ export function registerIpcHandlers(
 			if (!request?.source?.sourceId) {
 				return { success: false, error: "Native macOS capture request is missing a source." };
 			}
+			const diskSpaceError = await lowDiskSpaceStartError();
+			if (diskSpaceError) return diskSpaceError;
 
 			const recordingId =
 				typeof request.recordingId === "number" && Number.isFinite(request.recordingId)
@@ -3490,7 +3561,12 @@ export function registerIpcHandlers(
 	// Declared here because both the webcam attach below and store-recorded-session
 	// finalize through the same registry.
 	const recordingStreams = new RecordingStreamRegistry();
-	registerRecordingStreamHandlers(ipcMain, recordingStreams, resolveRecordingOutputPath);
+	registerRecordingStreamHandlers(
+		ipcMain,
+		recordingStreams,
+		resolveRecordingOutputPath,
+		lowDiskSpaceStartError,
+	);
 
 	/**
 	 * Writes a browser-recorded webcam clip next to a natively-recorded screen

electron/ipc/recordingStream.ts

@@ -96,10 +96,13 @@ export function registerRecordingStreamHandlers(
 	ipcMain: IpcMain,
 	registry: RecordingStreamRegistry,
 	resolveRecordingOutputPath: (fileName: string) => string,
+	lowDiskSpaceStartError: () => Promise<{ success: false; error: string } | null>,
 ): void {
 	ipcMain.handle(
 		"open-recording-stream",
 		async (_, fileName: string): Promise<{ success: boolean; error?: string }> => {
+			const diskSpaceError = await lowDiskSpaceStartError();
+			if (diskSpaceError) return diskSpaceError;
 			try {
 				await registry.open(fileName, resolveRecordingOutputPath(fileName));
 				return { success: true };

electron/main.ts

@@ -1,4 +1,3 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -60,6 +59,7 @@ import {
 	registerIpcHandlers,
 } from "./ipc/handlers";
 import { installMainProcessErrorGuards } from "./main-process-errors";
+import { RecordingsDirManager } from "./recording/recordingsDirManager";
 import { registerSttIpc, shutdownStt } from "./stt";
 import { checkLatestRelease } from "./update-checker";
 import { loadUpdateMode, saveUpdateMode } from "./update-settings";
@@ -105,18 +105,44 @@ disableHttpCacheForDevServer(app.commandLine, process.env);
 
 installMainProcessErrorGuards();
 
-export const RECORDINGS_DIR = path.join(app.getPath("userData"), "recordings");
+const recordingsDirManager = new RecordingsDirManager(app.getPath("userData"), () => isRecording);
+
+export const DEFAULT_RECORDINGS_DIR = recordingsDirManager.defaultDir;
+
+// Mutable: reassigned by setRecordingsDir() when the user picks a custom
+// location in settings. `handlers.ts` imports this as a live named binding,
+// so every call site there sees the change immediately — no restart needed.
+export let RECORDINGS_DIR = recordingsDirManager.dir;
 
 async function ensureRecordingsDir() {
 	try {
-		await fs.mkdir(RECORDINGS_DIR, { recursive: true });
+		await recordingsDirManager.ensureExists();
 		console.log("RECORDINGS_DIR:", RECORDINGS_DIR);
 		console.log("User Data Path:", app.getPath("userData"));
 	} catch (error) {
 		console.error("Failed to create recordings directory:", error);
 	}
 }
 
+/**
+ * Switches where recordings are read from and written to, going forward.
+ * Pass `null` to reset to the default (userData/recordings). Does not move
+ * any existing files — the old location is left untouched.
+ *
+ * Refuses to run while a recording is active: a capture in progress builds
+ * its output path from `RECORDINGS_DIR` up front, so swapping it mid-take
+ * would split one session's video and manifest across two directories. See
+ * RecordingsDirManager.setDir for the tested guard/ordering logic.
+ */
+export async function setRecordingsDir(customDir: string | null): Promise<string> {
+	RECORDINGS_DIR = await recordingsDirManager.setDir(customDir);
+	return RECORDINGS_DIR;
+}
+
+export function getRecordingsDirInfo() {
+	return recordingsDirManager.getInfo();
+}
+
 // The built directory structure
 //
 // ├─┬─┬ dist

electron/preload.ts

@@ -410,6 +410,27 @@ contextBridge.exposeInMainWorld("electronAPI", {
 	revealInFolder: (filePath: string) => {
 		return ipcRenderer.invoke("reveal-in-folder", filePath);
 	},
+	getRecordingsDir: () => {
+		return ipcRenderer.invoke("get-recordings-dir") as Promise<{
+			path: string;
+			isDefault: boolean;
+		}>;
+	},
+	chooseRecordingsDir: () => {
+		return ipcRenderer.invoke("choose-recordings-dir") as Promise<
+			{ success: true; path: string } | { success: false; canceled?: boolean; message?: string }
+		>;
+	},
+	resetRecordingsDir: () => {
+		return ipcRenderer.invoke("reset-recordings-dir") as Promise<
+			{ success: true; path: string } | { success: false; message?: string }
+		>;
+	},
+	checkRecordingDiskSpace: () => {
+		return ipcRenderer.invoke("check-recording-disk-space") as Promise<
+			{ success: true } | { success: false; error: string }
+		>;
+	},
 	getShortcuts: () => {
 		return ipcRenderer.invoke("get-shortcuts");
 	},

electron/recording/diskSpaceCheck.test.ts

@@ -0,0 +1,33 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { checkDiskSpace } from "./diskSpaceCheck";
+
+describe("checkDiskSpace", () => {
+	let dir: string;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(path.join(tmpdir(), "openscreen-disk-space-"));
+	});
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	it("reports the real filesystem as not low, using a near-zero threshold", async () => {
+		const status = await checkDiskSpace(dir, 1);
+		expect(status.low).toBe(false);
+		expect(status.availableBytes).toBeGreaterThan(0);
+	});
+
+	it("reports low when the threshold is set far above any real free space", async () => {
+		const status = await checkDiskSpace(dir, Number.MAX_SAFE_INTEGER);
+		expect(status.low).toBe(true);
+	});
+
+	it("does not throw and reports not-low for a directory that doesn't exist", async () => {
+		const status = await checkDiskSpace(path.join(dir, "does-not-exist"));
+		expect(status.low).toBe(false);
+	});
+});

electron/recording/diskSpaceCheck.ts

@@ -0,0 +1,34 @@
+// Pre-flight free-space check for recording start. Before this, the app had
+// no disk-space awareness anywhere: a recording could run for its full
+// duration and only fail once the user tried to save it, discarding the
+// take. Catching it before capture starts costs one statfs() call and saves
+// a wasted recording.
+import fs from "node:fs/promises";
+
+/** Recording output is usually well under this; below it, a take is likely to run out mid-capture. */
+export const LOW_DISK_SPACE_THRESHOLD_BYTES = 500 * 1024 * 1024;
+
+export interface DiskSpaceStatus {
+	/** Bytes free on the filesystem backing the recordings directory. */
+	availableBytes: number;
+	low: boolean;
+}
+
+/**
+ * Checks free space on the filesystem that backs `dir`. Never throws — a
+ * platform or filesystem that doesn't support statfs (or a directory that
+ * doesn't exist yet) reports as not-low, since a bad check must never block
+ * a recording that would otherwise have worked.
+ */
+export async function checkDiskSpace(
+	dir: string,
+	thresholdBytes: number = LOW_DISK_SPACE_THRESHOLD_BYTES,
+): Promise<DiskSpaceStatus> {
+	try {
+		const stats = await fs.statfs(dir);
+		const availableBytes = stats.bavail * stats.bsize;
+		return { availableBytes, low: availableBytes < thresholdBytes };
+	} catch {
+		return { availableBytes: Number.POSITIVE_INFINITY, low: false };
+	}
+}