Skip to main content

Frequently Asked Questions

Common questions and solutions for the Zvid Package.

Installation & Setup​

Q: FFmpeg not found error​

Error: FFmpeg not found in PATH

Solution:

  1. Ensure FFmpeg is properly installed on your system
  2. Verify it's accessible from command line: ffmpeg -version
  3. Add FFmpeg to your system PATH if needed
  4. Restart your terminal/IDE after installation

Platform-specific solutions:

Windows:

# Using Chocolatey
choco install ffmpeg

# Or download and add to PATH manually

macOS:

brew install ffmpeg

Linux:

sudo apt install ffmpeg  # Ubuntu/Debian
sudo yum install ffmpeg  # CentOS/RHEL

Q: Permission denied errors​

Error: EACCES: permission denied

Solution:

  1. Ensure write permissions to output directory
  2. On Linux/macOS, check directory ownership
  3. Avoid running with sudo unless necessary
  4. Use a directory you have write access to

Project Configuration​

Q: Video dimensions and aspect ratios​

Q: What video dimensions should I use?

A: Use resolution presets for common formats, or specify custom dimensions:

Using Resolution Presets (Recommended):

// Social media formats
const project = {
  resolution: "instagram-post", // 1080×1080 (Square)
  // resolution: "youtube-short", // 1080×1920 (Vertical)
  // resolution: "tiktok", // 1080×1920 (Vertical)
  // resolution: "full-hd", // 1920×1080 (Landscape)
};

Manual Dimensions:

// Custom dimensions
const project = {
  resolution: "custom", // or omit resolution property
  width: 1920,
  height: 1080,
};

Popular Resolution Presets:

  • full-hd - 1920×1080 (16:9) - Most common
  • hd - 1280×720 (16:9) - Good for smaller files
  • squared - 1080×1080 (1:1) - Square format
  • youtube-short - 1080×1920 (9:16) - YouTube Shorts
  • tiktok - 1080×1920 (9:16) - TikTok videos
  • instagram-post - 1080×1080 (1:1) - Instagram posts
  • instagram-story - 1080×1920 (9:16) - Instagram Stories

Q: Resolution presets vs custom dimensions​

Q: When should I use resolution presets vs custom dimensions?

A: Use resolution presets for:

  • Social media content - Optimized for platform requirements
  • Standard formats - HD, Full HD, etc.
  • Quick setup - No need to remember exact dimensions
  • Consistency - Ensures correct aspect ratios

Use custom dimensions for:

  • Unique requirements - Non-standard sizes
  • Specific client needs - Custom aspect ratios
  • Legacy formats - Older or specialized dimensions
// Platform-optimized (recommended)
const socialVideo = {
  resolution: "instagram-reel", // Perfect for Instagram
  duration: 30,
  visuals: [
    /* ... */
  ],
};

// Custom requirements
const customVideo = {
  resolution: "custom",
  width: 1600, // Custom width
  height: 900, // Custom height (16:9 ratio)
  duration: 30,
  visuals: [
    /* ... */
  ],
};

Q: Frame rate selection​

Q: What frame rate should I use?

A: Frame rate guidelines:

  • 30 fps - Standard for most content
  • 60 fps - Smooth motion, gaming content
  • 24 fps - Cinematic look
  • 25 fps - PAL standard (Europe)

Higher frame rates create larger files and consume more time for processing but provide smoother motion.

Q: Output format options​

Q: Which output format should I choose?

A: Format recommendations:

  • MP4 - Best compatibility, recommended for most uses
  • WebM - Good for web, smaller file sizes
  • AVI - Older format, larger files
  • MOV - Good quality, Apple ecosystem
const project = {
  outputFormat: "mp4", // Recommended
  // outputFormat: "webm", // For web
  // outputFormat: "mov", // For Apple
};

Element Positioning​

Q: Centering elements​

Q: How do I center elements in my video?

A: You now have two options for centering elements:

  1. Center both horizontally and vertically
    Use the position: "center-center" option to automatically center an element in the middle of the video:

    {
      position: "center-center",
      width: 400,
      height: 100,
      // Element will be centered horizontally & vertically
    }

  2. Center only horizontally (or vertically) using x and y

    If you want to center only along one axis, you can manually calculate x or y as follows:

    For horizontal centering: x = project.width / 2 - item.width / 2

    For vertical centering: y = project.height / 2 - item.height / 2

    {
      x: project.width / 2 - item.width / 2,  // center horizontally
      y: 100,                                 // fixed vertical position
      width: 400,
      height: 100
    }

Q: Element sizing​

Q: How do I size elements properly?

A: Sizing guidelines:

  • You can either:
    • Use the resize attribute, which will override width and height if they exist
      • "contain": Scales the element to fit inside the container while preserving its aspect ratio
      • "cover": Scales the element to cover the entire container while preserving its aspect ratio (may crop the content)
    • Or set width and height manually for full control over dimensions
