Installation

Pre-release

ext-ffmpeg is pre-release. Building from source works today; the PIE and prebuilt-binary paths below are the intended distribution and aren’t published yet. Want them sooner? Sponsor the project — and support FFmpeg too.

Requirements

• PHP ≥ 8.4 (non-thread-safe builds are what we test; ZTS should work but is untested).
• FFmpeg ≥ 7.0 shared libraries present at runtime — libavformat, libavcodec, libavutil, libswscale, libswresample. Developed and tested against FFmpeg 7.1.
• A C toolchain + phpize (the PHP development headers) for the source / PIE builds.

Install the FFmpeg libraries with your package manager:

# macOS
brew install ffmpeg

# Debian / Ubuntu
sudo apt install libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libswresample-dev

Install

PIE (recommended) — coming with the first release

PIE is the PHP Foundation’s modern extension installer (the successor to PECL). Once ext-ffmpeg is published:

pie install artisan-build/ext-ffmpeg

PIE compiles the extension against your PHP and FFmpeg and enables it for you. If FFmpeg isn’t auto-detected via pkg-config, point PIE at it:

pie install artisan-build/ext-ffmpeg --with-ffmpeg=/path/to/ffmpeg/prefix

From source — works today

git clone https://github.com/artisan-build/ext-ffmpeg
cd ext-ffmpeg/ext
phpize
./configure            # or: ./configure --with-ffmpeg="$(brew --prefix ffmpeg)"
make
sudo make install

configure finds FFmpeg via pkg-config; if your FFmpeg isn’t on the default PKG_CONFIG_PATH, pass --with-ffmpeg=<prefix> (a directory containing lib/pkgconfig).

Prebuilt binary — planned

Prebuilt .so files (per PHP version / OS / architecture) will be attached to GitHub Releases. These will be self-contained — FFmpeg is statically bundled in, so you do not need FFmpeg installed on the system. Drop the matching ffmpeg.so into your PHP extension_dir and enable it (below). This is the path for managed hosts (e.g. Laravel Cloud) where you can load a custom extension but can’t install system binaries.

Enable & verify

Add the extension to your php.ini (PIE does this automatically):

extension=ffmpeg

Then confirm it’s loaded:

php -m | grep ffmpeg
php -r 'var_dump(extension_loaded("ffmpeg"));'

Now head to the Introduction for a 60-second tour.