merge

Concatenate multiple video files into a single continuous video with optional transitions.

Overview

The merge command intelligently joins multiple videos into one seamless file. It automatically detects format compatibility and chooses the optimal method: fast concat (instant, lossless) for identical formats, or re-encode mode for mixed formats. Perfect for combining video segments, creating compilations, or assembling multi-part recordings.

Key Features:

  • 🚀 Auto-detection of compatible formats (fast concat)
  • 🔄 Smart re-encoding for mixed formats
  • ✨ Transition effects (fade, wipe, dissolve)
  • 📐 Automatic resolution matching
  • 🎵 Audio normalization across clips
  • 📁 Batch processing with wildcards

Common Use Cases:

  • Joining multi-part recordings
  • Creating video compilations or montages
  • Combining screen recordings
  • Merging camera footage from multiple takes
  • Assembling split downloads
  • Creating highlight reels
Info

Auto-Detection: The command analyzes all input videos and automatically selects fast concat (lossless) if formats match, or re-encode mode if they differ in resolution, codec, or frame rate.

Usage

Terminal
$ mediaproc video merge <input1> <input2> [input3...] [options]

Options

OptionAliasTypeDefaultDescription
--output-ostringmerged.mp4Output file path
--re-encodebooleanfalseForce re-encoding (handles different formats)
--transitionstringnoneTransition effect: fade, wipe, dissolve, none
--transition-durationnumber1Transition duration in seconds
--codec-cstringh264Video codec: h264, h265, vp9
--qualitynumber23CRF quality if re-encoding
--scalestringScale all videos to same resolution (e.g., 1080p)
--audio-tracknumber1Select audio track from videos (1-based)
--audio-codecstringaacAudio codec: aac, mp3, opus
--normalize-audiobooleanfalseNormalize audio levels across videos
--formatstringmp4Output format: mp4, mkv, avi, webm
--dry-runbooleanfalsePreview without executing
--verbose-vbooleanfalseShow detailed FFmpeg output

Flag Details

--re-encode - Force Re-encoding

Force re-encoding even if videos are compatible for fast concat.

When to Use:

  • Want to apply effects/filters during merge
  • Need to change codec/resolution
  • Videos technically compatible but want quality consistency
  • Adding transitions between clips

Trade-offs:

  • ⏱️ Slower (re-processes all video)
  • 📉 Slight quality loss (minimized with CRF 23)
  • ✨ Enables advanced features (transitions, filters)

Example:

# Force re-encode to apply transition
mediaproc video merge video1.mp4 video2.mp4 --re-encode --transition fade

--transition - Transition Effects

Add smooth transitions between video clips (requires re-encoding).

Available Transitions:

none - Default

  • Direct cut, no transition
  • Instant switch between clips

fade - Crossfade

  • First video fades out while second fades in
  • Smooth, professional look
  • Best for: General use, presentations

wipe - Directional wipe

  • Second video "wipes" over first
  • Dynamic, modern feel
  • Best for: Action sequences, energetic content

dissolve - Dissolve/blend

  • Gradual blend between clips
  • Subtle, elegant transition
  • Best for: Slow-paced content, documentaries

Duration Control: Use --transition-duration to set transition length (default: 1 second).

Examples:

# 1-second fade between clips
mediaproc video merge clip1.mp4 clip2.mp4 clip3.mp4 --transition fade

# 2-second dissolve
mediaproc video merge part1.mp4 part2.mp4 --transition dissolve --transition-duration 2

# Quick 0.5s wipe
mediaproc video merge video1.mp4 video2.mp4 --transition wipe --transition-duration 0.5
Tip

Professional Touch: Use 1-2 second transitions for most content. Shorter (0.3-0.5s) for fast-paced videos, longer (2-3s) for dramatic effect.


--scale - Resolution Matching

Scale all videos to same resolution before merging.

Format: Resolution preset or dimensions

  • Presets: 360p, 480p, 720p, 1080p, 1440p, 2160p
  • Custom: 1920x1080, 1280x720

When to Use:

  • Videos have different resolutions
  • Want consistent output resolution
  • Preparing for specific platform requirements

Behavior:

  • Videos are scaled to match specified resolution
  • Aspect ratios preserved with letterboxing if needed
  • Automatically enables re-encoding

Example:

