Video Elements

Complete reference for video elements with the Zvid, including video source trimming, timeline timing, transitions, audio control, animations, and visual/effect properties.

Overview

Video elements let you place video clips on the project timeline with precise control over:

• Source trimming (videoBegin, videoEnd, videoDuration)
• Timeline timing (enterBegin, enterEnd, exitBegin, exitEnd)
• Audio (volume)
• Playback (speed, frameRate)
• Transitions (transition, transitionDuration, transitionId)
• Layout & effects (positioning, resize, cropping, chroma key, etc.)

VideoItem Interface

interface VideoItem {
  // Required
  type: "VIDEO";
  src: string;

  // Layout (optional)
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: ResizeMode;

  // Timeline timing (optional)
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;

  // Visual (optional)
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  zoom?: boolean;

  // Animations (optional)
  enterAnimation?: string | undefined;
  exitAnimation?: string | undefined;

  // Effects (optional)
  cropParams?: CropParams;
  chromaKey?: ChromaKey;
  filter?: FilterOptions;

  // Video source trimming (optional)
  videoBegin?: number;
  videoEnd?: number;
  videoDuration?: number;

  // Audio / playback (optional)
  volume?: number;
  speed?: number;
  frameRate?: number;

  // Transitions (optional)
  transition?: XFadeEffect | undefined;
  transitionDuration?: number;
  transitionId?: string | undefined;

  // Transition identity (optional; required when using transitions)
  id?: string;
}

---

Properties

Required Properties

Property	Type	Description
type	"VIDEO"	Element type identifier
src	string	Video file path or URL

---

Layout Properties

Property	Type	Default	Description
x	number	0	Horizontal position in pixels
y	number	0	Vertical position in pixels
width	number	Source width	Video render width in pixels
height	number	Source height	Video render height in pixels
position	PositionPreset	"custom"	Position preset (overrides x, y)
anchor	Anchor	"top-left"	Anchor point used for positioning
resize	ResizeMode	undefined	Resize mode (overrides width, height)

---

Timeline Timing Properties

These control when the element is visible on the project timeline.

Property	Type	Default	Description
enterBegin	number	0	Time when the element starts appearing (seconds)
enterEnd	number	0	Time when the entrance animation ends (seconds)
exitBegin	number	project.duration	Time when the exit animation starts (seconds)
exitEnd	number	project.duration	Time when the element fully disappears (seconds)

---

Visual Properties

Property	Type	Default	Description
track	number	0	Layer/track number (higher = on top)
opacity	number	1	Transparency (0–1)
angle	number	0	Rotation in degrees
flipV	boolean	false	Flip vertically
flipH	boolean	false	Flip horizontally
zoom	boolean	false	Add zoom effect

Border Radius

For now, radius is not supported with the VIDEO element.

---

Animation Properties

Property	Type	Description
enterAnimation	string | undefined	Entrance animation name
exitAnimation	string | undefined	Exit animation name

---

Effect Properties

Property	Type	Description
filter	FilterOptions	Image filters and effects
cropParams	CropParams	Crop configuration
chromaKey	ChromaKey	Chroma key (green screen)

CropParams Interface

interface CropParams {
  x: number; // horizontal start position (px)
  y: number; // vertical start position (px)
  width: number; // cropped width (px)
  height: number; // cropped height (px)
}

ChromaKey Interface

interface ChromaKey {
  color: string;
  similarity?: number;
  blend?: number;
}

---

Video Source Trimming Properties

These control which part of the source video is used.

Property	Type	Default	Description
videoBegin	number	0	Start time in source video (seconds)
videoEnd	number	Source duration	End time in source video (seconds)
videoDuration	number	Source duration	Total duration of the source video

If you set videoBegin/videoEnd, the engine plays only that slice from the source.

---

Audio & Playback Properties

Property	Type	Default	Description
volume	number	1	Audio volume (0–1)
speed	number	1	Playback speed multiplier

---

Transition Properties

Transitions are implemented using FFMPEG xfade and allow smooth visual changes between two video clips.
To create a transition, you must:

• Assign an id to each video involved
• Define transition, transitionDuration, and transitionId on the video that starts the transition
• Ensure the two videos overlap correctly on the timeline (see example below)

Property	Type	Default	Description
transition	XFadeEffect | undefined	undefined	The transition effect applied between two videos
transitionDuration	number | undefined	undfined	Duration of the transition in seconds
transitionId	string | undefined	undefined	id of the other video participating in the transition
id	string	Auto-generated	Unique video identifier (required when using transitions)

---

Supporting Types

PositionPreset

type PositionPreset =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-right"
  | "bottom-center"
  | "bottom-left"
  | "custom";

ResizeMode

type ResizeMode = "contain" | "cover";

Anchor

export type Anchor =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

FilterOptions Interface

interface FilterOptions {
  brightness?: number;
  contrast?: number;
  "hue-rotate"?: string;
  saturate?: number;
  blur?: string;
}

Zoom Property

The zoom property adds a zoom effect to image elements.
When enabled, the image will smoothly zoom toward its center during its visible duration.

Usage

// Boolean usage (uses default settings)
zoom: true;

---

Animations and Transitions Types

We support these transitions from FFMPEG xfade

