compile_cli

Compiles FFmpeg filter graphs into command-line arguments.

This module provides functionality to convert the internal DAG (Directed Acyclic Graph) representation of an FFmpeg filter chain into the actual command-line arguments that would be passed to FFmpeg. It traverses the graph in the correct order, handling global options, inputs, complex filtergraphs, and outputs.

Functions:

Name	Description
compile	Compile a stream into a list of FFmpeg command-line arguments.
get_stream_label	Generate the FFmpeg label for this stream in filter graphs.
get_args_filter_node	Generate the FFmpeg filter string for this filter node.
get_args_input_node	Generate the FFmpeg command-line arguments for this input file.
get_args_output_node	Generate the FFmpeg command-line arguments for this output file.
get_args_global_node	Generate the FFmpeg command-line arguments for these global options.
get_args	Get the arguments for a node.
get_node_label	Get the string label for a specific node in the filter graph.

compile

compile(stream: Stream, auto_fix: bool = True) -> list[str]

Compile a stream into a list of FFmpeg command-line arguments.

This function takes a Stream object representing an FFmpeg filter graph and converts it into a list of command-line arguments that can be passed to FFmpeg. It processes the graph in the correct order: 1. Global nodes (general FFmpeg options) 2. Input nodes (input files and their options) 3. Filter nodes (combined into a -filter_complex argument) 4. Output nodes (output files and their options)

The function validates the graph before compilation to ensure it's properly formed. If auto_fix is enabled, it will attempt to fix common issues.

Parameters:

Name	Type	Description	Default
stream	Stream	The Stream object to compile into arguments	required
auto_fix	bool	Whether to automatically fix issues in the stream (e.g., reconnecting disconnected nodes)	True

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

# Create a simple video scaling filter graph
input_stream = ffmpeg.input("input.mp4")
scaled = input_stream.filter("scale", 1280, 720)
output_stream = scaled.output("output.mp4")

# Compile to FFmpeg arguments
args = ffmpeg.dag.compile(output_stream)
print(
    args
)  # ['ffmpeg', '-i', 'input.mp4', '-filter_complex', '...', 'output.mp4']

get_stream_label

get_stream_label(
    stream: Stream, context: DAGContext | None = None
) -> str

Generate the FFmpeg label for this stream in filter graphs.

This method creates the label string used to identify this stream in FFmpeg filter graphs. The format of the label depends on the stream's source (input file or filter) and type (video or audio).

For input streams, labels follow FFmpeg's stream specifier syntax: - Video streams: "0:v" (first input, video stream) - Audio streams: "0:a" (first input, audio stream) - AV streams: "0" (first input, all streams)

For filter outputs, labels use the filter's label: - Single output filters: "filterlabel" - Multi-output filters: "filterlabel#index"

Parameters:

Name	Type	Description	Default
context	DAGContext | None	Optional DAG context for resolving node labels. If not provided, a new context will be built.	None

Returns:

Type	Description
str	A string label for this stream in FFmpeg filter syntax

Raises:

Type	Description
FFMpegValueError	If the stream has an unknown type or node type

get_args_filter_node

get_args_filter_node(
    node: FilterNode, context: DAGContext
) -> list[str]

Generate the FFmpeg filter string for this filter node.

This method creates the filter string that will be used in the filter_complex argument of the FFmpeg command. The format follows FFmpeg's syntax where input labels are followed by the filter name and parameters, and then output labels.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context for resolving stream labels. If not provided, a new context will be built.	required

Returns:

Type	Description
list[str]	A list of strings that, when joined, form the filter string
list[str]	for this node in the filter_complex argument

Example

For a scale filter with width=1280 and height=720, this might return: ['[0:v]', 'scale=', 'width=1280:height=720', '[s0]']

get_args_input_node

get_args_input_node(
    node: InputNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for this input file.

This method creates the command-line arguments needed to specify this input file to FFmpeg, including any input-specific options.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context (not used for input nodes)	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an input file "input.mp4" with options like seeking to 10 seconds: ['-ss', '10', '-i', 'input.mp4']

get_args_output_node

get_args_output_node(
    node: OutputNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for this output file.

This method creates the command-line arguments needed to specify this output file to FFmpeg, including stream mapping and output-specific options like codecs and formats.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context for resolving stream labels. If not provided, a new context will be built.	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For an output file "output.mp4" with H.264 video codec: ['-map', '[v0]', '-c:v', 'libx264', 'output.mp4']

get_args_global_node

get_args_global_node(
    node: GlobalNode, context: DAGContext
) -> list[str]

Generate the FFmpeg command-line arguments for these global options.

This method creates the command-line arguments needed to specify global options to FFmpeg, such as -y for overwrite or -loglevel for controlling log output.

Parameters:

Name	Type	Description	Default
context	DAGContext	Optional DAG context (not used for global options)	required

Returns:

Type	Description
list[str]	A list of strings representing FFmpeg command-line arguments

Example

For global options like overwrite and quiet logging: ['-y', '-loglevel', 'quiet']

get_args

get_args(
    node: Node, context: DAGContext | None = None
) -> list[str]

Get the arguments for a node.

get_node_label

get_node_label(node: Node, context: DAGContext) -> str

Get the string label for a specific node in the filter graph.

This method returns the label assigned to the node, which is used in FFmpeg filter graph notation. The label format depends on the node type: - Input nodes: sequential numbers (0, 1, 2...) - Filter nodes: 's' prefix followed by a number (s0, s1, s2...)

Parameters:

Name	Type	Description	Default
node	Node	The node to get the label for (must be an InputNode or FilterNode)	required

Returns:

Type	Description
str	The string label for the node

Raises:

Type	Description
AssertionError	If the node is not an InputNode or FilterNode