# Mix of 720p and 1080p videos → all scaled to 1080p
mediaproc video merge 720p-clip.mp4 1080p-clip.mp4 --scale 1080p

# Scale everything to 720p for web delivery
mediaproc video merge *.mp4 --scale 720p -o web-version.mp4

--audio-track - Audio Track Selection

Select which audio track to use from multi-track videos.

Format: Track number (1-based)

  • 1 = First audio track (default)
  • 2 = Second audio track
  • etc.

Use Cases:

  • Videos have multiple audio tracks (commentary, music, original)
  • Want specific language track
  • Select music-only or voice-only track

--normalize-audio - Audio Level Normalization

Normalize audio levels across all videos for consistent volume.

Problem It Solves: Different videos often have different audio levels (some loud, some quiet), creating jarring volume changes during playback.

How It Works:

  • Analyzes peak levels in all input videos
  • Adjusts gain to match target level (-23 LUFS standard)
  • Prevents clipping while maximizing volume

Example:

# Merge with normalized audio
mediaproc video merge loud-video.mp4 quiet-video.mp4 --normalize-audio
Info

Audio Standards: Normalization targets -23 LUFS (Loudness Units Full Scale), the broadcast standard for consistent audio levels.

Learn More:


--codec / --audio-codec - Codec Selection

Specify video and audio codecs when re-encoding.

Video Codecs:

  • h264 - Universal compatibility (default)
  • h265 - Better compression, modern devices
  • vp9 - WebM format, web streaming

Audio Codecs:

  • aac - Best for MP4 (default)
  • mp3 - Universal compatibility
  • opus - Best quality-to-bitrate, modern browsers

Example:

# H.265 for better compression
mediaproc video merge video1.mp4 video2.mp4 -c h265 -o output.mp4

# WebM with VP9 + Opus
mediaproc video merge clip1.mp4 clip2.mp4 -c vp9 --audio-codec opus --format webm

--quality - Encoding Quality

Set CRF quality when re-encoding (0-51, lower = better).

Recommended Values:

  • 18-20 - High quality, large files
  • 23 - Default, good balance
  • 26-28 - Smaller files, acceptable quality

--format - Output Container

Specify output container format.

Options:

  • mp4 - Universal (default)
  • mkv - Advanced features, multi-track support
  • webm - Web streaming
  • avi - Legacy compatibility

Concat Modes

The plugin automatically selects the best concatenation method:

Fast Mode (Concat Demuxer)

Used when: All input videos have same format, codec, resolution, and frame rate

  • Method: Container-level concatenation
  • Speed: Very fast (seconds)
  • Quality: Lossless (no re-encoding)
  • Requirements: Identical format/codec/resolution

Re-encode Mode (Filter Complex)

Used when: Input videos differ in format, codec, resolution, or frame rate

  • Method: Decode all, filter, re-encode
  • Speed: Slower (depends on total duration)
  • Quality: Near-lossless (CRF 23)
  • Requirements: Any mix of videos

Examples

Basic Merging

Terminal
$ mediaproc video merge video1.mp4 video2.mp4
Input files:
1. video1.mp4 (1920x1080, H.264, 00:02:30)
2. video2.mp4 (1920x1080, H.264, 00:03:15)
Format check: All videos compatible
Method: Fast concat (no re-encoding)
Merging videos...
✓ Merge complete
Output: merged.mp4 • Duration: 00:05:45 • 180.3 MB
$ mediaproc video merge part1.mp4 part2.mp4 part3.mp4
Terminal
$ mediaproc video merge clip1.mp4 clip2.mp4 clip3.mp4 -o complete.mp4
✓ Merged to complete.mp4

Specify Output Location

Terminal
$ mediaproc video merge video1.mp4 video2.mp4 -o output/combined.mp4
✓ Saved to output/combined.mp4
Terminal
$ mediaproc video merge video1.mp4 video2.mp4 -o output/
✓ Saved to output/merged.mp4

Multiple Files

Terminal
$ mediaproc video merge seg1.mp4 seg2.mp4 seg3.mp4 seg4.mp4 seg5.mp4 -o full.mp4
✓ Merged 5 segments • Total: 00:15:30
$ mediaproc video merge clip*.mp4 -o compilation.mp4
$ mediaproc video merge *.mp4 -o merged.mp4

Different Formats

