ffmpegio.ffmpegprocess: Direct invocation of FFmpeg subprocess

Instead of indirectly calling FFmpeg with ffmpegio’s Basic I/O Functions, you can directly invoke a FFmpeg subprocess with ffmpegio.ffmpegprocess module, which mocks Python’s builtin subprocess module.

ffmpegio.ffmpegprocess.run	run FFmpeg subprocess with standard pipes with a single transaction
ffmpegio.ffmpegprocess.run_two_pass	run FFmpeg subprocess with standard pipes with a single transaction twice for 2-pass encoding
ffmpegio.ffmpegprocess.Popen	Execute FFmpeg in a new process.

While both ffmpegio.ffmpegprocess.run() and ffmpegio.ffmpegprocess.Popen constructor accepts the args argument of Python’s subprocess.run() and subprocess.Popen constructor, the FFmpeg command argument can also be specified with a Python dict: see its specification page for the details.

ffmpegio.ffmpegprocess.run_two_pass() runs FFmpeg twice to perform two-pass video encoding. The audio encoding is automatically disabled during the first pass by default. It also offers a finer control of which options to turn on/off during the first pass.

ffmpegio.ffmpegprocess Module Reference

ffmpegio.ffmpegprocess.run(ffmpeg_args, *, hide_banner=True, progress=None, overwrite=None, capture_log=None, stdin=None, stdout=None, stderr=None, input=None, **other_popen_kwargs)

run FFmpeg subprocess with standard pipes with a single transaction

Parameters:

• ffmpeg_args (dict) – FFmpeg argument options

• hide_banner (bool, optional) – False to output ffmpeg banner in stderr, defaults to True

• progress (callable object, optional) –

  progress callback function, defaults to None. This function takes two arguments:

  progress(data:dict, done:bool) -> None

• overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)

• capture_log (bool, optional) – True to capture log messages on stderr, False to send logs to console, defaults to None (no show/capture)

• stdin (readable file-like object, optional) – source file object, defaults to None

• stdout (writable file-like object, optional) – sink file object, defaults to None

• stderr (writable file-like object, optional) – file to log ffmpeg messages, defaults to None

• input (bytes-convertible object, optional) – input data buffer must be given if FFmpeg is configured to receive data stream from Python. It must be bytes convertible to bytes.

• **other_popen_kwargs (dict, optional) – other keyword arguments of Popen, defaults to {}

Rparam:

completed process

Return type:

subprocess.CompleteProcess

ffmpegio.ffmpegprocess.run_two_pass(ffmpeg_args, pass1_omits=None, pass1_extras=None, overwrite=None, stdin=None, **other_run_kwargs)

run FFmpeg subprocess with standard pipes with a single transaction twice for 2-pass encoding

Parameters:

• ffmpeg_args (dict) – FFmpeg argument options

• pass1_omits (seq(str) or seq(seq(str)) or dict(int:seq(str)) optional) – per-file list of output arguments to ignore in pass 1. If not applicable to every output file, use a nested dict with int keys to specify which output, defaults to None (remove ‘c:a’ or ‘acodec’).

• pass1_extras (dict(str) or seq(dict(str)) or dict(int:dict(str)), optional) – per-file list of additional output arguments to include in pass 1. If it does not apply to every output files, use a nested dict with int keys to specify which output, defaults to None (add ‘an’ if pass1_omits also None)

• hide_banner (bool, optional) – False to output ffmpeg banner in stderr, defaults to True

• progress (callable object, optional) –

  progress callback function, defaults to None. This function takes two arguments:

  progress(data:dict, done:bool) -> None

• overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)

• capture_log (bool, optional) – True to capture log messages on stderr, False to send logs to console, defaults to None (no show/capture)

• stdin (readable file-like object, optional) – source file object, defaults to None

• stderr (writable file-like object, optional) – file to log ffmpeg messages, defaults to None

• input (bytes-convertible object, optional) – input data buffer must be given if FFmpeg is configured to receive data stream from Python. It must be bytes convertible to bytes.

• **other_popen_kwargs (dict, optional) – other keyword arguments of Popen, defaults to {}

Rparam:

completed process

Return type:

subprocess.CompleteProcess

class ffmpegio.ffmpegprocess.Popen(ffmpeg_args, *, hide_banner=True, progress=None, overwrite=None, capture_log=None, stdin=None, stdout=None, stderr=None, on_exit=None, **other_popen_args)

Execute FFmpeg in a new process.

Parameters:

• ffmpeg_args (dict) – FFmpeg arguments

• hide_banner (bool, optional) – False to output ffmpeg banner in stderr, defaults to True

• progress (Callable, optional) –

  progress callback function, defaults to None. This function takes two arguments and may return True to terminate execution:

  progress(data:dict, done:bool) -> bool|None
  

• overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)

• capture_log (bool, optional) – True to capture log messages on stderr, False to send logs to console, defaults to None (no show/capture)

• stdin (readable file object, optional) – source file object, defaults to None

• stdout (writable file object, optional) – sink file object, defaults to None

• stderr (writable file object, optional) – file to log ffmpeg messages, defaults to None

• on_exit (Callable or seq(Callable), optional) – function(s) to execute when FFmpeg process terminates, defaults to None

• **other_popen_args (dict, optional) – other keyword arguments to subprocess.Popen

If ffmpeg_args calls for input or output to be piped (e.g., url=”-”) then Popen automatically sets stdin=PIPE or stdout=PIPE. Alternately, a file-stream object could be specified in the argument for each of stdin, stdout, and stderr to redirect pipes to existing file streams. If files aren’t already open in Python, specify their urls in ffmpeg_args instead of using the pipes.

ffmpeg_args

The FFmpeg args argument as it was passed to Popen

Type:

dict

kill()

Kill the FFmpeg process

send_signal(sig=None, kill_monitor=False)

Sends the signal signal to the FFmpeg process

Parameters:

• sig (int, optional) – signal id, default SIGINT (POSIX) / CTRL_C_EVENT (Windows)

• kill_monitor (bool, optional) – True to kill the monitor thread, default False

Without any argument, send_signal() will perform control-C to initiate soft-terminate FFmpeg. FFmpeg may output additional frames before exits.

Note: Setting kill_monitor=True will block the caller thread until the FFmpeg terminates.

terminate()

Terminate the FFmpeg process

wait(timeout=None)

Wait for FFmpeg process to terminate; returns self.returncode

Parameters:

timeout (float, optional) – optional timeout in seconds, defaults to None

For FFmpeg to terminate autonomously, its stdin PIPE must be closed.

If the process does not terminate after timeout seconds, raise a TimeoutExpired exception. It is safe to catch this exception and retry the wait.