Skip to main content

API Reference Overview

Complete reference for the Zvid Package API, including all functions, types, and configuration options.

Main Function​

renderVideo(project, outputFolder, progressCallback?)​

The primary function for rendering videos from JSON configurations.

Signature:

function renderVideo(
  project: Project,
  outputFolder: string,
  progressCallback?: (percentage: number) => void,
): Promise<void>;

Parameters:

ParameterTypeRequiredDescription
projectProjectYesVideo project configuration object
outputFolderstringYesDirectory path where the output video will be saved
progressCallbackfunctionNoCallback function to track rendering progress

Returns: Promise<void> - Resolves when rendering is complete

Example:

import renderVideo from "video-rendering";

await renderVideo(project, "./output", (progress) => {
  console.log(`Progress: ${progress}%`);
});

Project Configuration​

Project Object​

The main configuration object that defines your video.

interface Project {
  name?: string;
  width?: number;
  height?: number;
  duration?: number;
  frameRate?: number;
  backgroundColor?: string;
  outputFormat?: string;
  resolution?: ResolutionPreset;
  visuals?: Items[];
  audios?: AudioItem[];
  subtitle?: Subtitle;
}

Properties:

PropertyTypeRequiredDefaultDescription
namestringNoDate.now() + 'unnamed'Output filename (without extension)
widthnumberNo1280Video width in pixels (overridden by resolution)
heightnumberNo720Video height in pixels (overridden by resolution)
resolutionResolutionPresetNo"custom"Preset resolution that overrides width/height
durationnumberNo10Total video duration in seconds
frameRatenumberNo30Frames per second (e.g., 30, 60)
backgroundColorstringNo"#ffffff"Background color in hex format (#000000)
outputFormatstringNo"mp4"Output video format
visualsItems[]No[]Array of visual elements
audiosAudioItem[]No[]Array of audio elements
subtitleSubtitleNonullCaption and subtitle configuration

Example:

const project = {
  name: "my-video",
  duration: 30,
  visuals: [
    // ... visual elements
  ],
  audios: [
    // ... audio elements
  ],
};

Resolution Presets​

The resolution property allows you to use predefined video dimensions optimized for different platforms and use cases. When specified, it overrides the width and height properties.

Available Presets​

PresetDimensionsAspect RatioUse Case
sd640×4804:3Standard definition
hd1280×72016:9HD content
full-hd1920×108016:9Full HD content
squared1080×10801:1Square format
youtube-short1080×19209:16YouTube Shorts
youtube-video1920×108016:9YouTube videos
tiktok1080×19209:16TikTok videos
instagram-reel1080×19209:16Instagram Reels
instagram-post1080×10801:1Instagram posts
instagram-story1080×19209:16Instagram Stories
instagram-feed1080×10801:1Instagram feed posts
twitter-landscape1200×67516:9Twitter landscape videos
twitter-portrait1080×13504:5Twitter portrait videos
twitter-square1080×10801:1Twitter square videos
facebook-video1080×19209:16Facebook videos
facebook-story1080×19209:16Facebook Stories
facebook-post1080×10801:1Facebook posts
snapshat1080×19209:16Snapchat content
customUses w×hVariableCustom dimensions (default)

Resolution Examples​

// Using preset resolution
const instagramPost = {
  name: "instagram-content",
  resolution: "instagram-post", // 1080×1080
  duration: 15,
  visuals: [
    /* ... */
  ],
};

// Using custom dimensions
const customVideo = {
  name: "custom-content",
  resolution: "custom", // or omit resolution property
  width: 1600,
  height: 900,
  duration: 20,
  visuals: [
    /* ... */
  ],
};

// Resolution overrides width/height
const overrideExample = {
  name: "override-example",
  width: 1920, // This will be ignored
  height: 1080, // This will be ignored
  resolution: "squared", // Final dimensions: 1080×1080
  duration: 10,
  visuals: [
    /* ... */
  ],
};

Platform-Specific Examples​

// YouTube Short
const youtubeShort = {
  name: "my-youtube-short",
  resolution: "youtube-short",
  duration: 60,
  visuals: [
    /* ... */
  ],
};

// TikTok Video
const tiktokVideo = {
  name: "my-tiktok",
  resolution: "tiktok",
  duration: 30,
  visuals: [
    /* ... */
  ],
};

// Twitter Landscape
const twitterVideo = {
  name: "twitter-promo",
  resolution: "twitter-landscape",
  duration: 45,
  visuals: [
    /* ... */
  ],
};

Position and Resize Properties​

The Zvido Package includes two powerful properties that simplify element positioning and sizing:

Position Property​

The position property provides preset positioning options that override the x and y coordinates for any visual element.

Available Position Presets:

PresetDescriptionCoordinates
"top-left"Position element at top-left cornerx=0, y=0
"top-right"Position element at top-right cornerx=projectWidth - itemWidth, y=0
"bottom-right"Position element at bottom-right cornerx=projectWidth - itemWidth, y=projectHeight - itemHeight
"bottom-left"Position element at bottom-left cornerx=0, y=projectHeight - itemHeight
"center-center"Position element at center of videox=(projectWidth - itemWidth)/2, y=(projectHeight - itemHeight)/2
"custom"Use explicit x and y values (default)Uses provided x and y coordinates

Position Examples:

// Center an image in the video
{
  type: "IMAGE",
  src: "https://example.com/image.jpg",
  width: 400,
  height: 300,
  position: "center-center"
}

// Position text at top-right corner
{
  type: "TEXT",
  text: "Watermark",
  width: 200,
  height: 50,
  position: "top-right",
  style: { fontSize: "24px", color: "#ffffff" }
}

// Use custom positioning (same as not specifying position)
{
  type: "IMAGE",
  src: "https://example.com/logo.png",
  x: 100,
  y: 50,
  position: "custom" // or omit position property
}

Resize Property​

The resize property provides CSS-like resizing behavior for image, video, and GIF elements, overriding the width and height properties while maintaining aspect ratio.

Available Resize Modes:

ModeDescriptionBehavior
"contain"Scale to fit within bounds (letterboxing)Entire media visible, may have empty space
"cover"Scale to fill bounds (cropping)Fills entire area, may crop parts of media

Resize Examples:

// Fit image within 400x300 bounds while maintaining aspect ratio
{
  type: "IMAGE",
  src: "https://example.com/photo.jpg",
  width: 400,   // Target width
  height: 300,  // Target height
  resize: "contain" // Will scale to fit within 400x300
}

// Fill 400x300 area completely, cropping if necessary
{
  type: "VIDEO",
  src: "https://example.com/video.mp4",
  width: 400,   // Target width
  height: 300,  // Target height
  resize: "cover" // Will scale to fill 400x300, may crop
}

// Combine position and resize
{
  type: "IMAGE",
  src: "https://example.com/background.jpg",
  width: 1920,  // Full video width
  height: 1080, // Full video height
  position: "center-center",
  resize: "cover" // Fill entire background
}

Resize Behavior Details:

  • Contain: Similar to CSS object-fit: contain

    • Scales media to fit entirely within the specified dimensions
    • Maintains original aspect ratio
    • May result in letterboxing (empty space) if aspect ratios don't match

  • Cover: Similar to CSS object-fit: cover

    • Scales media to completely fill the specified dimensions
    • Maintains original aspect ratio
    • May crop parts of the media if aspect ratios don't match

Zoom Property​

The zoom property adds zoom effects to image, video, and GIF elements. It can be used to create dynamic zoom-in effects for videos or static zoom effects for images.

Zoom Configuration:

The zoom property accepts a boolean value, which would add a zoom effect at the center of the item.

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

Zoom Examples:

// Simple zoom with defaults (2x zoom from center)
{
  type: "IMAGE",
  src: "https://example.com/photo.jpg",
  width: 400,
  height: 300,
  zoom: true
}

Anchor Property​

The anchor property sets the element's anchor point used for positioning, scaling and rotation. It works alongside position/x/y and affects how transforms are applied relative to the item's bounds.

export type Anchor =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";
  • Default: center-center
  • Applies to: IMAGE, TEXT, SVG, GIF
  • Description: Changes the origin point for position, rotation (angle) and zoom/scale operations. For example, top-left anchors transforms at the element's top-left corner, while center-center uses the element center.

Anchor Examples:

// Anchor at top-center (useful for titles that expand downward)
{
  type: "TEXT",
  text: "Headline",
  anchor: "center-center",
  x: 640,
  y: 50
}

Element Types​

The Zvid Package supports various element types for creating rich video content:

Visual Elements​

Audio Elements​

Captions & Subtitles​

  • Subtitle - Add synchronized captions with word-level timing

Effects and Animations​

Configuration Defaults​

The package is designed to be flexible, with many optional properties that have sensible default values.

Project Defaults​

PropertyDefault ValueDescription
width1280Video width in pixels
height720Video height in pixels
duration10Duration in seconds
frameRate30Frames per second
backgroundColor"#ffffff"Background color (hex)
outputFormat"mp4"Output format (e.g., mp4, mov)
nameDate.now() + 'unnamed'Output file name (without extension)

Visual Item Defaults​

These defaults apply to all visual elements (IMAGE, VIDEO, TEXT, GIF, SVG).

PropertyDefault ValueDescription
x0Horizontal position (pixels)
y0Vertical position (pixels)
position"custom"Position preset (overrides x, y)
anchor"center-center"Anchor point for transforms and positioning
resizenullResize mode for media items
zoomnullZoom effect configuration
enterBegin0Start time of enter animation (seconds)
enterEnd0End time of enter animation (seconds)
exitBeginproject.durationStart time of exit animation (seconds)
exitEndproject.durationEnd time of exit animation (seconds)
opacity1Opacity (0 to 1)
angle0Rotation angle (degrees)
flipVfalseFlip Vertically
flipHfalseFlip Horizontal
track0Composition track index
enterAnimationnullEnter animation name (e.g., "fade")
exitAnimationnullExit animation name (e.g., "fade")

Video Item Defaults​

PropertyDefault ValueDescription
videoBegin0Start time within the source video
videoEndsource durationEnd time within the source video
volume1Audio volume (0 to 1)
speed1Playback speed

Audio Item Defaults​

PropertyDefault ValueDescription
audioBegin0Start time within the source audio
audioEndsource durationEnd time within the source audio
volume1Audio volume (0 to 1)
speed1Playback speed

Quick Examples​

Basic Text Element​

{
  type: "TEXT",
  text: "Hello World",
  x: 640, y: 360,
  style: {
    fontSize: "48px",
    color: "#000000",
    textAlign: "center"
  }
}

Basic Image Element​

{
  type: "IMAGE",
  src: "https://images.pexels.com/photos/32972375/pexels-photo-32972375.jpeg",
  x: 100, y: 100,
  width: 607, height: 910
}

Basic Video Element​

{
  type: "VIDEO",
  src: "https://videos.pexels.com/video-files/1409899/1409899-sd_640_360_25fps.mp4",
  videoEnd: 10, // just take the first 10 seconds of the video.
}

Basic Audio Element​

{
  src: "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
  volume: 0.5
}

Error Handling​

The package provides structured error handling with specific error types:

Error Categories​

  • Configuration Errors (001-099) - Project setup and validation issues
  • Media Processing Errors (100-199) - FFmpeg and encoding problems
  • Resource Errors (200-299) - File access and network issues
  • Validation Errors (300-399) - Data validation failures
  • Rendering Errors (400-499) - Canvas and browser rendering issues
  • Unexpected Errors (500-599) - System and third-party errors

Error Handling Example​

try {
  await renderVideo(project, "./output");
} catch (error) {
  console.error("Error code:", error.code);
  console.error("Error message:", error.message);

  switch (error.code) {
    case "VR_CONFIG_001":
      console.log("Missing duration in project configuration.");
      break;
    case "VR_MEDIA_100":
      console.log("FFmpeg processing failed.");
      break;
    case "VR_RESOURCE_200":
      console.log("File not found. Check file paths and availability.");
      break;
    default:
      console.log("Unexpected error occurred.");
  }
}

Supported Formats​

Video Formats​

  • Input: It supports all FFMPEG Video formats (ex: MP4, AVI, MOV, WebM, MKV)
  • Output: it supports all FFMPEG Video formats (ex: MP4, AVI, MOV, WebM, MKV)

Image Formats​

  • Supported: All browser supported image formats

Audio Formats​

  • Supported: It supports all FFMPEG Audio formats (ex: MP3, WAV, AAC, OGG)

Performance Considerations​

Optimization Tips​

  1. Image Sizes: Use appropriate image dimensions to avoid unnecessary scaling
  2. Video Codecs: Use H.264 for best compatibility and performance
  3. Audio Quality: Balance quality vs file size for audio tracks
  4. Memory Usage: Monitor memory usage for long or high-resolution videos
  5. Parallel Processing: The package handles FFmpeg optimization automatically

Resource Limits​

  • Maximum Resolution: Limited by available system memory
  • Maximum Duration: No hard limit, but longer videos require more processing time
  • Concurrent Elements: No limit on number of visual elements per track

Detailed Documentation​

For comprehensive information about each element type and feature:

Element Types​

Captions & Subtitles​

  • Subtitle - Add synchronized captions with word-level timing

Effects and Animations​

Next Steps​

  • Quick Start - Get started with your first video
  • Examples - Practical implementation examples
  • FAQ - Common questions and troubleshooting