@miraiclip/core

npm install @miraiclip/core

FunctionsCopy Anchor Link

animationCommandsCopy Anchor Link

The commands that give clip exactly recipe: clear its visual keyframes (volume automation stays), then set the recipe's. Dispatch them in one transaction for a single undo step. An empty recipe removes the animation.

function animationCommands(clip: Clip, recipe: AnimationRecipe): BuiltinCommand[]

Guides: Keyframes & animation

applyCommandsCopy Anchor Link

Apply a batch of commands as ONE transaction: all-or-nothing (a failure rolls back every command already applied — the engine's transaction rollback), one undo step on success, and the failing index reported so an agent can fix exactly the command that broke.

function applyCommands(project: Project, commands: readonly Command[], options?: {
    label?: string;
}): ApplyCommandsResult

Guides: MCP server, Tools from the command catalog, Collaboration, History & transactions

applyJsonPatchesCopy Anchor Link

Apply RFC-6902 add/replace/remove operations (the subset this engine emits) to a plain JSON document, returning a new document. The input is not mutated. Use this to replay a peer's patches events onto a local copy of the document for sync/collaboration.

function applyJsonPatches<T>(doc: T, ops: readonly JsonPatchOp[]): T

Guides: Collaboration, Events & patches

captionClipsFromAsrWordsCopy Anchor Link

ASR word timestamps → caption clips with TRUE word timing (karaoke). Words group into clips on silence gaps and a max-words cap.

function captionClipsFromAsrWords(words: readonly AsrWord[], options: CaptionImportOptions & AsrGroupingOptions): BuiltinCommand[]

Guides: Captions

captionClipsFromSubtitlesCopy Anchor Link

SRT/VTT → one caption clip per cue (words evenly split across the cue). Dispatch the result in one transaction.

function captionClipsFromSubtitles(text: string, options: CaptionImportOptions): BuiltinCommand[]

Guides: Captions

captionsToSrtCopy Anchor Link

Caption clips → SubRip (.srt), one cue per clip, in timeline order.

function captionsToSrt(clips: readonly CaptionCueSource[]): string

Guides: Captions

captionsToTextCopy Anchor Link

Caption clips → plain transcript text, one line per clip.

function captionsToText(clips: readonly CaptionCueSource[]): string

Guides: Captions

captionsToVttCopy Anchor Link

Caption clips → WebVTT (.vtt), one cue per clip, in timeline order.

function captionsToVtt(clips: readonly CaptionCueSource[]): string

Guides: Captions

clipHeadroomUsCopy Anchor Link

Source footage past a clip's end ("out") or before its start ("in"). Generated clips are unlimited.

function clipHeadroomUs(doc: ProjectDocument, clip: Clip, side: "in" | "out"): number

Guides: Timeline, Clips, Transitions

clipKindRegistrationCopy Anchor Link

function clipKindRegistration(kind: string): ClipKindRegistration | undefined

Guides: Custom clip kinds

commandCatalogCopy Anchor Link

The machine-readable command catalog: one JSON Schema per command type. Suitable for handing to an LLM as tool definitions.

function commandCatalog(extra?: Record<string, z.ZodType>): Record<string, unknown>

Guides: Editing assistant, Tools from the command catalog, Properties panel, Commands

commandTypeForToolCopy Anchor Link

Reverse of toolNameForCommand, resolved against the known types.

function commandTypeForTool(toolName: string, commandTypes: Iterable<string>): string | undefined

Guides: Tools from the command catalog

createProjectCopy Anchor Link

function createProject(init: ProjectSettings | ProjectDocument, options?: CreateProjectOptions): Project

Guides: Editing assistant, Asset import, Collaboration, Commands

creditsForCopy Anchor Link

Credit lines for the assets the project uses whose license asks for attribution (or that carry an attribution anyway), de-duplicated, in a stable order — ready for an end card, a description box, or a sidecar file.

function creditsFor(doc: ProjectDocument): string[]

Guides: Assets, Audio, Personalized video

cubicBezierProgressCopy Anchor Link

CSS-convention cubic bézier: control points map input progress x∈[0,1] to eased progress y. Solve x(t)=progress for t (Newton with bisection fallback), then evaluate y(t).

function cubicBezierProgress(x1: number, y1: number, x2: number, y2: number, progress: number): number

defaultEffectParamsCopy Anchor Link

A kind's default params — what effect/add fills in when params are omitted.

function defaultEffectParams(kind: string): Record<string, number | string> | undefined

Guides: Effects

describeAnimationCopy Anchor Link

Plain-language summary of a recipe ("Fade in · Pulse · Slide down out").

function describeAnimation(r: AnimationRecipe): string

Guides: Keyframes & animation

describeProjectCopy Anchor Link

A compact, deterministic summary of the document, written for LLM prompts: everything an agent needs to place commands (ids, kinds, time ranges in the same microsecond unit commands take), nothing it doesn't.

function describeProject(doc: ProjectDocument, options?: DescribeProjectOptions): string

Guides: Editing assistant, MCP server, Tools from the command catalog, Roadmap

effectParamsSchemaCopy Anchor Link

function effectParamsSchema(kind: string): z.ZodType | undefined

Guides: Custom effects

evaluateClipAtCopy Anchor Link

Convenience allocating variant of evaluateClipInto.

function evaluateClipAt(clip: Clip, clipTimeUs: Us): EvaluatedClip

Guides: Properties panel, Keyframes & animation

evaluateClipIntoCopy Anchor Link

Evaluate a clip's animated properties at a clip-relative time into out (alloc-free — call per tick with a reused object). Static clip values are the fallback for properties without keyframes.

function evaluateClipInto(clip: Clip, clipTimeUs: Us, out: EvaluatedClip): EvaluatedClip

Guides: Keyframes & animation

evaluateKeyframesCopy Anchor Link

Evaluate one property's keyframe list at a clip-relative time. Keyframes must be in stored order (the keyframe/set command maintains it). Pass clipDurationUs when the list may hold end-anchored keyframes. Before the first keyframe the first value holds; after the last, the last value holds; between, the LEFT keyframe's easing shapes the segment.

function evaluateKeyframes(keyframes: readonly Keyframe[], timeUs: Us, fallback: number, clipDurationUs?: Us): number

Guides: Keyframes & animation

findCutsCopy Anchor Link

Every cut on the project's video tracks, top track first, in time order.

function findCuts(doc: ProjectDocument, options?: {
    minTransitionUs?: Us;
}): Cut[]

Guides: Timeline, Transitions, Custom clip kinds, Headless editor logic

fitAnimationCopy Anchor Link

In/Out lengths that fit the clip (they share it, leaving a sliver between).

function fitAnimation(recipe: AnimationRecipe, clipUs: Us): AnimationRecipe

Guides: Keyframes & animation

formatFrameRateCopy Anchor Link

Display form: "30", "29.97", "23.976".

function formatFrameRate(rate: FrameRateLike): string

frameCountCopy Anchor Link

Frames needed to cover durationUs (the frames that start before it ends).

function frameCount(durationUs: Us, rate: FrameRateLike): number

Guides: Project & time

frameDurationUsCopy Anchor Link

Duration of one frame in µs (fractional at NTSC rates — use frameToUs for positions).

function frameDurationUs(rate: FrameRateLike): number

Guides: Selection & canvas editing, Timeline, Project & time

frameToUsCopy Anchor Link

Timeline position where the given frame starts: the first whole µs inside it.

function frameToUs(frame: number, rate: FrameRateLike): Us

Guides: Selection & canvas editing, Timeline, Project & time

fromJsonPointerCopy Anchor Link

function fromJsonPointer(pointer: string): string[]

getEffectInfoCopy Anchor Link

Editor/UI metadata for a built-in effect kind (undefined for custom kinds).

function getEffectInfo(kind: string): EffectInfo | undefined

Guides: Properties panel, Effects, Custom effects

isBuiltinClipKindCopy Anchor Link

function isBuiltinClipKind(kind: string): boolean

keyframeTimeUsCopy Anchor Link

A keyframe's time from the clip's visible start, given the clip's duration.

function keyframeTimeUs(keyframe: Keyframe, clipDurationUs: Us): Us

licenseReportCopy Anchor Link

License check for the assets the project uses. commercial: true reports non-commercial assets; assets without license info are reported only when they came from a provider (plain uploads are the user's own business).

function licenseReport(doc: ProjectDocument, options?: {
    commercial?: boolean;
}): LicenseIssue[]

Guides: Assets, Audio, Personalized video

parseSubtitlesCopy Anchor Link

Parse SubRip (.srt) or WebVTT (.vtt) text into cues. Tolerant subset: numeric counters, WEBVTT headers, NOTE/STYLE blocks, and cue settings are ignored; HTML-ish tags inside cue text are stripped.

function parseSubtitles(text: string): CaptionCue[]

Guides: Captions

planAnimationCopy Anchor Link

Every keyframe a recipe produces on a clip, plus the properties it owns.

function planAnimation(recipe: AnimationRecipe, base: Base, clipUs: Us): {
    keyframes: PlannedKeyframe[];
    props: Set<Prop>;
}

projectFrameRateCopy Anchor Link

The project's exact frame rate: settings.frameRate when set, else read from settings.fps.

function projectFrameRate(settings: Pick<ProjectSettings, "fps" | "frameRate">): FrameRate

Guides: Selection & canvas editing, Timeline, Project & time

readAnimationCopy Anchor Link

Recognize the recipe that produced a clip's keyframes. Each In / Out candidate (preset × easing, its length read off the keyframes) must reproduce a subset of them on its own; the surviving combinations, with each loop, are checked against the whole set. A clip moved on the canvas after animating still reads, because bases come from the keyframes.

function readAnimation(clip: Clip): ReadAnimation

Guides: Keyframes & animation

registerClipKindCopy Anchor Link

function registerClipKind(kind: string, registration: ClipKindRegistration): void

Guides: Custom clip kinds

registerEffectKindCopy Anchor Link

Register a custom effect kind's param schema (renderer registers its filter separately).

function registerEffectKind(kind: string, paramsSchema: z.ZodType): void

Guides: Custom effects

registerTransitionKindCopy Anchor Link

function registerTransitionKind(kind: string, paramsSchema: z.ZodType): void

Guides: Custom transitions

resolveEasingCopy Anchor Link

Accepts a preset name or an explicit easing; returns the stored form.

function resolveEasing(input: EasingPreset | Easing | undefined): Easing

Guides: Keyframes & animation

resolveKeyframesCopy Anchor Link

Keyframes with every time measured from the clip's visible start, sorted. End-anchored keyframes are placed using clipDurationUs; when a clip is shorter than its In + Out animations the two interleave by time (ties keep the start-anchored one first). Returns the input array itself when nothing is end-anchored.

function resolveKeyframes(keyframes: readonly Keyframe[], clipDurationUs: Us): readonly Keyframe[]

Guides: Keyframes & animation

retimeWordsCopy Anchor Link

New text for a caption clip, re-timed: when the word count is unchanged each word keeps its original timing (a typo fix keeps karaoke sync); otherwise the words split the clip's span evenly. Returns clip-relative words for clip/set-property { words }; empty text returns [].

function retimeWords(previous: readonly CaptionWord[], text: string, durationUs: Us): CaptionWord[]

Guides: Captions

secondsToUsCopy Anchor Link

function secondsToUs(seconds: number): Us

Guides: Project & time

snapToFrameCopy Anchor Link

Snap a position to the nearest frame start (halfway rounds to the later frame).

function snapToFrame(us: Us, rate: FrameRateLike): Us

Guides: Timeline, Project & time, Headless editor logic

toFrameRateCopy Anchor Link

The exact rate for a number or ratio. NTSC rates written as decimals (23.976, 23.98, 29.97, 59.94, 119.88…) become base·1000/1001; whole numbers become n/1; other decimals are read to 1/1000 (12.5 → 25/2). Ratios are reduced. Throws a RangeError for non-positive or non-finite input.

function toFrameRate(rate: FrameRateLike): FrameRate

toJsonPatchesCopy Anchor Link

Convert Immer patches to RFC-6902 JSON Patch operations.

function toJsonPatches(patches: readonly Patch[]): JsonPatchOp[]

toJsonPointerCopy Anchor Link

function toJsonPointer(path: readonly (string | number)[]): string

toolNameForCommandCopy Anchor Link

"clip/add" → "clip_add" — the sanitized name used in tool definitions.

function toolNameForCommand(type: string): string

Guides: Tools from the command catalog

toToolDefinitionsCopy Anchor Link

The command catalog as ready-to-send LLM tool definitions. Pass the result of project.commandCatalog() so registered custom commands are included.

function toToolDefinitions(catalog: Record<string, unknown>, options?: ToToolDefinitionsOptions): unknown[]

Guides: Tools from the command catalog, Roadmap

transitionParamsSchemaCopy Anchor Link

function transitionParamsSchema(kind: string): z.ZodType | undefined

Guides: Custom transitions

tryDispatchCopy Anchor Link

Dispatch one command, returning a structured result instead of throwing on command failures. Non-command errors (bugs) still throw.

function tryDispatch(project: Project, command: Command): CommandResult

Guides: MCP server, Tools from the command catalog, Properties panel, Commands

usedAssetsCopy Anchor Link

Assets referenced by at least one clip (fonts count when a clip names their family).

function usedAssets(doc: ProjectDocument): Asset[]

Guides: Assets

usToFrameCopy Anchor Link

Index of the frame containing the given timeline position.

function usToFrame(us: Us, rate: FrameRateLike): number

Guides: Selection & canvas editing, Timeline, Project & time

usToSecondsCopy Anchor Link

function usToSeconds(us: Us): number

Guides: Project & time

usToTimecodeCopy Anchor Link

Format µs as "HH:MM:SS:FF" timecode. Frames count from the exact rate, with the nominal rate (30 for 29.97) as frames per second — non-drop-frame, which runs about 3.6 s per hour behind the clock at 29.97. Pass { dropFrame: true } for "HH:MM:SS;FF" drop-frame timecode at 29.97 / 59.94.

function usToTimecode(us: Us, rate: FrameRateLike, options?: TimecodeOptions): string

Guides: Timeline, Project & time

wordsFromCueCopy Anchor Link

Fallback word timing: split a cue's span evenly across its words.

function wordsFromCue(cue: CaptionCue): CaptionWord[]

ClassesCopy Anchor Link

CommandRejectedErrorCopy Anchor Link

The command was well-formed but cannot be applied to the current state (unknown entity, track/clip kind mismatch, …). State was not touched.

Extends Error.

new CommandRejectedError(commandType: string, code: string, message: string)

Guides: Properties panel, Timeline, Commands, Tracks

CommandValidationErrorCopy Anchor Link

The command's payload failed schema validation. State was not touched.

Extends Error.

new CommandValidationError(commandType: string, error: ZodError)

Guides: Timeline, Commands

EmitterCopy Anchor Link

UnknownCommandErrorCopy Anchor Link

Dispatched a command type that is not registered.

Extends Error.

new UnknownCommandError(commandType: string)

Guides: Commands

ConstantsCopy Anchor Link

ANIMATION_DEFAULT_SLOT_USCopy Anchor Link

const ANIMATION_DEFAULT_SLOT_US: 600000

ANIMATION_EASINGSCopy Anchor Link

const ANIMATION_EASINGS: {
    id: AnimationEasing;
    label: string;
}[]

Guides: Keyframes & animation

ANIMATION_MAX_SLOT_USCopy Anchor Link

const ANIMATION_MAX_SLOT_US: 3000000

ANIMATION_MIN_SLOT_USCopy Anchor Link

const ANIMATION_MIN_SLOT_US: 200000

ANIMATION_PRESETSCopy Anchor Link

const ANIMATION_PRESETS: readonly AnimationPreset[]

Guides: Keyframes & animation

animationPresetCopy Anchor Link

A preset by id ("in:pop", "loop:pulse", …).

const animationPreset: (id: string) => AnimationPreset | undefined

Guides: Keyframes & animation

builtinEffectParamSchemasCopy Anchor Link

Kind registries — the extension seam. Built-in effect, transition, and clip kinds are pre-registered here with their Zod param schemas, which is what puts them in the AI command catalog and validates their commands. register*Kind lets consumers add custom kinds (the renderer's factory registries are the rendering half of the same seam).

const builtinEffectParamSchemas: {
    readonly colorAdjust: z.ZodObject<{
        brightness: z.ZodDefault<z.ZodNumber>;
        contrast: z.ZodDefault<z.ZodNumber>;
        saturation: z.ZodDefault<z.ZodNumber>;
        hue: z.ZodDefault<z.ZodNumber>;
    }, z.core.$strip>;
    readonly blur: z.ZodObject<{
        amount: z.ZodDefault<z.ZodNumber>;
    }, z.core.$strip>;
    readonly chromaKey: z.ZodObject<{
        color: z.ZodDefault<z.ZodString>;
        similarity: z.ZodDefault<z.ZodNumber>;
        smoothness: z.ZodDefault<z.ZodNumber>;
        spill: z.ZodDefault<z.ZodNumber>;
    }, z.core.$strip>;
}

builtinPayloadSchemasCopy Anchor Link

const builtinPayloadSchemas: {
    readonly "project/set-settings": z.ZodObject<{
        width: z.ZodOptional<z.ZodNumber>;
        height: z.ZodOptional<z.ZodNumber>;
        fps: z.ZodOptional<z.ZodNumber>;
        frameRate: z.ZodOptional<z.ZodObject<{
            num: z.ZodNumber;
            den: z.ZodNumber;
        }, z.core.$strip>>;
        name: z.ZodOptional<z.ZodString>;
    }, z.core.$strip>;
    readonly "asset/add": z.ZodObject<{
        id: z.ZodString;
        kind: z.ZodEnum<{
            video: "video";
            audio: "audio";
            image: "image";
            font: "font";
        }>;
       …

Guides: Properties panel

builtinTransitionParamSchemasCopy Anchor Link

const builtinTransitionParamSchemas: {
    readonly crossDissolve: z.ZodObject<{}, z.core.$strip>;
    readonly dipToBlack: z.ZodObject<{}, z.core.$strip>;
    readonly dipToWhite: z.ZodObject<{}, z.core.$strip>;
    readonly wipe: z.ZodObject<{
        direction: z.ZodDefault<z.ZodEnum<{
            left: "left";
            right: "right";
            up: "up";
            down: "down";
        }>>;
    }, z.core.$strip>;
    readonly slide: z.ZodObject<{
        direction: z.ZodDefault<z.ZodEnum<{
            left: "left";
            right: "right";
            up: "up";
            down: "down";
        }>>;
    }, z.core.$s …

DEFAULT_TRANSFORMCopy Anchor Link

const DEFAULT_TRANSFORM: Transform

EASING_PRESETSCopy Anchor Link

Named presets, stored expanded — CSS cubic-bezier() control points.

const EASING_PRESETS: Record<EasingPreset, Easing>

EFFECT_CATALOGCopy Anchor Link

Every built-in effect kind, grouped by category (catalog order = picker order).

const EFFECT_CATALOG: readonly EffectInfo[]

Guides: Effects, Custom effects

EFFECT_CATEGORIESCopy Anchor Link

const EFFECT_CATEGORIES: readonly {
    id: EffectCategory;
    label: string;
}[]

Guides: Effects

isAudioClipCopy Anchor Link

const isAudioClip: (clip: Clip) => clip is AudioClip

Guides: Clips

isCaptionClipCopy Anchor Link

const isCaptionClip: (clip: Clip) => clip is CaptionClip

Guides: Clips, Captions

isHtmlClipCopy Anchor Link

const isHtmlClip: (clip: Clip) => clip is HtmlClip

Guides: Clips

isImageClipCopy Anchor Link

const isImageClip: (clip: Clip) => clip is ImageClip

Guides: Clips

isTextClipCopy Anchor Link

const isTextClip: (clip: Clip) => clip is TextClip

Guides: Clips

isVideoClipCopy Anchor Link

const isVideoClip: (clip: Clip) => clip is VideoClip

Guides: Clips

TRACK_ACCEPTSCopy Anchor Link

Which clip kinds a track kind accepts (custom kinds declare theirs at registration).

const TRACK_ACCEPTS: Record<TrackKind, readonly ClipKind[]>

Guides: Timeline, Tracks

transformSchemaCopy Anchor Link

const transformSchema: z.ZodObject<{
    x: z.ZodNumber;
    y: z.ZodNumber;
    scale: z.ZodNumber;
    rotation: z.ZodNumber;
    opacity: z.ZodNumber;
}, z.core.$strip>

TYPOGRAPHY_DEFAULTSCopy Anchor Link

What an absent typography field means. Renderers and editor UIs read these rather than hard-coding them; the schema deliberately has no .default()s for these fields, so parsed documents never gain keys nobody set.

const TYPOGRAPHY_DEFAULTS: {
    readonly fontWeight: 400;
    readonly fontStyle: "normal";
    readonly letterSpacing: 0;
    readonly textAlign: "left";
    /** Caption line height multiple (text clips default to the font's natural line height). */
    readonly captionLineHeight: 1.3;
}

Guides: Text & typography

US_PER_SECONDCopy Anchor Link

const US_PER_SECOND: 1000000

InterfacesCopy Anchor Link

AnimationPresetCopy Anchor Link

AnimationRecipeCopy Anchor Link

AnimationSlotChoiceCopy Anchor Link

AsrGroupingOptionsCopy Anchor Link

AsrWordCopy Anchor Link

One ASR word, in seconds — the shape Whisper-style pipelines emit.

AssetCopy Anchor Link

AssetLicenseCopy Anchor Link

The terms an asset may be used under.

Guides: Audio

AssetSourceCopy Anchor Link

Where an asset came from (a stock library, a generator, a recording, an upload).

AudioClipCopy Anchor Link

Extends ClipBase, AudioFades.

AudioFadesCopy Anchor Link

Linear fades at a sound-making clip's edges (absent = none). Clamped to the clip's length when rendered.

CaptionClipCopy Anchor Link

Reels-style karaoke caption: word-level timing with an active-word style.

Extends ClipBase.

CaptionCueCopy Anchor Link

Caption import — pure text parsing that produces clip/add commands, so importing subtitles is just a transaction of ordinary commands (undoable, replayable, and visible to the AI command catalog like everything else).

Two sources: SRT/VTT cues (line-level timing; words get an even split as the fallback) and ASR word timestamps (Whisper-shape; real karaoke timing).

CaptionCueSourceCopy Anchor Link

The caption-clip fields subtitle export reads (any CaptionClip fits).

CaptionImportOptionsCopy Anchor Link

CaptionStyleCopy Anchor Link

Caption lines are always centered, so captions take no textAlign.

Extends Typography.

CaptionWordCopy Anchor Link

One word of a caption, timed relative to the clip's start.

ClipBaseCopy Anchor Link

ClipKindRegistrationCopy Anchor Link

Guides: Custom clip kinds

CommandCopy Anchor Link

CommandDefinitionCopy Anchor Link

CommandFailureCopy Anchor Link

CreateProjectOptionsCopy Anchor Link

CustomClipCopy Anchor Link

A clip of a registered custom kind (see registerClipKind). Its payload lives under props, validated by the kind's registered schema.

Extends ClipBase.

CutCopy Anchor Link

Cuts: where one clip ends exactly where the next starts on the same video track — the only places transition/add accepts. A transition is centered on the cut, so it borrows half its length from footage past the outgoing clip's end and half from before the incoming clip's start ("handles"); maxTransitionUs is what those handles (and both clips' lengths) allow.

Editor panels and AI tools share this, so "every cut" means the same thing everywhere.

Guides: Transitions

DescribeProjectOptionsCopy Anchor Link

EffectInfoCopy Anchor Link

Guides: Effects

EffectInstanceCopy Anchor Link

One effect in a clip's stack. kind resolves through the effect registry (built-ins: see EFFECT_CATALOG); params are validated against the kind's schema at command time. Length-denoting params are normalized to composition units — absolute pixels would render differently between a scaled preview and a full-resolution export.

EphemeralStateCopy Anchor Link

Ephemeral session state: lives in the store, excluded from undo history and from serialization.

EvaluatedClipCopy Anchor Link

Flat evaluated state — reusable output object keeps evaluation alloc-free.

FrameRateCopy Anchor Link

An exact frame rate as a ratio of positive integers: NTSC 29.97 is { num: 30000, den: 1001 }.

HtmlClipCopy Anchor Link

HTML rendered into the composition: the template (with {{param}} placeholders) is rasterized via SVG foreignObject at widthPx×heightPx (default: the composition size) and composited like any other clip — keyframes, effects, and transitions all apply to the raster.

Extends ClipBase.

ImageClipCopy Anchor Link

Extends ClipBase.

JsonPatchOpCopy Anchor Link

RFC-6902 JSON Patch operation (the subset Immer produces).

KeyframeCopy Anchor Link

LicenseIssueCopy Anchor Link

PlannedKeyframeCopy Anchor Link

ProjectCopy Anchor Link

Guides: MCP server, Collaboration, Stills

ProjectDocumentCopy Anchor Link

The document: everything that is part of the composition, serialized and covered by undo history.

Guides: Collaboration, Stills, Defining templates

ProjectEventsCopy Anchor Link

Extends Record<string, unknown>.

ProjectSettingsCopy Anchor Link

ProjectStateCopy Anchor Link

Extends EphemeralState.

ReadAnimationCopy Anchor Link

TextClipCopy Anchor Link

Extends ClipBase, Typography.

TimecodeOptionsCopy Anchor Link

ToToolDefinitionsOptionsCopy Anchor Link

TrackCopy Anchor Link

Guides: Timeline, React

TransformCopy Anchor Link

TransitionCopy Anchor Link

TypographyCopy Anchor Link

Optional typography shared by text clips and caption styles. Absent fields mean the default (see TYPOGRAPHY_DEFAULTS) — which is exactly how clips rendered before these fields existed. Documents only carry what was set, so older projects load, render, and serialize unchanged.

VideoClipCopy Anchor Link

Extends ClipBase, AudioFades.

TypesCopy Anchor Link

AnimatablePropertyCopy Anchor Link

type AnimatableProperty = "x" | "y" | "scale" | "rotation" | "opacity" | "volume";

AnimationEasingCopy Anchor Link

type AnimationEasing = "smooth" | "linear" | "snappy";

AnimationSlotCopy Anchor Link

Animation presets, built on ordinary keyframes so they play in preview and every export with no special support.

A clip's animation is a RECIPE of up to three slots: In (from the start), Loop (between In and Out) and Out (into the end, end-anchored so it follows trims). Applying a recipe regenerates the clip's visual keyframes. The recipe isn't stored anywhere: readAnimation recognizes it from the keyframes (presets are deterministic), so it survives save / reload and undo. Hand-made keyframes that match no preset read as "custom".

Editor panels and AI tools share this module, so "pop in" means the same keyframes wherever it's applied.

type AnimationSlot = "in" | "out" | "loop";

ApplyCommandsResultCopy Anchor Link

type ApplyCommandsResult = {
    ok: true;
    applied: number;
} | {
    ok: false;
    applied: 0;
    failedIndex: number;
    error: CommandFailure;
};

AssetKindCopy Anchor Link

type AssetKind = "video" | "audio" | "image" | "font";

BuiltinClipCopy Anchor Link

type BuiltinClip = VideoClip | AudioClip | ImageClip | TextClip | CaptionClip | HtmlClip;

BuiltinCommandCopy Anchor Link

A built-in command as dispatched.

type BuiltinCommand = {
    [T in BuiltinCommandType]: {
        type: T;
        payload: BuiltinCommandPayload<T>;
    };
}[BuiltinCommandType];

BuiltinCommandPayloadCopy Anchor Link

type BuiltinCommandPayload<T extends BuiltinCommandType> = z.input<(typeof builtinPayloadSchemas)[T]>;

BuiltinCommandTypeCopy Anchor Link

type BuiltinCommandType = keyof typeof builtinPayloadSchemas;

ClipCopy Anchor Link

type Clip = BuiltinClip | CustomClip;

Guides: Timeline, React

ClipKindCopy Anchor Link

type ClipKind = "video" | "audio" | "image" | "text" | "caption" | "html";

CommandHandlerCopy Anchor Link

Applies a validated payload to a draft of the document.

type CommandHandler<P = unknown> = (doc: Draft<ProjectDocument>, payload: P) => void;

CommandResultCopy Anchor Link

type CommandResult = {
    ok: true;
} | {
    ok: false;
    error: CommandFailure;
};

EasingCopy Anchor Link

Easings are STORED as cubic-bézier control points (CSS convention: progress x → eased y) — named presets are input sugar that expands at command time. "hold" steps to the next keyframe with no interpolation.

type Easing = {
    kind: "bezier";
    x1: number;
    y1: number;
    x2: number;
    y2: number;
} | {
    kind: "hold";
};

EasingPresetCopy Anchor Link

type EasingPreset = "linear" | "hold" | "easeIn" | "easeOut" | "easeInOut";

EffectCategoryCopy Anchor Link

The built-in effect library: every built-in effect kind's name, category and params, as plain data. One declaration feeds three consumers:

• validation — each entry's param schema is derived from it (see registry.ts), so effect/add / effect/update validate and fill defaults;
• the AI command catalog — kinds and ranges reach LLM tools;
• editor UIs — labels, categories, slider ranges and display hints for property panels and effect pickers (EFFECT_CATALOG, getEffectInfo).

The renderer draws every kind listed here (its shaders are keyed by kind). Length params (length: true) are fractions of COMPOSITION HEIGHT — never pixels — so a scaled preview and a full-resolution export look identical.

type EffectCategory = "color" | "film" | "stylize" | "glitch" | "light" | "distort" | "frame";

EffectParamFormatCopy Anchor Link

How a UI should display a number param's value.

type EffectParamFormat = "percent" | "int" | "deg" | "stops" | "decimal";

EffectParamInfoCopy Anchor Link

type EffectParamInfo = {
    key: string;
    label: string;
    type: "number";
    min: number;
    max: number;
    step: number;
    default: number;
    format?: EffectParamFormat;
    length?: true;
} | {
    key: string;
    label: string;
    type: "color"; default: string;
};

Guides: Effects

FontStyleCopy Anchor Link

type FontStyle = "normal" | "italic";

FontWeightCopy Anchor Link

CSS font weight: 100–900 in steps of 100 (validated by the command schemas).

type FontWeight = number;

FrameRateLikeCopy Anchor Link

Anything the frame helpers accept: a plain number (29.97 → 30000/1001) or an exact ratio.

type FrameRateLike = number | FrameRate;

HtmlParamValueCopy Anchor Link

A template parameter value — plain data, so html clips serialize and cross process boundaries.

type HtmlParamValue = string | number | boolean;

ListenerCopy Anchor Link

Minimal typed event emitter.

type Listener<T> = (payload: T) => void;

PatchSourceCopy Anchor Link

type PatchSource = "dispatch" | "undo" | "redo" | "transaction-rollback";

TextAlignCopy Anchor Link

type TextAlign = "left" | "center" | "right";

TrackKindCopy Anchor Link

type TrackKind = "video" | "audio";

UsCopy Anchor Link

Microseconds — the timeline unit. 1 second = 1_000_000 µs.

type Us = number;