Skip to main content

JSON Structure Overview

Complete reference for the Zvid JSON video configuration, including all object structures, types, and configuration options.

Main JSON Structure​

A Zvid project is defined as a plain JSON object.

Example:

{
  "name": "my-video",
  "duration": 30,
  "visuals": [],
  "audios": []
}

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
namestringNo'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:

{
  "name": "my-video",
  "duration": 30,
  "visuals": [],
  "audios": []
}

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​

{
  "name": "instagram-content",
  "resolution": "instagram-post",
  "duration": 15,
  "visuals": []
}
{
  "name": "custom-content",
  "resolution": "custom",
  "width": 1600,
  "height": 900,
  "duration": 20,
  "visuals": []
}
{
  "name": "override-example",
  "width": 1920,
  "height": 1080,
  "resolution": "squared",
  "duration": 10,
  "visuals": []
}

Platform-Specific Examples​

{
  "name": "my-youtube-short",
  "resolution": "youtube-short",
  "duration": 60,
  "visuals": []
}
{
  "name": "my-tiktok",
  "resolution": "tiktok",
  "duration": 30,
  "visuals": []
}
{
  "name": "twitter-promo",
  "resolution": "twitter-landscape",
  "duration": 45,
  "visuals": []
}

Position and Resize Properties​

The Zvid JSON format 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-center"Position element at top-centerx = (projectWidth - itemWidth) / 2, y = 0
"top-right"Position element at top-right cornerx = projectWidth - itemWidth, y = 0
"center-left"Position element at center-leftx = 0, y = (projectHeight - itemHeight) / 2
"center-center"Position element at center of videox = (projectWidth - itemWidth) / 2, y = (projectHeight - itemHeight) / 2
"center-right"Position element at center-rightx = projectWidth - itemWidth, y = (projectHeight - itemHeight) / 2
"bottom-left"Position element at bottom-left cornerx = 0, y = projectHeight - itemHeight
"bottom-center"Position element at bottom-centerx = (projectWidth - itemWidth) / 2, y = projectHeight - itemHeight
"bottom-right"Position element at bottom-right cornerx = projectWidth - itemWidth, y = projectHeight - itemHeight
"custom"Use explicit x and y values (default)Uses provided x and y coordinates

Position Examples:

{
  "type": "IMAGE",
  "src": "https://example.com/image.jpg",
  "width": 400,
  "height": 300,
  "position": "center-center"
}
{
  "type": "TEXT",
  "text": "Watermark",
  "width": 200,
  "height": 50,
  "position": "top-right",
  "style": {
    "fontSize": "24px",
    "color": "#ffffff"
  }
}
{
  "type": "IMAGE",
  "src": "https://example.com/logo.png",
  "x": 100,
  "y": 50,
  "position": "custom"
}

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:

{
  "type": "IMAGE",
  "src": "https://example.com/photo.jpg",
  "width": 400,
  "height": 300,
  "resize": "contain"
}
{
  "type": "VIDEO",
  "src": "https://example.com/video.mp4",
  "width": 400,
  "height": 300,
  "resize": "cover"
}
{
  "type": "IMAGE",
  "src": "https://example.com/background.jpg",
  "width": 1920,
  "height": 1080,
  "position": "center-center",
  "resize": "cover"
}

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 adds a zoom effect at the center of the item.

zoom: true;

Zoom Examples:

{
  "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. It works alongside position.

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:

{
  "type": "TEXT",
  "text": "Headline",
  "anchor": "center-center",
  "x": 640,
  "y": 50
}

Element Types​

The Zvid JSON format 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 format 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)
name'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"top-left"Anchor point for positioning
resizenullResize mode for media items
zoomfalseAdding zoom effect
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
}

Basic Audio Element​

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

Supported Formats​

Video Formats​

  • Input: Supports FFmpeg-compatible video formats (for example: MP4, AVI, MOV, WebM, MKV)
  • Output: Supports FFmpeg-compatible video formats (for example: MP4, AVI, MOV, WebM, MKV)

Image Formats​

  • Supported: All browser-supported image formats

Audio Formats​

  • Supported: Supports FFmpeg-compatible audio formats (for example: 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: FFmpeg optimization depends on the rendering environment

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​

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