type XFadeEffect =
  | "fade"
  | "fadeblack"
  | "fadewhite"
  | "wipeleft"
  | "wiperight"
  | "wipeup"
  | "wipedown"
  | "slideleft"
  | "slideright"
  | "slideup"
  | "slidedown"
  | "smoothleft"
  | "smoothright"
  | "smoothup"
  | "smoothdown"
  | "circlecrop"
  | "rectcrop"
  | "circleclose"
  | "circleopen"
  | "horzclose"
  | "horzopen"
  | "vertclose"
  | "vertopen"
  | "diagbl"
  | "diagbr"
  | "diagtl"
  | "diagtr"
  | "hlslice"
  | "hrslice"
  | "vuslice"
  | "vdslice"
  | "dissolve"
  | "pixelize"
  | "radial"
  | "hblur"
  | "wipetl"
  | "wipetr"
  | "wipebl"
  | "wipebr"
  | "fadegrays";

Unsupported Transitions

These transitions are not yet supported: squeezeh, squeezev, hlwind, hrwind, vuwind, vdwind, coverleft, coverright, coverup, coverdown, revealleft, revealright, revealup, revealdown, zoomin, and distance

---

Basic Examples

Simple Video Clip

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
}

Video with Timeline Timing + Source Trim

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
  videoBegin: 5,
  videoEnd: 25,
  volume: 0.8,
  width: 1920,
  height: 1080,
  enterBegin: 0,
  enterEnd: 1,
  exitBegin: 19,
  exitEnd: 20
}

Video with Resize Mode

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
  resize: "cover" // Fill the video dimensions, may crop
}

Picture-in-Picture with Position Preset

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
  videoBegin: 10,
  videoEnd: 30,
  width: 300,
  height: 200,
  position: "bottom-right",
  volume: 0.3,
  track: 10,
  enterBegin: 0,
  enterEnd: 1,
  exitBegin: 9,
  exitEnd: 10,
  enterAnimation: "slideright",
  exitAnimation: "slideleft"
}

---

Advanced Examples

Slow Motion Effect

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
  speed: 0.5
}

Fast Forward Effect (Muted)

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
  speed: 2.0,
  volume: 0
}

Green Screen Video

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2021/07/22/82431-580137651_large.mp4",
  resize: "cover",
  chromaKey: {
    color: "#00D800",
    similarity: 10,
    blend: 20
  }
}

---

Complex Examples

Multi-Video Sequence with Transitions

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/03/12/264272_large.mp4",
  resize: "cover",
  enterBegin: 0,
  exitEnd: 5,
  id: "intro",
  transition: "slideleft",
  transitionDuration: 2,
  transitionId: "main"
},
{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
  resize: "cover",
  enterBegin: 5,
  exitEnd: 10,
  id: "main"
}

Split Screen Videos

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/08/12/296958_large.mp4",
  x: 0,
  y: 0,
  width: 640,
  height: 720,
  volume: 0.5
},
{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/08/20/298643_large.mp4",
  x: 640,
  y: 0,
  width: 640,
  height: 720,
  volume: 0.5
}

Cropping Video

{
  type: "VIDEO",
  src: "https://cdn.pixabay.com/video/2025/03/12/264272_large.mp4",
  width: 1280,
  height: 720,
  cropParams: {
    x: 100,
    y: 50,
    width: 1080,
    height: 620
  }
}

---

Video Timing Explained

Source Timing (Trim)

• videoBegin: start point in the source file
• videoEnd: end point in the source file
• videoDuration: full source length

{
  videoBegin: 10,
  videoEnd: 20,
  videoDuration: 60
}

Timeline Timing (Placement)

• enterBegin: when the video starts on the timeline
• enterEnd: when entrance animation completes
• exitBegin: when exit animation starts
• exitEnd: when it fully disappears

{
  enterBegin: 5,
  enterEnd: 6,
  exitBegin: 25,
  exitEnd: 26
}

Transition System

Basic Transitions

Transitions create smooth changes between video clips:

// Video 1 fades out as Video 2 fades in
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/03/12/264272_large.mp4",
    resize: "cover",
    exitEnd: 5, // `exitEnd` should be equal to the `enterBegin` of the next video in transition.
    id: "intro",
    transition: "slideleft", // type of  transition
    transitionDuration: 2,
    transitionId: "main" // the `id` of the next video to transition
},
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/05/01/275983_large.mp4",
    resize: "cover",
    enterBegin: 5, // `enterBegin` should be equal to the `exitEnd` of the previous video in transition
    exitEnd: 10,
    id: "main" // In transition `id` is required to identify
}

Transition Categories

Fade Transitions

• fade - Standard crossfade
• fadeblack - Fade through black
• fadewhite - Fade through white
• fadegrays - Fade through grayscale

Wipe Transitions

• wipeleft, wiperight, wipeup, wipedown
• wipetl, wipetr, wipebl, wipebr (diagonal wipes)

Slide Transitions

• slideleft, slideright, slideup, slidedown
• smoothleft, smoothright, smoothup, smoothdown

Shape Transitions

• circlecrop, rectcrop
• circleclose, circleopen
• horzclose, horzopen, vertclose, vertopen

Creative Transitions

• dissolve - Dissolve effect
• pixelize - Pixelation transition
• radial - Radial wipe

Audio Management

Volume Control

{
  volume: 0,    // Muted
  volume: 0.5,  // Half volume
  volume: 1,    // Full volume
  volume: 1.5   // Amplified (may cause distortion)
}

Speed and Pitch

{
  speed: 0.5,  // Half speed (also lowers pitch)
  speed: 1,    // Normal speed
  speed: 2,    // Double speed (also raises pitch)
}

Supported Video Formats

Input and Ouptut Formats

All FFMPEG input and output formats are supported.

Related Pages

• Transitions - Detailed transition effects guide
• Audio Elements - Managing audio tracks
• Animation Effects - Video animations

Next Steps

• Transitions - Master video transition effects
• Audio Elements - Add background music and sound effects