Introduction

ext-ffmpeg is a native PHP extension that binds the FFmpeg libraries (libavformat, libavcodec, libavutil, libswscale, libswresample) directly — in pure C against the Zend API. No shell_exec, no CLI string-building, no FFI. You call methods; FFmpeg runs in-process, and failures come back as real typed exceptions instead of text on stderr.

It’s an Artisan Build project, built on FFmpeg (an independent binding — not affiliated with the FFmpeg project).

Quick start

use FFmpeg\Media;
use FFmpeg\MediaEncoder;
use FFmpeg\Codec\VideoCodec;
use FFmpeg\Codec\AudioCodec;

// Open + probe (eager: avformat_open_input + find_stream_info)
$media = Media::open('input.mp4');
echo "{$media->format}, {$media->duration}s\n";

$v = $media->videoStream();
echo "{$v->width}x{$v->height} {$v->codec}\n";

// Transcode: re-encode video to H.264, stream-copy audio, write to disk
(new MediaEncoder())
    ->addVideo($media->videoStream(), VideoCodec::H264)
    ->addAudio($media->audioStream(), AudioCodec::Copy)
    ->save('output.mp4');

The v1 surface

Open → probe → transcode → save: one video + one audio mapping, re-encode or stream-copy. Filters, per-frame callbacks, subtitles, and HLS are later waves.

• Media — open & probe a file; access stream views
• VideoStream / AudioStream — typed stream views
• MediaEncoder — compose output; re-encode or copy
• VideoCodec / AudioCodec — codec choices
• Exceptions — typed errors carrying ->operation + ->avError

Errors

Every FFmpeg failure raises a typed FFmpeg\Exception\* carrying the failing call (->operation) and the av_strerror() text (->avError). Catch the base FFmpeg\Exception\FFmpegException to handle them all.