zvid

Zvid Package

The First fully featured Node.js npm package for generating videos from JSON configurations using FFmpeg. Create dynamic videos with text overlays, images, GIFs, shapes, animations, and audio tracks programmatically.

Features

• 🎬 Video Composition: Combine multiple video clips with precise timing control
• 🖼️ Image Integration: Add static images with positioning, scaling, and filters
• 🎭 Animated GIFs: Incorporate animated GIFs seamlessly into your videos
• 📝 Text Overlays: Add styled text with custom fonts, colors, and animations
• 💬 Subtitles & Captions: Add subtitle captions with timing, styling, and positioning control
• 🎨 Vector Graphics: Include SVG shapes and custom graphics
• 🎵 Audio Mixing: Background music and sound effects with timing and volume control
• ✨ Effects & Transitions: Apply filters, animations, and smooth transitions
• ⚡ High Performance: As fast as FFmpeg.

Installation

Install the Package

npm install zvid

Install FFmpeg

FFmpeg is required for video processing.

macOS (using Homebrew):

brew install ffmpeg

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

Windows (using Chocolatey):

choco install ffmpeg

Verify Installation:

ffmpeg -version

For detailed installation instructions for all platforms, see our Installation Guide.

Quick Start

Create your first video in just a few minutes:

import zvid from 'zvid';

const project = {
  name: 'hello-world',
  resolution: 'full-hd', // 1920x1080
  duration: 5,
  visuals: [
    {
      type: 'TEXT',
      text: 'Hello, World!',
      position: 'center-center',
      enterBegin: 0,
      enterEnd: 1,
      exitBegin: 4,
      exitEnd: 5,
      style: {
        fontSize: '72px',
        fontFamily: 'Roboto',
        textAlign: 'center',
        fontWeight: 'bold',
      },
      enterAnimation: 'fade',
      exitAnimation: 'fade',
    },
  ],
};

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

console.log('Video created: ./output/hello-world.mp4');

CLI Usage (Render from JSON)

Zvid can be executed directly from the command line, making it ideal for CI/CD pipelines, automation scripts, and quick renders without writing JavaScript code.

Render a Video from a JSON File

Use npx to render a video directly from a JSON configuration file:

npx zvid render example.json

This command will:

• Load the project configuration from example.json
• Render the video using FFmpeg
• Write the output video to the directory defined in the project config

Specify an Output Directory

npx zvid render <config.json> --out [outputDir]

Examples:

# Render using the output directory defined in the JSON
npx zvid render project.json

# Render and override the output directory
npx zvid render project.json --out ./dist

Example JSON Configuration

{
  "name": "cli-example",
  "backgroundColor": "#753C73",
  "visuals": [
    {
      "type": "text",
      "text": "Welcome, Zvid.io!",
      "position": "center-center",
      "style": {
        "color": "#ffffff"
      }
    }
  ]
}

When to Use the CLI

✅ CI/CD pipelines
✅ Batch video rendering
✅ Server-side automation ✅ Quick testing
✅ No JavaScript code required

The CLI uses the same rendering engine and feature set as the JavaScript API, ensuring identical output and performance.

Why JSON instead of editors?

JSON makes video creation programmable, repeatable, and scalable. Instead of manually editing timelines, you describe your video declaratively—perfect for automation, templates, and data-driven content.

• Deterministic & versionable – Videos can be diffed, reviewed, and stored in git
• Automation-friendly – Generate thousands of videos from data or APIs
• No UI bottlenecks – Ideal for servers, CI/CD, and headless environments
• Reusable templates – Change content without re-editing timelines

Popular Resolution Presets

Choose from optimized presets for different platforms:

Social Media:

• instagram-post - 1080×1080 (square)
• instagram-reel - 1080×1920 (vertical)
• instagram-story - 1080×1920 (vertical)
• instagram-feed - 1080×1080 (square)
• youtube-short - 1080×1920 (vertical)
• youtube-video - 1920×1080 (16:9)
• tiktok - 1080×1920 (vertical)
• twitter-landscape - 1200×675 (landscape)
• twitter-portrait - 720×900 (portrait)
• twitter-square - 1200×1200 (square)
• facebook-video - 1280×720 (16:9)
• facebook-story - 1080×1920 (vertical)
• facebook-post - 1200×1200 (square)
• snapshat - 1080x1920 (vertical)