Terminal
$ mediaproc video merge video.mp4 video.avi video.mkv -o combined.mp4
Input files:
1. video.mp4 (1920x1080, H.264)
2. video.avi (1280x720, MPEG-4)
3. video.mkv (1920x1080, H.265)
Format check: Videos have different properties
Method: Re-encode mode
Merging with re-encoding...
✓ Merge complete (slower due to re-encoding)
Output: combined.mp4
Terminal
$ mediaproc video merge 1080p.mp4 720p.mp4 4k.mp4 -o mixed.mp4
✓ Merged different resolutions (re-encoded)
$ mediaproc video merge h264.mp4 h265.mp4 -o merged.mp4

Dry Run Preview

Terminal
$ mediaproc video merge video1.mp4 video2.mp4 video3.mp4 --dry-run
[DRY RUN] Would merge 3 files:
1. video1.mp4 (00:02:30, 1920x1080, H.264)
2. video2.mp4 (00:01:45, 1920x1080, H.264)
3. video3.mp4 (00:03:00, 1920x1080, H.264)
Method: Fast concat (all files compatible)
Total duration: 00:07:15
Output: merged.mp4

With Verbose Output

# See detailed FFmpeg processing
mediaproc video merge video1.mp4 video2.mp4 -v

Use Cases

Join Split Videos

Merge videos that were split for storage or transfer:

# Merge split parts
mediaproc video merge movie-part1.mp4 movie-part2.mp4 movie-part3.mp4 -o movie-complete.mp4

# Numbered segments
mediaproc video merge segment-{1..10}.mp4 -o full-recording.mp4

Create Compilations

Combine multiple clips into a single video:

# Highlight reel
mediaproc video merge goal1.mp4 goal2.mp4 goal3.mp4 -o highlights.mp4

# Best moments
mediaproc video merge moment*.mp4 -o best-moments.mp4

# Tutorial sections
mediaproc video merge intro.mp4 step1.mp4 step2.mp4 step3.mp4 outro.mp4 -o full-tutorial.mp4

Presentations and Lectures

Combine multiple lecture segments or presentations:

# Lecture parts
mediaproc video merge lecture-intro.mp4 lecture-content.mp4 lecture-qa.mp4 -o full-lecture.mp4

# Multi-presenter webinar
mediaproc video merge speaker1.mp4 speaker2.mp4 speaker3.mp4 -o webinar.mp4

Concatenate with Trimmed Clips

Merge clips after removing unwanted sections:

# Remove intro/outro from each, then merge
mediaproc video trim video1.mp4 -s 10 -e 290 -o clip1.mp4
mediaproc video trim video2.mp4 -s 5 -e 295 -o clip2.mp4
mediaproc video trim video3.mp4 -s 8 -e 292 -o clip3.mp4

mediaproc video merge clip1.mp4 clip2.mp4 clip3.mp4 -o final.mp4

Multi-Camera Merge

Combine footage from multiple camera angles:

# Sequential camera footage
mediaproc video merge camera-a.mp4 camera-b.mp4 camera-c.mp4 -o multi-angle.mp4

# Before/after segments
mediaproc video merge before.mp4 during.mp4 after.mp4 -o transformation.mp4

Screen Recording Assembly

Merge multiple screen recording sessions:

# Recording sessions
mediaproc video merge session1.mp4 session2.mp4 session3.mp4 -o full-recording.mp4

# Tutorial steps recorded separately
mediaproc video merge step*.mp4 -o complete-tutorial.mp4

Technical Details

Fast Concat (Demuxer)

Used when all inputs are identical:

# Creates temporary concat list
file 'video1.mp4'
file 'video2.mp4'
file 'video3.mp4'

# FFmpeg command
ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4

Requirements:

  • Same container format (all MP4, or all MKV, etc.)
  • Same video codec (all H.264, or all H.265, etc.)
  • Same resolution (all 1920x1080, etc.)
  • Same frame rate (all 30fps, etc.)
  • Same audio codec

Advantages:

  • Extremely fast (seconds)
  • Lossless (no quality loss)
  • No CPU intensive processing

Re-encode Mode (Filter Complex)

Used when inputs differ:

ffmpeg -i video1.mp4 -i video2.avi -i video3.mkv \
  -filter_complex '[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[v][a]' \
  -map '[v]' -map '[a]' -c:v libx264 -crf 23 -c:a aac output.mp4

