runnable ¶

Execution capabilities for FFmpeg filter graphs.

This module provides the GlobalRunable class, which extends GlobalArgs with methods for executing FFmpeg commands. It enables compiling filter graphs into command-line arguments and running FFmpeg processes both synchronously and asynchronously.

Classes:

Name	Description
`GlobalRunable`	Base class that provides execution capabilities for FFmpeg filter graphs.

GlobalRunable ¶

Bases: GlobalArgs

Base class that provides execution capabilities for FFmpeg filter graphs.

This class extends GlobalArgs with methods for compiling filter graphs into FFmpeg command-line arguments and executing FFmpeg processes. It serves as a mixin for stream classes that need to be executed as FFmpeg commands.

Methods:

Name	Description
`merge_outputs`	Merge multiple output streams into a single command.
`overwrite_output`	Set the FFmpeg command to overwrite output files without asking.
`compile`	Build command-line arguments for invoking FFmpeg.
`compile_line`	Build a command-line string for invoking FFmpeg.
`run_async`	Run FFmpeg asynchronously as a subprocess.
`run`	Run FFmpeg synchronously and wait for completion.
`global_args`	Set global options.

merge_outputs ¶

merge_outputs(*streams: OutputStream) -> GlobalStream

Merge multiple output streams into a single command.

This method allows combining multiple output files into a single FFmpeg command, which is more efficient than running separate commands for each output. It creates a GlobalNode that includes all the specified output streams.

Parameters:

Name	Type	Description	Default
`*streams`	`OutputStream`	Additional output streams to include in the same command	`()`

Returns:

Type	Description
`GlobalStream`	A GlobalStream that represents the combined outputs

Example

# Create two output files with one command
video = ffmpeg.input("input.mp4").video
output1 = video.output("output1.mp4")
output2 = video.output("output2.webm")
merged = output1.merge_outputs(output2)
merged.run()  # Creates both output files with one FFmpeg command

overwrite_output ¶

overwrite_output() -> GlobalStream

Set the FFmpeg command to overwrite output files without asking.

This method adds the -y option to the FFmpeg command, which causes FFmpeg to overwrite output files without prompting for confirmation. It's equivalent to calling global_args(y=True).

Returns:

Type	Description
`GlobalStream`	A GlobalStream with the overwrite option enabled

Example

# Overwrite output file if it already exists
ffmpeg.input("input.mp4").output("output.mp4").overwrite_output().run()

compile ¶

