TimeLapse Maker 🎬

A beautiful, interactive command-line tool for creating stunning time-lapse videos from your video clips. Speed up your footage, merge multiple clips seamlessly, and add background music—all with an elegant interface that makes the process enjoyable.

The Scenario

Imagine you've just returned from an amazing day trip. You have three video clips on your camera:

1. A 20-minute sunrise over the mountains
2. A 15-minute drive through scenic countryside
3. A 30-minute sunset at the beach

You want to turn these into a 1-minute time-lapse video that captures the entire journey, compress it to under 90 MB for easy sharing, and add your favorite background music to set the mood.

This is exactly what TimeLapse Maker does.

Instead of wrestling with complex video editing software or memorizing arcane ffmpeg commands, you simply run this script, answer a few friendly questions, and let it handle the rest. The tool automatically:

• Speeds up your clips to your desired length
• Merges them into a single cohesive video
• Optimizes file size without sacrificing quality
• Adds background music (optional)
• Leverages GPU acceleration when available for faster processing

---

Features

✨ Beautiful Interactive Interface – Rich, colorful terminal UI with tables, progress bars, and spinners
🚀 GPU Acceleration – Automatically detects and uses NVIDIA hardware encoding when available
🎯 Smart Recommendations – Suggests optimal speed factors based on your content
📦 Size Optimization – Calculates precise bitrates to hit your target file size
🎵 Audio Integration – Easily add background music to your final video
🔄 Batch Processing – Handles multiple clips automatically, preserving their order
📊 Real-time Progress – Live status updates as each clip is processed
🛡️ Error Handling – Detailed logs for troubleshooting if anything goes wrong

---

Requirements

System Requirements

FFmpeg & FFprobe must be installed and accessible from your command line. These are the core video processing engines that power this tool.

Optional but Recommended:

• NVIDIA GPU with NVENC support (for 5-10× faster processing)
• At least 2GB free disk space for temporary files

Software Dependencies

Python 3.6 or newer is required.

Python Package:

• rich – Provides the beautiful terminal interface

---

Installation

Step 1: Install FFmpeg

FFmpeg is the video processing engine. Install it for your operating system:

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Linux (RHEL/CentOS/Fedora)

# RHEL/CentOS 8+ with EPEL
sudo dnf install epel-release
sudo dnf install ffmpeg

# Fedora
sudo dnf install ffmpeg

macOS

