Errors

General Behaviour

When PyAV encounters an FFmpeg error, it raises an appropriate exception.

FFmpeg has a couple dozen of its own error types which we represent via Error Exception Classes and at a lower level via Error Type Enumerations.

FFmpeg will also return more typical errors such as ENOENT or EAGAIN, which we do our best to translate to extensions of the builtin exceptions as defined by PEP 3151 (and fall back onto OSError if using Python < 3.3).

Error Type Enumerations

We provide av.error.ErrorType as an enumeration of the various FFmpeg errors. To mimick the stdlib errno module, all enumeration values are available in the av.error module, e.g.:

try:
    do_something()
except OSError as e:
    if e.errno != av.error.FILTER_NOT_FOUND:
        raise
    handle_error()
class av.error.ErrorType

Bases: av.enum.EnumItem

An enumeration of FFmpeg’s error types.

tag

The FFmpeg byte tag for the error.

strerror

The error message that would be returned.

Error Exception Classes

PyAV raises the typical builtin exceptions within its own codebase, but things get a little more complex when it comes to translating FFmpeg errors.

There are two competing ideas that have influenced the final design:

  1. We want every exception that originates within FFmpeg to inherit from a common FFmpegError exception;

  2. We want to use the builtin exceptions whenever possible.

As such, PyAV effectivly shadows as much of the builtin exception heirarchy as it requires, extending from both the builtins and from FFmpegError.

Therefore, an argument error within FFmpeg will raise a av.error.ValueError, which can be caught via either FFmpegError or ValueError. All of these exceptions expose the typical errno and strerror attributes (even ValueError which doesn’t typically), as well as some PyAV extensions such as FFmpegError.log.

All of these exceptions are available on the top-level av package, e.g.:

try:
    do_something()
except av.FilterNotFoundError:
    handle_error()
class av.FFmpegError(code, message, filename=None, log=None)

Bases: Exception

Exception class for errors from within FFmpeg.

errno

FFmpeg’s integer error code.

strerror

FFmpeg’s error message.

filename

The filename that was being operated on (if available).

type

The av.error.ErrorType enum value for the error type.

log

The tuple from av.logging.get_last_log(), or None.

Mapping Codes and Classes

Here is how the classes line up with the error codes/enumerations:

Exception Class

Code/Enum Name

FFmpeg Error Message

av.BSFNotFoundError

av.error.BSF_NOT_FOUND

Bitstream filter not found

av.BugError

av.error.BUG

Internal bug, should not have happened

av.BufferTooSmallError

av.error.BUFFER_TOO_SMALL

Buffer too small

av.DecoderNotFoundError

av.error.DECODER_NOT_FOUND

Decoder not found

av.DemuxerNotFoundError

av.error.DEMUXER_NOT_FOUND

Demuxer not found

av.EncoderNotFoundError

av.error.ENCODER_NOT_FOUND

Encoder not found

av.EOFError

av.error.EOF

End of file

av.ExitError

av.error.EXIT

Immediate exit requested

av.ExternalError

av.error.EXTERNAL

Generic error in an external library

av.FilterNotFoundError

av.error.FILTER_NOT_FOUND

Filter not found

av.InvalidDataError

av.error.INVALIDDATA

Invalid data found when processing input

av.MuxerNotFoundError

av.error.MUXER_NOT_FOUND

Muxer not found

av.OptionNotFoundError

av.error.OPTION_NOT_FOUND

Option not found

av.PatchWelcomeError

av.error.PATCHWELCOME

Not yet implemented in FFmpeg, patches welcome

av.ProtocolNotFoundError

av.error.PROTOCOL_NOT_FOUND

Protocol not found

av.UnknownError

av.error.UNKNOWN

Unknown error occurred

av.ExperimentalError

av.error.EXPERIMENTAL

Experimental feature

av.InputChangedError

av.error.INPUT_CHANGED

Input changed

av.OutputChangedError

av.error.OUTPUT_CHANGED

Output changed

av.HTTPBadRequestError

av.error.HTTP_BAD_REQUEST

Server returned 400 Bad Request

av.HTTPUnauthorizedError

av.error.HTTP_UNAUTHORIZED

Server returned 401 Unauthorized (authorization failed)

av.HTTPForbiddenError

av.error.HTTP_FORBIDDEN

Server returned 403 Forbidden (access denied)

av.HTTPNotFoundError

av.error.HTTP_NOT_FOUND

Server returned 404 Not Found

av.HTTPOtherClientError

av.error.HTTP_OTHER_4XX

Server returned 4XX Client Error, but not one of 40{0,1,3,4}

av.HTTPServerError

av.error.HTTP_SERVER_ERROR

Server returned 5XX Server Error reply