iLoveVideoEditor Docs

Appearance

@ilovevideoeditor/core — API reference ​

The builder, layer classes, Time parser, and VideoJSON compiler.

Classes ​

AudioLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: AuditoryLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: AudioLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: AuditoryLayerProperties, settings: AudioLayerSettings): AudioLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

CaptionsLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: TextualLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: CaptionsLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: TextualLayerProperties, settings: CaptionsLayerSettings): CaptionsLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

ImageLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: MediaLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: MediaLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: MediaLayerProperties, settings: MediaLayerSettings): ImageLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

ShapeLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: ShapeLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: ShapeLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: ShapeLayerProperties, settings: ShapeLayerSettings): ShapeLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

TextLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: TextLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: BaseLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: TextLayerProperties, settings: BaseLayerSettings): TextLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

iLoveVideoEditor ​

Properties ​

  • flow: Action[] — The sequential list of flow actions. This is the "program" that gets compiled into the video JSON.
  • layers: BaseLayer[] — All layers created through the flow API. Used during compilation to look up layer metadata.
  • settings: Required<ProjectSettings> — Project settings (dimensions, fps, defaults).
  • loadedMedia

Methods ​

  • constructor(settings: ProjectSettings): iLoveVideoEditor
  • addAudio(properties?: AuditoryLayerProperties, settings?: AudioLayerSettings, options?: AddLayerOptions): AudioLayer — Add an audio layer from a URL or file path.
  • addCaptions(properties?: TextualLayerProperties, settings?: CaptionsLayerSettings, options?: AddLayerOptions): CaptionsLayer — Add a captions layer with pre-defined timed captions.
  • addImage(properties?: MediaLayerProperties, settings?: MediaLayerSettings, options?: AddLayerOptions): ImageLayer — Add an image layer from a URL or file path.
  • addLayer(LayerClass: (parent: iLoveVideoEditor, properties?: any, settings?: any) => T, properties: Record<string, any>, settings: Record<string, any>, options: AddLayerOptions): T — Add a layer of the given class to the flow.
  • addShape(properties?: ShapeLayerProperties, settings?: ShapeLayerSettings, options?: AddLayerOptions): ShapeLayer — Add a vector shape layer (rectangle, ellipse, polygon, or star).
  • addText(properties?: TextLayerProperties, settings?: BaseLayerSettings, options?: AddLayerOptions): TextLayer — Add a text layer.
  • addVideo(properties?: VideoLayerProperties, settings?: MediaLayerSettings, options?: AddLayerOptions): VideoLayer — Add a video layer from a URL or file path.
  • compile(): Promise<VideoJSON> — Compile the flow into a VideoJSON object.

This method:

  1. Walks the flow actions sequentially, maintaining a time pointer.
  2. Converts all time values to frame numbers.
  3. Builds keyframe arrays from set / animate actions.
  4. Calculates the total project duration.
  5. Returns the complete JSON ready for rendering.

