ffmpy3

exception ffmpy3.FFExecutableNotFoundError[source]

Raised when FFmpeg/FFprobe executable was not found.

exception ffmpy3.FFRuntimeError(cmd, exit_code, stdout=b'', stderr=b'')[source]

Raised when FFmpeg/FFprobe command line execution returns a non-zero exit code.

cmd

The command used to launch the executable, with all command line options.

Type:str
exit_code

The resulting exit code from the executable.

Type:int
stdout

The contents of stdout (only if executed synchronously).

Type:bytes
stderr

The contents of stderr (only if executed synchronously).

Type:bytes
class ffmpy3.FFmpeg(executable='ffmpeg', global_options=None, inputs=None, outputs=None)[source]

Wrapper for various FFmpeg related applications (ffmpeg, ffprobe).

Compiles FFmpeg command line from passed arguments (executable path, options, inputs and outputs).

inputs and outputs are dictionaries containing inputs/outputs as keys and their respective options as values.

One dictionary value (set of options) must be either a single space separated string, or a list or strings without spaces (i.e. each part of the option is a separate item of the list, the result of calling split() on the options string).

If the value is a list, it cannot be mixed, i.e. cannot contain items with spaces. An exception are complex FFmpeg command lines that contain quotes: the quoted part must be one string, even if it contains spaces (see Examples for more info).

Parameters:
  • executable (str) – path to ffmpeg executable; by default the ffmpeg command will be searched for in the PATH, but can be overridden with an absolute path to ffmpeg executable
  • global_options (iterable) – global options passed to ffmpeg executable (e.g. -y, -v etc.); can be specified either as a list/tuple/set of strings, or one space-separated string; by default no global options are passed
  • inputs (dict) – a dictionary specifying one or more input arguments as keys with their corresponding options (either as a list of strings or a single space separated string) as values
  • outputs (dict) – a dictionary specifying one or more output arguments as keys with their corresponding options (either as a list of strings or a single space separated string) as values
run(input_data=None, stdout=None, stderr=None)[source]

Execute FFmpeg command line.

input_data can contain input for FFmpeg in case pipe protocol is used for input.

stdout and stderr specify where to redirect the stdout and stderr of the process. By default no redirection is done, which means all output goes to running shell (this mode should normally only be used for debugging purposes).

If FFmpeg pipe protocol is used for output, stdout must be redirected to a pipe by passing subprocess.PIPE as stdout argument.

Returns a 2-tuple containing stdout and stderr of the process. If there was no redirection or if the output was redirected to e.g. os.devnull, the value returned will be a tuple of two None values, otherwise it will contain the actual stdout and stderr data returned by ffmpeg process.

Parameters:
  • input_data (bytes) – input data for FFmpeg to deal with (audio, video etc.) as bytes (e.g. the result of reading a file in binary mode)
  • stdout – Where to redirect FFmpeg stdout to. Default is None, meaning no redirection.
  • stderr – Where to redirect FFmpeg stderr to. Default is None, meaning no redirection.
Raises:
Returns:

A 2-tuple containing stdout and stderr from the process.
Return type:

tuple
run_async(input_data=None, stdout=None, stderr=None)[source]

Asynchronously execute FFmpeg command line.

input_data can contain input for FFmpeg in case pipe

stdout and stderr specify where to redirect the stdout and stderr of the process. By default no redirection is done, which means all output goes to running shell (this mode should normally only be used for debugging purposes).

If FFmpeg pipe protocol is used for output, stdout must be redirected to a pipe by passing subprocess.PIPE as stdout argument.

Note that the parent process is responsible for reading any output from stdout/stderr. This should be done even if the output will not be used since the process may otherwise deadlock. This can be done by awaiting on asyncio.subprocess.Process.communicate() on the returned asyncio.subprocess.Process or by manually reading from the streams as necessary.

Returns a reference to the child process created for use by the parent program.

Parameters:
  • input_data (bytes) – input data for FFmpeg to deal with (audio, video etc.) as bytes (e.g. the result of reading a file in binary mode)
  • stdout – Where to redirect FFmpeg stdout to. Default is None, meaning no redirection.
  • stderr – Where to redirect FFmpeg stderr to. Default is None, meaning no redirection.
Raises:

FFExecutableNotFoundError – The executable path passed was not valid.
Returns:

The child process created.
Return type:

asyncio.subprocess.Process
wait()[source]

Asynchronously wait for the process to complete execution.

Raises:FFRuntimeError – The process exited with an error.
Returns:0 if the process finished successfully, or None if it has not been started
Return type:int or None
class ffmpy3.FFprobe(executable='ffprobe', global_options='', inputs=None)[source]

Wrapper for ffprobe.

Compiles FFprobe command line from passed arguments (executable path, options, inputs). FFprobe executable by default is taken from PATH but can be overridden with an absolute path.

Parameters:
  • executable (str) – absolute path to ffprobe executable
  • global_options (iterable) – global options passed to ffprobe executable; can be specified either as a list/tuple of strings or a space-separated string
  • inputs (dict) – a dictionary specifying one or more inputs as keys with their corresponding options as values