Using Homebrew (install from https://brew.sh if you don't have it):

brew install ffmpeg

Windows

Option 1: Using Chocolatey (easiest)

choco install ffmpeg

Option 2: Manual Installation

1. Download FFmpeg from https://ffmpeg.org/download.html
2. Extract the archive to C:\ffmpeg
3. Add C:\ffmpeg\bin to your system PATH:
   • Right-click "This PC" → Properties → Advanced system settings
   • Click "Environment Variables"
   • Under "System variables", find "Path", click Edit
   • Click New and add C:\ffmpeg\bin
   • Click OK on all dialogs
4. Open a new Command Prompt and verify with ffmpeg -version

Step 2: Install Python Dependencies

Navigate to the folder containing the script and run:

pip install rich

Or if you're using Python 3 specifically:

pip3 install rich

That's it! You're ready to create time-lapses.

---

How to Use

Basic Usage

1. Organize your clips – Place all your video clips in a folder. They can be named anything, but the script will process them in numerical/alphabetical order.

2. Navigate to the folder containing your clips (or just note its path).

3. Run the script:

   python3 fftimelapse_cli_rich.py

4. Answer the interactive prompts:

   • Specify the folder with your clips (or press Enter for current folder)
   • Set desired final video length in seconds
   • Choose whether to use recommended speed factor
   • Set target file size in MB
   • Choose output frame rate (30 fps is good for most content)
   • Keep original resolution or downscale to 1080p/720p
   • Add background music if desired

5. Wait for processing – The script will show you real-time progress with spinners and progress bars.

6. Enjoy your time-lapse! – Find the final video in the same folder.

Example Session

╭─────────────── FFTIMELAPSE ───────────────╮
│              Rich TUI                     │
╰───────────────────────────────────────────╯

Folder with clips: ./vacation_clips

              Clips (in order)
┏━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ # ┃ Filename       ┃ Duration ┃ Status ┃
┡━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ 1 │ sunrise.mp4    │ 20m0s    │ Queued │
│ 2 │ drive.mp4      │ 15m0s    │ Queued │
│ 3 │ sunset.mp4     │ 30m0s    │ Queued │
└───┴────────────────┴──────────┴────────┘

Desired final length in seconds [60]: 60
Use recommended factor? (y/n) [y]: y
Target final file size in MB [90]: 90
Output FPS [30]: 30
Keep original resolution or downscale? (keep/1080/720) [keep]: keep
Codec preference (h264/h265) [h264]: h264

╭────────── Selected Settings ──────────╮
│ Speed factor:     65.00×              │
│ Final duration:   1m0s                │
│ Target size (MB): 90                  │
│ Estimated bitrate: 10000 kbps         │
│ Output FPS:       30                  │
│ Scale:            original            │
│ Codec:            h264 (NVENC)        │
╰───────────────────────────────────────╯

Proceed with processing? (y/n) [y]: y

⠹ Processing sunrise.mp4 (1/3) ━━━━━━━━━━━━━━━━ 33%

---

Understanding the Options

Folder with clips

The directory containing your video files. Press Enter to use the current directory. The script will automatically find all .mp4, .mov, .mkv, .avi, and .webm files.

Desired final length in seconds

How long you want the final time-lapse to be. For example:

• 60 = 1 minute
• 120 = 2 minutes
• 30 = 30 seconds

Speed factor

How much to speed up your videos. The script recommends a factor based on your target length, but you can customize it:

• 2× = twice as fast (20 min → 10 min)
• 60× = sixty times faster (60 min → 1 min)
• 128× = very dramatic time-lapse (128 min → 1 min)

Target file size (MB)

The desired size of your final video. The script calculates the optimal bitrate to hit this target:

• 50 MB = good for sharing online, moderate quality
• 90 MB = excellent quality for most purposes
• 200 MB = very high quality for archival

Output FPS (frames per second)

The frame rate of your final video:

• 24 fps = cinematic look
• 30 fps = standard, smooth (recommended)
• 60 fps = very smooth, larger file size

Resolution

Whether to keep your original resolution or downscale:

• keep = maintain original quality (4K stays 4K)
• 1080 = downscale to 1920×1080 (Full HD)
• 720 = downscale to 1280×720 (HD)

Downscaling can significantly reduce file size and processing time.

Codec preference

The video compression format:

• h264 = widely compatible, smaller files
• h265 = better compression, newer format (some older devices may not support it)

If NVENC (NVIDIA hardware encoding) is detected, processing will be much faster.

Background audio

After processing, you'll be prompted to add audio. Provide the path to any audio file (.mp3, .wav, .aac, etc.). The audio will loop to match your video length.

---

Platform-Specific Notes

Linux

Works perfectly out of the box once dependencies are installed. If you have an NVIDIA GPU, ensure you have the proprietary drivers installed for NVENC support:

# Check if NVENC is detected
ffmpeg -encoders | grep nvenc

macOS

The script works great on macOS. Note that NVENC (GPU acceleration) is only available on systems with NVIDIA GPUs, which excludes most modern Macs. The script will automatically fall back to CPU encoding, which is slower but still works well.

Windows

Running the Script

Open Command Prompt or PowerShell and run:

python fftimelapse_cli_rich.py

Or if you have Python 3 specifically:

python3 fftimelapse_cli_rich.py

Path Considerations

When entering folder paths on Windows, you can use either:

• Forward slashes: C:/Users/YourName/Videos
• Backslashes (escaped): C:\\Users\\YourName\\Videos
• Just drag and drop the folder into the terminal window

GPU Acceleration

If you have an NVIDIA GPU, make sure you have the latest drivers installed from https://nvidia.com. The script will automatically detect and use NVENC if available.

RHEL/CentOS

FFmpeg isn't in the default repositories. Use EPEL (Extra Packages for Enterprise Linux):

sudo dnf install epel-release
sudo dnf config-manager --set-enabled crb  # For RHEL 9
sudo dnf install ffmpeg ffmpeg-devel

For RHEL 7:

sudo yum install epel-release
sudo yum localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm
sudo yum install ffmpeg

---

Customization & Advanced Usage

Processing Clips from Different Folders

Instead of moving all your clips to one location, you can specify any folder when prompted:

Folder with clips: /path/to/your/vacation/footage

Naming Your Clips for Specific Order

The script processes files in numerical/alphabetical order. For specific ordering:

Good naming:

• 001_sunrise.mp4
• 002_midday.mp4
• 003_sunset.mp4

Or simply:

• 1.mp4
• 2.mp4
• 3.mp4

Alphabetical (works too):

• a_morning.mp4
• b_afternoon.mp4
• c_evening.mp4

Preserving Temporary Files

When asked "Delete temporary files?", you can choose n to keep them. This is useful for:

• Inspecting intermediate clips before merging
• Debugging processing issues
• Reusing processed clips with different settings

Temporary files are stored in /tmp/fftl_* (Linux/macOS) or %TEMP%\fftl_* (Windows).

Running Without the Rich Interface

If you're on a system where the rich library isn't available or you prefer a plain interface, the script automatically falls back to a simple text mode. All functionality remains the same.

---

Troubleshooting

"ffmpeg not found" or "ffprobe not found"

Solution: FFmpeg isn't installed or isn't in your PATH. Follow the installation instructions above for your operating system. Verify installation:

ffmpeg -version
ffprobe -version

"No video files found in folder"

Solution:

• Ensure your clips are in a supported format (.mp4, .mov, .mkv, .avi, .webm)
• Check that you've specified the correct folder path
• Look for typos in the path

Processing is very slow

Solution:

• Get GPU acceleration: If you have an NVIDIA GPU, install the latest drivers to enable NVENC
• Downscale resolution: Choose 1080 or 720 instead of keep
• Use h264 instead of h265: H264 is faster to encode
• Reduce target file size: Lower bitrates process faster

"ffmpeg failed" error

Solution:

• Check the log files in the temporary folder (path shown in output)
• Common issues:
  • Corrupted source video
  • Unsupported codec in source
  • Insufficient disk space
  • Permission issues

Final file size doesn't match target

Solution: The target size is an estimate. Actual size can vary by ±15% depending on video complexity. For more precise control:

• Adjust the overhead_ratio in the script (default: 0.95)
• Use two-pass encoding (requires script modification)

Audio doesn't match video length

Solution: The audio is automatically looped (with -stream_loop -1) and trimmed (with -shortest) to match the video duration. If it's not working:

• Ensure your audio file isn't corrupted
• Try a different audio format (MP3 is most reliable)
• Check the log output for ffmpeg errors

---

Technical Details

How It Works

1. Discovery: Scans the folder for video files and sorts them
2. Analysis: Uses ffprobe to determine duration of each clip
3. Calculation: Computes optimal speed factor and bitrate for your targets
4. Processing: For each clip:
   • Applies setpts filter to change speed
   • Scales resolution if requested
   • Sets frame rate
   • Encodes with calculated bitrate
5. Merging: Concatenates all processed clips using ffmpeg's concat demuxer
6. Audio (optional): Merges background audio with the final video
7. Cleanup: Removes temporary files (unless you choose to keep them)

GPU Acceleration (NVENC)

When an NVIDIA GPU is detected:

• Uses h264_nvenc or hevc_nvenc encoders
• Applies -hwaccel cuda for hardware decoding
• Uses scale_cuda filter for GPU-based resizing
• Processes 5-10× faster than CPU encoding
• Quality is comparable to CPU encoding at the same bitrate

File Size Calculation

The script uses this formula:

target_bytes = target_MB × 1024² × 0.95
bitrate_kbps = (target_bytes × 8) / duration_seconds / 1000

The 0.95 factor accounts for container overhead and metadata.

Codec Choices

H.264 (AVC):

• Universally supported
• Fast encoding
• Good quality-to-size ratio
• Recommended for sharing

H.265 (HEVC):

• Better compression (30-50% smaller files at same quality)
• Slower encoding
• Not supported on older devices
• Recommended for archival or modern devices only

---

Tips & Best Practices

For Best Quality

• Keep original resolution if file size permits
• Use higher target file sizes (150+ MB for 1 minute)
• Use 30 or 60 fps output
• Use h265 codec if compatibility isn't a concern

For Fastest Processing

• Enable GPU acceleration (NVIDIA GPU + latest drivers)
• Downscale to 720p
• Use h264 codec
• Use lower fps (24)

For Smallest Files

• Use h265 codec
• Downscale to 720p
• Use calculated bitrates (don't override)
• Use 24 fps

For Social Media Sharing

• Target: 90-100 MB for 1 minute
• Resolution: 1080p
• FPS: 30
• Codec: h264 (best compatibility)

For Dramatic Time-Lapses

• Use high speed factors (100×+)
• Longer source material works better
• 60 fps makes motion smoother at high speeds
• Consider 24 fps for more "cinematic" stutter effect

---

Examples

Example 1: Quick Social Media Time-Lapse

Scenario: 3 GoPro clips from a hike, want a 30-second Instagram-ready video

Desired final length: 30
Use recommended factor: y
Target file size: 50
Output FPS: 30
Resolution: 1080
Codec: h264

Example 2: High-Quality Archival Time-Lapse

Scenario: 4K drone footage of a construction project, want highest quality for archival

Desired final length: 180
Use recommended factor: y  
Target file size: 500
Output FPS: 60
Resolution: keep
Codec: h265

Example 3: Ultra-Fast Dramatic Time-Lapse

Scenario: 8 hours of security camera footage compressed to 2 minutes

Desired final length: 120
Speed factor: 240
Target file size: 100
Output FPS: 24
Resolution: 720
Codec: h264

---

License & Credits

This script uses FFmpeg (licensed under LGPL/GPL) for video processing. The Rich library provides the beautiful terminal interface.

Enjoy creating stunning time-lapses! 🎬✨

---

FAQ

Q: Can I use this with different video formats mixed together?
A: Yes! Mix .mp4, .mov, .mkv, .avi, and .webm files freely. The script normalizes everything during processing.

Q: What if my clips have different resolutions?
A: The script will maintain each clip's resolution during processing, then the concat operation handles mixed resolutions gracefully. For best results, use the scale option to normalize everything to the same resolution.

Q: Can I process just one video file?
A: Absolutely! The script works with any number of clips, including just one.

Q: How much disk space do I need?
A: At least 2× the size of your source material for temporary files. The script cleans up automatically when done.

Q: Can I cancel processing midway?
A: Press Ctrl+C to cancel. Temporary files will be retained for inspection.

Q: Will this work on Raspberry Pi?
A: Yes, but it will be slower since there's no NVENC. Downscale to 720p for reasonable processing times.

Q: Can I add multiple audio tracks?
A: Currently only one background audio track is supported. For multiple tracks, you'll need to merge them in an audio editor first.