Exceptions

Every FFmpeg failure surfaces as a typed exception under FFmpeg\Exception\. Each one carries the failing FFmpeg call and the decoded error text, so you never parse a message string.

Properties (on every exception)

Property	Type	Description
$operation	string	The FFmpeg API call that failed, e.g. "avcodec_open2".
$avError	string	The av_strerror() text for the failing AVERROR, when there was one.

getMessage() returns "{$operation}: {$avError}".

Hierarchy

FFmpegException                 (base — extends \Exception)
├── FileNotFoundException       input path did not exist
├── InvalidFormatException      opened but not valid/probeable media
├── StreamNotFoundException     a requested stream was not present
├── EncoderNotFoundException    chosen encoder not built into this FFmpeg
├── EncodingException           a failure during encoding / muxing
└── InvalidExpressionException  a filter expression failed to parse / evaluate

InvalidExpressionException is the one you’ll catch most while authoring filters: a malformed expression (a stray operator, an unknown variable) throws it the moment the filter is constructed — at that line, before anything runs — so you can pinpoint the bad expression in a long chain. Catch it to handle “my expression was wrong” distinctly from an I/O or encoding failure.

Catch the base FFmpegException to handle everything, or a leaf for a specific case.

Example

use FFmpeg\Media;
use FFmpeg\Exception\{FileNotFoundException, FFmpegException};

try {
    $media = Media::open($path);
} catch (FileNotFoundException $e) {
    // handle a missing file specifically
} catch (FFmpegException $e) {
    fprintf(STDERR, "ffmpeg failed in %s: %s\n", $e->operation, $e->avError);
}