Quick Start

Get up and running with the Zvid Package in just a few minutes! This guide will walk you through creating your first video.

Your First Video

Let's create a simple video with text overlay to demonstrate the basic workflow.

Step 1: Create a New Project

Create a new directory and initialize your project:

mkdir my-video-project
cd my-video-project
npm init -y
npm install video-rendering

Step 2: Create Your First Script

Create a file called create-video.js:

import renderVideo from "video-rendering";

// Define your video project
const project = {
  name: "hello-world",
  resolution: "hd", // 1280x720 - you can also use "full-hd", "squared", etc.
  duration: 5,
  visuals: [
    {
      type: "TEXT",
      text: "Hello, World!",
      position: "center-center",
      // enterStart: 0, // The default enterBegin is 0
      enterEnd: 1,
      exitBegin: 4,
      // exitEnd: 5, // The exitEnd is the project duration = 5
      style: {
        fontSize: "72px",
        fontFamily: "Roboto",
        textAlign: "center",
        fontWeight: "bold",
      },
      enterAnimation: "fade",
      exitAnimation: "fade",
    },
  ],
};

// Create the video
async function createVideo() {
  try {
    console.log("Starting video creation...");

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

    console.log("Video created successfully! Check ./output/hello-world.mp4");
  } catch (error) {
    console.error("Error creating video:", error);
  }
}

createVideo();

Step 3: Run Your Script

node create-video.js

You should see progress updates and then find your video at ./output/hello-world.mp4!

Understanding the Project Structure

Let's break down the key components of a video project:

Project Configuration

const project = {
  name: "hello-world", // Output filename (without extension)
  resolution: "hd", // Preset resolution (overrides width/height)
  duration: 5, // Total duration in seconds
  visuals: [], // Array of visual elements
  audios: [], // Array of audio elements
};

Resolution Presets

Instead of manually setting width and height, you can use preset resolutions optimized for different platforms:

// Social Media Examples
const instagramPost = {
  name: "insta-post",
  resolution: "instagram-post", // 1080×1080 square
  duration: 15,
  visuals: [
    /* ... */
  ],
};

const youtubeShort = {
  name: "yt-short",
  resolution: "youtube-short", // 1080×1920 vertical
  duration: 60,
  visuals: [
    /* ... */
  ],
};

const tiktokVideo = {
  name: "tiktok-vid",
  resolution: "tiktok", // 1080×1920 vertical
  duration: 30,
  visuals: [
    /* ... */
  ],
};

// Traditional Video Formats
const hdVideo = {
  name: "hd-content",
  resolution: "hd", // 1280×720
  duration: 120,
  visuals: [
    /* ... */
  ],
};

const fullHdVideo = {
  name: "fullhd-content",
  resolution: "full-hd", // 1920×1080
  duration: 180,
  visuals: [
    /* ... */
  ],
};

// Custom dimensions (when you need specific sizes)
const customVideo = {
  name: "custom-content",
  resolution: "custom", // or omit resolution property
  width: 1600,
  height: 900,
  duration: 90,
  visuals: [
    /* ... */
  ],
};

Popular Resolution Presets:

• sd - 640×480 (4:3)
• hd - 1280×720 (16:9)
• full-hd - 1920×1080 (16:9)
• squared - 1080×1080 (1:1)
• youtube-short - 1080×1920 (9:16)
• youtube-video - 1920×1080 (16:9)
• tiktok - 1080×1920 (9:16)
• instagram-reel - 1080×1920 (9:16)
• instagram-post - 1080×1080 (1:1)
• instagram-story - 1080×1920 (9:16)
• instagram-feed - 1080×1080 (1:1)
• twitter-landscape - 1200×675 (16:9)
• twitter-portrait - 1080×1350 (4:5)
• twitter-square - 1080×1080 (1:1)
• facebook-video - 1080×1920 (9:16)
• facebook-story - 1080×1920 (9:16)
• facebook-post - 1080×1080 (1:1)
• snapshat - 1080×1920 (9:16)
• custom - Use explicit width/height

Visual Elements

Each visual element has timing and positioning properties:

