timelape_tuner/README.org

Timelapse Tuner

• Video Demo
• Features
• Prerequisites
• Installation
• Usage
  • Options:
  • Examples:
• How It Works
• Providing Background Music
• Logging
• Troubleshooting
• Contributing
• Acknowledgments

Timelapse Tuner is a Bash script that automates the process of creating timelapse videos with randomly selected background music. It can merge multiple timelapse video files and combine them with a randomly chosen audio file from the current directory, applying fade-in and fade-out effects to the audio for a polished result. It supports both horizontal and vertical video output!

Video Demo

Check out this quick demo of what Timelapse Tuner can do (Youtube)

Vertical example (Youtube)

Features

• Merges multiple timelapse video files into a single video
• Combines the merged video with a randomly selected MP3 audio file
• Applies fade-in and fade-out effects to the audio for smooth transitions
• Randomly selects a start point in the audio file to add variety
• Supports custom input timelapse videos and output file specification
• Allows customization of fade duration
• Provides option to convert horizontal videos to vertical format
• Provides detailed logging of the merging process

Prerequisites

This script requires the following tools to be installed and available in your system PATH:

• Bash (version 4.0 or later)
• FFmpeg
• FFprobe (usually comes with FFmpeg)
• bc (Basic Calculator)

You will also need to provide your own MP3 files for background music. If you need royalty-free music, you can find a great selection at Pixabay Music.

Installation

1. Clone this repository or download the script file:

   git clone https://gitlab.com/rogs/timelape_tuner.git
   cd timelapse_tuner

2. Make the script executable:

   chmod +x tt

Usage

Run the script with the following command:

./tt --video <video_file1> [<video_file2> ...] --output <output_file> [--fade <fade_duration>] [--vertical]

Options:

• --video: Specify one or more input video files (at least one is required)
• --output: Specify the output MP4 file name (optional, default: output_video.mp4)
• --fade: Specify the fade duration in seconds (optional, default: 2)
• --vertical: Convert the video to vertical format (optional, default: horizontal)

Examples:

For merging multiple horizontal videos (default):

./tt --video timelapse1.mp4 timelapse2.mp4 timelapse3.mp4 --output merged_timelapse.mp4 --fade 3

For merging multiple videos and converting to vertical format:

./tt --video timelapse1.mp4 timelapse2.mp4 --output vertical_timelapse.mp4 --fade 3 --vertical

How It Works

1. The script checks for the required dependencies (FFmpeg, FFprobe, bc).
2. It verifies that all input video files exist.
3. A random MP3 file is selected from the current directory to serve as background music.
4. The lengths of all video files and the audio file are calculated.
5. If multiple video files are provided, they are concatenated in the order specified.
6. Fade-in and fade-out durations are set (default 2 seconds, customizable with –fade) for smooth audio transitions.
7. A random start point in the audio file is selected to ensure variety in the background music.
8. If the –vertical option is used, the combined video is scaled and cropped to 1080x1920 resolution.
9. FFmpeg is used to merge the concatenated video with the selected portion of the audio, applying fade effects and any necessary format conversion.
10. The final timelapse video with background music is saved as an MP4 file.

Providing Background Music

Timelapse Tuner requires MP3 files in the same directory as the script to use as background music. Before running the script, make sure to add your desired MP3 files to the project directory.

For royalty-free music options, we recommend visiting Pixabay Music. They offer a wide variety of high-quality, free-to-use tracks that can enhance your timelapse videos.

Logging

The script provides detailed logging of each step in the process. Logs are printed to the console with timestamps, allowing you to follow the progress of your timelapse creation.

Troubleshooting

If you encounter any issues:

1. Ensure all prerequisites are installed and up to date.
2. Check that you have read/write permissions in the current directory.
3. Verify that there are MP3 files in the same directory as the script for background music.
4. If FFmpeg fails, check the error message for details on what went wrong.
5. When using multiple input videos, ensure they have compatible formats and resolutions.

Contributing

Contributions to improve Timelapse Tuner are welcome. Please feel free to submit a Merge Request with your enhancements.

Acknowledgments

• FFmpeg project for providing powerful multimedia processing tools.
• The timelapse photography community for inspiration.
• Pixabay for providing a great source of royalty-free music.