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
// Typed read/write layer over `document.legacyEditor`.
//
// The v3 schema keeps `legacyEditor` as a `Record<string, unknown>` envelope so
// v2 projects round-trip without losing fields. The right panes and the
// per-region inspectors need a typed surface — this module provides it.
//
// The shape mirrors the legacy editor's `ProjectEditorState` so the same names
// are used everywhere; values that v3 owns directly (zoomRanges, annotations,
// transcripts, clips) stay in their dedicated fields.
import {
type CropRegion,
type CursorVisualSettings,
DEFAULT_CROP_REGION,
isWallpaperMotion,
isWebcamBackgroundMode,
type WallpaperMotion,
type WebcamBackgroundMode,
type WebcamLayoutPreset,
type WebcamMaskShape,
type WebcamPosition,
type WebcamSizePreset,
} from "@/components/video-editor/types";
import { normalizeCursorThemeId, readCursorAsArrow } from "@/lib/cursor/cursorThemes";
import {
DEFAULT_PROJECT_APPEARANCE,
type FrameTheme,
isFrameTheme,
type RecordingFrame,
readBackgroundBlur,
readBounded,
readRecordingFrame,
readWebcamAnchor,
readWebcamMask,
type WebcamAnchor,
type WebcamMask,
} from "@/lib/projectDefaults";
import type { AspectRatio } from "@/utils/aspectRatioUtils";
import type { AxcutDocument } from "../schema";
// ponytail: avoid dragging in lib/exporter full surface here — we only
// need the type names. Wallpaper + cursor theme are stored as plain strings
// for the same reason (their canonical types live in lib/wallpaper and
// lib/cursor/cursorThemes as the source of truth).
/** Output gain bound, shared by the slider, this store and `finish_audio` (Rust).
*
* A linear gain is the one audio setting that behaves identically on the preview's source
* file and on the export's assembled timeline, which is why it is the only one left. A sync
* offset was tried and removed: the preview seeks in SOURCE time while the export shifts the
* stretched, concatenated timeline, so the same value meant different delays under a speed
* region, and near a cut the export pulls audio across the junction while the preview cannot. */
export const AUDIO_GAIN_DB_LIMIT = 12;
export const AUDIO_TRACK_GAIN_DB_MIN = -60;
export const AUDIO_TRACK_GAIN_DB_MAX = 12;
/** dB to the linear scalar every side of the boundary multiplies by.
*
* Exported rather than written out three times. `finish_audio` applies
* `10f32.powf(gain_db / 20.0)` per sample; the preview feeds this to a `GainNode`; the
* timeline waveform scales its bars by it. The claim those three make together — that what
* you see is what you hear is what you export — only holds while they are the same number,
* and a hand-copied `10 ** (dB / 20)` is exactly how that stops being true. */
export function audioGainScalar(gainDb: number): number {
return 10 ** (gainDb / 20);
}
/**
* Where the webcam crop window sits inside the room its zoom leaves, 0..1 per axis:
* 0 hard against one edge, 1 against the other, 0.5 centred.
*
* Stored because the rect cannot hold it. At 100% zoom the crop IS the frame, so `x` and `y`
* are necessarily 0 and the pan they used to be read back from is gone — which meant a trip
* down to 100% and back erased the framing the user had set. Expressed as a fraction of the
* available room, the pan survives every zoom, including the one where it does not apply.
*
* This never leaves the app. `webcamCropRegion` remains the only thing the scene carries to
* the compositor, so the preview and the export see exactly what they saw before.
*/
export interface CropPan {
x: number;
y: number;
}
/** Centred: the crop window sits in the middle of whatever room the zoom leaves. */
const DEFAULT_CROP_PAN: CropPan = { x: 0.5, y: 0.5 };
export interface EditorSettingsSnapshot {
wallpaper: string;
/** Only a gradient wallpaper moves; kept as chosen when the wallpaper changes kind. */
wallpaperMotion: WallpaperMotion;
/** The frame drawn around the recording (window chrome or a modelled device), or "none". */
frame: RecordingFrame;
/** Light or dark, for whichever frame is on. Inert with `frame: "none"`. */
frameTheme: FrameTheme;
aspectRatio: AspectRatio;
/**
* Under a fixed format that is not the recording's shape: fill the frame with a window of
* the recording that follows the smoothed cursor (true), or show it whole (false). `null`
* until the user picks a format or this option: projects from before it keep showing the
* recording whole. See `formatFillAvailability`.
*/
formatFollowCursor: boolean | null;
shadowIntensity: number;
backgroundBlur: number;
motionBlurAmount: number;
depthOfField: boolean;
borderRadius: number;
padding: number;
cropRegion: CropRegion;
webcamLayoutPreset: WebcamLayoutPreset;
/** The camera's proportions. `circle` and `rounded` are read as a roundness: see `readWebcamMask`. */
webcamMaskShape: WebcamMask;
/** 0 square corners to 1 fully round, a fraction of half the camera's short side. */
webcamRoundness: number;
webcamMirrored: boolean;
webcamReactiveZoom: boolean;
webcamSizePreset: WebcamSizePreset;
/** Where the picture-in-picture camera sits, at a constant distance from the border. */
webcamAnchor: WebcamAnchor;
webcamCropRegion: CropRegion;
/** Where the crop window sits in the room the zoom leaves it, 0..1 per axis.
* Authoritative: `webcamCropRegion.x/y` are rebuilt from it on read. */
webcamCropPan: CropPan;
audioGainDb: number;
webcamBackgroundMode: WebcamBackgroundMode;
webcamWallpaper: string;
webcamBlurIntensity: number;
cursor: CursorVisualSettings;
cursorShow: boolean;
cursorAutoHide: boolean;
cursorTheme: string;
autoFocusAll: boolean;
}
export const DEFAULT_EDITOR_SETTINGS: EditorSettingsSnapshot = {
// Opinionated by default: the wallpaper and the padding were already on, but
// with square corners and no shadow the recording read as a rectangle pasted
// onto the background rather than a window floating above it (#271 reported
// the symptom and blamed the padding). These three are the rest of that look;
// shipping the background without them was shipping half a composition.
...DEFAULT_PROJECT_APPEARANCE,
cropRegion: DEFAULT_CROP_REGION,
webcamCropRegion: DEFAULT_CROP_REGION,
webcamCropPan: DEFAULT_CROP_PAN,
audioGainDb: 0,
formatFollowCursor: null,
};
interface LegacyShape {
wallpaper?: string;
wallpaperMotion?: WallpaperMotion;
/** `unknown`: it may still hold `window-light` / `window-dark` (`readRecordingFrame`). */
frame?: unknown;
frameTheme?: FrameTheme;
aspectRatio?: AspectRatio;
formatFollowCursor?: boolean;
shadowIntensity?: number;
backgroundBlur?: number;
/** Before the amount: an on/off switch. Read by `readBackgroundBlur`, never written. */
showBlur?: boolean;
motionBlurAmount?: number;
depthOfField?: boolean;
borderRadius?: number;
padding?: number;
cropRegion?: CropRegion;
webcamLayoutPreset?: WebcamLayoutPreset;
webcamMaskShape?: WebcamMaskShape;
webcamRoundness?: number;
webcamMirrored?: boolean;
webcamReactiveZoom?: boolean;
webcamSizePreset?: WebcamSizePreset;
webcamAnchor?: WebcamAnchor;
/** Written by builds that let the camera be dragged anywhere; read as the nearest anchor. */
webcamPosition?: WebcamPosition | null;
webcamCropRegion?: CropRegion;
webcamCropPan?: CropPan;
audioGainDb?: number;
webcamBackgroundMode?: WebcamBackgroundMode;
webcamWallpaper?: string;
webcamBlurIntensity?: number;
cursorSize?: number;
cursorSmoothing?: number;
cursorMotionBlur?: number;
cursorClickBounce?: number;
cursorModel3d?: boolean;
/** `unknown`: read through `readCursorAsArrow`, which drops what this build does not know. */
cursorAsArrow?: unknown;
/** Written by builds with one "always use the arrow" switch; read as every kind. */
cursorAlwaysArrow?: boolean;
cursorClickImpact?: boolean;
cursorClickSound?: boolean;
cursorClickSoundGainDb?: number;
cursorShow?: boolean;
cursorAutoHide?: boolean;
cursorTheme?: string;
autoFocusAll?: boolean;
}
function isShape(value: unknown): value is LegacyShape {
return typeof value === "object" && value !== null;
}
function isNumber(v: unknown): v is number {
return typeof v === "number" && Number.isFinite(v);
}
function isBoolean(v: unknown): v is boolean {
return typeof v === "boolean";
}
function isString(v: unknown): v is string {
return typeof v === "string";
}
export function getEditorSettings(doc: AxcutDocument | null | undefined): EditorSettingsSnapshot {
const legacy = isShape(doc?.legacyEditor) ? (doc.legacyEditor as LegacyShape) : null;
const num = (v: unknown, fallback: number) => (isNumber(v) ? v : fallback);
const bool = (v: unknown, fallback: boolean) => (isBoolean(v) ? v : fallback);
const str = (v: unknown, fallback: string) => (isString(v) ? v : fallback);
// `window-light` / `window-dark` were the frame AND its theme; they split here.
const stored = readRecordingFrame(legacy?.frame);
const defaults = DEFAULT_EDITOR_SETTINGS;
const cursor: CursorVisualSettings = {
size: readBounded(legacy?.cursorSize, "cursorSize", defaults.cursor.size),
smoothing: readBounded(legacy?.cursorSmoothing, "cursorSmoothing", defaults.cursor.smoothing),
motionBlur: readBounded(
legacy?.cursorMotionBlur,
"cursorMotionBlur",
defaults.cursor.motionBlur,
),
clickBounce: readBounded(
legacy?.cursorClickBounce,
"cursorClickBounce",
defaults.cursor.clickBounce,
),
// Absent in every project saved before the setting existed: those keep the flat cursor.
model3d: bool(legacy?.cursorModel3d, DEFAULT_EDITOR_SETTINGS.cursor.model3d),
asArrow: readCursorAsArrow(
legacy?.cursorAsArrow,
legacy?.cursorAlwaysArrow,
defaults.cursor.asArrow,
),
clickImpact: bool(legacy?.cursorClickImpact, DEFAULT_EDITOR_SETTINGS.cursor.clickImpact),
clickSound: bool(legacy?.cursorClickSound, DEFAULT_EDITOR_SETTINGS.cursor.clickSound),
clickSoundGainDb: readBounded(
legacy?.cursorClickSoundGainDb,
"cursorClickSoundGainDb",
defaults.cursor.clickSoundGainDb,
),
autoHide: bool(legacy?.cursorAutoHide, DEFAULT_EDITOR_SETTINGS.cursorAutoHide),
};
// The pan is authoritative and the rect's offset is rebuilt from it, so the two cannot
// drift apart — on disk, or in a patch that wrote one and not the other. Only the SIZE
// survives from the stored rect; `pan * (1 - size)` is a position that cannot leave the
// frame, which is why nothing here clamps it.
// `circle` and `rounded` were a proportion and a rounding in one value; they split here.
const webcamMask = readWebcamMask(legacy?.webcamMaskShape, legacy?.webcamRoundness);
const storedCrop = normaliseCropRegion(legacy?.webcamCropRegion);
const webcamCropPan = normaliseCropPan(legacy?.webcamCropPan, storedCrop);
const webcamCrop: CropRegion = {
...storedCrop,
x: webcamCropPan.x * (1 - storedCrop.width),
y: webcamCropPan.y * (1 - storedCrop.height),
};
return {
wallpaper: str(legacy?.wallpaper, DEFAULT_EDITOR_SETTINGS.wallpaper),
wallpaperMotion: isWallpaperMotion(legacy?.wallpaperMotion)
? legacy.wallpaperMotion
: DEFAULT_EDITOR_SETTINGS.wallpaperMotion,
// An unknown value (a frame a newer build added) reads as no frame, like the compositor.
// `window-light` / `window-dark` split into a frame PLUS a theme, so a project written
// before the theme existed opens with the look it had (`readRecordingFrame`).
frame: stored?.frame ?? DEFAULT_EDITOR_SETTINGS.frame,
frameTheme: isFrameTheme(legacy?.frameTheme)
? legacy.frameTheme
: (stored?.theme ?? DEFAULT_EDITOR_SETTINGS.frameTheme),
aspectRatio: legacy?.aspectRatio ?? DEFAULT_EDITOR_SETTINGS.aspectRatio,
formatFollowCursor:
typeof legacy?.formatFollowCursor === "boolean" ? legacy.formatFollowCursor : null,
// Every number below is read into its `SETTING_BOUNDS` range: the slider's range, and the
// one a preset and the agent are held to. A stored value past it plays at the bound.
shadowIntensity: readBounded(
legacy?.shadowIntensity,
"shadowIntensity",
defaults.shadowIntensity,
),
backgroundBlur: readBackgroundBlur(legacy, defaults.backgroundBlur),
motionBlurAmount: readBounded(
legacy?.motionBlurAmount,
"motionBlurAmount",
defaults.motionBlurAmount,
),
depthOfField: bool(legacy?.depthOfField, DEFAULT_EDITOR_SETTINGS.depthOfField),
borderRadius: readBounded(legacy?.borderRadius, "borderRadius", defaults.borderRadius),
padding: readBounded(legacy?.padding, "padding", defaults.padding),
cropRegion: legacy?.cropRegion ?? DEFAULT_EDITOR_SETTINGS.cropRegion,
webcamLayoutPreset: legacy?.webcamLayoutPreset ?? DEFAULT_EDITOR_SETTINGS.webcamLayoutPreset,
webcamMaskShape: webcamMask.shape,
webcamRoundness: webcamMask.roundness,
webcamMirrored: bool(legacy?.webcamMirrored, DEFAULT_EDITOR_SETTINGS.webcamMirrored),
webcamReactiveZoom: bool(
legacy?.webcamReactiveZoom,
DEFAULT_EDITOR_SETTINGS.webcamReactiveZoom,
),
webcamSizePreset: readBounded(
legacy?.webcamSizePreset,
"webcamSizePreset",
defaults.webcamSizePreset,
),
webcamAnchor: readWebcamAnchor(legacy?.webcamAnchor, legacy?.webcamPosition),
webcamCropRegion: webcamCrop,
webcamCropPan: webcamCropPan,
// Same bound the slider offers and the native `finish_audio` clamps to. Two
// different ranges for one value is how a project ends up exporting a gain the
// UI cannot display.
audioGainDb: Math.min(
AUDIO_GAIN_DB_LIMIT,
Math.max(-AUDIO_GAIN_DB_LIMIT, num(legacy?.audioGainDb, 0)),
),
webcamBackgroundMode: isWebcamBackgroundMode(legacy?.webcamBackgroundMode)
? legacy.webcamBackgroundMode
: DEFAULT_EDITOR_SETTINGS.webcamBackgroundMode,
webcamWallpaper: str(legacy?.webcamWallpaper, DEFAULT_EDITOR_SETTINGS.webcamWallpaper),
// Unclamped, a stored 1000 reached `blur(25000px)` on the preview canvas and wedged the
// compositing thread.
webcamBlurIntensity: readBounded(
legacy?.webcamBlurIntensity,
"webcamBlurIntensity",
defaults.webcamBlurIntensity,
),
cursor,
cursorShow: bool(legacy?.cursorShow, DEFAULT_EDITOR_SETTINGS.cursorShow),
cursorAutoHide: bool(legacy?.cursorAutoHide, DEFAULT_EDITOR_SETTINGS.cursorAutoHide),
// A pack the app no longer ships reads as the default art, which is what the renderer
// draws for it anyway. Left raw, the id would also switch off the modelled cursor: the
// compositor only builds it for the default theme.
cursorTheme: normalizeCursorThemeId(legacy?.cursorTheme),
autoFocusAll: bool(legacy?.autoFocusAll, DEFAULT_EDITOR_SETTINGS.autoFocusAll),
};
}
export interface EditorSettingsPatch {
wallpaper?: string;
wallpaperMotion?: WallpaperMotion;
frame?: RecordingFrame;
frameTheme?: FrameTheme;
aspectRatio?: AspectRatio;
formatFollowCursor?: boolean;
shadowIntensity?: number;
backgroundBlur?: number;
motionBlurAmount?: number;
depthOfField?: boolean;
borderRadius?: number;
padding?: number;
cropRegion?: CropRegion;
webcamLayoutPreset?: WebcamLayoutPreset;
webcamMaskShape?: WebcamMask;
webcamRoundness?: number;
webcamMirrored?: boolean;
webcamReactiveZoom?: boolean;
webcamSizePreset?: WebcamSizePreset;
webcamAnchor?: WebcamAnchor;
webcamCropRegion?: CropRegion;
webcamCropPan?: CropPan;
audioGainDb?: number;
webcamBackgroundMode?: WebcamBackgroundMode;
webcamWallpaper?: string;
webcamBlurIntensity?: number;
cursor?: Partial<CursorVisualSettings> & { theme?: string; show?: boolean; autoHide?: boolean };
cursorAutoHide?: boolean;
autoFocusAll?: boolean;
}
function nextLegacy(current: LegacyShape | null, patch: EditorSettingsPatch): LegacyShape {
const base: LegacyShape = current ?? {};
// Spread, but only over keys the patch actually set — a plain {...base,
// ...patch} would write undefined over a value the caller left alone.
// `cursor` is handled separately below: its keys are renamed (size ->
// cursorSize), so it is not a straight passthrough.
// The Pick keeps what the 16 `if`s used to check: a patch key with no
// LegacyShape counterpart fails to compile instead of leaking into the
// persisted blob.
const { cursor: _cursor, ...rest } = patch;
const defined = Object.fromEntries(
Object.entries(rest).filter(([, v]) => v !== undefined),
) as Partial<Pick<LegacyShape, keyof Omit<EditorSettingsPatch, "cursor">>>;
const next: LegacyShape = { ...base, ...defined };
if (patch.cursor) {
const c = patch.cursor;
if (c.size !== undefined) next.cursorSize = c.size;
if (c.smoothing !== undefined) next.cursorSmoothing = c.smoothing;
if (c.motionBlur !== undefined) next.cursorMotionBlur = c.motionBlur;
if (c.clickBounce !== undefined) next.cursorClickBounce = c.clickBounce;
if (c.model3d !== undefined) next.cursorModel3d = c.model3d;
if (c.asArrow !== undefined) {
next.cursorAsArrow = c.asArrow;
// The kinds now say it all; the old switch would only contradict them.
delete next.cursorAlwaysArrow;
}
if (c.clickImpact !== undefined) next.cursorClickImpact = c.clickImpact;
if (c.clickSound !== undefined) next.cursorClickSound = c.clickSound;
if (c.clickSoundGainDb !== undefined) next.cursorClickSoundGainDb = c.clickSoundGainDb;
if (c.theme !== undefined) next.cursorTheme = c.theme;
if (c.show !== undefined) next.cursorShow = c.show;
if (c.autoHide !== undefined) next.cursorAutoHide = c.autoHide;
}
if (patch.cursorAutoHide !== undefined) next.cursorAutoHide = patch.cursorAutoHide;
return next;
}
export function patchEditorSettings(doc: AxcutDocument, patch: EditorSettingsPatch): AxcutDocument {
const current = isShape(doc.legacyEditor) ? (doc.legacyEditor as LegacyShape) : null;
return {
...doc,
legacyEditor: nextLegacy(current, patch) as Record<string, unknown>,
};
}
const MIN_CROP_SIZE = 0.01;
/**
* Recovers the pan of a crop rect authored before the pan was stored.
*
* `x / (1 - width)` is the expression the pane used to derive the slider's value from the
* rect on every render, and it has to stay that expression: every project on disk today has
* a rect and no pan, so anything else here would silently reframe them on first open. A
* full-frame crop has no room to sit in, so it reports centred — the one case where the
* answer is arbitrary, and the one case where nothing depends on it.
*/
export function panOfCropRegion(crop: CropRegion): CropPan {
// Guarded at 1 and not at some epsilon below it: the zoom slider is integer percent, so
// the smallest window short of full frame is 100/101 and leaves ~0.0099 of room — a
// perfectly ordinary divisor that a wider guard would throw away as if it were centred.
// `normaliseCropRegion` keeps `x + width <= 1`, so the quotient is in range by
// construction; the clamp is for a hand-edited document that got there another way.
const axis = (offset: number, size: number) =>
size >= 1 ? 0.5 : Math.min(1, Math.max(0, offset / (1 - size)));
return { x: axis(crop.x, crop.width), y: axis(crop.y, crop.height) };
}
function normaliseCropPan(value: unknown, crop: CropRegion): CropPan {
if (!value || typeof value !== "object") return panOfCropRegion(crop);
const candidate = value as Record<string, unknown>;
const fallback = panOfCropRegion(crop);
return {
x: isNumber(candidate.x) ? Math.min(1, Math.max(0, candidate.x)) : fallback.x,
y: isNumber(candidate.y) ? Math.min(1, Math.max(0, candidate.y)) : fallback.y,
};
}
function normaliseCropRegion(value: unknown): CropRegion {
if (!value || typeof value !== "object") return DEFAULT_CROP_REGION;
const candidate = value as Record<string, unknown>;
const x = isNumber(candidate.x) ? Math.min(1 - MIN_CROP_SIZE, Math.max(0, candidate.x)) : 0;
const y = isNumber(candidate.y) ? Math.min(1 - MIN_CROP_SIZE, Math.max(0, candidate.y)) : 0;
const width = isNumber(candidate.width)
? Math.min(1 - x, Math.max(MIN_CROP_SIZE, candidate.width))
: 1 - x;
const height = isNumber(candidate.height)
? Math.min(1 - y, Math.max(MIN_CROP_SIZE, candidate.height))
: 1 - y;
return { x, y, width, height };
}