repository·main·Indexed 23 days ago
https://github.com/protonemedia/laravel-ffmpegA wrapper around PHP-FFMpeg that integrates with Laravel's Filesystem, configuration, and logging systems for video processing. It supports audio/video conversion, HLS adaptive bitrate streaming with AES-128 encryption, frame extraction, watermarking, and video tiling. The library provides tools for monitoring transcoding progress, handling encoding exceptions, and managing temporary files from remote disks.
The object returned by open() is a ProtoneMedia\LaravelFFMpeg\MediaOpener. It uses dynamic method calls to proxy requests to the underlying driver (e.g., PHP-FFMpeg).
MediaOpener instance.To secure HLS exports, use withEncryptionKey() on the HLS exporter.
ProtoneMedia\LaravelFFMpeg\Exporters\HLSExporter::generateEncryptionKey().secret.key, but you can pass a second argument to withEncryptionKey() to change it.Warning: You must store the generated key securely; the exported video cannot be played without it.
use ProtoneMedia\LaravelFFMpeg\Exporters\HLSExporter;
$encryptionKey = HLSExporter::generateEncryptionKey();
FFMpeg::open('steve_howe.mp4')
->exportForHLS()
->withEncryptionKey($encryptionKey)
->addFormat($lowBitrate)
->addFormat($midBitrate)
->addFormat($highBitrate)
->save('adaptive_steve.m3u8');You can convert files by specifying a source disk, opening a file, defining an export format, and choosing a destination disk and filename. Use fromDisk($disk) to specify the source disk, or fromFilesystem($filesystem) to use an instance of Illuminate\\Contracts\\Filesystem\\Filesystem.
FFMpeg::fromDisk('songs')
->open('yesterday.mp3')
->export()
->toDisk('converted_songs')
->inFormat(new \FFMpeg\Format\Audio\Aac)
->save('yesterday.aac');You can export videos to HLS format to enable adaptive bitrate streaming. Use exportForHLS() on an opened media file. You can define multiple bitrates using addFormat() to create an adaptive stream.
Key methods:
setSegmentLength(int): Set the duration of each segment (optional).setKeyFrameInterval(int): Set the keyframe interval (optional).keepAllAudioStreams(): By default, HLS exports only include the first audio stream (0:a:0). Call this to include all audio streams.$lowBitrate = (new X264)->setKiloBitrate(250);
$midBitrate = (new X264)->setKiloBitrate(500);
$highBitrate = (new X264)->setKiloBitrate(1000);
FFMpeg::fromDisk('videos')
->open('steve_howe.mp4')
->exportForHLS()
->setSegmentLength(10)
->setKeyFrameInterval(48)
->addFormat($lowBitrate)
->addFormat($midBitrate)
->addFormat($highBitrate)
->save('adaptive_steve.m3u8');To use Laravel FFMpeg, ensure you have the latest version of FFmpeg installed on your system by running ffmpeg -version. Then, install the package via Composer.
If you are not using Laravel's Package Discovery, you must manually register the Service Provider and the Facade in your config/app.php file. Finally, publish the configuration file to your application using the Artisan CLI.
When upgrading to version 8, note the following breaking changes and configuration updates:
set_command_and_error_output_on_exception config key now defaults to true, providing more informative error messages.enable_logging key has been replaced by log_channel. To disable logging entirely, set log_channel to false.2 or greater.spatie/image is upgraded to v2.For higher security, you can rotate the encryption key for every segment using withRotatingEncryptionKey().
$filename and $contents of the key. Use this to save keys to your database or storage.1 (one key per segment).Performance Tip: On slow filesystems, rotating keys might cause encoding exceptions like No key URI specified in key info file. To mitigate this, you can set a tmpfs filesystem (like /dev/shm on Linux) in the temporary_files_encrypted_hls config key.
FFMpeg::open('steve_howe.mp4')
->exportForHLS()
->withRotatingEncryptionKey(function ($filename, $contents) {
$videoId = 1;
// Store the encryption keys (e.g., in DB or Storage)
Storage::disk('secrets')->put($videoId . '/' . $filename, $contents);
})
->addFormat($lowBitrate)
->addFormat($midBitrate)
->addFormat($highBitrate)
->save('adaptive_steve.m3u8');
// To rotate every 10 segments:
// ->withRotatingEncryptionKey($callable, 10);When upgrading to version 7, note the following major changes:
ProtoneMedia\LaravelFFMpeg. The Facade is now ProtoneMedia\LaravelFFMpeg\Support\FFMpeg and the Service Provider is ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider.map and filter_complex features instead of separate jobs. You may need to replace addFilter with addLegacyFilter or migrate filters manually.To prevent unauthorized access to HLS segments and keys, use the DynamicHLSPlaylist class. This allows you to serve playlists through Laravel routes where you can implement authentication/authorization (e.g., via Gates or Middleware).
Instead of linking directly to a file on a public disk, you use FFMpeg::dynamicHLSPlaylist() to resolve paths dynamically via three resolvers:
setKeyUrlResolver: Maps a relative key path to a secure route/URL.setMediaUrlResolver: Maps a relative media segment path to a public URL.setPlaylistUrlResolver: Maps a relative playlist path to a route/URL.The DynamicHLSPlaylist instance implements Illuminate\Contracts\Support\Responsable, so it can be returned directly from a controller.
// Route to serve the actual key file securely
Route::get('/video/secret/{key}', function ($key) {
return Storage::disk('secrets')->download($key);
})->name('video.key');
// Route to serve the dynamic playlist
Route::get('/video/{playlist}', function ($playlist) {
return FFMpeg::dynamicHLSPlaylist()
->fromDisk('public')
->open($playlist)
->setKeyUrlResolver(function ($key) {
return route('video.key', ['key' => $key]);
})
->setMediaUrlResolver(function ($mediaFilename) {
return Storage::disk('public')->url($mediaFilename);
})
->setPlaylistUrlResolver(function ($playlistFilename) {
return route('video.playlist', ['playlist' => $playlistFilename]);
});
})->name('video.playlist');If Package Discovery is disabled, add the following to your config/app.php file:
'providers' => [
...
ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider::class,
...
],
'aliases' => [
...
'FFMpeg' => ProtoneMedia\LaravelFFMpeg\Support\FFMpeg::class
...
];// config/app.php
'providers' => [
...
ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider::class,
...
];
'aliases' => [
...
'FFMpeg' => ProtoneMedia\LaravelFFMpeg\Support\FFMpeg::class
...
];The PHPFFMpeg class is the primary driver used to interact with media files via the underlying PHP-FFMpeg library. It acts as a wrapper that provides Laravel-friendly methods for opening media collections, handling video/audio types, and managing complex operations like concatenation or frame extraction.
Key capabilities include:
MediaCollection (which can trigger 'Advanced' mode for multiple files).Video, Audio, Frame, or Concat object.$this to allow chaining, or return a new media object when the state changes (e.g., extracting a frame).Disk class uses the ForwardsCalls trait to proxy all method calls to the underlying Laravel FilesystemAdapter. This means you can call any standard Laravel storage method (like exists(), put(), delete(), get(), etc.) directly on the Disk instance.