Used for:

  • Different formats (MP4 + AVI + MKV)
  • Different resolutions (1080p + 720p + 4K)
  • Different codecs (H.264 + H.265)
  • Different frame rates (30fps + 60fps)

Advantages:

  • Handles any combination
  • Normalizes output
  • Produces consistent result

Limitations:

  • Slower processing
  • Quality loss (minimal with CRF 23)
  • CPU intensive

Compatibility Detection

The plugin automatically detects if fast concat is possible:

// Checks for:
- Same format (container)
- Same video codec
- Same resolution
- Same frame rate
- Same audio codec

// If all match → Fast concat
// If any differ → Re-encode

Output Format

Output format is determined by file extension:

# MP4 output (default)
mediaproc video merge video1.mp4 video2.mp4 -o output.mp4

# MKV output
mediaproc video merge video1.mp4 video2.mp4 -o output.mkv

# WebM output
mediaproc video merge video1.mp4 video2.mp4 -o output.webm

Temporary Files

Fast concat creates a temporary file list that's deleted after completion.

Performance Considerations

Processing Speed

Fast concat:

  • Speed: ~1-5 seconds regardless of video length
  • CPU: Minimal
  • Memory: Low

Re-encode mode:

  • Speed: Proportional to total video length
  • ~0.5-1x real-time for H.264
  • ~0.2-0.4x real-time for H.265
  • CPU: High
  • Memory: Scales with resolution

Optimization Tips

  1. Standardize inputs: Use same format/resolution for fast concat
  2. Pre-process: Transcode to same format first if needed
  3. Order matters: Maintain desired sequence when specifying files
  4. Disk space: Ensure enough space for output (sum of inputs + overhead)

Error Handling

Common Errors

No input files:

Error: Must specify at least 2 input files Usage: mediaproc video merge <input1> <input2> [...]

Input file not found:

Error: Input file not found: video2.mp4 Check file path and try again

Insufficient disk space:

Error: Not enough disk space Required: ~500 MB Available: 100 MB

FFmpeg error (fast concat failed):

Error: Fast concat failed (format incompatibility) Retrying with re-encode mode...

Best Practices

  1. Use same format: All MP4 or all MKV for fast concat
  2. Match resolution: Same resolution for best results
  3. Test with --dry-run: Preview before processing
  4. Order carefully: Specify files in desired sequence
  5. Keep originals: Never delete source files until verified
  6. Check compatibility: Similar specs = faster processing
  7. Verify output: Always watch merged video completely
  8. Use wildcards wisely: Ensure correct alphabetical order

Troubleshooting

Audio/Video Desync

If audio becomes out of sync in merged video:

Cause: Different frame rates between input videos

Solution: Re-encode to standardize frame rate first

# Transcode all to same frame rate
for file in *.mp4; do
  ffmpeg -i "$file" -r 30 -c:v libx264 -crf 23 "${file%.mp4}-30fps.mp4"
done

# Then merge standardized files
mediaproc video merge *-30fps.mp4 -o merged.mp4

Black Frames Between Clips

Black frames appear at transitions:

Cause: Keyframe alignment issues in fast concat

Solution: Use re-encode mode (automatically selected if needed)

Files in Wrong Order

Videos merged in incorrect sequence:

Cause: Wildcard expansion order

Solution: Specify files explicitly

# Wrong (alphabetical)
mediaproc video merge video*.mp4

# Right (explicit order)
mediaproc video merge video1.mp4 video2.mp4 video3.mp4

# Right (numbered)
mediaproc video merge video{1..10}.mp4

Merge Failed

Fast concat fails with error:

Cause: Input files incompatible

Solution: Plugin automatically retries with re-encode. If still fails:

# Manually transcode to same format
for file in *.mp4; do
  mediaproc video transcode "$file" -f mp4 -c h264 -o "standardized-$file"
done

mediaproc video merge standardized-*.mp4 -o merged.mp4

Processing Too Slow

Re-encode mode is too slow:

Solution 1: Standardize formats first for fast concat

# Convert all to same format once
for file in *.{avi,mkv,mov}; do
  mediaproc video transcode "$file" -f mp4 -c h264 -o "${file%.*}.mp4"
done

# Then fast merge
mediaproc video merge *.mp4

Solution 2: Use faster codec

# Already uses H.264 by default (fastest reasonable codec)

Advanced Examples

