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
// Vendored from @axcut/schema (https://github.com/EtienneLescot/axcut) —
// original file: packages/axcut-schema/src/index.ts. Modifications for
// OpenScreen's AI-edition merge (Phase 0, see technical-documentation/architecture/document-model.md):
//
// 1. axcutSchemaVersion bumped 2 -> 3.
// 2. clip.sourceEndSec made optional (duration is unknown until asset is probed).
// 3. documentSchema gains annotations[], zoomRanges[], legacyEditor envelopes
// so OpenScreen's existing regions + appearance settings survive the merge.
//
// ponytail: this exists as the SSOT project model. Phase 0 only touches the
// shape — runtime ops, IPC, and exporter integration land in Phase 1+.
import { z } from "zod";
// Cycle-safe: `aspectRatioUtils` has no schema dependency, and `document/outputFormat`
// is downstream of schema. We import the leaf tokeniser directly so the v5→v6 upgrader
// can rewrite `"native"` without dragging in the whole output-format module.
// Relative, not `@/`: the Electron main bundle imports this module and
// vite-plugin-electron builds it without the root resolve.alias.
import { toAspectRatioToken } from "../../../utils/aspectRatioUtils";
import { LAYOUT_PRESETS } from "../../layoutTypes";
import { clampToBound } from "../../projectDefaults";
// Cycle-safe: `document/ids` only pulls `uuid`, and `timeline/timelineMap`'s
// transitive value-imports (region-ventilation, virtual-preview) import from this
// module TYPE-ONLY, so requiring them here never re-enters schema at runtime.
import { createId } from "../document/ids";
import { materializeLayouts } from "../document/layout";
import { anchorRegionsWithDerivedMs } from "../timeline/timelineMap";
// 4. v5 — modifiers (zoom / annotation / speed / cameraFullscreen) become
// CLIP-ANCHORED fragments: `{clipId, sourceStartSec, sourceEndSec}` is the
// source of truth, `startMs`/`endMs` stay as a derived cache for the
// transition. See technical-documentation/architecture/timeline-model.md
// 5. v6 — `"native"` AspectRatio is retired OPPORTUNISTICALLY. The v5→v6
// upgrader rewrites a stored `"native"` to a concrete `"W:H"` token from
// the timeline's largest clip, but only when the source dimensions are
// actually known; otherwise it leaves the sentinel, which keeps resolving
// dynamically at runtime. See `upgradeV5DocumentToV6` for why guessing
// would corrupt v1.7 imports.
// 6. v7 — trims join the v5 clip anchor: `AxcutTrimRange` gains `clipId`.
// They were the last region kind still addressed by `assetId` alone, which
// made them AMBIGUOUS the moment two clips drew from the same asset (a
// duplicated clip): every reader either matched both clips or picked the
// first. See `upgradeV6DocumentToV7`.
// 7. v8 — Auto becomes the default AspectRatio. A document that never chose a
// ratio stores none and reads the default, so the upgrader pins the one it
// has always shown, 16:9. See `upgradeV7DocumentToV8`.
// 8. v9 — layoutRegions replaces Full Camera with a typed layout partition.
// Legacy camera envelopes are migrated once, preserving their original easing.
export const axcutSchemaVersion = 9;
// ponytail: every region schema shares the same monotonicity rule
// (end >= start) with the same error shape. Factor the refine so the
// five call sites stay declarative; the message + path stay tied to
// the field names (e.g. `endSec >= startSec`, `endMs >= startMs`).
const endGteStart = <T extends z.ZodObject<z.ZodRawShape>>(
schema: T,
endKey: keyof T["shape"] & string,
startKey: keyof T["shape"] & string,
) =>
schema.refine((data) => (data[endKey] as number) >= (data[startKey] as number), {
message: `${endKey} must be greater than or equal to ${startKey}`,
path: [endKey],
});
export const isoDateSchema = z.string().datetime({ offset: true });
export const wordSchema = z
.object({
id: z.string().min(1),
segmentId: z.string().min(1),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
text: z.string(),
// Provenance of the TEXT, so a hand-corrected word can be told from a
// transcribed one. Both fields are additive and absent on every document
// written before them (like `cameraTrack.width`), so no schema bump: an
// older build simply drops them on save.
//
// `document/transcript.ts` is the only writer, and it keeps the pair
// consistent: `originalText` is set from the ASR text the first time a user
// rewrites the word and never overwritten afterwards, so it stays the revert
// target however many times the word is edited; typing the original back
// clears both, which IS the revert.
//
// Absent `source` means the word came from the transcriber. It is what makes
// a re-transcription able to carry the user's corrections forward
// (`carryOverWordEdits`) instead of silently discarding them — and what a
// future TTS pass will read to know which words it has to speak.
originalText: z.string().optional(),
source: z.enum(["asr", "user", "synth"]).optional(),
})
.refine((data) => data.endSec >= data.startSec, {
message: "endSec must be greater than or equal to startSec",
path: ["endSec"],
});
export const transcriptSegmentSchema = z
.object({
id: z.string().min(1),
kind: z.enum(["speech", "silence"]),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
text: z.string(),
wordIds: z.array(z.string().min(1)).default([]),
})
.refine((data) => data.endSec >= data.startSec, {
message: "endSec must be greater than or equal to startSec",
path: ["endSec"],
});
export const transcriptSchema = z.object({
assetId: z.string().min(1),
language: z.string().min(1),
sourceDslPath: z.string().optional(),
sourceJsonPath: z.string().optional(),
segments: z.array(transcriptSegmentSchema).default([]),
words: z.array(wordSchema).default([]),
});
export const assetVideoSchema = z.object({
codec: z.string().default("unknown"),
width: z.number().int().nonnegative().default(0),
height: z.number().int().nonnegative().default(0),
fps: z.number().nonnegative().default(0),
});
export const assetAudioSchema = z.object({
codec: z.string().default("unknown"),
sampleRate: z.number().int().nonnegative().default(0),
channels: z.number().int().nonnegative().default(0),
});
// ponytail: the webcam is a derived stream — it is NOT edited. Cut / zoom /
// speed live on the main timeline and apply to the camera as a render of the
// same source-time progression. Source path comes from the recording
// session sidecar (auto-linked when an asset is imported from a recording).
// `offsetMs` accounts for the camera starting before/after the screen.
//
// Lives on the asset (not the document) since P4 (per-asset media links) —
// a project can hold multiple assets, each recorded with its own camera (or
// none). See technical-documentation/architecture/document-model.md.
export const cameraTrackSchema = z
.object({
sourcePath: z.string().min(1),
startMs: z.number().nonnegative().default(0),
offsetMs: z.number().int().default(0),
visible: z.boolean().default(true),
// The camera file's real pixel dimensions, the camera's answer to
// `assetVideoSchema.width/height` for the screen. The layout box for the PiP is
// derived from them, and without them it falls back to a hardcoded 4:3 — which is
// how a 16:9 camera came out framed one way in the preview (where a mounted
// <video> had reported its size) and another way in an export (where none had).
//
// Optional and absent on every document written before this, exactly like
// `transcriptionFailure` below: additive, so no schema-version bump, and an older
// build simply drops the key on save. The fallback stays for that window.
width: z.number().int().positive().optional(),
height: z.number().int().positive().optional(),
})
.nullable()
.default(null);
// Why a media can never be transcribed. Only the DETERMINISTIC verdicts live
// here: a container with no audio track (a screen recording captured with no
// mic and no system audio — the common case) fails identically on every
// attempt, and re-deciding that costs a full audio extraction on each project
// open. Transient failures (engine down, decode hiccup) are deliberately NOT
// persistable and stay in the transcription store for the session, so the next
// load retries them. See `src/lib/ai-edition/transcription/status.ts`.
export const assetTranscriptionFailureSchema = z.object({
kind: z.enum(["no-audio", "unsupported-audio"]),
message: z.string().default(""),
at: isoDateSchema.optional(),
});
export const assetSchema = z.object({
id: z.string().min(1),
// Widened from a `"video"` literal when external-audio import landed (issue
// #350). An imported voiceover / BGM / SFX file carries no video stream, so it
// needs its own kind; every document written before this only ever held
// `"video"`, which still validates, so the widening is additive (no
// schemaVersion bump — same rule as `transcriptionFailure` below).
kind: z.enum(["video", "audio"]).default("video"),
label: z.string().min(1),
originalPath: z.string().min(1),
proxyPath: z.string().optional(),
waveformPath: z.string().optional(),
durationSec: z.number().nonnegative().optional(),
// P3.1 — file size captured at import time (fs.stat in document-service).
sizeBytes: z.number().int().nonnegative().optional(),
video: assetVideoSchema.optional(),
audio: assetAudioSchema.optional(),
// Absent on every document written before auto-transcription; additive, so
// no schema-version bump (an older build simply drops the key on save).
transcriptionFailure: assetTranscriptionFailureSchema.nullish(),
cameraTrack: cameraTrackSchema,
});
// A crop is a sub-rectangle of the source video, expressed as fractions
// (0-1) of its full frame. Lives on the clip (not the document/legacyEditor
// envelope) since a crop frames one specific piece of footage — two clips
// cut from the same or different assets can reasonably want different
// framings. Mirrors `CropRegion` in `src/components/video-editor/types.ts`;
// duplicated here so the schema package has no dependency on the React
// editor module (same rationale as AnnotationRegion/ZoomRegion above).
export const clipCropRegionSchema = z.object({
x: z.number().min(0).max(1),
y: z.number().min(0).max(1),
width: z.number().min(0).max(1),
height: z.number().min(0).max(1),
});
export const clipSchema = z
.object({
id: z.string().min(1),
assetId: z.string().min(1),
sourceStartSec: z.number().nonnegative(),
// ponytail: optional because v2 migrations have unknown asset duration at
// migration time. The renderer fills this in once StreamingVideoDecoder probes
// the file (Phase 1+).
sourceEndSec: z.number().nonnegative().optional(),
timelineStartSec: z.number().nonnegative(),
timelineEndSec: z.number().nonnegative(),
wordRefs: z.array(z.string().min(1)).default([]),
origin: z.enum(["system", "agent", "user"]),
reason: z.string().default(""),
// Absent/undefined means "no crop" (full frame) — callers should treat
// that as the identity region {x:0,y:0,width:1,height:1} rather than
// storing the identity explicitly, so untouched clips stay lean.
cropRegion: clipCropRegionSchema.optional(),
})
.refine((data) => data.timelineEndSec >= data.timelineStartSec, {
message: "timelineEndSec must be greater than or equal to timelineStartSec",
path: ["timelineEndSec"],
})
.refine((data) => data.sourceEndSec === undefined || data.sourceEndSec >= data.sourceStartSec, {
message: "sourceEndSec must be greater than or equal to sourceStartSec",
path: ["sourceEndSec"],
});
export const gapSchema = endGteStart(
z.object({
id: z.string().min(1),
timelineStartSec: z.number().nonnegative(),
timelineEndSec: z.number().nonnegative(),
reason: z.string().default(""),
}),
"timelineEndSec",
"timelineStartSec",
);
export const rangeSchema = endGteStart(
z.object({
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
reason: z.string().default(""),
}),
"endSec",
"startSec",
);
// ponytail: trimRanges reference asset source-time (not timeline). trimRegions
// in v2 are the inverse — a skip = the region inside the source we DON'T keep.
//
// `startSec`/`endSec` ARE the source range of `clipAnchorShape` under their older
// names, so a trim needs only `clipId` to become a complete v5 clip anchor. Optional
// for the same reason it is on the other kinds: a trim that could not be anchored
// (`upgradeV6DocumentToV7`) is kept, not dropped, and falls back to the historical
// asset-wide matching. Everything that asks "does this trim apply to this clip?" must
// go through `trimAppliesToClip` (timeline/trim-mapping) so the two rules stay one rule.
export const trimRangeSchema = endGteStart(
z.object({
id: z.string().min(1),
assetId: z.string().min(1),
clipId: z.string().min(1).optional(),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
reason: z.string().default(""),
origin: z.enum(["system", "agent", "user"]),
}),
"endSec",
"startSec",
);
export const timelineSchema = z.preprocess(
// Back-compat: the field was renamed skipRanges → trimRanges. Old persisted
// documents (disk + browser-shim localStorage) still carry `skipRanges`;
// fold it into `trimRanges` on load so trims aren't silently dropped.
(value) => {
if (value && typeof value === "object" && !Array.isArray(value)) {
const v = value as Record<string, unknown>;
if (v.skipRanges !== undefined && v.trimRanges === undefined) {
return { ...v, trimRanges: v.skipRanges };
}
}
return value;
},
z.object({
clips: z.array(clipSchema).default([]),
gaps: z.array(gapSchema).default([]),
trimRanges: z.array(trimRangeSchema).default([]),
// Additive, like every optional field before it: absent on every document written
// before this, so no schema bump — an older build simply drops the key on save, and
// the words it belonged to keep their text and lose only their pause.
muteRanges: z.array(rangeSchema).default([]),
speedRanges: z.array(rangeSchema).default([]),
captionRanges: z.array(rangeSchema).default([]),
}),
);
export const timelineOperationSchema = z.discriminatedUnion("type", [
z.object({
type: z.literal("replace_timeline"),
reason: z.string().default(""),
intervals: z
.array(z.object({ startSec: z.number().nonnegative(), endSec: z.number().nonnegative() }))
.default([]),
}),
z.object({
type: z.literal("drop_range"),
reason: z.string().default(""),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
}),
z.object({
type: z.literal("drop_word_range"),
reason: z.string().default(""),
startWordId: z.string().min(1),
endWordId: z.string().min(1),
}),
z.object({
type: z.literal("add_trim_range"),
reason: z.string().default(""),
assetId: z.string().min(1),
// Which clip the cut was authored on. Optional so callers that genuinely have no
// clip context still work, but every UI path knows it — without it a trim on the
// second clip of a duplicated asset is indistinguishable from one on the first.
clipId: z.string().min(1).optional(),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
}),
z.object({
type: z.literal("update_trim_range"),
reason: z.string().default(""),
trimRangeId: z.string().min(1),
startSec: z.number().nonnegative(),
endSec: z.number().nonnegative(),
}),
z.object({
type: z.literal("remove_trim_range"),
reason: z.string().default(""),
trimRangeId: z.string().min(1),
}),
z.object({
type: z.literal("update_clip_range"),
reason: z.string().default(""),
clipId: z.string().min(1),
sourceStartSec: z.number().nonnegative(),
sourceEndSec: z.number().nonnegative().optional(),
}),
z.object({
type: z.literal("duplicate_clip"),
reason: z.string().default(""),
clipId: z.string().min(1),
}),
z.object({
type: z.literal("move_clip"),
reason: z.string().default(""),
clipId: z.string().min(1),
// ponytail: `insertIndex`, matching the ONE implementation
// (`AxcutTimelineOperation` in document/operations.ts, applied by
// `applyTimelineOperation`). This schema declared `timelineStartSec`
// instead — a second, incompatible contract for the same op name, with no
// importer anywhere to notice. Whoever wired the two together next would
// have had a parse that accepted what the dispatcher could not run.
insertIndex: z.number().int().nonnegative(),
}),
z.object({
type: z.literal("insert_asset_clip"),
reason: z.string().default(""),
assetId: z.string().min(1),
beforeClipId: z.string().min(1).nullable(),
afterClipId: z.string().min(1).nullable(),
sourceStartSec: z.number().nonnegative(),
sourceEndSec: z.number().nonnegative().optional(),
}),
z.object({
type: z.literal("restore_full_timeline"),
reason: z.string().default(""),
}),
]);
// OpenScreen additions to the axcut document. Mirrors src/components/video-editor/types.ts
// (AnnotationRegion / ZoomRegion) — duplicated here so the schema package has no
// dependency on the React editor module.
export const blurDataSchema = z
.object({
type: z.enum(["blur", "mosaic"]).default("mosaic"),
shape: z.enum(["rectangle", "oval", "freehand"]).default("rectangle"),
color: z.enum(["white", "black"]).default("white"),
intensity: z.number().nonnegative().default(12),
blockSize: z.number().nonnegative().default(12),
freehandPoints: z
.array(z.object({ x: z.number().nonnegative(), y: z.number().nonnegative() }))
.optional(),
})
.optional();
export const figureDataSchema = z
.object({
arrowDirection: z
.enum(["up", "down", "left", "right", "up-right", "up-left", "down-right", "down-left"])
.default("right"),
color: z.string().default("#34B27B"),
strokeWidth: z.number().nonnegative().default(4),
})
.optional();
const annotationStyleSchema = z.object({
color: z.string().default("#ffffff"),
backgroundColor: z.string().default("transparent"),
// `backgroundColor: "transparent"` is how every renderer reads "no background", so switching
// the background off has to overwrite the colour the user picked — and switching it back on had
// nothing left to restore, which is why it always came back black. This keeps that last colour
// so the toggle is reversible. Nothing renders it: the paint path still reads `backgroundColor`
// alone.
lastBackgroundColor: z.string().optional(),
// Read into its bound rather than refused: a size of 0, which an emptied field used to store,
// must still open, as the smallest text instead of none.
fontSize: z
.number()
.default(32)
.transform((size) => clampToBound(size, "annotationFontSize")),
fontFamily: z.string().default("Inter"),
fontWeight: z.enum(["normal", "bold"]).default("bold"),
fontStyle: z.enum(["normal", "italic"]).default("normal"),
textDecoration: z.enum(["none", "underline"]).default("none"),
textAlign: z.enum(["left", "center", "right"]).default("center"),
textAnimation: z
.enum(["none", "fade", "rise", "pop", "slide-left", "typewriter", "pulse"])
.optional(),
});
// v5 clip anchor — the source of truth for a modifier's position. A region the user drew
// across a clip boundary is stored as one fragment per covered clip; they need no shared
// marker, because two regions with equal properties that touch render as one pill by the
// universal merge rule (see timelineMap). Optional during the Stage B transition: the
// v4→v5 migration fills it in, and regions created by not-yet-migrated code still validate
// on startMs/endMs alone, which remain a DERIVED cache of the fragment's ruler span.
const clipAnchorShape = {
clipId: z.string().min(1).optional(),
sourceStartSec: z.number().nonnegative().optional(),
sourceEndSec: z.number().nonnegative().optional(),
};
export const annotationRegionSchema = endGteStart(
z.object({
id: z.string().min(1),
startMs: z.number().nonnegative(),
endMs: z.number().nonnegative(),
...clipAnchorShape,
type: z.enum(["text", "image", "figure", "blur"]),
content: z.string().default(""),
textContent: z.string().optional(),
imageContent: z.string().optional(),
// The box `position`, `size` and the text size are measured against. `"frame"`, the output
// frame: where text, images and arrows are placed, so padding and the footage's size never
// move them. Absent, the footage (screen rect): a privacy blur always, since it must stay on
// what it hides, and every annotation saved before frame placement existed. See
// `annotations/placement.ts`.
space: z.literal("frame").optional(),
// At least 0 too, except for an arrow: see the refine below.
position: z.object({
x: z.number().max(100),
y: z.number().max(100),
}),
size: z.object({
width: z.number().positive(),
height: z.number().positive(),
}),
style: annotationStyleSchema,
zIndex: z.number().int().nonnegative(),
annotationSource: z.literal("auto-caption").optional(),
figureData: figureDataSchema,
blurData: blurDataSchema,
}),
"endMs",
"startMs",
).refine(
// The compositor draws an arrow in the middle of its square box, so an arrow drawn against the
// frame's left or top edge has a box that starts before the frame (`annotations/arrowBounds.ts`).
// Its strokes stay inside. Every other box starts inside the frame.
(region) => region.type === "figure" || (region.position.x >= 0 && region.position.y >= 0),
{ message: "position must be at least 0", path: ["position"] },
);
export const zoomRegionSchema = endGteStart(
z.object({
id: z.string().min(1),
startMs: z.number().nonnegative(),
endMs: z.number().nonnegative(),
...clipAnchorShape,
depth: z.union([
z.literal(1),
z.literal(2),
z.literal(3),
z.literal(4),
z.literal(5),
z.literal(6),
]),
focus: z.object({
cx: z.number().min(0).max(1),
cy: z.number().min(0).max(1),
}),
focusMode: z.enum(["manual", "auto"]).optional(),
/** The zoom's 3D camera (`Rotation3DPreset` in `components/video-editor/types.ts` — same
* literal list, duplicated here): a fixed angle, or the camera that orbits the screen
* (`crates/compositor/src/camera.rs`), placed by the zoom's focus mode. Absent means a flat
* screen. A stored `iso`, the retired "turned left, seen from above" angle, reads as
* `left`, which kept its look (`readRotation3DPreset`): every document load goes through
* this parse. A stored `follow-cursor` never reaches it (`readFollowCursorAsAutoOrbit`). */
rotationPreset: z
.enum(["iso", "left", "right", "orbit"])
.transform((preset) => (preset === "iso" ? "left" : preset))
.optional(),
customScale: z.number().positive().optional(),
source: z.enum(["auto", "manual"]).optional(),
hideCursor: z.boolean().optional(),
}),
"endMs",
"startMs",
);
// Agent-written shader effects (docs/shader-effects.md, B). A definition carries the WGSL and its
// declared parameters; a range poses it on the timeline, clip-anchored like a zoom, with its own
// parameter values. Additive: a document written before these existed loads unchanged.
const shaderEffectParamName = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/);
const shaderEffectColor = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
const shaderEffectPoint = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) });
// Written by the agent, in the user's language, shown as-is: content, not interface copy.
const shaderEffectLabel = z.string().max(40).default("");
export const shaderEffectParamSchema = z.discriminatedUnion("type", [
z.object({
type: z.literal("number"),
name: shaderEffectParamName,
label: shaderEffectLabel,
default: z.number(),
min: z.number(),
max: z.number(),
}),
z.object({
type: z.literal("toggle"),
name: shaderEffectParamName,
label: shaderEffectLabel,
default: z.boolean(),
}),
z.object({
type: z.literal("color"),
name: shaderEffectParamName,
label: shaderEffectLabel,
default: shaderEffectColor,
}),
z.object({
type: z.literal("point"),
name: shaderEffectParamName,
label: shaderEffectLabel,
default: shaderEffectPoint,
}),
]);
export const shaderEffectValueSchema = z.union([
z.number(),
z.boolean(),
shaderEffectColor,
shaderEffectPoint,
]);
export const shaderEffectSchema = z
.object({
id: z.string().min(1),
// What the pill shows.
name: z.string().min(1).max(60),
// For the next agent: what the effect does, in one sentence.
description: z.string().max(500).default(""),
// The WGSL contract version. Not a literal: a version this build does not know (written by
// a newer one) must still load; the compositor leaves its regions undrawn.
contract: z.number().int().positive(),
code: z.string().min(1).max(65_536),
// The `max` here is a technical ceiling, not a budget: see the cost tiers.
params: z.array(shaderEffectParamSchema).max(32).default([]),
origin: z.enum(["agent", "user"]).default("agent"),
// The compositor's cost estimate, cached when the code was last checked. Derived, never an
// input: `frameReads` is `frame()` reads per pixel, `tier` its indicative tier.
cost: z
.object({
tier: z.enum(["light", "medium", "heavy", "very-heavy"]),
frameReads: z.number().nonnegative(),
})
.optional(),
})
.superRefine((effect, ctx) => {
const names = new Set<string>();
for (const [index, param] of effect.params.entries()) {
if (names.has(param.name)) {
ctx.addIssue({
code: "custom",
message: `parameter "${param.name}" is declared twice`,
path: ["params", index],
});
}
names.add(param.name);
if (param.type === "number" && !(param.min <= param.default && param.default <= param.max)) {
ctx.addIssue({
code: "custom",
message: `parameter "${param.name}": min ≤ default ≤ max`,
path: ["params", index],
});
}
}
});
export const shaderEffectRangeSchema = endGteStart(
z.object({
id: z.string().min(1),
startMs: z.number().nonnegative(),
endMs: z.number().nonnegative(),
...clipAnchorShape,
effectId: z.string().min(1),
// Only the values that differ from the definition's defaults.
values: z.record(z.string(), shaderEffectValueSchema).default({}),
// What the effect transforms: the picture under the texts, the texts alone, or both.
target: z.enum(["image", "text", "both"]).default("image"),
}),
"endMs",
"startMs",
);
// External audio import (issue #350) — voiceover / BGM / SFX layered over the
// programme. Unlike zoom/speed/annotation/trim, an audio track is NOT
// clip-anchored: it floats over the whole timeline, addressed in RAW/document
// timeline seconds — the same clock the ruler, playhead and clip
// `timelineStartSec`/`timelineEndSec` use, and the one `addAudioTrack` seeds from
// the playhead. The preview positions the track on exactly this clock (see
// `resolveTimelineAudioPlayback` in VirtualPreview). The export's OUTPUT programme
// is trim-compressed, so the renderer maps this position to output time when
// building the scene — an identity map when the project has no trims/speed (the
// common case), an accepted approximation otherwise, the same way the preview
// approximates trims by re-seeking. See `SceneAudioTrack` (sceneDescription.ts,
// audio.rs).
//
// `assetId` points at an asset with `kind: "audio"`. `timelineStartSec` places
// the track's head; `trimStartSec`/`trimEndSec` window the source file (both in
// source seconds); `gainDb` sets its level.
// An imported or recorded audio track (voiceover / BGM / SFX) placed on the
// timeline (issue #350).
//
// CLIP-ANCHORED, on the same v5 contract as zoom/annotation: `{clipId,
// sourceStartSec, sourceEndSec}` is the source of truth and `startMs`/`endMs`
// is a derived ruler cache, so a track travels with the content it was placed
// over instead of sitting still while a reorder or trim slides the programme
// underneath it. Positions are RAW ruler ms; the export projects them onto the
// trim-compressed programme (`projectRawTimelineSecToPlayback`).
//
// `offsetMs` skips INTO the source file — start the music at its chorus. It
// replaces #502's `trimStartSec`/`trimEndSec` pair: the track's own span
// (`startMs`..`endMs`) is where it plays, so the tail trim is implied by the
// span and does not need storing twice. A file longer than its span is cut off
// at the span unless `loop` is set, in which case it repeats.
//
// The anchor ventilates one user-visible track into one fragment PER CLIP it
// covers. Fragments of the same track share `trackId`, and each carries its own
// `offsetMs` advanced by the source time its predecessors consumed — see
// `anchorAudioTrackFragments`. Without that every fragment would restart the
// file at the same offset and re-run the fades, so a bed spanning a cut would
// audibly restart at the boundary.
export const audioTrackSchema = endGteStart(
z.object({
id: z.string().min(1),
// Shared by every fragment of one user-visible track: what the lane draws
// as a single pill, what the inspector edits, and what delete removes.
// Absent on tracks written before ventilation existed — they are their own
// single fragment, so `trackId ?? id` is always the group key.
trackId: z.string().min(1).optional(),
startMs: z.number().nonnegative(),
endMs: z.number().nonnegative(),
...clipAnchorShape,
assetId: z.string().min(1),
kind: z.enum(["voiceover", "music"]).default("music"),
// Full source duration of the underlying file, cached here so the timeline
// can lay out the pill before the asset is re-probed on load.
durationSec: z.number().nonnegative().default(0),
offsetMs: z.number().int().nonnegative().default(0),
gainDb: z.number().min(-60).max(12).default(0),
loop: z.boolean().default(false),
fadeInMs: z.number().int().nonnegative().default(0),
fadeOutMs: z.number().int().nonnegative().default(0),
muted: z.boolean().default(false),
label: z.string().default(""),
origin: z.enum(["system", "agent", "user"]).default("user"),
}),
"endMs",
"startMs",
);
// Legacy OpenScreen appearance / export settings that the v3 schema doesn't
// normalize into the timeline / assets model. They are applied at export time
// by the existing pipeline (see technical-documentation/architecture/document-model.md).
//
// ponytail: passthrough blob — v2 ProjectEditorState carries ~25 fields, several
// of which (autoZoomEnabled, autoFocusAll, cursorTheme, …) have no first-class
// home yet. Phase 1 timeline rewrite + Phase 9 settings sync will tighten this.
// Round-trip through the migration must be lossless for now.
export const legacyEditorSchema = z.object({}).passthrough().nullable().default(null);
export const layoutRegionSchema = endGteStart(
z.object({
id: z.string().min(1),
startMs: z.number().nonnegative(),
endMs: z.number().nonnegative(),
...clipAnchorShape,
preset: z.enum(LAYOUT_PRESETS),
legacyCamera: z
.object({
basePreset: z.enum(LAYOUT_PRESETS),
envelopes: z.array(
endGteStart(
z.object({
sourceStartSec: z.number().nonnegative(),
sourceEndSec: z.number().nonnegative(),
}),
"sourceEndSec",
"sourceStartSec",
),
),
})
.optional(),
}),
"endMs",
"startMs",
);
const documentSchemaShape = z.object({
schemaVersion: z.literal(axcutSchemaVersion),
project: z.object({
id: z.string().min(1),
title: z.string().min(1),
createdAt: isoDateSchema,
updatedAt: isoDateSchema,
primaryAssetId: z.string().optional(),
// Names and terms passed to Whisper as its initial prompt (issue #1023).
// Additive, so no schemaVersion bump: an older build drops the key on save.
vocabulary: z.string().optional(),
}),
assets: z.array(assetSchema).default([]),
transcript: transcriptSchema.nullable().default(null),
transcripts: z.array(transcriptSchema).default([]),
timeline: timelineSchema.default({
clips: [],
gaps: [],
trimRanges: [],
muteRanges: [],
speedRanges: [],
captionRanges: [],
}),
annotations: z.array(annotationRegionSchema).default([]),
zoomRanges: z.array(zoomRegionSchema).default([]),
// Agent-written shader effects (docs/shader-effects.md). Optional rather than defaulted, like
// `vocabulary`: a document without effects carries no trace of them, and every reader treats
// an absent list as empty. An older build drops both keys when it saves.
shaderEffects: z.array(shaderEffectSchema).optional(),
shaderEffectRanges: z.array(shaderEffectRangeSchema).optional(),
// Imported audio tracks (issue #350). Defaulted so every document written
// before this loads unchanged; an older build simply strips the key on save.
audioTracks: z.array(audioTrackSchema).default([]),
// Absent/empty means one global layout; fragments are materialised on first change.
layoutRegions: z.array(layoutRegionSchema).optional(),
legacyEditor: legacyEditorSchema.nullable().default(null),
});
// P4 — v3 documents carried a single project-level `cameraTrack` (one project
// = one camera, inherited from the pre-multi-clip editor). v4 moves it onto
// the owning asset (see `assetSchema.cameraTrack` above) so each asset in a
// multi-clip project can carry its own camera link. This is invoked at LOAD
// TIME by `migrateRawDocumentToCurrent` in `document/migrate.ts`, not at every
// `documentSchema.parse(...)` call (the parse is now a pure v6 validation
// step — see the comment above `documentSchema` below). It does NOT touch v2
// (still handled solely by the separate `migrateProjectDataToAxcutDocument`
// pure function) or reject unknown versions; anything that isn't exactly v3
// passes through unchanged so the caller's `documentSchema.parse` can
// reject it via the `schemaVersion` literal.
export function upgradeV3DocumentToV4(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as Record<string, unknown>;
if (doc.schemaVersion !== 3) return raw;
const legacyCameraTrack = doc.cameraTrack ?? null;
const assets = Array.isArray(doc.assets) ? doc.assets : [];
const project = (doc.project ?? {}) as { primaryAssetId?: string };
const targetAssetId = project.primaryAssetId ?? (assets[0] as { id?: string } | undefined)?.id;
const nextAssets = assets.map((asset) => {
if (!asset || typeof asset !== "object") return asset;
const a = asset as Record<string, unknown>;
return legacyCameraTrack && a.id === targetAssetId && a.cameraTrack === undefined
? { ...a, cameraTrack: legacyCameraTrack }
: a;
});
const { cameraTrack: _legacyCameraTrack, ...rest } = doc;
return { ...rest, schemaVersion: 4, assets: nextAssets };
}
/**
* v4 → v5 — modifiers become CLIP-ANCHORED fragments. Every RAW-virtual-ms region
* (document `zoomRanges` / `annotations`, plus the `legacyEditor.speedRegions` /
* `cameraFullscreenRegions` envelopes) is ventilated across the stored RAW clip
* layout it was authored against, yielding one fragment per covered clip, with
* `startMs`/`endMs` re-derived as a transition cache. The fragments carry no marker
* tying them together: they share the same properties, so the ruler already renders
* them as one pill whenever they are adjacent (see timelineMap merge rule).
*
* A region covering no clip (zero-length, or off the end of the timeline) is
* dropped: it could never play. A document with no clips has nothing to anchor to,
* so its regions pass through untouched (still valid — the anchor is optional).
*
* Invoked at LOAD TIME by `migrateRawDocumentToCurrent` in `document/migrate.ts`,
* not at every `documentSchema.parse(...)` call.
*/
export function upgradeV4DocumentToV5(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as Record<string, unknown>;
if (doc.schemaVersion !== 4) return raw;
const timeline = (doc.timeline ?? {}) as Record<string, unknown>;
const clips = (Array.isArray(timeline.clips) ? timeline.clips : []) as unknown as AxcutClip[];
const anchor = (value: unknown, prefix: string): unknown => {
if (!Array.isArray(value) || clips.length === 0) return value;
return anchorRegionsWithDerivedMs(
value as Array<{ id: string; startMs: number; endMs: number }>,
clips,
() => createId(prefix),
);
};
const legacy =
doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
? (doc.legacyEditor as Record<string, unknown>)
: null;
return {
...doc,
schemaVersion: 5,
zoomRanges: anchor(doc.zoomRanges, "zoom"),
annotations: anchor(doc.annotations, "ann"),
legacyEditor: legacy
? {
...legacy,
...(Array.isArray(legacy.speedRegions)
? { speedRegions: anchor(legacy.speedRegions, "speed") }
: {}),
...(Array.isArray(legacy.cameraFullscreenRegions)
? { cameraFullscreenRegions: anchor(legacy.cameraFullscreenRegions, "camfull") }
: {}),
}
: doc.legacyEditor,
};
}
/**
* Largest raw asset footprint among the timeline's clips. A local copy of the
* `referenceClipDims` pick from `document/outputFormat` — duplicated here so the schema
* package doesn't import from a module that itself imports from this one (cycle), and so
* the upgrader doesn't need the runtime `probedAssetDims` map (it runs at load time, before
* any asset is probed). Crop IS applied: `"native"` resolved to the *cropped* clip
* dimensions at runtime (`clipEffectiveDims` → `calculateEffectiveSourceDimensions`),
* so ignoring it here would silently reframe every cropped project.
*/
/** Mirrors `atLeastEven` in mp4ExportSettings — H.264 4:2:0 rejects odd dims. */
function atLeastEven(value: number): number {
return Math.max(2, Math.floor(value / 2) * 2);
}
function largestClipDims(doc: Record<string, unknown>): { width: number; height: number } | null {
const timeline = (doc.timeline ?? {}) as Record<string, unknown>;
const clips = Array.isArray(timeline.clips) ? timeline.clips : [];
const assets = Array.isArray(doc.assets) ? doc.assets : [];
const assetById = new Map<string, Record<string, unknown>>();
for (const a of assets) {
if (a && typeof a === "object" && typeof (a as { id?: unknown }).id === "string") {
assetById.set((a as { id: string }).id, a as Record<string, unknown>);
}
}
let best: { width: number; height: number } | null = null;
let bestArea = 0;
for (const clip of clips) {
if (!clip || typeof clip !== "object") continue;
const c = clip as Record<string, unknown>;
const assetId = c.assetId;
if (typeof assetId !== "string") continue;
const asset = assetById.get(assetId);
if (!asset) continue;
const video = (asset.video ?? {}) as Record<string, unknown>;
const rawW = typeof video.width === "number" ? video.width : 0;
const rawH = typeof video.height === "number" ? video.height : 0;
if (rawW <= 0 || rawH <= 0) continue;
// Apply the clip's crop, exactly as `calculateEffectiveSourceDimensions`
// (mp4ExportSettings) does at runtime — including the snap to even pixels,
// so the reduced token matches the size the encoder is actually handed.
// "native" meant "the cropped source's shape"; ignoring crop here would
// bake the wrong ratio into every cropped project.
const crop = (c.cropRegion ?? {}) as Record<string, unknown>;
const cropW = typeof crop.width === "number" && crop.width > 0 ? crop.width : 1;
const cropH = typeof crop.height === "number" && crop.height > 0 ? crop.height : 1;
const w = atLeastEven(Math.round(rawW * cropW));
const h = atLeastEven(Math.round(rawH * cropH));
const area = w * h;
if (area > bestArea) {
bestArea = area;
best = { width: w, height: h };
}
}
return best;
}
/**
* v5 → v6 — retire the `"native"` AspectRatio. `"native"` was a runtime-only sentinel
* that resolved to the timeline's largest clip; v6 makes that resolution permanent by
* baking the concrete `"W:H"` token into the document. The new value matches the OLD
* runtime answer (largest clip), so projects migrate losslessly — preview and export
* will keep framing the same shape they did yesterday.
*
* Falls back to `"16:9"` when the timeline has no clips with known dimensions (the same
* value the runtime bridge in `resolveAspectRatioValue` returned when no document was
* available). A document without a `legacyEditor` envelope is unchanged apart from the
* version bump.
*/
function upgradeV5DocumentToV6(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as Record<string, unknown>;
if (doc.schemaVersion !== 5) return raw;
const legacy =
doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
? (doc.legacyEditor as Record<string, unknown>)
: null;
if (!legacy || legacy.aspectRatio !== "native") {
return { ...doc, schemaVersion: 6 };
}
// OPPORTUNISTIC, never forced. Baking requires real source dimensions, and a
// project imported from v1.7 has none yet: `migrateProjectDataToAxcutDocument`
// builds its asset from `{version:2, media, editor}`, which carries only file
// paths — dimensions arrive later, when `useTimeline`'s probe effect writes
// `asset.video` back to disk.
//
// So when dimensions are unknown we leave `"native"` in place rather than
// stamping a hardcoded ratio. `"native"` keeps resolving dynamically at runtime
// (`resolveAspectRatioValue`), which IS the v1.7 behaviour, and the next load
// after the probe has persisted dimensions converts it for real. Forcing
// `"16:9"` here would permanently reframe every portrait v1.7 project that used
// "Native", on its first open in v1.8, with no way back.
const dims = largestClipDims(doc);
if (!dims) {
return { ...doc, schemaVersion: 6 };
}
return {
...doc,
schemaVersion: 6,
legacyEditor: { ...legacy, aspectRatio: toAspectRatioToken(dims.width, dims.height) },
};
}
/**
* v6 → v7 — trims become CLIP-ANCHORED, the last region kind that wasn't.
*
* A v6 trim says only "this source span of this asset is cut". That is unambiguous while
* one asset backs one clip, and ambiguous the moment it doesn't: with two clips over the
* same media every reader had to guess, and each guessed differently — the transcript pane
* showed the cut on BOTH clips, the ruler drew it on the FIRST, and playback/export removed
* the span from BOTH. Anchoring the trim to the clip it was authored on removes the guess.
*
* The upgrade VENTILATES rather than picks: a stored trim is replaced by one anchored entry
* per clip it currently covers, each clamped to that clip's source window. That is a
* faithful restatement of what the document already renders (a v6 trim really did cut every
* clip of its asset), so nothing about the output moves — but the entries are now separately
* addressable, which is what lets a user delete the copy on the clip they didn't mean.
* Mirrors `upgradeV4DocumentToV5`, which ventilated the other kinds the same way.
*
* A trim covering no clip is kept UNCHANGED rather than dropped — never lose user data.
* `replaceTimeline` mints exactly such trims (the inverted kept-intervals lie outside every
* clip by construction), and a document with no clips has nothing to anchor against.
* Un-anchored trims keep the v6 asset-wide behaviour via `trimAppliesToClip`.
*/
export function upgradeV6DocumentToV7(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as Record<string, unknown>;
if (doc.schemaVersion !== 6) return raw;
const timeline =
doc.timeline && typeof doc.timeline === "object" && !Array.isArray(doc.timeline)
? (doc.timeline as Record<string, unknown>)
: null;
const trims = timeline && Array.isArray(timeline.trimRanges) ? timeline.trimRanges : null;
const clips = (timeline && Array.isArray(timeline.clips)
? timeline.clips
: []) as unknown as AxcutClip[];
if (!timeline || !trims || clips.length === 0) return { ...doc, schemaVersion: 7 };
const anchored = trims.flatMap((entry) => {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [entry];
const trim = entry as Record<string, unknown>;
// Already anchored (a re-run, or a doc written by a mixed-version chain): leave it.
if (typeof trim.clipId === "string") return [trim];
if (typeof trim.assetId !== "string") return [trim];
if (typeof trim.startSec !== "number" || typeof trim.endSec !== "number") return [trim];
const lo = Math.min(trim.startSec, trim.endSec);
const hi = Math.max(trim.startSec, trim.endSec);
const fragments = clips.flatMap((clip) => {
// `clips` is raw, untrusted input at this point (the schema parse runs after the
// upgrade chain), so a malformed entry must not take the whole project load down.
if (!clip || typeof clip !== "object" || typeof clip.id !== "string") return [];
if (clip.assetId !== trim.assetId) return [];
const clipEnd = clip.sourceEndSec ?? clip.sourceStartSec;
// An unprobed clip has no real window yet; anchoring against it would clamp the
// trim to nothing. Leave those to the un-anchored fallback (same reasoning as
// `rederiveRegionMs`, which refuses to clamp against an unprobed window).
if (clipEnd <= clip.sourceStartSec) return [];
const startSec = Math.max(lo, clip.sourceStartSec);
const endSec = Math.min(hi, clipEnd);
if (endSec <= startSec) return [];
return [{ ...trim, clipId: clip.id, startSec, endSec }];
});
if (fragments.length === 0) return [trim];
// The first fragment keeps the original id, so ids already held elsewhere (an undo
// entry, an in-flight `removeTrim`) still resolve; extras get fresh ones.
return fragments.map((f, i) => (i === 0 ? f : { ...f, id: createId("trim") }));
});
return { ...doc, schemaVersion: 7, timeline: { ...timeline, trimRanges: anchored } };
}
/**
* v7 → v8 — Auto becomes the default AspectRatio, and older documents keep their frame.
*
* A project whose user never opened the ratio menu stores no `aspectRatio` at all: every
* reader falls back to the default (`getEditorSettings`). Changing that default would
* therefore reshape every such project on its next open, which is the silent drift v6
* removed for `"native"`. So the value those documents have always shown, 16:9, is written
* down; only documents created from v8 on take the new default.
*
* Mirrors the read: `getEditorSettings` takes any stored value as is, so only a missing one
* (no envelope, or no key) is pinned.
*/
export function upgradeV7DocumentToV8(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as Record<string, unknown>;
if (doc.schemaVersion !== 7) return raw;
const legacy =
doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
? (doc.legacyEditor as Record<string, unknown>)
: null;
if (legacy?.aspectRatio != null) return { ...doc, schemaVersion: 8 };
return { ...doc, schemaVersion: 8, legacyEditor: { ...legacy, aspectRatio: "16:9" } };
}
/**
* Runs the whole upgrade chain on a raw, untrusted value. Idempotent: each step
* is gated on an exact `schemaVersion`, so an already-current document passes
* through untouched.
*
* Lives here rather than in `document/migrate.ts` on purpose — the Electron main
* process imports this composer, and `migrate.ts` pulls a value import
* (`PROJECT_VERSION`) through the `@/` alias, which `vite-plugin-electron` does
* not configure for the main bundle. Keep this module alias-free.
*/
export function upgradeV8DocumentToV9(raw: unknown): unknown {
if (!raw || typeof raw !== "object") return raw;
const doc = raw as AxcutDocument & { schemaVersion: number };
if (Number(doc.schemaVersion) !== 8) return raw;
const legacy = doc.legacyEditor ?? {};
if (!Array.isArray(doc.timeline?.clips)) return { ...doc, schemaVersion: 9 };
const { cameraFullscreenRegions, ...appearance } = legacy;
return {
...doc,
schemaVersion: 9,
...(Array.isArray(cameraFullscreenRegions) && cameraFullscreenRegions.length
? { layoutRegions: materializeLayouts(doc) }
: {}),
legacyEditor:
Array.isArray(doc.layoutRegions) && appearance.aspectRatio == null
? { ...appearance, aspectRatio: "16:9" }
: doc.legacyEditor == null
? null
: appearance,
};
}
/**
* Drop the ghost trims commit `b9e0f1ff` wrote (issue #560).
*
* That build let the transcript pane author a cut from the voiceover lane while still
* anchoring it on whatever the words belonged to — an AUDIO asset and an audio fragment.
* `resolvePlaybackSegments` matches no clip for such a row, so it removed nothing from the
* film, the preview or the export; all it did was strike the word through. Now that both
* lanes read the same removed set, leaving those rows behind would keep striking words
* through for a cut that never existed.
*
* The test is exact and needs no clip lookup: an audio asset is never a clip's `assetId`
* (audio is filtered out of the lists that make clips), so a trim naming one can only have
* come from that build. An un-anchored pre-v7 trim names a VIDEO asset and is untouched;
* so is a trim whose clip was deleted, which in-session undo can still bring back.
*
* No `schemaVersion` bump: nothing about the format changed, and no output moves — these
* rows were already inert. What changes is that words the user "deleted" on that build
* come back as kept, which is the correction, and belongs in the release note.
*
* Runs on RAW, untrusted input like the rest of the chain, so every read is guarded.
*/
function dropAudioAnchoredTrims(raw: unknown): unknown {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
const doc = raw as Record<string, unknown>;
const assets = Array.isArray(doc.assets) ? doc.assets : null;
if (!assets) return raw;
const audioAssetIds = new Set<string>();
for (const asset of assets) {
if (!asset || typeof asset !== "object" || Array.isArray(asset)) continue;
const entry = asset as Record<string, unknown>;
if (entry.kind === "audio" && typeof entry.id === "string") audioAssetIds.add(entry.id);
}
if (audioAssetIds.size === 0) return raw;
const timeline =
doc.timeline && typeof doc.timeline === "object" && !Array.isArray(doc.timeline)
? (doc.timeline as Record<string, unknown>)
: null;
const trims = timeline && Array.isArray(timeline.trimRanges) ? timeline.trimRanges : null;
if (!trims) return raw;
const kept = trims.filter((entry) => {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return true;
const trim = entry as Record<string, unknown>;
return !(typeof trim.assetId === "string" && audioAssetIds.has(trim.assetId));
});
if (kept.length === trims.length) return raw;
return { ...doc, timeline: { ...timeline, trimRanges: kept } };
}
/**
* Raise to its start the end of every transcript segment or word stored BEFORE its start.
*
* The transcription core before a9fdd97ff (transformers.js, removed 2026-07-05) clamped a
* timestamp's end to the audio length but not its start, so a Whisper hallucination past the
* end of the audio ("very good" at 13.5 s in 6.76 s of sound) was written as [13.5, 6.76].
* The schema rejects that, and a single such word made the whole project unreadable: it
* vanished from the project list.
*
* Raising the end loses nothing: the text, any edit made to it, and every id a segment or a
* caption refers to all survive. The word becomes a zero-length point at its start, which in
* the known case lies past the media, so it plays and shows nowhere.
*
* No `schemaVersion` bump, like `dropAudioAnchoredTrims`: the document comes back untouched
* when there is nothing to repair. Runs on RAW, untrusted input, so every read is guarded.
*/
function raiseInvertedTranscriptEnds(raw: unknown): unknown {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
const doc = raw as Record<string, unknown>;
let repaired = false;
const repairSpans = (spans: unknown): unknown => {
if (!Array.isArray(spans)) return spans;
return spans.map((entry) => {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
const span = entry as Record<string, unknown>;
if (typeof span.startSec !== "number" || typeof span.endSec !== "number") return entry;
if (span.endSec >= span.startSec) return entry;
repaired = true;
return { ...span, endSec: span.startSec };
});
};
const repairTranscript = (value: unknown): unknown => {
if (!value || typeof value !== "object" || Array.isArray(value)) return value;
const transcript = value as Record<string, unknown>;
return {
...transcript,
segments: repairSpans(transcript.segments),
words: repairSpans(transcript.words),
};
};
const transcript = repairTranscript(doc.transcript);
const transcripts = Array.isArray(doc.transcripts)
? doc.transcripts.map(repairTranscript)
: doc.transcripts;
return repaired ? { ...doc, transcript, transcripts } : raw;
}
/**
* Carry a zoom's click impact over to the cursor setting it became.
*
* Builds up to v1.13.0 stored `clickImpact` on each zoom range, and only a 3D camera used it.
* It is now a cursor setting (`legacyEditor.cursorClickImpact`) that acts under every camera,
* and the zoom range schema no longer has the key, so the parse would drop it silently. A
* document that turned it on for any zoom keeps it on, now for the whole project; one that
* never did, or already stores the cursor setting, comes back untouched.
*
* No `schemaVersion` bump, like `dropAudioAnchoredTrims`. Runs on RAW, untrusted input, so
* every read is guarded.
*/
function liftZoomClickImpact(raw: unknown): unknown {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
const doc = raw as Record<string, unknown>;
const zooms = Array.isArray(doc.zoomRanges) ? doc.zoomRanges : [];
const on = zooms.some(
(zoom) =>
zoom && typeof zoom === "object" && (zoom as Record<string, unknown>).clickImpact === true,
);
if (!on) return raw;
const legacy =
doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
? (doc.legacyEditor as Record<string, unknown>)
: null;
if (typeof legacy?.cursorClickImpact === "boolean") return raw;
return { ...doc, legacyEditor: { ...legacy, cursorClickImpact: true } };
}
/**
* Read a zoom stored with the `follow-cursor` camera as the `orbit` camera under auto focus.
*
* `follow-cursor` was the orbit before it had a manual mode: it followed the cursor whatever the
* zoom's focus mode said, and most such zooms carry "manual", the default. The camera now reads
* the focus mode like every other zoom, so the auto focus is written down along with the new
* name, and the zoom keeps following the cursor as it did.
*
* No `schemaVersion` bump, as for `iso` → `left`: the retired value is the marker, and nothing
* writes it any more, so a second run finds nothing. A document without such a zoom comes back
* untouched. Runs on RAW, untrusted input, so every read is guarded.
*/
function readFollowCursorAsAutoOrbit(raw: unknown): unknown {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
const doc = raw as Record<string, unknown>;
if (!Array.isArray(doc.zoomRanges)) return raw;
let renamed = false;
const zoomRanges = doc.zoomRanges.map((entry) => {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
const zoom = entry as Record<string, unknown>;
if (zoom.rotationPreset !== "follow-cursor") return entry;
renamed = true;
return { ...zoom, rotationPreset: "orbit", focusMode: "auto" };
});
return renamed ? { ...doc, zoomRanges } : raw;
}
export function migrateRawDocumentToCurrent(raw: unknown): unknown {
return upgradeV8DocumentToV9(
readFollowCursorAsAutoOrbit(
raiseInvertedTranscriptEnds(
dropAudioAnchoredTrims(
liftZoomClickImpact(
upgradeV7DocumentToV8(
upgradeV6DocumentToV7(
upgradeV5DocumentToV6(upgradeV4DocumentToV5(upgradeV3DocumentToV4(raw))),
),
),
),
),
),
),
);
}
// PURE v9 validation. Callers that read a document from disk (or any other
// source that might carry an older `schemaVersion`) MUST run
// `migrateRawDocumentToCurrent` on the raw value first. The previous
// implementation wrapped this schema in a `z.preprocess` that re-ran the whole
// v3→…→v8 chain on EVERY parse, including in-memory parses of documents that
// were already current. Hoisting it to load time makes the in-memory parse a
// single `z.literal(8)` + shape check.
export const documentSchema = documentSchemaShape;
/**
* Whether a parsed `.openscreen` file is an AxcutDocument — what the editor saves, at any
* `schemaVersion` — rather than a legacy v2 `{ version, media, editor }` project, which must go
* through `migrateProjectDataToAxcutDocument` instead (it reads `.media` / `.editor` and would
* yield an empty document from a current one).
*/
export function isAxcutDocumentFile(raw: unknown): raw is Record<string, unknown> {
return typeof raw === "object" && raw !== null && "schemaVersion" in raw && "timeline" in raw;
}
/** A document read from a file, at any supported `schemaVersion`: upgraded, then validated. */
export function parseDocumentFile(raw: unknown): AxcutDocument {
return documentSchema.parse(migrateRawDocumentToCurrent(raw));
}
export const createProjectInputSchema = z.object({
title: z.string().trim().min(1).default("Untitled Project"),
});
// Every code whisper.cpp's multilingual model can resolve, plus "auto" for
// detection. Codes and order mirror whisper.cpp's own `g_lang` table
// (`src/whisper.cpp`, verified against the tag `nix/whisper-stt.nix` pins —
// v1.9.1) — `wparams.language` in
// electron/native/whisper-stt/src/main.cpp forwards the code verbatim, so a
// value outside this list fails to resolve a language id there. "auto" is
// always index 0 — code that needs "every real language, no sentinel" relies
// on that (see `WhisperLanguageCode` below) rather than filtering it out.
// Consumed by the "Regenerate as" picker in `MediaStage.tsx`. A second,
// unreachable copy lived in the v3 left panel's transcript modal until that
// whole surface was deleted — see decisions.md.
export const TRANSCRIPT_LANGUAGE_CODES = [
"auto",
"en",
"zh",
"de",
"es",
"ru",
"ko",
"fr",
"ja",
"pt",
"tr",
"pl",
"ca",
"nl",
"ar",
"sv",
"it",
"id",
"hi",
"fi",
"vi",
"he",
"uk",
"el",
"ms",
"cs",
"ro",
"da",
"hu",
"ta",
"no",
"th",
"ur",
"hr",
"bg",
"lt",
"la",
"mi",
"ml",
"cy",
"sk",
"te",
"fa",
"lv",
"bn",
"sr",
"az",
"sl",
"kn",
"et",
"mk",
"br",
"eu",
"is",
"hy",
"ne",
"mn",
"bs",
"kk",
"sq",
"sw",
"gl",
"mr",
"pa",
"si",
"km",
"sn",
"yo",
"so",
"af",
"oc",
"ka",
"be",
"tg",
"sd",
"gu",
"am",
"yi",
"lo",
"uz",
"fo",
"ht",
"ps",
"tk",
"nn",
"mt",
"sa",
"lb",
"my",
"bo",
"tl",
"mg",
"as",
"tt",
"haw",
"ln",
"ha",
"ba",
"jw",
"su",
"yue",
] as const;
export const transcriptLanguageSchema = z.enum(TRANSCRIPT_LANGUAGE_CODES);
export type AxcutWord = z.infer<typeof wordSchema>;
export type AxcutTranscriptSegment = z.infer<typeof transcriptSegmentSchema>;
export type AxcutTranscript = z.infer<typeof transcriptSchema>;
export type AxcutAsset = z.infer<typeof assetSchema>;
export type AxcutAssetTranscriptionFailure = z.infer<typeof assetTranscriptionFailureSchema>;
export type AxcutClip = z.infer<typeof clipSchema>;
export type AxcutClipCropRegion = z.infer<typeof clipCropRegionSchema>;
export type AxcutGap = z.infer<typeof gapSchema>;
export type AxcutTrimRange = z.infer<typeof trimRangeSchema>;
export type AxcutTimeline = z.infer<typeof timelineSchema>;
export type AxcutTimelineOperation = z.infer<typeof timelineOperationSchema>;
export type AxcutAnnotationRegion = z.infer<typeof annotationRegionSchema>;
export type AxcutZoomRegion = z.infer<typeof zoomRegionSchema>;
export type AxcutCameraTrack = z.infer<typeof cameraTrackSchema>;
export type AxcutAudioTrack = z.infer<typeof audioTrackSchema>;
export type AxcutShaderEffect = z.infer<typeof shaderEffectSchema>;
export type AxcutShaderEffectParam = z.infer<typeof shaderEffectParamSchema>;
export type AxcutShaderEffectRange = z.infer<typeof shaderEffectRangeSchema>;
export type AxcutShaderEffectValue = z.infer<typeof shaderEffectValueSchema>;
export type AxcutLegacyEditor = z.infer<typeof legacyEditorSchema>;
export type AxcutDocument = z.infer<typeof documentSchema>;
export type AxcutDocumentInput = z.input<typeof documentSchema>;
export type CreateProjectInput = z.infer<typeof createProjectInputSchema>;
export type TranscriptLanguageCode = z.infer<typeof transcriptLanguageSchema>;
/** A real whisper.cpp language code — `TranscriptLanguageCode` minus the "auto" detection sentinel. */
export type WhisperLanguageCode = Exclude<TranscriptLanguageCode, "auto">;
export function createEmptyDocument(
input: CreateProjectInput & { projectId: string; createdAt?: string },
): AxcutDocument {
const createdAt = input.createdAt ?? new Date().toISOString();
return documentSchema.parse({
schemaVersion: axcutSchemaVersion,
project: {
id: input.projectId,
title: input.title,
createdAt,
updatedAt: createdAt,
},
assets: [],
transcript: null,
transcripts: [],
timeline: {
clips: [],
gaps: [],
trimRanges: [],
muteRanges: [],
speedRanges: [],
captionRanges: [],
},
annotations: [],
zoomRanges: [],
audioTracks: [],
legacyEditor: null,
});
}
export function ensureDocument(value: unknown): AxcutDocument {
return documentSchema.parse(value);
}
/**
* The level and ramps a track starts with. A music bed sits UNDER the voice, at −18 dB,
* and eases in and out over a second instead of cutting in; a voiceover is voice, levelled
* by the export like the recording itself, so it starts flat.
*
* Applied when a track is created, and by the inspector's reset. Deliberately NOT the
* schema's parse defaults above: a track saved before these existed keeps the level its
* author set.
*/
export function audioTrackDefaults(
kind: AxcutAudioTrack["kind"],
): Pick<AxcutAudioTrack, "gainDb" | "fadeInMs" | "fadeOutMs"> {
return kind === "music"
? { gainDb: -18, fadeInMs: 1000, fadeOutMs: 1000 }
: { gainDb: 0, fadeInMs: 0, fadeOutMs: 0 };
}
/**
* Build a timeline audio track for an imported or recorded audio asset
* (issue #350). The head is placed at `timelineStartSec` (RAW/document timeline
* seconds — the same clock the ruler, playhead and clip `timelineStartSec` use,
* NOT the trim-compressed output programme; the export projects it with
* `projectRawTimelineSecToPlayback`) and the track spans the whole source file
* unless the caller asks for a shorter `spanSec`. Starts at its kind's
* `audioTrackDefaults`, then parsed through the schema so every other default
* (loop, mute) is applied in one place.
*
* The result is UNANCHORED — `clipId` is absent. Callers place it through
* `anchorAudioTrackFragments`, which ventilates it across the clips it covers.
*/
export function createAudioTrack(input: {
assetId: string;
durationSec: number;
kind?: "voiceover" | "music";
/** Raw ruler head. The span runs from here for `durationSec`, or for
* `spanSec` when the caller wants a shorter placement than the file. */
timelineStartSec?: number;
spanSec?: number;
label?: string;
}): AxcutAudioTrack {
const startMs = Math.round(Math.max(0, input.timelineStartSec ?? 0) * 1000);
// A track with no measurable source still needs a visible span, or the pill
// is zero-width and cannot be grabbed to fix.
const spanMs = Math.max(1, Math.round((input.spanSec ?? input.durationSec) * 1000));
const kind = input.kind ?? "music";
return audioTrackSchema.parse({
id: createId("audio"),
assetId: input.assetId,
kind,
...audioTrackDefaults(kind),
durationSec: input.durationSec,
startMs,
endMs: startMs + spanMs,
label: input.label ?? "",
});
}