Traditional Formats:

• sd - 640×480 (4:3)
• hd - 1280×720 (16:9)
• full-hd - 1920×1080 (16:9)
• custom - Use explicit width/height

Common Use Cases

Automated Video Generation:

const project = {
  name: 'promo-video',
  resolution: 'youtube-video',
  duration: 15,
  visuals: [
    {
      type: 'IMAGE',
      src: 'https://cdn.pixabay.com/photo/2016/01/19/16/27/sale-1149344_1280.jpg',
      resize: 'cover',
      enterEnd: 0.5,
      exitBegin: 14.5,
    },
    {
      type: 'TEXT',
      html: '<div style="position:relative;width:520px;max-width:92vw;padding:22px;border-radius:18px;overflow:hidden;background:#0f172a;border:1px solid #2a3346;box-shadow:0 18px 45px rgba(0,0,0,0.35);color:#ffffff;" role="note" aria-label="Summer sale banner"><div style="position:absolute;top:-60px;right:-80px;width:240px;height:240px;background:rgba(255,214,102,0.22);filter:blur(6px);pointer-events:none;" aria-hidden="true"></div><div style="position:absolute;top:14px;left:14px;padding:6px 10px;border-radius:999px;font-size:12px;letter-spacing:0.12em;font-weight:800;background:#ff5a2a;box-shadow:0 10px 22px rgba(255,90,42,0.25);text-transform:uppercase;">HOT</div><div style="margin-top:34px;display:flex;align-items:baseline;justify-content:space-between;gap:16px;padding-left:4px;"><div style="font-size:22px;font-weight:800;letter-spacing:0.02em;opacity:0.95;">Summer Sale</div><div style="font-size:34px;font-weight:900;line-height:1;color:#ffd666;white-space:nowrap;">50% <span style="font-size:20px;font-weight:900;color:#ffffff;opacity:0.95;margin-left:6px;">Off!</span></div></div></div>',
      position: 'center-center',
      enterEnd: 1,
      exitBegin: 14,
      style: {
        fontSize: '64px',
        color: '#ffffff',
        fontWeight: 'bold',
      },
      enterAnimation: 'slidedown',
    },
  ],
  audios: [
    {
      src: 'https://cdn.pixabay.com/audio/2025/03/19/audio_56ae1dae5f.mp3',
      volume: 0.5,
    },
  ],
};

Visual Element Types

The package supports various visual element types:

• TEXT - Text and Styled HTML overlays with custom fonts and colors
• IMAGE - Static images with positioning and effects
• VIDEO - Video clips with timing control
• GIF - Animated GIFs
• SVG - Vector graphics and shapes

Audio Elements

The package supports audio elements for music and voice overs.

Subtitles/Captions

The package support the ability to add styled subtitles and captions with different modes like karaoke, one-word, and progressive.

Animation and transition Effects

Apply smooth animations to your elements:

Entrance Animations: 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, hlwind, hrwind

Exit Animations: Same options available for exit animations

Transition between videos Same options available for transition between videos

You can visually view these animations on the official FFmpeg Xfade website

Requirements

• Node.js: Version 18.0 or higher
• FFmpeg: Must be installed and available in your system PATH

Documentation

For comprehensive guides and API documentation:

• 📖 Full Documentation
• 🚀 Quick Start Guide
• 📚 API Reference
• 💡 Examples

License

Licensed under BSL 1.1 — see LICENSE

Support & Community

• 📖 Documentation
• 🐛 Issue Tracker
• 📦️ npm Package

Contributing

Contributions are welcome!

Keywords

npm ffmpeg nodejs video json-to-video json2video object-to-video rendering video-editing multimedia automation programmatic-video video-generation video-api video-rendering