Skip to main content

Installation

This guide will walk you through installing the Zvid Package and its dependencies.

Installing the Package​

Using npm​

npm install zvid

Using yarn​

yarn add zvid

Using pnpm​

pnpm add zvid

Installing FFmpeg​

FFmpeg is required for video processing. Choose the installation method for your operating system:

Windows​

# Install Chocolatey if you haven't already
# Then install FFmpeg
choco install ffmpeg

Option 2: Manual Installation​

  1. Download FFmpeg from https://ffmpeg.org/download.html
  2. Extract the archive to a folder (e.g., C:\ffmpeg)
  3. Add the bin folder to your system PATH:
    • Open System Properties → Advanced → Environment Variables
    • Edit the Path variable and add C:\ffmpeg\bin
    • Restart your command prompt

macOS​

# Install Homebrew if you haven't already
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install FFmpeg
brew install ffmpeg

Using MacPorts​

sudo port install ffmpeg

Linux​

Ubuntu/Debian​

sudo apt update
sudo apt install ffmpeg

CentOS/RHEL/Fedora​

# CentOS/RHEL
sudo yum install ffmpeg

# Fedora
sudo dnf install ffmpeg

Arch Linux​

sudo pacman -S ffmpeg

Verifying Installation​

After installation, verify that everything is working correctly:

1. Check Node.js Version​

node --version
# Should output v18.0.0 or higher

2. Check FFmpeg Installation​

ffmpeg -version
# Should output FFmpeg version information

3. Test the Package​

Create a simple test file to verify the package works:

// test.js
import renderVideo from "zvid";

console.log("Zvid Package installed successfully!");

// Simple test project
const testProject = {
  name: "test-video",
  width: 640,
  height: 480,
  duration: 3,
  frameRate: 30,
  backgroundColor: "#000000",
  outputFormat: "mp4",
  visuals: [],
  audios: [],
};

// This will create a 3-second black video
renderVideo(testProject, "./test-output")
  .then(() => console.log("Test video created successfully!"))
  .catch((err) => console.error("Test failed:", err));

Run the test:

node test.js

Troubleshooting​

Common Issues​

FFmpeg Not Found​

Error: FFmpeg not found in PATH

Solution:

  1. Ensure FFmpeg is properly installed
  2. Verify it's in your system PATH
  3. Restart your terminal/command prompt
  4. Try running ffmpeg -version to test

Permission Errors​

Error: EACCES: permission denied

Solution:

  • Ensure you have write permissions to the output directory
  • On Linux/macOS, you might need to use sudo or change directory permissions

Memory Issues​

Error: Out of memory or similar

Solution:

  • Reduce video resolution or duration for testing
  • Ensure sufficient RAM is available
  • Close other memory-intensive applications

Node.js Version Issues​

Error: Package requires Node.js 18+

Solution:

  • Update Node.js to version 18.0 or higher
  • Use a Node.js version manager like nvm:
# Install nvm (Linux/macOS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 18
nvm install 18
nvm use 18

Platform-Specific Notes​

Windows​

  • Use PowerShell or Command Prompt as Administrator for installations
  • Ensure Windows Defender doesn't block FFmpeg execution
  • Consider using WSL2 for a Linux-like environment

macOS​

  • You might need to allow FFmpeg in Security & Privacy settings
  • Ensure Xcode Command Line Tools are installed: xcode-select --install

Linux​

  • Some distributions require additional codecs for certain video formats
  • Ensure you have build tools installed: sudo apt install build-essential

Development Setup​

For development or contributing to the package:

1. Clone the Repository​

git clone https://github.com/Zvid-io/zvid.git
cd zvid

2. Install Dependencies​

yarn install

3. Build the Package​

yarn build

Next Steps​

Now that you have everything installed, you're ready to:

  1. Create your first video - Follow the quick start guide
  2. Explore examples - Learn through practical examples
  3. Read the API reference - Understand all available options

Getting Help​

If you encounter issues during installation:

  • Check the FAQ for common solutions
  • Search existing GitHub Issues
  • Create a new issue with your system details and error messages