{
  type: "TEXT",              // Element type (TEXT, IMAGE, VIDEO, GIF, SVG)
  text: "Text Here."

  // Positioning
  x: 660,                    // X position (center for 1920px width)
  y: 480,                    // Y position (center for 1080px height)
  width: 600,                // Element width
  height: 120,               // Element height

  // Timing
  enterStart: 0, // The default enterBegin is 0
  enterEnd: 1,               // When element is fully visible
  exitBegin: 4,              // When element starts disappearing
  exitEnd: 5, // The default exitEnd is the project duration = 5

  // Effects
  enterAnimation: "fade",   // Entrance animation
  exitAnimation: "fade"    // Exit animation
}

Adding More Elements

Let's enhance our video with an image and background shape:

const enhancedProject = {
  name: "enhanced-video",
  duration: 8,
  backgroundColor: "#000000",
  visuals: [
    // Background shape
    {
      type: "SVG",
      width: 1280,
      height: 720,
      enterEnd: 0.5,
      exitBegin: 7.5,
      svg: '<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="0" width="1280" height="720" fill="#ffcb00"/></svg>',
      opacity: 0.3,
    },

    // Main title
    {
      type: "TEXT",
      text: "Welcome to Zvid",
      position: "center-center",
      enterBegin: 1,
      enterEnd: 2,
      exitBegin: 6,
      exitEnd: 7,
      track: 2,
      style: {
        fontSize: "64px",
        color: "#ffffff",
        textAlign: "center",
        fontWeight: "bold",
        letterSpacing: "2px",
      },
      enterAnimation: "slidedown",
      exitAnimation: "slideup",
    },

    // Subtitle
    {
      type: "TEXT",
      html: "<span>Create amazing videos with code</span>",
      x: 420,
      y: 460,
      enterBegin: 2.5,
      enterEnd: 3.5,
      exitBegin: 6,
      exitEnd: 7,
      track: 2,
      style: {
        fontSize: "24px",
        color: "#e5e7eb",
        textAlign: "center",
        isItalic: true,
        letterSpacing: "1px",
      },
      enterAnimation: "fade",
      exitAnimation: "fade",
    },
  ],
};

Working with Images

Add an image to your video:

// Add this to your visuals array
{
    type: "IMAGE",
    src: "https://cdn.pixabay.com/photo/2025/07/12/12/54/scarlet-robin-9710532_960_720.jpg",
    resize: "cover",
    enterBegin: 0,
    enterEnd: 1,
    exitBegin: 7,
    exitEnd: 8,
    enterAnimation: "hrslice",
    exitAnimation: "hlslice"
}

Adding Background Music

Include audio in your video:

const projectWithAudio = {
  // ... other project properties
  audios: [
    {
      src: "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
      volume: 0.5, // Volume (0-1)
    },
  ],
};

Common Patterns

Centering Elements

Keep in mind default video resolution is 1280x720:

• Center X: (projectWidth / 2) - ( itemWidth / 2 )
• Center Y: (projectHeight / 2) - ( itemHeight / 2 )

Timing Patterns

// Element appears immediately and stays until end
enterBegin: 0,
enterEnd: 0,
exitBegin: {videoDuration},
exitEnd: {videoDuration},

// Element fades in over 1 second, stays, then fades out
enterBegin: 2,
enterEnd: 3,
exitBegin: 7,
exitEnd: 8,

// Quick flash effect
enterBegin: 5,
enterEnd: 5.2,
exitBegin: 5.8,
exitEnd: 6,

Error Handling

Always wrap your rendering in try-catch:

async function createVideo() {
  try {
    await renderVideo(project, "./output", (progress) => {
      console.log(`Progress: ${progress}%`);
    });
    console.log("Success!");
  } catch (error) {
    console.error("Error:", error.message);

    // Handle specific error types
    if (error.code === "VR_CONFIG_004") {
      console.log("Check your project configuration");
    } else if (error.code === "VR_MEDIA_100") {
      console.log("FFmpeg processing failed");
    }
  }
}

Next Steps

Now that you've created your first video, explore more advanced features:

1. API Reference - Complete documentation of all options
2. Examples - More complex examples
3. FAQ - Common questions and solutions

Tips for Success

• Start Simple: Begin with basic text and images before adding complex effects
• Test Frequently: Create short test videos to verify your configuration
• Use Progress Callbacks: Monitor rendering progress for long videos
• Optimize Assets: Use appropriate image sizes and formats for better performance
• Plan Your Timeline: Sketch out timing before coding complex sequences

Happy video creating! 🎬