Using FFmpeg on a VPS or dedicated server, paths and a usage guide Print

FFmpeg is a powerful open-source tool for processing video and audio files. It is commonly used with PHP, ColdFusion and Lucee applications for tasks such as video conversion, thumbnail generation, and extracting media information. This article covers installing FFmpeg on a Host Media VPS or dedicated server and how to use it in your applications.

VPS and dedicated server customers only. FFmpeg is not provided on shared or reseller hosting. You will need root SSH access to install and manage it on your server.

Installing FFmpeg

Install FFmpeg via your server's package manager:

Ubuntu / Debian:

sudo apt update && sudo apt install ffmpeg -y

AlmaLinux / Rocky Linux / CentOS (with EPEL):

sudo dnf install epel-release -y
sudo dnf install ffmpeg -y

Once installed, confirm it is working and check the version:

ffmpeg -version

Confirm the binary path with:

which ffmpeg

FFmpeg path

On most Linux servers, FFmpeg installs to the following path. Use this when configuring your application:

/usr/bin/ffmpeg

Always use the full path in your application code rather than just ffmpeg, as the web server process may not have the same PATH environment as your shell session.

Using FFmpeg in ColdFusion and Lucee

FFmpeg is called from CFML using the <cfexecute> tag. Always use the full path to the FFmpeg binary rather than just ffmpeg, as the web server process may not have the same PATH as your shell session.

Converting a video file

<cfexecute
    name="/usr/bin/ffmpeg"
    arguments="-i /home/username/public_html/videos/input.mp4 -c:v libx264 -crf 23 /home/username/public_html/videos/output.mp4"
    timeout="120"
    variable="ffmpegOutput"
    errorVariable="ffmpegError" />

Generating a thumbnail from a video

<cfexecute
    name="/usr/bin/ffmpeg"
    arguments="-i /home/username/public_html/videos/input.mp4 -ss 00:00:02 -vframes 1 /home/username/public_html/images/thumbnail.jpg"
    timeout="30"
    variable="ffmpegOutput"
    errorVariable="ffmpegError" />

This captures a single frame 2 seconds into the video and saves it as a JPEG. Adjust the -ss value to change which point in the video is captured.

Getting video file information

<cfexecute
    name="/usr/bin/ffmpeg"
    arguments="-i /home/username/public_html/videos/input.mp4"
    timeout="10"
    variable="ffmpegOutput"
    errorVariable="ffmpegError" />

<cfoutput>#ffmpegError#</cfoutput>

Note: FFmpeg outputs file information to stderr rather than stdout, so use the errorVariable attribute to capture it rather than variable.

Using FFmpeg in PHP

In PHP, FFmpeg is called using exec() or shell_exec(). Always use the full binary path and validate any user-supplied input before passing it to these functions.

Converting a video file

<?php
$ffmpeg = '/usr/bin/ffmpeg';
$input  = '/home/username/public_html/videos/input.mp4';
$output = '/home/username/public_html/videos/output.mp4';

$command = escapeshellcmd("$ffmpeg -i $input -c:v libx264 -crf 23 $output") . ' 2>&1';
$result  = shell_exec($command);

echo '<pre>' . htmlspecialchars($result) . '</pre>';
?>

Generating a thumbnail from a video

<?php
$ffmpeg    = '/usr/bin/ffmpeg';
$input     = '/home/username/public_html/videos/input.mp4';
$thumbnail = '/home/username/public_html/images/thumbnail.jpg';
$timestamp = '00:00:02'; // capture frame at 2 seconds in

$command = escapeshellcmd("$ffmpeg -i $input -ss $timestamp -vframes 1 $thumbnail") . ' 2>&1';
$result  = shell_exec($command);
?>

Getting video file information

<?php
$ffmpeg = '/usr/bin/ffmpeg';
$input  = '/home/username/public_html/videos/input.mp4';

// FFmpeg outputs file info to stderr, so redirect with 2>&1
$command = escapeshellcmd("$ffmpeg -i $input") . ' 2>&1';
$result  = shell_exec($command);

echo '<pre>' . htmlspecialchars($result) . '</pre>';
?>

Running FFmpeg as a background process

For large files, video conversion can take a long time and will cause a PHP timeout if run synchronously. Run FFmpeg in the background and check for the output file's existence instead:

<?php
$ffmpeg = '/usr/bin/ffmpeg';
$input  = '/home/username/public_html/videos/input.mp4';
$output = '/home/username/public_html/videos/output.mp4';
$log    = '/home/username/logs/ffmpeg.log';

// Runs FFmpeg in the background — PHP continues immediately
$command = "$ffmpeg -i $input -c:v libx264 $output > $log 2>&1 &";
exec($command);

// Later, check whether conversion is complete
if (file_exists($output)) {
    echo 'Conversion complete.';
} else {
    echo 'Still processing...';
}
?>

Security note: Always use escapeshellcmd() and escapeshellarg() when building FFmpeg commands from any user-supplied data such as uploaded filenames. Never pass raw user input directly into a shell command.

If you have SSH access to your server, you can run FFmpeg commands directly from the command line for testing:

Troubleshooting

CFExecute times out during conversion

Video conversion can take a long time for large files. Increase the timeout attribute on your <cfexecute> tag. For long conversions, consider running FFmpeg as a background process and checking for the output file's existence rather than waiting for the process to complete.

Permission denied error

The web server user needs execute permission on the FFmpeg binary and read/write permission on the input and output file paths. On shared hosting, files in your public_html directory are accessible. If you are using a custom path, check the permissions with ls -la /usr/bin/ffmpeg.

Output file is not being created

Check the errorVariable output from <cfexecute> for the actual FFmpeg error message. Common causes are an unsupported input format, a missing codec, or an invalid output path.

If you need FFmpeg installed or have a query about its configuration on your server, open a support ticket and our team can assist.