// Option 1: Manual sizing
{
  width: 800,
  height: 100,
}

// Option 2: Automatic sizing using resize
{
  resize: "contain"  // or "cover"
}

Timing and Animation​

Q: Animation timing​

Q: How do timing properties work?

A: Four timing properties control element lifecycle:

{
  enterBegin: 2,   // Starts appearing at 2 seconds
  enterEnd: 3,     // Fully visible at 3 seconds
  exitBegin: 7,    // Starts disappearing at 7 seconds
  exitEnd: 8,      // Completely gone at 8 seconds
}

// Element is:
// - Invisible: 0-2 seconds
// - Appearing: 2-3 seconds (1 second transition)
// - Visible: 3-7 seconds (4 seconds visible)
// - Disappearing: 7-8 seconds (1 second transition)
// - Invisible: 8+ seconds

Q: Smooth animations​

Q: How do I create smooth animations between elements?

A: Overlap timing for smooth animations:

// First element
{
  enterBegin: 0, enterEnd: 1,
  exitBegin: 4, exitEnd: 5,
  enterAnimation: "fade",
  exitAnimation: "fade"
}

// Second element (overlaps with first)
{
  enterBegin: 3, enterEnd: 4,  // Starts appearing before first exits
  exitBegin: 7, exitEnd: 8,
  enterAnimation: "slideup",
  exitAnimation: "slidedown"
}

Q: Animation effects not working​

Q: My animations aren't showing up

A: Check these common issues:

  1. Animation names are case-sensitive
  2. Ensure timing allows for animation duration
  3. Verify element is on correct track
  4. Ensuring the timing coordinations
// Correct animation names
enterAnimation: "fade",     // ✓ Correct
enterAnimation: "FadeIn",     // ✗ Wrong case
enterAnimation: "fade-in",    // ✗ Wrong format

// Ensure timing allows animation
enterBegin: 0,
enterEnd: 1,    // 1 second for animation - good
// enterEnd: 0.1,  // 0.1 second - too fast to see

Media Files​

Q: Supported file formats​

Q: What media formats are supported?

A: Supported formats: All FFMPEG supported formats are accepted.

For example:

Images:

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • GIF (.gif) - static only for IMAGE type
  • SVG (.svg) - for SVG type

Videos:

  • MP4 (.mp4) - Recommended
  • AVI (.avi)
  • MOV (.mov)
  • WebM (.webm)
  • MKV (.mkv)

Audio:

  • MP3 (.mp3) - Recommended
  • WAV (.wav)
  • AAC (.aac)
  • OGG (.ogg)

Q: File path issues​

Q: My files aren't loading

A: File path troubleshooting:

  1. Use URLs
  2. If you want to use local files, you need to launch a server and use absolute paths or paths relative to the script location.
  3. Check file exists and is accessible
  4. Verify file permissions
  5. Use forward slashes or escape backslashes
// Good file paths
src: "./assets/image.jpg",           //  Absolute path
src: "C:\\Users\\Name\\image.jpg",   // Windows (escaped)
src: "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg", // URL

// Problematic paths
src: "C:\Users\Name\image.jpg",      // Unescaped backslashes
src: "../../../image.jpg",           // Too many levels up

Q: Large file handling​

Q: How do I handle large media files?

A: Optimization strategies:

  1. Resize images to video dimensions
  2. Compress videos before using
  3. Use appropriate quality settings
  4. Consider file size vs quality trade-offs
// For 1920x1080 video, use images around that size
{
  type: "IMAGE",
  src: "large-image.jpg",  // 4K image
  width: 1920,             // Scaled down
  height: 1080,
}

Performance​

Q: Slow rendering​

Q: Video rendering is very slow

A: Performance optimization:

  1. Reduce video resolution for testing
  2. Use shorter durations during development
  3. Optimize source media files
  4. Close other applications
  5. Ensure sufficient RAM
  6. For now GIFs are the most slow processing elements, I'm working on optimizing it.
// Fast rendering for testing
const testProject = {
  width: 640, // Lower resolution
  height: 360,
  duration: 5, // Shorter duration
  frameRate: 24, // Lower frame rate
  // ... rest of config
};

Q: Progress tracking​

Q: How do I track rendering progress?

A: Use the progress callback:

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

  // Update UI progress bar
  updateProgressBar(progress);
});

Text and Fonts​

Q: Font not displaying​

Q: My custom font isn't showing

A: Font troubleshooting:

  1. For now, only google fonts working.
  2. Use exact font family name are provided from google fonts
style: {
  fontFamily: "Poppins",              // ✓ Google font
}

Q: Getting help​

Q: Where can I get more help?

A: Support resources:

  1. Check this FAQ first
  2. Search GitHub Issues
  3. Create new issue with:
    • Error message
    • System information
    • Minimal reproduction code
    • Expected vs actual behavior
  4. Join community discussions

Still have questions? Check our GitHub Issues or start a Discussion.