FFmpeg

Social media platforms' main purpose is to share content like videos, images, audio, and more. When users upload video or audio content, it's necessary to optimize it for the best quality and loading speed.

ColibriPlus uses FFmpeg to optimize and convert videos, audio, user stories, and more.

FFmpeg is free and open-source software for video and audio processing. It is a command-line tool that can be used to convert, resize, and compress videos and audio files.

Installation Methods

Method 1: Static Build (Recommended)

The static build is the recommended approach for production environments as it includes all dependencies and ensures consistent behavior across different systems.

Linux Installation

Navigate to the project root and run the installation script:

cd services/ffmpeg

# Make the script executable
chmod +x ffmpeg-install.sh

# Run the script
sudo ./ffmpeg-install.sh

This will install FFmpeg static build in the services/ffmpeg/bin directory with the following structure:

services/ffmpeg/bin/
├── ffmpeg
├── ffprobe
└── (other binaries if included)

Configuration

Once installation is complete, add the paths to your .env file:

# FFmpeg binary paths (use absolute paths)
FFMPEG_PATH=/absolute/path/to/colibriplus/services/ffmpeg/bin/ffmpeg
FFPROBE_PATH=/absolute/path/to/colibriplus/services/ffmpeg/bin/ffprobe

# FFmpeg processing settings
FFMPEG_TIMEOUT=3600
FFMPEG_THREADS=12
FFMPEG_TEMP_DIR=/absolute/path/to/colibriplus/storage/app/tmp/ffmpeg

💡 Path Configuration: Replace /absolute/path/to/colibriplus with your actual project path. You can get the absolute path by running pwd in your project root directory.

Set Permissions

Ensure the binaries have execute permissions:

chmod +x services/ffmpeg/bin/ffmpeg
chmod +x services/ffmpeg/bin/ffprobe

Method 2: System Installation

If you prefer to use your system's package manager or already have FFmpeg installed:

Ubuntu/Debian

sudo apt update
sudo apt install ffmpeg

CentOS/RHEL/Fedora

# CentOS/RHEL (requires EPEL repository)
sudo yum install epel-release
sudo yum install ffmpeg

# Fedora
sudo dnf install ffmpeg

macOS

# Using Homebrew
brew install ffmpeg

# Using MacPorts
sudo port install ffmpeg

Configuration for System Installation

For system installations, update your .env file with the system paths:

# System installation paths
FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe

# FFmpeg processing settings
FFMPEG_TIMEOUT=3600
FFMPEG_THREADS=12
FFMPEG_TEMP_DIR=/absolute/path/to/colibriplus/storage/app/tmp/ffmpeg

To find the exact paths on your system:

which ffmpeg
which ffprobe

Configuration Options

Environment Variables Explained

• FFMPEG_PATH: Absolute path to the FFmpeg binary
• FFPROBE_PATH: Absolute path to the FFprobe binary (used for media analysis)
• FFMPEG_TIMEOUT: Maximum execution time in seconds (3600 = 1 hour)
• FFMPEG_THREADS: Number of CPU threads to use for processing
• FFMPEG_TEMP_DIR: Directory for temporary files during processing

Recommended Settings

For Development:

FFMPEG_TIMEOUT=1800  # 30 minutes
FFMPEG_THREADS=4     # Lower thread count

For Production:

FFMPEG_TIMEOUT=3600  # 1 hour
FFMPEG_THREADS=12    # Higher thread count based on your server

⚠️ Thread Configuration: Set FFMPEG_THREADS based on your server's CPU cores. Generally, use 1-2 threads per CPU core for optimal performance.

Create Temporary Directory

Ensure the temporary directory exists and has proper permissions:

mkdir -p storage/app/tmp/ffmpeg
chmod 755 storage/app/tmp/ffmpeg

Testing Installation

Basic Version Check

Test if FFmpeg is properly installed and accessible:

# For static build
./services/ffmpeg/bin/ffmpeg -version

# For system installation
ffmpeg -version

You should see output similar to:

ffmpeg version 4.4.2 Copyright (c) 2000-2021 the FFmpeg developers
built with gcc 9 (Ubuntu 9.4.0-1ubuntu1~20.04.1)

Test Media Processing

Create a simple test to verify FFmpeg can process media files:

# Test video conversion (creates a 5-second test video)
ffmpeg -f lavfi -i testsrc=duration=5:size=320x240:rate=1 -y test_output.mp4

# Test audio conversion
ffmpeg -f lavfi -i sine=frequency=1000:duration=5 -y test_output.wav

Troubleshooting

Common Issues

Permission Denied:

# Fix permissions for static build
chmod +x services/ffmpeg/bin/ffmpeg
chmod +x services/ffmpeg/bin/ffprobe

# Fix temporary directory permissions
chmod 755 storage/app/tmp/ffmpeg

Command Not Found:

• Verify the paths in your .env file are absolute and correct
• Check if the binary exists at the specified location
• For system installations, ensure FFmpeg is properly installed

Timeout Issues:

• Increase FFMPEG_TIMEOUT for large files
• Reduce FFMPEG_THREADS if running out of memory
• Monitor server resources during processing

Temporary Directory Issues:

# Create the directory if it doesn't exist
mkdir -p storage/app/tmp/ffmpeg

# Ensure web server can write to it
chown -R www-data:www-data storage/app/tmp/ffmpeg
chmod -R 755 storage/app/tmp/ffmpeg

Performance Optimization

CPU Usage:

• Adjust FFMPEG_THREADS based on your server capacity
• Monitor CPU usage during video processing

Official Resources

• FFmpeg Official Website
• FFmpeg Documentation
• FFmpeg Wiki

---

📋 Installation Checklist:

• ✅ FFmpeg installed (static build or system)
• ✅ Binaries have execute permissions
• ✅ .env file configured with correct paths
• ✅ Temporary directory created and writable