Smart Sequential Merge

#!/bin/bash
# Merge files in numerical order

files=($(ls -v segment-*.mp4))
echo "Merging ${#files[@]} files in order..."

mediaproc video merge "${files[@]}" -o complete.mp4

Standardize Before Merge

#!/bin/bash
# Ensure all videos have same properties before merging

input_files=("video1.mp4" "video2.avi" "video3.mkv")
standardized=()

for file in "${input_files[@]}"; do
  output="standardized-${file%.*}.mp4"
  echo "Standardizing $file..."

  mediaproc video transcode "$file" \
    -f mp4 \
    -c h264 \
    --crf 23 \
    -o "$output"

  standardized+=("$output")
done

echo "Merging standardized files..."
mediaproc video merge "${standardized[@]}" -o merged.mp4

# Cleanup
rm standardized-*.mp4

Multi-Stage Compilation

#!/bin/bash
# Create compilation with intro/outro

intro="intro.mp4"
outro="outro.mp4"
clips=(clip1.mp4 clip2.mp4 clip3.mp4)

# Merge main clips
mediaproc video merge "${clips[@]}" -o main-content.mp4

# Add intro and outro
mediaproc video merge "$intro" main-content.mp4 "$outro" -o final-with-bookends.mp4

# Cleanup
rm main-content.mp4

Merge with Transition Preparation

#!/bin/bash
# Add fade transitions by trimming overlap points

videos=(video1.mp4 video2.mp4 video3.mp4)
trimmed=()

for ((i=0; i<${#videos[@]}; i++)); do
  input="${videos[$i]}"
  output="trimmed-$i.mp4"

  if [ $i -eq 0 ]; then
    # First video: trim last 0.5 sec
    duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$input")
    end=$(echo "$duration - 0.5" | bc)
    mediaproc video trim "$input" -e "$end" -o "$output"
  elif [ $i -eq $((${#videos[@]}-1)) ]; then
    # Last video: trim first 0.5 sec
    mediaproc video trim "$input" -s 0.5 -o "$output"
  else
    # Middle videos: trim both ends
    duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$input")
    end=$(echo "$duration - 0.5" | bc)
    mediaproc video trim "$input" -s 0.5 -e "$end" -o "$output"
  fi

  trimmed+=("$output")
done

# Merge trimmed videos
mediaproc video merge "${trimmed[@]}" -o seamless.mp4

# Cleanup
rm trimmed-*.mp4

Batch Chapter Creation

#!/bin/bash
# Create multiple merged videos from chapter definitions

# Define chapters (output_name: input_files...)
declare -A chapters
chapters["chapter1"]="intro.mp4 section1a.mp4 section1b.mp4"
chapters["chapter2"]="section2a.mp4 section2b.mp4 section2c.mp4"
chapters["chapter3"]="section3a.mp4 section3b.mp4 outro.mp4"

for chapter in "${!chapters[@]}"; do
  echo "Creating $chapter..."
  files=(${chapters[$chapter]})
  mediaproc video merge ${files[@]} -o "$chapter.mp4"
done

# Merge all chapters
mediaproc video merge chapter*.mp4 -o complete-course.mp4

Playlist Merge with Logging

#!/bin/bash
# Merge videos from playlist with detailed logging

playlist="playlist.txt"
log="merge-log.txt"

echo "Merge started: $(date)" > "$log"
echo "---" >> "$log"

files=()
while IFS= read -r file; do
  if [ -f "$file" ]; then
    duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$file")
    size=$(du -h "$file" | cut -f1)
    echo "Adding: $file (Duration: ${duration}s, Size: $size)" >> "$log"
    files+=("$file")
  else
    echo "Warning: File not found: $file" >> "$log"
  fi
done < "$playlist"

echo "---" >> "$log"
echo "Total files: ${#files[@]}" >> "$log"

if [ ${#files[@]} -ge 2 ]; then
  echo "Merging..." >> "$log"
  mediaproc video merge "${files[@]}" -o merged-playlist.mp4 -v >> "$log" 2>&1
  echo "Merge completed: $(date)" >> "$log"
else
  echo "Error: Need at least 2 files to merge" >> "$log"
fi
  • trim - Cut clips before merging
  • transcode - Standardize format before merging
  • compress - Reduce size after merging

See Also

Found an issue? Help us improve this page.

Edit on GitHub →