Laravel FFMpeg

This package provides an integration with FFmpeg for Laravel 10. Laravel's Filesystem handles the storage of the files.

Sponsor this package!

❤️ We proudly support the community by developing Laravel packages and giving them away for free. If this package saves you time or if you're relying on it professionally, please consider sponsoring the maintenance and development. Keeping track of issues and pull requests takes time, but we're happy to help!

Features

• Super easy wrapper around PHP-FFMpeg, including support for filters and other advanced features.
• Integration with Laravel's Filesystem, configuration system and logging handling.
• Compatible with Laravel 10, support for Package Discovery.
• Built-in support for HLS.
• Built-in support for encrypted HLS (AES-128) and rotating keys (optional).
• Built-in support for concatenation, multiple inputs/outputs, image sequences (timelapse), complex filters (and mapping), frame/thumbnail exports.
• Built-in support for watermarks (positioning and manipulation).
• Built-in support for creating a mosaic/sprite/tile from a video.
• Built-in support for generating VTT Preview Thumbnail files.
• Requires PHP 8.1 or higher.
• Tested with FFmpeg 4.4 and 5.0.

Installation

Verify you have the latest version of FFmpeg installed:

ffmpeg -version

You can install the package via composer:

composer require pbmedia/laravel-ffmpeg

Add the Service Provider and Facade to your app.php config file if you're not using Package Discovery.

// config/app.php

'providers' => [
    ...
    ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider::class,
    ...
];

'aliases' => [
    ...
    'FFMpeg' => ProtoneMedia\LaravelFFMpeg\Support\FFMpeg::class
    ...
];

Publish the config file using the artisan CLI tool:

php artisan vendor:publish --provider="ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider"

Upgrading to v8

• The set_command_and_error_output_on_exception configuration key now defaults to true, making exceptions more informative. Read more at the Handling exceptions section.
• The enable_logging configuration key has been replaced by log_channel to choose the log channel used when writing messages to the logs. If you still want to disable logging entirely, you may set the new configuration key to false.
• The segment length and keyframe interval of HLS exports should be 2 or more; less is not supported anymore.
• As Laravel 9 has migrated from Flysystem 1.x to 3.x, this version is not compatible with Laravel 8 or earlier.
• If you're using the Watermark manipulation feature, make sure you upgrade spatie/image to v2.

Upgrading to v7

• The namespace has changed to ProtoneMedia\LaravelFFMpeg, the facade has been renamed to ProtoneMedia\LaravelFFMpeg\Support\FFMpeg, and the Service Provider has been renamed to ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider.
• Chaining exports are still supported, but you have to reapply filters for each export.
• HLS playlists now include bitrate, framerate and resolution data. The segments also use a new naming pattern (read more). Please verify your exports still work in your player.
• HLS export is now executed as one job instead of exporting each format/stream separately. This uses FFMpeg's map and filter_complex features. It might be sufficient to replace all calls to addFilter with addLegacyFilter, but some filters should be migrated manually. Please read the documentation on HLS to find out more about adding filters.

Usage

Convert an audio or video file:

FFMpeg::fromDisk('songs')
    ->open('yesterday.mp3')
    ->export()
    ->toDisk('converted_songs')
    ->inFormat(new \FFMpeg\Format\Audio\Aac)
    ->save('yesterday.aac');

Instead of the fromDisk() method you can also use the fromFilesystem() method, where $filesystem is an instance of Illuminate\Contracts\Filesystem\Filesystem.

$media = FFMpeg::fromFilesystem($filesystem)->open('yesterday.mp3');

Progress monitoring

You can monitor the transcoding progress. Use the onProgress method to provide a callback, which gives you the completed percentage. In previous versions of this package you had to pass the callback to the format object.

FFMpeg::open('steve_howe.mp4')
    ->export()
    ->onProgress(function ($percentage) {
        echo "{$percentage}% transcoded";
    });

The callback may also expose $remaining (in seconds) and $rate:

FFMpeg::open('steve_howe.mp4')
    ->export()
    ->onProgress(function ($percentage, $remaining, $rate) {
        echo "{$remaining} seconds left at rate: {$rate}";
    });

Opening uploaded files

You can open uploaded files directly from the Request instance. It's probably better to first save the uploaded file in case the request aborts, but if you want to, you can open a UploadedFile instance:

class UploadVideoController
{
    public function __invoke(Request $request)
    {
        FFMpeg::open($request->file('video'));
    }
}

Open files from the web

You can open files from the web by using the openUrl method. You can specify custom HTTP headers with the optional second parameter:

FFMpeg::openUrl('https://videocoursebuilder.com/lesson-1.mp4');

FFMpeg::openUrl('https://videocoursebuilder.com/lesson-2.mp4', [
    'Authorization' => 'Basic YWRtaW46MTIzNA==',
]);

Handling exceptions

When the encoding fails, a ProtoneMedia\LaravelFFMpeg\Exporters\EncodingException shall be thrown, which extends the underlying FFMpeg\Exception\RuntimeException class. This class has two methods that can help you identify the problem. Using the getCommand method, you can get the executed command with all parameters. The getErrorOutput method gives you a full output log.

In previous versions of this package, the message of the exception was always Encoding failed. You can downgrade to this message by updating the set_command_and_error_output_on_exception configuration key to false.

try {
    FFMpeg::open('yesterday.mp3')
        ->export()
        ->inFormat(new Aac)
        ->save('yesterday.aac');
} catch (EncodingException $exception) {
    $command = $exception->getCommand();
    $errorLog = $exception->getErrorOutput();
}

Filters

You can add filters through a Closure or by using PHP-FFMpeg's Filter objects:

use FFMpeg\Filters\Video\VideoFilters;

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->addFilter(function (VideoFilters $filters) {
        $filters->resize(new \FFMpeg\Coordinate\Dimension(640, 480));
    })
    ->export()
    ->toDisk('converted_videos')
    ->inFormat(new \FFMpeg\Format\Video\X264)
    ->save('small_steve.mkv');

// or

$start = \FFMpeg\Coordinate\TimeCode::fromSeconds(5)
$clipFilter = new \FFMpeg\Filters\Video\ClipFilter($start);

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->addFilter($clipFilter)
    ->export()
    ->toDisk('converted_videos')
    ->inFormat(new \FFMpeg\Format\Video\X264)
    ->save('short_steve.mkv');

You can also call the addFilter method after the export method:

use FFMpeg\Filters\Video\VideoFilters;

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->export()
    ->toDisk('converted_videos')
    ->inFormat(new \FFMpeg\Format\Video\X264)
    ->addFilter(function (VideoFilters $filters) {
        $filters->resize(new \FFMpeg\Coordinate\Dimension(640, 480));
    })
    ->save('small_steve.mkv');

Resizing

Since resizing is a common operation, we've added a dedicated method for it:

FFMpeg::open('steve_howe.mp4')
    ->export()
    ->inFormat(new \FFMpeg\Format\Video\X264)
    ->resize(640, 480)
    ->save('steve_howe_resized.mp4');

The first argument is the width, and the second argument the height. The optional third argument is the mode. You can choose between fit (default), inset, width or height. The optional fourth argument is a boolean whether or not to force the use of standards ratios. You can find about these modes in the FFMpeg\Filters\Video\ResizeFilter class.

Custom filters

Sometimes you don't want to use the built-in filters. You can apply your own filter by providing a set of options. This can be an array or multiple strings as arguments:

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->addFilter(['-itsoffset', 1]);

// or

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->addFilter('-itsoffset', 1);

Watermark filter

You can easily add a watermark using the addWatermark method. With the WatermarkFactory, you can open your watermark file from a specific disk, just like opening an audio or video file. When you discard the fromDisk method, it uses the default disk specified in the filesystems.php configuration file.

After opening your watermark file, you can position it with the top, right, bottom, and left methods. The first parameter of these methods is the offset, which is optional and can be negative.

use ProtoneMedia\LaravelFFMpeg\Filters\WatermarkFactory;

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->addWatermark(function(WatermarkFactory $watermark) {
        $watermark->fromDisk('local')
            ->open('logo.png')
            ->right(25)
            ->bottom(25);
    });

Instead of using the position methods, you can also use the horizontalAlignment and verticalAlignment methods.

For horizontal alignment, you can use the WatermarkFactory::LEFT, WatermarkFactory::CENTER and WatermarkFactory::RIGHT constants. For vertical alignment, you can use the WatermarkFactory::TOP, WatermarkFactory::CENTER and WatermarkFactory::BOTTOM constants. Both methods take an optional second parameter, which is the offset.

