merge-videos

Merge all videos inside a directory (recursively) into a single video file.

Perfect for combining downloaded course videos, lecture series, or any collection of video files into one continuous video.

Features

• Recursively finds all video files in nested folders
• Maintains correct order (files must be numbered: 1.intro.mp4, 2.setup.mp4, etc.)
• Supports .mp4, .mkv, .m4v, and .ts formats
• Works as a CLI tool or a Node.js library
• Progress spinner with status updates

Prerequisites

FFmpeg must be installed on your system.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (with chocolatey)
choco install ffmpeg

Installation

As a CLI tool (recommended)

npm install -g merge-videos

As a project dependency

npm install merge-videos

Use without installing

npx merge-videos ./my-videos

CLI Usage

merge-videos <input-dir> [options]

Options

| Option | Description | |---|---| | -o, --output <path> | Output file path (default: ./output/merged.mp4) | | --no-overwrite | Don't overwrite existing output file | | --verbose | Show detailed ffmpeg output | | --dry-run | List files that would be merged without merging | | -h, --help | Show help | | -v, --version | Show version |

Examples

# Merge all videos in a directory
merge-videos ./my-course

# Specify output path
merge-videos ./lectures -o ./result/final.mp4

# Preview which files will be merged (without merging)
merge-videos ./videos --dry-run

# Show ffmpeg output for debugging
merge-videos ./videos --verbose

Programmatic API

const mergeVideos = require("merge-videos");

mergeVideos("./my-course", {
  output: "./result/final.mp4",
  silent: true,       // suppress ffmpeg output (default: true)
  overwrite: true,    // overwrite existing file (default: true)
})
  .then((outputPath) => {
    console.log("Merged to:", outputPath);
  })
  .catch((err) => {
    console.error("Failed:", err.message);
  });

mergeVideos(inputDir, options?)

| Parameter | Type | Default | Description | |---|---|---|---| | inputDir | string | (required) | Path to directory containing videos | | options.output | string | ./output/merged.mp4 | Output file path | | options.silent | boolean | true | Suppress ffmpeg console output | | options.overwrite | boolean | true | Overwrite existing output file |

Returns: Promise<string> — path to the merged output file.

How It Works

1. Recursively walks through all subdirectories in the input folder
2. Collects all supported video files (.mp4, .mkv, .m4v, .ts)
3. Sorts files numerically by filename prefix (e.g., 1.intro, 2.setup, 3.basics)
4. Concatenates them into a single output video using ffmpeg

File Naming Convention

Videos and folders must start with a number followed by a dot:

my-course/
  1. Getting Started/
    1. Welcome.mp4
    2. Prerequisites.mp4
  2. Core Concepts/
    1. Basics.mp4
    2. Advanced.mp4
    3. Summary.mkv

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - Shaurya Singhal