README

FFmphp

A simple, clean, and elegant way to run FFmpeg from your php applications.

Installation

You will need a working install of FFmpeg (and FFprobe) in your system (https://www.ffmpeg.org/download.html).

This library can be installed via composer:

$ composer require tbritz/ffmphp

As long as ffmpeg and ffprobe are available from your system's PATH variable, this library should use them automatically. If not, you can configure FFmphp before using it:

FFmphp::configure([
    'ffmpeg' => 'C:\ffmpeg\ffmpeg.exe',
    'ffprobe' => 'C:\ffmpeg\ffprobe.exe',
    'timeout' => 0, // default, no timeout (in seconds)
]);

These settings will be applied to all FFmphp calls for the remainder of the script execution.

Basic Usage

Video Transcoding

Getting started is easy. Converting a video can be as simple as this command:

FFmphp::load($infile)
    ->save('outfile.mp4')
    ->run();

FFmpeg will guess the output type based on the extension.

Most of the time, however, you will give save() the name of an OutputFormat:

FFmphp::load($infile)
    ->save('outfile.mp4', 'FFmphp\Formats\Video\MP4')
    ->run();

For the rest of the document we will use php's ::class syntax instead of providing the fully qualified class name of the format. Here is what the previous example looks like when it is rewritten:

use FFmphp\Formats\Video\MP4;

FFmphp::load($infile)
    ->save('outfile.mp4', MP4::class)
    ->run();

Extracting Audio Tracks from Video

Working with audio formats is just as easy:

FFmphp::load($infile)
    ->save('outfile.mp3', MP3::class)
    ->run();

Saving Thumbnails

Saving a video poster, or thumbnail image, works the same way:

FFmphp::load($file)
    ->save('thumbnail.jpg')
    ->run();

FFmphp::load($file)
    ->save('poster.jpg', Poster::class)
    ->run();

Saving Tiled/Mosaic Images

You guessed it:

FFmphp::load($file)
    ->save('preview-4x3.jpg', TileFourByThree::class)
    ->run();

Save Multiple Files with One Command

You can add an arbitrary number of outputs with one command. For example:

FFmphp::load($input)
    ->save('output.mp4', MP4::class)
    ->save('output.webm', Webm::class)
    ->save('output-audio.mp3', MP3::class)
    ->save('poster.jpg', Poster::class)
    ->save('preview-5x5.jpg', TileFiveByFive::class)
    ->run();

The above command would run FFmpeg once and create 5 files.

Note: This is only provided as an example. Although the code may be more readable and make it easier to reason about the overall progress (or failures) during conversion, actual memory usage of FFmpeg increases for every output stream. In many cases the number of outputs you can chain on a single command instance will be limited by the available system memory and the resolution of your video streams.

Advanced Usage

Output Formats

The best way to keep your project organized is to create an OutputFormat class for every type of file that you will save. An output format includes codecs, bitrate, container, resolution, and more. Don't worry, it's actually much simpler than it sounds!

To make it easier to start writing code, these formats are included:

You are welcome to use these classes in your own application, however in most cases it is better to use them only as a reference, and instead create your own formats which are tuned to the unique requirements of your application.

You can either create your class from scratch, or you may extend another format. Your class must implement the FFmphp\Formats\OutputFormat interface, which has one method: build().

For example, you may wish to create a format which is specifically tuned for animation content by extending the existing MP4 class:

<?php

use FFmphp\Formats\Video\MP4;

class MP4Anime extends MP4
{
    public function build()
    {
        return parent::build()->withOption('-tune', 'animation');
    }
}

Or perhaps you want more control over the default encoder options. Here is an another complete example, this time creating a new MP4 format from scratch:

<?php

use FFmphp\Formats\InteractsWithOutput;
use FFmphp\Formats\OutputFormat;

class MyMP4 implements OutputFormat
{
    use InteractsWithOutput;

    public function build()
    {
        return $this->withOptions([
            '-vcodec' => 'libx264',
            '-acodec' => 'aac',
            '-b:a' => '128k',
            '-preset' => 'slower',
            '-crf' => '26',
            '-max_muxing_queue_size' => '9999',
            '-movflags' => '+faststart',
            '-threads' => '4',
        ]);
    }
}

To use your output format, simply reference it in save():

->save('output.mp4', MyMP4::class)

Getting the Command

If you want to inspect the command that will be run (without running it), you can use the toCommand() method:

FFmphp::load($input)
    ->save('output.mp4', MP4::class)
    ->toCommand();

Which will return a string like this:

ffmpeg -i "/path/to/input.mp4" -acodec aac -vcodec libx264 -b:a 128k -preset slower "output.mp4"

Conditionally Adding Output Streams

You may want to add some output formats only when certain conditions are met. You can use when() for those situations. For example, you might want to create a 1080p version of a video only when the source resolution was high enough:

$is_hd = true;

FFmphp::load($input)
    ->save('output.webm', Webm::class)
    ->when($is_hd, function ($command) {
        $command->save('output-1080p.webm', Webm1080p::class);
    })
    ->save('thumbnail.jpg', Thumbnail::class)
    ->run();

The second parameter of when() accepts a function that will only be applied when the first argument is true.

Adding Encoder Options

The third parameter of save() accepts an associative array of options that will be added to the output. In some cases this may be more convenient than creating a new class for each output type.

FFmphp::load($input)
    ->save('output.mp4', MP4::class, ['-preset' => 'veryslow', '-crf' => '28',])
    ->run();

The third argument can also be a closure, if you need more control:

FFmphp::load($input)
    ->save('output.mp4', MP4::class, function (StreamBuilder $output) {
        return $output->withOption('-preset', 'veryslow')
                      ->withOption('-crf', '28');
    })
    ->run();

Using this feature excessively will make your code harder to read, which is why it is recommended instead to have a class for every type of output.

The Progress Callback

The run() method accepts an optional callback function, which will be run approximately once every second for as long as FFmpeg is running. The function will receive the current time position of the input as reported by FFmpeg, formatted like 00:00:00.00.

For example:

FFmphp::load($input)
    ->save('output.mp4')
    ->run(function ($time) {
        // Logic for notifying users of progress updates
    });

Raw Commands

The raw() method is perfect if you need more control, have complicated filters, or already know FFmpeg and just want the convenience of the php integration. The raw() method takes an array of arguments to be passed to FFmpeg.

FFmphp::raw([
        '-y',
        '-i',
        'input.mp4',
        'output.mp4',
    ])
    ->run();

tbritz / ffmphp

Maintainers

Details