Editron - Video Concatenation with Fade Transitions

A powerful bash script for concatenating multiple video files with smooth fade-to-black/fade-in-from-black transitions between each segment.

Features

• Automatic file detection: Finds all files matching a numbered pattern
• Smooth transitions: Fade-to-black at the end of each video, fade-in-from-black at the start of the next
• Audio preservation: Maintains all audio tracks throughout the concatenation
• Hardware acceleration: Uses Apple's VideoToolbox for fast processing
• Robust error handling: Handles various video formats and timestamp issues
• Flexible input: Works with any number of input files

Requirements

• macOS: Designed for Apple Silicon/Intel Macs with VideoToolbox support
• ffmpeg: Must be installed with VideoToolbox and AudioToolbox support
• ffprobe: For video duration detection

Installing ffmpeg

# Using Homebrew (recommended)
brew install ffmpeg

# Verify VideoToolbox support
ffmpeg -encoders | grep videotoolbox

Usage

./editron.sh join <first-file>

Parameters

• join: The only supported command (required)
• first-file: The first file in your numbered sequence (required)

File Naming Convention

The script expects files to follow a numbered pattern. For example:

Fin-1.mp4
Fin-2.mp4
Fin-3.mp4
...
Fin-15.mp4

The script will automatically find all files matching the base pattern and sort them numerically.

Configuration

You can modify these parameters at the top of the script:

# --- CONFIGURATION ---
TRANSITION_DURATION=0.4  # seconds - Duration of fade transitions
PADDING_FRAMES=12        # Unused in current version
FPS=30                   # Target frame rate for output

Key Parameters

• TRANSITION_DURATION: Length of fade transitions in seconds (default: 0.4)
• FPS: Target frame rate for output video (default: 30)

Examples

Basic Usage

# Concatenate Fin-1.mp4, Fin-2.mp4, Fin-3.mp4, etc.
./editron.sh join Fin-1.mp4

Expected Output

• Input: Fin-1.mp4, Fin-2.mp4, Fin-3.mp4
• Output: Fin-output.mp4 (contains all videos with fade transitions)

How It Works

1. File Discovery: Finds all files matching the base pattern
2. Duration Calculation: Determines fade start times for each video
3. Filter Complex: Creates a single ffmpeg filter that:
   • Applies fade-out to all videos except the last
   • Applies fade-in to all videos except the first
   • Concatenates all processed streams
4. Hardware Processing: Uses VideoToolbox for efficient encoding
5. Output Generation: Creates a single MP4 with all content

Technical Details

Video Processing

• Input formats: Supports HEVC (h265), H.264, and other formats
• Output format: H.264 with VideoToolbox hardware acceleration
• Resolution: Maintains original video resolution
• Frame rate: Normalized to target FPS (default: 30)

Audio Processing

• Input formats: AAC, MP3, and other common formats
• Output format: AAC at 192kbps
• Sample rate: Normalized to 48kHz
• Channels: Preserved as stereo

Fade Logic

• Fade-out: Applied to the last TRANSITION_DURATION seconds of each video (except the last)
• Fade-in: Applied to the first TRANSITION_DURATION seconds of each video (except the first)
• Short videos: If a video is shorter than TRANSITION_DURATION, the fade is adjusted automatically

Error Handling

The script includes comprehensive error handling for:

• Missing dependencies: Checks for ffmpeg and ffprobe
• File not found: Validates input file existence
• Insufficient disk space: Estimates required space
• Invalid patterns: Ensures proper file naming convention
• Timestamp issues: Handles complex video timestamp structures
• Cleanup: Removes temporary files on exit or error

Performance

• Hardware acceleration: Uses Apple's VideoToolbox for fast encoding
• Single-pass processing: All videos processed in one ffmpeg operation
• Memory efficient: No intermediate files for large video collections
• Optimized for macOS: Leverages native Apple hardware capabilities

Troubleshooting

Common Issues

1. "ffmpeg not found"

   brew install ffmpeg

2. "Could not detect file pattern"

   • Ensure files follow the numbered pattern (e.g., Fin-1.mp4, Fin-2.mp4)
   • Check that the first file exists

3. "Need at least 2 input files"

   • Verify multiple files match your pattern
   • Check file permissions

4. "Insufficient disk space"

   • Free up space on your drive
   • The script estimates 100MB minimum requirement

Performance Tips

• Large files: The script can handle videos of any size, but processing time scales with file size
• Many files: For 20+ files, consider processing in smaller batches
• Storage: Ensure you have enough free space for the output file

Limitations

• macOS only: Designed specifically for macOS with VideoToolbox
• Numbered files: Requires files to follow a numbered naming pattern
• Same format: All input videos should have similar properties for best results

License

This script is provided as-is for educational and personal use.

Contributing

Feel free to submit issues or feature requests. The script is designed to be easily modifiable for different use cases.