Media metadata (image dimensions, video/audio duration) is resolved during compilation so that waitFor: 'finish' and auto-duration work correctly.

  • group(properties: VisualLayerProperties, settings: BaseLayerSettings, fn: (group: GroupLayer) => void, options: AddLayerOptions): GroupLayer — Add a layer group — a container that nests other layers and treats them as one. Inside fn, the flow's time pointer resets to 0 (relative to the group's start), so children's timing is authored independently of where the group sits on the project timeline. The flow pointer of the outer scope advances by the group's waitFor (default 'finish' = the group's full footprint).

The group itself is a VisualLayer, so its position, scale, rotation, opacity, filters, transitions and effects all apply to the composited child sub-tree.

ts
const card = $.group({ position: [0.5, 0.5], scale: 1 }, {}, () => {
  $.addShape({ width: 60, height: 30, fill: '#fff' });
  $.addText({ text: 'Hello' });
});
card.animate({ scale: 1 }, { scale: 1.1 }, { duration: '500ms' });

Group timing is auto-derived: startTime defaults to the current flow time, and sourceDuration defaults to the latest child's end (so a group whose last child finishes at +5s lasts 5s). Both can still be overridden in settings if you need to.

  • parallel(funcs: () => void[]): this — Execute multiple sequences of actions in parallel.

Each function receives its own timeline; the overall flow pointer advances to the end of the longest parallel branch.

ts
$.parallel([
  () => { text.animate({opacity:0},{opacity:1},{duration:'1s'}); },
  () => { bg.animate({filterBlur:0},{filterBlur:5},{duration:'2s'}); },
]);
  • pushAction(action: Action): void — Push a raw action onto the current flow pointer. Used by layers to record their actions.
  • renderAudio(): Promise<any> — Compile and render the full audio track of the video.

Automatically detects the environment and uses the appropriate renderer. The renderer package must be installed separately.

  • renderFrame(frame: number): Promise<any> — Compile and render a single frame of the video.

Automatically detects the environment and uses the appropriate renderer. The renderer package must be installed separately.

  • renderVideo(options: Record<string, any>): Promise<any> — Compile and render the video in one call.

Automatically detects the environment and uses the appropriate renderer:

  • Browser (window/DOM present) → @ilovevideoeditor/renderer-browser
  • Node.js (no DOM, process.versions.node exists) → @ilovevideoeditor/renderer-server

The renderer package must be installed separately.

  • wait(time: Time): this — Pause the timeline for the given duration before the next action.

VideoLayer ​

Properties ​

  • id: string — Unique identifier for this layer instance.
  • properties: VideoLayerProperties — Layer properties — the visual/auditory attributes that can be animated.

Each property key maps to either a static value or an array of Keyframe objects describing its animation over time.

  • settings: MediaLayerSettings — Layer settings (timing, enable state, etc.).
  • type: string — Machine-readable layer type tag (overridden by subclasses).
  • endFrame
  • endTime
  • sourceDurationFrames
  • sourceStartFrames
  • startFrame
  • timelineDuration
  • timelineDurationFrames
  • defaultProperties
  • defaultSettings
  • propertiesDefinition
  • settingsKeys

Methods ​

  • constructor(parent: any, properties: VideoLayerProperties, settings: MediaLayerSettings): VideoLayer
  • animate(from: Record<string, any>, to: Record<string, any>, settings: { duration?: Time; easing?: Easing; wait?: boolean }): this — Animate properties from one state to another.
  • fadeIn(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer in from transparent.
  • fadeOut(duration: Time, easing?: Easing, wait?: boolean): this — Fade the layer out to transparent.
  • hide(): this — Hide the layer (set visible to false).
  • remove(): this — Remove this layer at the current flow position.

Once removed, calling any further flow method on this layer throws.

  • set(value: Record<string, any>): this — Set property values at the current flow position (step keyframe).
  • show(): this — Show the layer (set visible to true).
  • toJSON(): LayerJSON — Serialise this layer into the iLoveVideoEditor JSON model format.

Properties stored as keyframe arrays are converted into the animations array, while static properties go into properties.

Functions ​

formatTime ​

Format a duration in seconds as a human-readable mm:ss or hh:mm:ss string.

ts
formatTime(seconds: number): string

Parameters

  • seconds — number

Returns string

framesToTime ​

Convert a frame number back to seconds.

ts
framesToTime(frames: number, fps: number): number

Parameters

  • frames — number: Frame number.
  • fps — number: Frames per second.

Returns number

parseTime ​

Parse a flexible Time value into seconds.

Accepted formats:

  • number — seconds directly
  • "5" — seconds (unitless string)
  • "5s" / "2m" / "1h" / "500ms" — seconds / minutes / hours / ms
  • "120f" — frames, requires fps parameter
  • "mm:ss" / "hh:mm:ss" / "hh:mm:ss:ff" — colon-separated
ts
parseTime(time: Time, fps: number): number

Parameters

  • time — Time: The value to parse.
  • fps — number: Frames per second (needed when the value ends with "f" or contains a frames component in hh:mm:ss:ff).

Returns number

probeMediaDuration ​

Probe the intrinsic duration of a media source (in seconds).

Environment-aware:

  • Browser: spins up a transient <video> or <audio> element, waits for loadedmetadata, reads .duration, then disposes of the element.
  • Node: dynamically imports child_process and spawns ffprobe -v error -of json -show_format <source>, parsing format.duration from the JSON. Requires ffprobe to be installed and available on PATH (the same binary @ilovevideoeditor/renderer-server already depends on).

Throws on any failure (missing binary, network error, decode failure). Callers should catch and decide whether to fall back to "unknown duration".

ts
probeMediaDuration(source: string, kind: "video" | "audio"): Promise<number>

Parameters

  • source — string: URL or filesystem path to the media file.
  • kind — "video" | "audio": 'video' or 'audio' (only matters for the browser path).

Returns Promise<number>

timeToFrames ​

Convert a Time value to a frame number.

ts
timeToFrames(time: Time, fps: number): number

Parameters

  • time — Time: Flexible time value.
  • fps — number: Frames per second.

Returns number

Type aliases ​

Action ​

Union of all possible flow actions produced by the iLoveVideoEditor builder.

The flow is a sequential list of these actions that gets compiled into the final VideoJSON by the compile() method.

ts
Action: { duration: Time; statement: "wait" } | { actions: Action[][]; statement: "parallel" } | { id: Id; options?: AddLayerOptions; properties: Record<string, any>; settings: Record<string, any>; statement: "addLayer"; type: string } | { actions: Action[]; id: Id; options?: AddLayerOptions; properties: Record<string, any>; settings: Record<string, any>; statement: "group" } | { id: Id; statement: "removeLayer" } | { id: Id; statement: "set"; value: Record<string, any> } | { from: Record<string, any>; id: Id; settings: { duration: Time; easing?: Easing; wait?: boolean }; statement: "animate"; to: Record<string, any> }

AddLayerOptions ​

Options passed when adding a layer to the flow.

  • waitFor controls how long the flow pointer advances after the layer is added. 'finish' waits for the layer's full duration; a Time value waits for that specific amount.
  • index sets the visual stacking order (negative = back, positive = front).

Animation ​

A single animation definition attached to a layer.

Each animation targets one property and defines a sequence of keyframes with an optional default easing function.

AudioLayerProperties ​

ts
AudioLayerProperties: AuditoryLayerProperties

AudioLayerSettings ​

ts
AudioLayerSettings: AuditoryLayerSettings & { source: string }

CaptionEntry ​

A single caption entry with timing information.

CaptionsLayerProperties ​

ts
CaptionsLayerProperties: TextualLayerProperties

CaptionsLayerSettings ​

ts
CaptionsLayerSettings: TextualLayerSettings & { captions?: CaptionEntry[]; maxCharsPerLine?: number; maxLines?: number; captionContractVersion?: 2; captionLanguage?: string; captionLayout?: CaptionLayoutJSON; captionStyle?: CaptionStyleJSON; captionMotion?: CaptionMotionJSON; captionMotionMode?: 'full' | 'reduced' }

Easing ​

Easing functions supported by the animation system.

  • step — hold the start value until the next keyframe (no interpolation)
  • linear — constant rate of change
  • easeIn — starts slow, accelerates
  • easeOut — starts fast, decelerates
  • easeInOut — slow at both ends, fast in the middle
ts
Easing: "step" | "linear" | "easeIn" | "easeOut" | "easeInOut"

Id ​

Unique identifier for a layer (UUID v4).

ts
Id: string

ImageLayerProperties ​

ts
ImageLayerProperties: MediaLayerProperties

ImageLayerSettings ​

ts
ImageLayerSettings: MediaLayerSettings

Keyframe ​

An animation keyframe.

The time field is always in seconds, expressed in source media time (i.e. an absolute position inside the source clip, measured from the start of the source). For non-media layers (text, captions, …) source time collapses to "elapsed seconds since the layer started" because there is no external source.

LayerEffectJSON ​

A single effect entry on a layer. effect names a shader previously registered with Renderer.registerEffect(name, glsl, paramsDefinitions). params holds the uniform values used when the shader runs.

A layer may declare multiple effects; they run in array order, each pass reading the previous pass's output.

enabled defaults to true when absent. Setting it to false keeps the entry in the JSON (so editors can preserve user configuration) but skips the pass entirely at render time — equivalent to removing the entry, but non-destructive.

LayerJSON ​

A single layer as it appears in the compiled JSON model.

track is optional editor metadata: it groups layers into rows in a timeline UI. When set, the renderer also uses it to z-order the layer (z-index = track + 1); layers without a track are stacked by document order with no explicit z-index. Editors are free to pack layers into tracks and write the assignment back here; non-editor consumers can ignore the field entirely.

transitionIn / transitionOut attach registered transition presets to the layer's timeline edges; they modify the final (post-keyframe) properties during the transition window. effects attaches registered GLSL effects that run on the rasterized layer texture before it is composited.

children is only populated when type === 'group'. A group layer has no source content of its own — it composites its children onto a private project-sized surface, then runs the group's own transform / opacity / filter / transition / effects pipeline on that surface, exactly as if the group were a single visual layer. Children's settings.startTime are absolute timeline seconds (resolved at compile time from their group-relative positions inside the flow), so the runtime can look up a child's state at any frame without knowing about the enclosing group.

LayerSettingsJSON ​

Settings block for a layer inside the compiled JSON.

iLoveVideoEditor distinguishes three time contexts:

  1. Source media time — absolute time inside the source clip ([0, mediaDuration]). sourceStart, sourceEnd, mediaDuration and keyframe time values all live here.
  2. Source segment time — time within the playable segment ([0, sourceDuration]). Derived as sourceTime − sourceStart.
  3. Timeline time — wall-clock time on the project timeline ([0, projectDuration]). startTime, endTime and the playback head live here.

speed stretches the segment in the timeline: timelineDuration = sourceDuration / speed. So speed = 2 plays the segment twice as fast and occupies half as much timeline.

Different layer types extend this with additional keys (e.g. source for media layers, captions for the captions layer).

LayerTransitionJSON ​

A transition attached to the start or end of a layer's timeline footprint.

transition names a function previously registered with Renderer.registerTransition(name, fn). duration is in seconds and must fit inside the layer's own timeline duration — if transitionIn.duration + transitionOut.duration exceeds the layer duration, both are scaled down proportionally by the renderer.

params is passed verbatim to the transition function as its third argument and is free-form per preset (e.g. { amount: 8 } for a blur preset).

MediaEntry ​

MediaCache — global, refcounted, time-evicted cache for media sources.

One entry per source URL holds the fetched Blob plus a single object URL shared across every consumer (layers, audio render, compile-time probe). Consumers acquire() an entry to take a reference and release() when they no longer need it. When the refCount drops to zero the entry is scheduled for eviction after a short grace period (default 5 s) so that back-to-back loads — most importantly the compile → renderer handoff and loadVideo() reloads — reuse the bytes instead of re-fetching them.

Usage:

ts
import { loadedMedia } from '@ilovevideoeditor/core';

const entry = await loadedMedia.acquire(url);
use(entry.objectUrl);
loadedMedia.release(url);

ProjectSettings ​

Project-level settings provided when creating a iLoveVideoEditor instance.

These control the canvas dimensions, frame rate, visual defaults, and logging behaviour.

PropertyDefinition ​

Metadata describing a single property on a layer type.

Used internally by the rendering system to know how to apply, interpolate, and map properties onto CSS.

RenderOptions ​

Rendering options common to both browser and server renderers.

ShapeLayerProperties ​

ts
ShapeLayerProperties: VisualLayerProperties & { cornerRadius?: number | string; fill?: string; height?: number | string; innerRadius?: number; sides?: number; strokeAlignment?: StrokeAlignment; strokeColor?: string; strokeDash?: number | string; strokeGap?: number | string; strokeLinejoin?: StrokeLinejoin; strokeWidth?: number | string; width?: number | string }

ShapeLayerSettings ​

ts
ShapeLayerSettings: VisualLayerSettings & { shapeType?: ShapeType }

ShapeType ​

ts
ShapeType: "rectangle" | "ellipse" | "polygon" | "star"

TextLayerProperties ​

ts
TextLayerProperties: TextualLayerProperties & { text?: string }

TextLayerSettings ​

ts
TextLayerSettings: TextualLayerSettings

Time ​

A flexible time value accepted by the iLoveVideoEditor API.

Supported formats:

  • number — interpreted as seconds (e.g. 5 = 5 seconds)
  • string (no unit) — also seconds (e.g. "5" = 5 seconds)
  • string with unit:
    • "5s" → 5 seconds
    • "2m" → 2 minutes
    • "1h" → 1 hour
    • "120f" → 120 frames
    • "500ms" → 500 milliseconds
    • "01:30" → 1 min 30 sec (mm:ss)
    • "01:02:30" → 1 hr 2 min 30 sec (hh:mm:ss)
    • "01:02:30:15" → hh:mm:ss:ff (frames at the end)
ts
Time: string | number

VideoJSON ​

The top-level compiled video JSON model.

This is the format accepted by both the browser and server renderers.

tracks is optional editor metadata: it mirrors LayerJSON.track with per-row display state. Non-editor consumers should ignore it.

VideoLayerProperties ​

ts
VideoLayerProperties: MediaLayerProperties & AuditoryLayerProperties

VideoLayerSettings ​

ts
VideoLayerSettings: MediaLayerSettings

Released under the MIT License.

Copyright © iLoveVideoEditor