Video Elements

Complete reference for video elements in the Zvid Package, including video timing, transitions, audio control, and advanced video effects. a

Overview

Video elements allow you to add video clips to your projects with precise timing control, audio management, animtions, transition effects, and all the visual properties available to image elements. Video elements extend image functionality with video-specific features.

VideoItem Interface

interface VideoItem extends ImageItem {
  type: "VIDEO";
  videoBegin: number;
  videoEnd: number;
  videoDuration: number;
  volume?: number;
  speed?: number;
  transition?: XFadeEffect | null;
  transitionDuration?: number;
  transitionId?: string | null;
  frameRate?: number;
  id?: string;
  position?: PositionPreset;
  resize?: ResizeMode;
}

Properties

Required Properties

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

Video-Specific Properties

Property	Type	Default	Description
volume	number	1	Audio volume (0-1)
speed	number	1	Playback speed multiplier
frameRate	number	Source FPS	Override frame rate
id	string	Auto-generated	Unique identifier for transitions
videoBegin	number	0	Start time in source video (seconds)
videoEnd	number	Default Video Duration	End time in source video (seconds)
videoDuration	number	Default Video Duration	Total duration of source video

Transition Properties

Property	Type	Default	Description
transition	XFadeEffect | null	null	Transition effect when entering
transitionDuration	number	1	Transition duration in seconds
transitionId	string | null	null	ID of video to transition from

Inherited Properties

Video elements inherit all properties from Image Elements except radius:

• Position & Size: x, y, width, height
• Timing: enterBegin, enterEnd, exitBegin, exitEnd
• Visual: track, opacity, angle, flipV, flipH
• Animation: enterAnimation, exitAnimation
• Effects: cropParams, chromaKey

For now, radius doesn't work with VIDEO element

Animations and Transitions Types

We support these animations and transitions from FFMPEG xfade

type XFadeEffect =
  | "fade"
  | "fadeblack"
  | "fadewhite"
  | "distance"
  | "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"
  | "zoomin";

Unsupported Transitions

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

Basic Examples

Simple Video Clip

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

Video with Position Preset

{
  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

{
  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", // Automatically positions at bottom-right, or if you want some right and bottom gap, you can specify the `x` and `y` dimensions.
  volume: 0.3,
  track: 10,
  radius: {
    tl: 10, tr: 10, bl: 10, br: 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, // Half speed (slow motion)
}

Fast Forward Effect

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

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

// First video
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/03/12/264272_large.mp4",
    resize: "cover",
    enterBegin: 0,
    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
}

Split Screen Videos

// Left video
{
    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

Video Source Timing

• videoBegin: Start point in the source video file
• videoEnd: End point in the source video file
• videoDuration: Total length of the source video file

// Play seconds 10-20 from a 60-second video
{
  videoBegin: 10,
  videoEnd: 20,
  videoDuration: 60
}

Project Timeline Timing

• enterBegin: When video starts in project timeline
• enterEnd: When entrance animation completes
• exitBegin: When exit animation starts
• exitEnd: When video completely disappears

// Video appears at 5s, fully visible by 6s, starts exiting at 25s, gone by 26s
{
  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
• zoomin - Zoom transition

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)
}

Best Practices

Quality Guidelines

1. Aspect Ratio: Maintain aspect ratio to avoid distortion
2. Bitrate: Use consistent bitrate across clips for smooth playback
3. Color Space: Use consistent color space (Rec.709 recommended)

Transition Tips

1. Timing: Ensure transition duration doesn't exceed clip overlap
2. Effect Selection: Choose transitions that match content style
3. Audio Handling: Consider audio crossfading with video transitions

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