FFMpeg::open('steve_howe.mp4')
    ->addWatermark(function(WatermarkFactory $watermark) {
        $watermark->open('logo.png')
            ->horizontalAlignment(WatermarkFactory::LEFT, 25)
            ->verticalAlignment(WatermarkFactory::TOP, 25);
    });

The WatermarkFactory also supports opening files from the web with the openUrl method. It supports custom HTTP headers as well.

FFMpeg::open('steve_howe.mp4')
    ->addWatermark(function(WatermarkFactory $watermark) {
        $watermark->openUrl('https://videocoursebuilder.com/logo.png');

        // or

        $watermark->openUrl('https://videocoursebuilder.com/logo.png', [
            'Authorization' => 'Basic YWRtaW46MTIzNA==',
        ]);
    });

If you want more control over the GET request, you can pass in an optional third parameter, which gives you the Curl resource.

$watermark->openUrl('https://videocoursebuilder.com/logo.png', [
    'Authorization' => 'Basic YWRtaW46MTIzNA==',
], function($curl) {
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
});

Watermark manipulation

This package can manipulate watermarks by using Spatie's Image package. To get started, install the package with Composer:

composer require spatie/image

Now you can chain one more manipulation methods on the WatermarkFactory instance:

FFMpeg::open('steve_howe.mp4')
    ->addWatermark(function(WatermarkFactory $watermark) {
        $watermark->open('logo.png')
            ->right(25)
            ->bottom(25)
            ->width(100)
            ->height(100)
            ->greyscale();
    });

Check out the documentation for all available methods.

Export without transcoding

This package comes with a ProtoneMedia\LaravelFFMpeg\FFMpeg\CopyFormat class that allows you to export a file without transcoding the streams. You might want to use this to use another container:

use ProtoneMedia\LaravelFFMpeg\FFMpeg\CopyFormat;

FFMpeg::open('video.mp4')
    ->export()
    ->inFormat(new CopyFormat)
    ->save('video.mkv');

Chain multiple convertions

// The 'fromDisk()' method is not required, the file will now
// be opened from the default 'disk', as specified in
// the config file.

FFMpeg::open('my_movie.mov')

    // export to FTP, converted in WMV
    ->export()
    ->toDisk('ftp')
    ->inFormat(new \FFMpeg\Format\Video\WMV)
    ->save('my_movie.wmv')

    // export to Amazon S3, converted in X264
    ->export()
    ->toDisk('s3')
    ->inFormat(new \FFMpeg\Format\Video\X264)
    ->save('my_movie.mkv');

    // you could even discard the 'toDisk()' method,
    // now the converted file will be saved to
    // the same disk as the source!
    ->export()
    ->inFormat(new FFMpeg\Format\Video\WebM)
    ->save('my_movie.webm')

    // optionally you could set the visibility
    // of the exported file
    ->export()
    ->inFormat(new FFMpeg\Format\Video\WebM)
    ->withVisibility('public')
    ->save('my_movie.webm')

Export a frame from a video

FFMpeg::fromDisk('videos')
    ->open('steve_howe.mp4')
    ->getFrameFromSeconds(10)
    ->export()
    ->toDisk('thumnails')
    ->save('FrameAt10sec.png');

// Instead of the 'getFrameFromSeconds()' method, you could
// also use the 'getFrameFromString()' or the
// 'getFrameFromTimecode()' methods:

$media = FFMpeg::open('steve_howe.mp4');
$frame = $media->getFrameFromString('00:00:13.37');

// or

$timecode = new FFMpeg\Coordinate\TimeCode(...);
$frame = $media->getFrameFromTimecode($timecode);

You can also get the raw contents of the frame instead of saving it to the filesystem:

$contents = FFMpeg::open('video.mp4')
    ->getFrameFromSeconds(2)
    ->export()
    ->getFrameContents();

Export multiple frames at once

There is a TileFilter that powers the Tile-feature. To make exporting multiple frames faster and simpler, we leveraged this feature to add some helper methods. For example, you may use the exportFramesByInterval method to export frames by a fixed interval. Alternatively, you may pass the number of frames you want to export to the exportFramesByAmount method, which will then calculate the interval based on the duration of the video.

FFMpeg::open('video.mp4')
    ->exportFramesByInterval(2)
    ->save('thumb_%05d.jpg');

Both methods accept an optional second and third argument to specify to width and height of the frames. Instead of passing both the width and height, you may also pass just one of them. FFmpeg will respect the