🎬 Video Maker CLI

A beautiful Node.js command-line tool to create WebM videos from MP3 audio files and image folders using FFmpeg.

✨ Features

• 🎵 Use any MP3 file as audio track
• 🖼️ Automatically process all images in a folder into a slideshow
• 🎥 Generate high-quality WebM videos with VP9 codec
• ⚙️ Customizable resolution, quality, and frame rate
• 🎨 Beautiful CLI interface with colored output and progress indicators
• 📊 Smart duration calculation - automatically divides audio length by number of images
• 🔧 Comprehensive input validation and error handling
• 📐 Auto-scales and pads images to maintain aspect ratio
• ⚡ Uses FFmpeg filter complex for efficient processing

Sample

• Unix Cowboy Song 🎸 | Tribute to Ken Thompson & Dennis Ritchie

📋 Prerequisites

• Node.js (v14 or higher)
• FFmpeg must be installed and available in PATH

Installing FFmpeg

Windows:

# Using Chocolatey
choco install ffmpeg

# Or download from https://ffmpeg.org/download.html

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

🚀 Installation

Global Installation

npm install -g video-maker-cli

📖 Usage

Basic Usage

video-maker -a audio.mp3 -i ./images -o output.webm

All Options

video-maker [options]

Required:
  -a, --audio <mp3-file>      Path to MP3 audio file
  -i, --images <folder>       Path to folder containing images
  -o, --output <webm-file>    Output WebM filename

Optional:
  -f, --fps <number>          Frames per second (default: 1) - affects video smoothness
  -r, --resolution <size>     Video resolution (default: "1280x720")
  -q, --quality <number>      Video quality 0-63, lower=better (default: 10)
  --transition <type>         Transition effect: fade, none (default: "none") [Coming soon]
  -V, --version               Output version number
  -h, --help                  Display help

Note: The -f (fps) option controls the frame rate of the output video, not the duration 
each image is displayed. Image duration is automatically calculated as:
  (audio duration in seconds) / (number of images)

💡 Examples

Create a simple slideshow

video-maker -a my-song.mp3 -i ./vacation-photos -o vacation.webm
# Creates a video where all images are shown sequentially
# Each image displays for (audio duration / number of images) seconds

HD video with custom settings

video-maker -a audio.mp3 -i ./images -o video.webm -r 1920x1080 -q 8
# Full HD resolution with excellent quality

4K high-quality video

video-maker -a music.mp3 -i ./photos -o movie.webm -r 3840x2160 -q 5
# 4K resolution with maximum quality

Quick slideshow for presentations

video-maker -a soundtrack.mp3 -i ./slides -o presentation.webm -q 12
# Balanced quality for smaller file size

Example: 30 images with 3-minute song

video-maker -a song.mp3 -i ./photos -o memories.webm
# Each of the 30 images will display for 6 seconds (180s / 30 = 6s)

🎨 Supported Image Formats

• JPEG/JPG
• PNG
• BMP
• GIF
• WebP

⚙️ How It Works

1. Validation: Checks if audio file, image folder, and FFmpeg exist
2. Image Discovery: Scans folder for supported image formats and sorts them alphabetically
3. Duration Calculation: Automatically divides audio length by number of images to determine display time per image
4. Video Generation:
   • Uses FFmpeg with -loop 1 to treat each image as a video stream
   • Applies scaling and padding filters to maintain aspect ratio
   • Concatenates all image streams into a continuous video
   • Adds audio track and syncs with video duration
5. Output: Creates WebM video with VP9 codec and Opus audio

Technical Details

The tool uses FFmpeg's powerful filter complex to:

• Load each image with its calculated duration (-loop 1 -t <duration>)
• Scale images to fit the target resolution while preserving aspect ratio
• Pad images with black bars to exact dimensions
• Concatenate all processed images into one seamless video
• Mix in the audio track and trim to audio length with -shortest

Example: If you have 10 images and a 60-second MP3, each image displays for 6 seconds.

🎯 Quality Settings Guide

The -q (quality) parameter uses CRF (Constant Rate Factor):

• 0-15: Excellent quality, larger file size
• 16-23: Good quality (recommended)
• 24-31: Moderate quality
• 32-63: Lower quality, smaller file size

🔧 Resolution Presets

Common resolutions you can use with -r:

• 640x480 - SD (4:3)
• 1280x720 - HD (16:9)
• 1920x1080 - Full HD (16:9)
• 2560x1440 - 2K (16:9)
• 3840x2160 - 4K (16:9)

🐛 Troubleshooting

"FFmpeg is not installed"

Make sure FFmpeg is installed and available in your system PATH:

# Test FFmpeg installation
ffmpeg -version

"No images found"

Ensure your images folder contains supported image formats (jpg, png, etc.) and check that:

• The folder path is correct
• Images have proper file extensions
• You have read permissions for the folder

Images display too quickly or slowly

The tool automatically calculates the optimal display time per image based on:

• Total audio duration ÷ Number of images = Seconds per image

If you want different timing:

• Add more/fewer images to your folder
• Use a longer/shorter audio file
• Each image gets equal display time

Quality issues

• Lower -q value = better quality (but larger file)
• Higher resolution requires lower -q for good results
• Try -q 10 for balanced quality/size
• Use -q 5-8 for high-quality videos

Video encoding takes too long

• Reduce resolution with -r (e.g., use 1280x720 instead of 3840x2160)
• Increase quality value -q (faster encoding, lower quality)
• VP9 encoding is CPU-intensive; be patient for high-quality output

Images appear in wrong order

Images are sorted alphabetically by filename. To control order:

• Name files with numbers: 001-image.jpg, 002-image.jpg, etc.
• Use ISO date format: 2024-01-01-photo.jpg
• Ensure consistent naming conventions

📝 License

MIT License - feel free to use this project however you'd like!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

👨‍💻 Author

Mohan Chinnappan

Made with ❤️ and Node.js