This fork has been fully rewritten in TypeScript, refactored for clarity, now includes simple unit tests, and introduces a strategy-based abstraction over the ffmpeg implementation.

A simple and powerful Node.js wrapper for ffmpeg that makes editing videos easy

Demo | Full Documentation

Features

• 🎥 Easy video concatenation
• 📐 Video scaling and padding
• 🔊 Audio processing and volume control
• 0️⃣ Zero dependencies besides ffmpeg
• 💬 Text overlay support
• 🎯 Position and timing control
• 🎨 Font customization and text effects
• 🛠️ Strategy-based ffmpeg implementation abstraction

Installation

npm install @mikefinch/ezffmpeg

Optional: if you use the default ffmpeg strategy, ensure you have ffmpeg installed on your system:

• Mac: brew install ffmpeg
• Ubuntu/Debian: apt-get install ffmpeg
• Windows: Download from ffmpeg.org

Otherwise, you can provide your own ffmpeg implementation (via the strategy abstraction), or omit ffmpeg entirely by supplying a no-op strategy.

Quick Start

1. Import the package

import ezffmpeg from '@mikefinch/ezffmpeg';

2. Create a project

The ezffmpeg constructor accepts a generic type parameter for strategy-specific options. The default strategy doesn’t require extra options, so its generic defaults to {} and you can omit it:

const project = new ezffmpeg({
  width: 1920,
  height: 1080,
  fps: 30,
  strategy: LocalFfmpegStrategy,
});

If your custom strategy requires its own options interface (e.g. MyStrategyOptions), you can pass it explicitly:

const MyFfmpegStrategy: FfmpegStrategy<{ param: number }> = {
  ffmpeg: async (command, options) => {
    // impl with options.param
  },

  ffprobe: async (command) => {
    // impl
  }
}
const project = new ezffmpeg<{ param: number }>({
  width: 1920,
  height: 1080,
  fps: 30,
  strategy: MyFfmpegStrategy,
});

3. Load clips into the project Load clips into the project**

await project.load([
  {
    type: 'video',
    url: 'path/to/cat.mp4',
    position: 0,
    end: 3,
  },
  {
    type: 'video',
    url: 'path/to/cat2.mp4',
    position: 3,
    end: 6,
  },
  {
    type: 'audio',
    url: 'path/to/music.mp4',
    position: 0,
    end: 6,
  },
  {
    type: 'text',
    text: 'this is so ez',
    position: 0,
    end: 3,
    fontSize: 50,
    fontColor: 'white',
    borderWidth: 5,
    borderColor: '#000000',
  },
]);

4. Export

You can now pass the output file path directly:

await project.export('final.mp4', {param: 3});

Documentation

Find the full API documentation here.