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
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
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--output | -o | string | merged.mp4 | Output file path |
--re-encode | boolean | false | Force re-encoding (handles different formats) | |
--transition | string | none | Transition effect: fade, wipe, dissolve, none | |
--transition-duration | number | 1 | Transition duration in seconds | |
--codec | -c | string | h264 | Video codec: h264, h265, vp9 |
--quality | number | 23 | CRF quality if re-encoding | |
--scale | string | Scale all videos to same resolution (e.g., 1080p) | ||
--audio-track | number | 1 | Select audio track from videos (1-based) | |
--audio-codec | string | aac | Audio codec: aac, mp3, opus | |
--normalize-audio | boolean | false | Normalize audio levels across videos | |
--format | string | mp4 | Output format: mp4, mkv, avi, webm | |
--dry-run | boolean | false | Preview without executing | |
--verbose | -v | boolean | false | Show 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
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
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 devicesvp9- WebM format, web streaming
Audio Codecs:
aac- Best for MP4 (default)mp3- Universal compatibilityopus- 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 files23- Default, good balance26-28- Smaller files, acceptable quality
--format - Output Container
Specify output container format.
Options:
mp4- Universal (default)mkv- Advanced features, multi-track supportwebm- Web streamingavi- 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
Specify Output Location
Multiple Files
Different Formats
Dry Run Preview
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
- Standardize inputs: Use same format/resolution for fast concat
- Pre-process: Transcode to same format first if needed
- Order matters: Maintain desired sequence when specifying files
- 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
- Use same format: All MP4 or all MKV for fast concat
- Match resolution: Same resolution for best results
- Test with --dry-run: Preview before processing
- Order carefully: Specify files in desired sequence
- Keep originals: Never delete source files until verified
- Check compatibility: Similar specs = faster processing
- Verify output: Always watch merged video completely
- 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
Related Commands
- trim - Cut clips before merging
- transcode - Standardize format before merging
- compress - Reduce size after merging