foxws/laravel-media

Laravel Media

Probe, encode, package and stream audio and video in Laravel with ffprobe and ffmpeg, on any Laravel disk.

• Probe files into typed streams, chapters and formats, and validate uploads by what they really contain.
• Encode with presets, filters, watermarks, HDR to SDR tone mapping, several outputs in one run, and rendition ladders with optional GPU encoding.
• Process clips, frames, subtitles, scene detection, reels and seek-preview thumbnail sprites.
• Stream HLS (CMAF or MPEG-TS) and DASH straight from the stored files, cutting segments on request like nginx-vod-module, with per-request encryption, subtitles, thumbnails, chapters, trick play and multiple audio languages.
• Package renditions into static HLS and DASH with ClearKey encryption, and serve private manifests with signed URLs.
• Export to local or S3 disks with concurrent multipart uploads, and follow progress, events and retryable failures from queued jobs.
• Test without ffmpeg using Media::fake().

It builds ffmpeg commands directly, without php-ffmpeg underneath, so any ffmpeg option is available without waiting on a package release.

See the full documentation: Installation, Opening and probing, Encoding, Streaming, Packaging, Queues, progress and errors, Testing, Configuration, Extending.

Requirements

• PHP 8.4 or higher, with the OpenSSL extension
• Laravel 13
• ffmpeg and ffprobe
• league/flysystem-aws-s3-v3 for S3 disks

Installation

composer require foxws/laravel-media

php artisan vendor:publish --tag="media-config"

Check that ffmpeg and ffprobe are found:

php artisan media:info

See Installation for the scheduled commands and queue setup.

[!TIP] Let your AI agent do the hard parts. This package ships a Laravel Boost skill, laravel-media-development, that teaches your agent how to install, configure and use Laravel Media. Install Boost and select the skill when prompted:

composer require laravel/boost --dev
php artisan boost:install

Already using Boost? Run php artisan boost:update --discover to pick up the skill. Then just ask, for example: "Transcode uploaded videos from S3 to 720p H.264 on a queue."

Quick start

Probe a file and encode a clip of it to another disk:

use Foxws\Media\Encoding\Format;
use Foxws\Media\Facades\Media;

$media = Media::fromDisk('s3')->open('videos/clip.mp4');

$media->probe()->duration();              // 93.4
$media->probe()->videoStream()?->height;  // 1080

$media->ffmpeg()
    ->clip(from: 12.5, to: 40)
    ->inFormat(Format::h264(crf: 22))
    ->toDisk('clips')
    ->save('intro.mp4');

Encode renditions once, then stream them as HLS and DASH without packaging them first:

use Foxws\Media\Encoding\Ladder;
use Foxws\Media\Facades\MediaStream;

// in a queued job
$result = Media::fromDisk('uploads')->open($upload)
    ->ladder(Ladder::standard(), "videos/{$video->id}/{height}p.mp4")
    ->toDisk('videos')
    ->save();

// AppServiceProvider::boot()
MediaStream::define('videos', fn (Video $video) => Media::fromDisk('videos')->open($video->renditions)
    ->stream()
    ->withChapters()
    ->withTrickPlay());

// routes/web.php
Route::middleware('auth')->group(fn () => Route::mediaStream('videos/{video}', 'videos'));

// the URL to give the player
MediaStream::url('videos', ['video' => $video]);

See Streaming for subtitles, thumbnails, encryption and the segment cache.

Testing

composer test

Links

• CHANGELOG
• Security policy
• ffmpeg documentation

Credits

• francoism90
• All Contributors

This package started from ideas in Laravel FFMpeg and nginx-vod-module.

Used by Stry, a self-hosted video streaming app.

AI, specifically Claude, was used to help build this package. All AI-assisted output is reviewed by me, and I retain final say over everything that is implemented and released.

License

MIT. See License File.