compile(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> list[str]

Build command-line arguments for invoking FFmpeg.

This method converts the filter graph into a list of command-line arguments that can be passed to subprocess functions or executed directly. It handles the FFmpeg executable name, overwrite options, and automatic fixing of the filter graph.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph, such as adding split filters for reused streams	`True`

Returns:

Type	Description
`list[str]`	A list of strings representing the complete FFmpeg command

Example

# Get the command-line arguments for a filter graph
args = ffmpeg.input("input.mp4").output("output.mp4").compile()
# Result: ['ffmpeg', '-i', 'input.mp4', 'output.mp4']

compile_line ¶

compile_line(
    cmd: str | list[str] = "ffmpeg",
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> str

Build a command-line string for invoking FFmpeg.

This method is similar to compile(), but returns a single string with proper escaping instead of a list of arguments. This is useful for logging or displaying the command to users.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`overwrite_output`	`bool`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`

Returns:

Type	Description
`str`	A string representing the complete FFmpeg command with proper escaping

Example

# Get a command-line string for a filter graph
cmd_str = ffmpeg.input("input.mp4").output("output.mp4").compile_line()
# Result: 'ffmpeg -i input.mp4 output.mp4'

run_async ¶

run_async(
    cmd: str | list[str] = "ffmpeg",
    pipe_stdin: bool = False,
    pipe_stdout: bool = False,
    pipe_stderr: bool = False,
    quiet: bool = False,
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> Popen[bytes]

Run FFmpeg asynchronously as a subprocess.

This method executes the FFmpeg command in a separate process without waiting for it to complete. This is useful for long-running operations or when you need to interact with the process while it's running.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`pipe_stdin`	`bool`	Whether to create a pipe for writing to the process's stdin	`False`
`pipe_stdout`	`bool`	Whether to create a pipe for reading from the process's stdout	`False`
`pipe_stderr`	`bool`	Whether to create a pipe for reading from the process's stderr	`False`
`quiet`	`bool`	Whether to capture stderr (implies pipe_stderr=True)	`False`
`overwrite_output`	`bool`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`

Returns:

Type	Description
`Popen[bytes]`	A subprocess.Popen object representing the running FFmpeg process

Example

# Start FFmpeg process and interact with it
process = ffmpeg.input("input.mp4").output("output.mp4").run_async()
# Do something while FFmpeg is running
process.wait()  # Wait for completion

run ¶

run(
    cmd: str | list[str] = "ffmpeg",
    capture_stdout: bool = False,
    capture_stderr: bool = False,
    input: bytes | None = None,
    quiet: bool = False,
    overwrite_output: bool = None,
    auto_fix: bool = True,
) -> tuple[bytes, bytes]

Run FFmpeg synchronously and wait for completion.

This method executes the FFmpeg command in a separate process and waits for it to complete before returning. It's the most common way to run FFmpeg commands when you just want to process media files.

Parameters:

Name	Type	Description	Default
`cmd`	`str \| list[str]`	The FFmpeg executable name or path, or a list containing the executable and initial arguments	`'ffmpeg'`
`capture_stdout`	`bool`	Whether to capture and return the process's stdout	`False`
`capture_stderr`	`bool`	Whether to capture and return the process's stderr	`False`
`input`	`bytes \| None`	Optional bytes to write to the process's stdin	`None`
`quiet`	`bool`	Whether to suppress output to the console	`False`
`overwrite_output`	`bool`	If True, add the -y option to overwrite output files If False, add the -n option to never overwrite If None (default), use the current settings	`None`
`auto_fix`	`bool`	Whether to automatically fix issues in the filter graph	`True`

Returns:

Type	Description
`bytes`	A tuple of (stdout_bytes, stderr_bytes), which will be empty bytes
`bytes`	objects if the respective capture_* parameter is False

Raises:

Type	Description
`FFMpegExecuteError`	If the FFmpeg process returns a non-zero exit code

Example

# Process a video file
stdout, stderr = ffmpeg.input("input.mp4").output("output.mp4").run()

# Capture FFmpeg's output
stdout, stderr = (
    ffmpeg.input("input.mp4").output("output.mp4").run(capture_stderr=True)
)
print(stderr.decode())  # Print FFmpeg's progress information

global_args ¶

global_args(
    *,
    loglevel: Func = None,
    v: Func = None,
    report: Func = None,
    max_alloc: Func = None,
    cpuflags: Func = None,
    cpucount: Func = None,
    hide_banner: Boolean = None,
    y: Boolean = None,
    n: Boolean = None,
    ignore_unknown: Boolean = None,
    copy_unknown: Boolean = None,
    recast_media: Boolean = None,
    benchmark: Boolean = None,
    benchmark_all: Boolean = None,
    progress: Func = None,
    stdin: Boolean = None,
    timelimit: Func = None,
    dump: Boolean = None,
    hex: Boolean = None,
    frame_drop_threshold: Float = None,
    copyts: Boolean = None,
    start_at_zero: Boolean = None,
    copytb: Int = None,
    dts_delta_threshold: Float = None,
    dts_error_threshold: Float = None,
    xerror: Boolean = None,
    abort_on: Func = None,
    filter_threads: Func = None,
    filter_complex: Func = None,
    filter_complex_threads: Int = None,
    lavfi: Func = None,
    filter_complex_script: Func = None,
    auto_conversion_filters: Boolean = None,
    stats: Boolean = None,
    stats_period: Func = None,
    debug_ts: Boolean = None,
    max_error_rate: Float = None,
    vstats: Func = None,
    vstats_file: Func = None,
    vstats_version: Int = None,
    init_hw_device: Func = None,
    filter_hw_device: Func = None,
    adrift_threshold: Func = None,
    qphist: Func = None,
    vsync: Func = None,
    extra_options: dict[str, Any] = None
) -> GlobalStream

Set global options.

Parameters:

Name	Type	Description	Default
`loglevel`	`Func`	set logging level	`None`
`v`	`Func`	set logging level	`None`
`report`	`Func`	generate a report	`None`
`max_alloc`	`Func`	set maximum size of a single allocated block	`None`
`cpuflags`	`Func`	force specific cpu flags	`None`
`cpucount`	`Func`	force specific cpu count	`None`
`hide_banner`	`Boolean`	do not show program banner	`None`
`y`	`Boolean`	overwrite output files	`None`
`n`	`Boolean`	never overwrite output files	`None`
`ignore_unknown`	`Boolean`	Ignore unknown stream types	`None`
`copy_unknown`	`Boolean`	Copy unknown stream types	`None`
`recast_media`	`Boolean`	allow recasting stream type in order to force a decoder of different media type	`None`
`benchmark`	`Boolean`	add timings for benchmarking	`None`
`benchmark_all`	`Boolean`	add timings for each task	`None`
`progress`	`Func`	write program-readable progress information	`None`
`stdin`	`Boolean`	enable or disable interaction on standard input	`None`
`timelimit`	`Func`	set max runtime in seconds in CPU user time	`None`
`dump`	`Boolean`	dump each input packet	`None`
`hex`	`Boolean`	when dumping packets, also dump the payload	`None`
`frame_drop_threshold`	`Float`	frame drop threshold	`None`
`copyts`	`Boolean`	copy timestamps	`None`
`start_at_zero`	`Boolean`	shift input timestamps to start at 0 when using copyts	`None`
`copytb`	`Int`	copy input stream time base when stream copying	`None`
`dts_delta_threshold`	`Float`	timestamp discontinuity delta threshold	`None`
`dts_error_threshold`	`Float`	timestamp error delta threshold	`None`
`xerror`	`Boolean`	exit on error	`None`
`abort_on`	`Func`	abort on the specified condition flags	`None`
`filter_threads`	`Func`	number of non-complex filter threads	`None`
`filter_complex`	`Func`	create a complex filtergraph	`None`
`filter_complex_threads`	`Int`	number of threads for -filter_complex	`None`
`lavfi`	`Func`	create a complex filtergraph	`None`
`filter_complex_script`	`Func`	deprecated, use -/filter_complex instead	`None`
`auto_conversion_filters`	`Boolean`	enable automatic conversion filters globally	`None`
`stats`	`Boolean`	print progress report during encoding	`None`
`stats_period`	`Func`	set the period at which ffmpeg updates stats and -progress output	`None`
`debug_ts`	`Boolean`	print timestamp debugging info	`None`
`max_error_rate`	`Float`	ratio of decoding errors (0.0: no errors, 1.0: 100% errors) above which ffmpeg returns an error instead of success.	`None`
`vstats`	`Func`	dump video coding statistics to file	`None`
`vstats_file`	`Func`	dump video coding statistics to file	`None`
`vstats_version`	`Int`	Version of the vstats format to use.	`None`
`init_hw_device`	`Func`	initialise hardware device	`None`
`filter_hw_device`	`Func`	set hardware device used when filtering	`None`
`adrift_threshold`	`Func`	deprecated, does nothing	`None`
`qphist`	`Func`	deprecated, does nothing	`None`
`vsync`	`Func`	set video sync method globally; deprecated, use -fps_mode	`None`
`extra_options`	`dict[str, Any]`	Additional options	`None`

Returns:

Name	Type	Description
`GlobalStream`	`GlobalStream`	GlobalStream instance